coop/rose-ash
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

SPA nav improvements: scroll restoration, popstate, history spec

Browse Source 
- boot.sx: popstate handler extracts scrollY from history state
- engine.sx: pass scroll position to handle-popstate
- boot-helpers.sx: scroll position tracking in navigation
- orchestration.sx: scroll state management for back/forward nav
- history.spec.js: new Playwright spec for history navigation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
giles
2026-04-02 15:36:24 +00:00
parent bea8779aea
commit b6e144a6fd
5 changed files with 217 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
tests/playwright/history.spec.js Normal file
View File

@@ -0,0 +1,184 @@
// History navigation tests — back/forward buttons (HTMX 4.0 style)
// Verifies that popstate re-renders content, restores scroll position,
// and matches a fresh load of the same URL.
const { test, expect } = require('playwright/test');
const { BASE_URL, waitForSxReady, loadPage, trackErrors } = require('./helpers');
test.describe('History navigation', () => {
let t;
test.beforeEach(({ page }) => { t = trackErrors(page); });
test.afterEach(() => { expect(t.errors()).toEqual([]); });
test('back button restores previous page content', async ({ page }) => {
await loadPage(page, '(geography)');
await expect(page.locator('#sx-content')).toContainText('Geography');
// Navigate forward
await page.click('a[href*="geography.(reactive)"]:not([href*="runtime"])');
await expect(page).toHaveURL(/reactive/, { timeout: 5000 });
await expect(page.locator('#sx-content')).toContainText('Reactive Islands', { timeout: 5000 });
// Back button
await page.goBack();
await expect(page).toHaveURL(/geography/, { timeout: 5000 });
await expect(page).not.toHaveURL(/reactive/);
// Content must update to match the URL
await expect(page.locator('#sx-content')).toContainText('Geography', { timeout: 5000 });
});
test('forward button restores next page content', async ({ page }) => {
await loadPage(page, '(geography)');
// Navigate forward
await page.click('a[href*="geography.(reactive)"]:not([href*="runtime"])');
await expect(page).toHaveURL(/reactive/, { timeout: 5000 });
await expect(page.locator('#sx-content')).toContainText('Reactive Islands', { timeout: 5000 });
// Back
await page.goBack();
await expect(page).toHaveURL(/geography/, { timeout: 5000 });
await expect(page.locator('#sx-content')).toContainText('Geography', { timeout: 5000 });
// Forward
await page.goForward();
await expect(page).toHaveURL(/reactive/, { timeout: 5000 });
await expect(page.locator('#sx-content')).toContainText('Reactive Islands', { timeout: 5000 });
});
test('back button after multiple navigations', async ({ page }) => {
await loadPage(page, '');
// Navigate: home -> geography -> reactive
await page.click('a[sx-get*="(geography)"]');
await expect(page).toHaveURL(/geography/, { timeout: 5000 });
await page.waitForTimeout(1000);
await page.click('a[href*="geography.(reactive)"]:not([href*="runtime"])');
await expect(page).toHaveURL(/reactive/, { timeout: 5000 });
await page.waitForTimeout(1000);
// Back to geography
await page.goBack();
await expect(page).toHaveURL(/geography/, { timeout: 5000 });
await expect(page).not.toHaveURL(/reactive/);
await expect(page.locator('#sx-content')).toContainText('Geography', { timeout: 5000 });
// Back to home
await page.goBack();
await expect(page).toHaveURL(/\/sx\/?$/, { timeout: 5000 });
});
test('back button is SPA nav, not full reload', async ({ page }) => {
await loadPage(page, '(geography)');
// Set marker that survives SPA nav but not full reload
await page.evaluate(() => window.__history_marker = true);
// Navigate forward
await page.click('a[href*="geography.(reactive)"]:not([href*="runtime"])');
await expect(page).toHaveURL(/reactive/, { timeout: 5000 });
// Marker should survive forward SPA nav
expect(await page.evaluate(() => window.__history_marker)).toBe(true);
// Back button
await page.goBack();
await expect(page).toHaveURL(/geography/, { timeout: 5000 });
// Marker should survive back nav (no full reload)
expect(await page.evaluate(() => window.__history_marker)).toBe(true);
});
test('nav sidebar updates on back button', async ({ page }) => {
await loadPage(page, '(geography)');
await expect(page.locator('#sx-nav')).toContainText('Geography');
// Navigate forward
await page.click('a[href*="geography.(reactive)"]:not([href*="runtime"])');
await expect(page).toHaveURL(/reactive/, { timeout: 5000 });
// Back button
await page.goBack();
await expect(page).toHaveURL(/geography/, { timeout: 5000 });
// Nav should show Geography content, not Reactive Islands
await expect(page.locator('#sx-nav')).toContainText('Geography', { timeout: 5000 });
});
test('layout preserved after back button', async ({ page }) => {
await loadPage(page, '(geography)');
await page.click('a[href*="geography.(reactive)"]:not([href*="runtime"])');
await expect(page).toHaveURL(/reactive/, { timeout: 5000 });
await page.goBack();
await expect(page).toHaveURL(/geography/, { timeout: 5000 });
// Key layout elements must exist and not be duplicated
const layout = await page.evaluate(() => ({
contentCount: document.querySelectorAll('#sx-content').length,
navCount: document.querySelectorAll('#sx-nav').length,
headerCount: document.querySelectorAll('[data-sx-island="layouts/header"]').length,
}));
expect(layout.contentCount).toBe(1);
expect(layout.navCount).toBe(1);
expect(layout.headerCount).toBe(1);
});
test('scroll position saved on forward nav', async ({ page }) => {
await loadPage(page, '(geography)');
// Scroll down
await page.evaluate(() => window.scrollTo(0, 200));
await page.waitForTimeout(100);
// Navigate forward — should save scroll via replaceState
await page.click('a[href*="geography.(reactive)"]:not([href*="runtime"])');
await expect(page).toHaveURL(/reactive/, { timeout: 5000 });
// Check that the previous history entry has scrollY saved
const state = await page.evaluate(() => {
// Can't read previous entry state directly, but we can check
// that pushState was called with state on the current entry
return window.history.state;
});
// Current entry (the new page) won't have scrollY,
// but we can verify the mechanism works by going back
await page.goBack();
await expect(page).toHaveURL(/geography/, { timeout: 5000 });
// The page should have restored (browser handles the state object)
// We verify the content loaded correctly as the primary check
await expect(page.locator('#sx-content')).toContainText('Geography', { timeout: 5000 });
});
test('back button content matches fresh load', async ({ page }) => {
await loadPage(page, '(geography)');
// Navigate forward
await page.click('a[href*="geography.(reactive)"]:not([href*="runtime"])');
await expect(page).toHaveURL(/reactive/, { timeout: 5000 });
await page.waitForTimeout(1000);
// Go back
await page.goBack();
await expect(page).toHaveURL(/geography/, { timeout: 5000 });
await page.waitForTimeout(1000);
// Snapshot the back-button DOM
const backContent = await page.evaluate(() =>
document.querySelector('#sx-content')?.textContent?.trim().substring(0, 200));
// Fresh load the same URL
await page.goto(page.url(), { waitUntil: 'domcontentloaded' });
await waitForSxReady(page);
const freshContent = await page.evaluate(() =>
document.querySelector('#sx-content')?.textContent?.trim().substring(0, 200));
// Back-button content should match fresh load
expect(backContent).toBe(freshContent);
});
});

10
web/boot.sx
View File

@@ -433,7 +433,15 @@
(run-post-render-hooks)
(flush-collected-styles)
(set-timeout (fn () (process-elements nil)) 0)
(dom-listen (dom-window) "popstate" (fn (e) (handle-popstate 0)))
(dom-listen
(dom-window)
"popstate"
(fn
(e)
(let
((state (host-get e "state"))
(scrollY (if state (or (dict-get state "scrollY") 0) 0)))
(handle-popstate scrollY))))
(dom-set-attr
(host-get (dom-document) "documentElement")
"data-sx-ready"

4
web/engine.sx
View File

@@ -719,7 +719,9 @@
hdr-replace
(browser-replace-state hdr-replace)
(and push-url (not (= push-url "false")))
(browser-push-state (if (= push-url "true") url push-url))
(do
(save-scroll-position)
(browser-push-state (if (= push-url "true") url push-url)))
(and replace-url (not (= replace-url "false")))
(browser-replace-state (if (= replace-url "true") url replace-url))))))

5
web/lib/boot-helpers.sx
View File

@@ -501,7 +501,10 @@
"#sx-content")))
(if
(try-client-route (url-pathname href) target-sel)
(do (browser-push-state nil "" href) (browser-scroll-to 0 0))
(do
(save-scroll-position)
(browser-push-state nil "" href)
(browser-scroll-to 0 0))
(do
(log-info (str "sx:route server fetch " href))
(dom-set-attr link "sx-get" href)

22
web/orchestration.sx
View File

@@ -527,6 +527,7 @@
(if
client-routed
(do
(save-scroll-position)
(browser-push-state (get live-info "url"))
(browser-scroll-to 0 0))
(do
@@ -1553,11 +1554,23 @@
(dom-dispatch el event-name detail))))))))
els))))
(define
save-scroll-position
:effects (io)
(fn
()
(let
((scrollY (host-get (dom-window) "scrollY")))
(browser-replace-state
(dict "scrollY" scrollY)
""
(browser-location-href)))))
(define
handle-popstate
:effects (mutation io)
(fn
((scrollY :as number))
(scrollY)
(let
((url (browser-location-href))
(boost-el (dom-query "[sx-boost]"))
@@ -1566,9 +1579,8 @@
boost-el
(let
((attr (dom-get-attr boost-el "sx-boost")))
(if (and attr (not (= attr "true"))) attr nil))
nil))
(target-sel (or target-sel "#main-panel"))
(if (and attr (not (= attr "true"))) attr "#sx-content"))
"#sx-content"))
(target (dom-query target-sel))
(pathname (url-pathname url)))
(when
@@ -1577,7 +1589,7 @@
(try-client-route pathname target-sel)
(browser-scroll-to 0 scrollY)
(let
((headers (build-request-headers target (loaded-component-names) _css-hash)))
((headers (build-request-headers target "GET" url)))
(fetch-and-restore target url headers scrollY)))))))
(define