Handle history scroll restoration using navigation api except for firefox

Author: MichaelWest22

src/ext/hx-history-cache.js

@@ -198,7 +198,7 @@
         // Before core pushes/replaces, save the outgoing page
         htmx_before_history_update: (elt, detail) => {
             if (cfg().disable) return;
-            if (!_currentId) stampCurrentEntry();
+            stampCurrentEntry();
             saveCurrentPage();
         },
 

src/htmx.js

@@ -1600,16 +1600,19 @@ var htmx = (() => {
             if (!history.state) {
                 history.replaceState({htmx: true}, '', location.href);
             }
-            window.addEventListener('popstate', (event) => {
-                if (event.state && event.state.htmx) {
-                    this.#historyAbort?.abort();
-                    this.__restoreHistory();
-                }
-            });
+            if (window.navigation && !/firefox/i.test(navigator.userAgent)) {
+                navigation.addEventListener('navigate', (event) => {
+                    if (event.navigationType === 'traverse' && event.canIntercept && !event.hashChange)
+                        event.intercept({handler: () => this.__restoreHistory()});
+                });
+            } else {
+                window.addEventListener('popstate', (event) => this.__restoreHistory(event.state));
+            }
         }
 
         __pushUrlIntoHistory(path) {
             if (!this.config.history) return;
+            if (!history.state) history.replaceState({htmx: true}, '', location.href);
             history.pushState({htmx: true}, '', path);
             this.__trigger(document, "htmx:after:history:push", {path});
         }
@@ -1620,15 +1623,19 @@ var htmx = (() => {
             this.__trigger(document, "htmx:after:history:replace", {path});
         }
 
-        __restoreHistory(path) {
+        async __restoreHistory(state, path) {
+            await this.timeout(1);
+            state ??= history.state;
+            if (!state?.htmx) return;
+            this.#historyAbort?.abort();
             path = path || location.pathname + location.search;
             let historyElt = document.querySelector(this.__prefixSelector('[hx-history-elt]')) || document.body;
             if (this.__trigger(document, "htmx:before:history:restore", {path, cacheMiss: true})) {
                 if (this.config.history === "reload") {
                     location.reload();
                 } else {
                     this.#historyAbort = new AbortController();
-                    this.ajax('GET', path, {
+                    return this.ajax('GET', path, {
                         target: historyElt,
                         swap: 'outerSync',
                         select: historyElt !== document.body ? this.__prefixSelector('[hx-history-elt]') : undefined,

test/lib/helpers.js

@@ -63,7 +63,14 @@ function cleanupTest() {
         }
         fetchMock.reset()
     }
-    history.replaceState(null, '', savedUrl);
+    let saved = new URL(savedUrl);
+    if (location.pathname !== saved.pathname || location.search !== saved.search) {
+        // Use location.replace() instead of history.replaceState() to avoid
+        // the browser's 100 replaceState/10s rate limit across large test suites.
+        // location.replace() navigates to the URL without adding a history entry
+        // and is not subject to the replaceState rate limit.
+        history.replaceState(null, '', savedUrl);
+    }
 }
 
 //================================================================================

test/tests/end2end/basic-history.js

@@ -153,7 +153,7 @@ describe('hx-push-url and hx-replace-url attributes', function() {
         try {
             mockResponse('GET', '/restore-test', '<div id="restored">Restored Content</div>');
 
-            htmx.__restoreHistory('/restore-test');
+            htmx.__restoreHistory({htmx: true}, '/restore-test');
             await forRequest();
 
             document.body.innerHTML.should.include('Restored Content');
@@ -336,7 +336,7 @@ describe('hx-history-elt scopes history restore', function() {
         </body></html>`;
         mockResponse('GET', '/restore-test', response);
 
-        htmx.__restoreHistory('/restore-test');
+        htmx.__restoreHistory({htmx: true}, '/restore-test');
         await forRequest();
 
         document.getElementById('sentinel').should.not.equal(null);
@@ -353,3 +353,231 @@ describe('hx-history-elt scopes history restore', function() {
         document.body.textContent.should.not.include('FOOTER LEAK');
     });
 });
+
+
+
+describe('scroll restoration on history traversal', function() {
+
+    const hasNavigationAPI = typeof Navigation === 'function' && !/Firefox\//.test(navigator.userAgent);
+
+    beforeEach(() => { setupTest(this.currentTest); });
+
+    afterEach(() => {
+        window.scrollTo(0, 0);
+        cleanupTest();
+    });
+
+    async function untilScrollY(y, timeout = 1500) {
+        let start = performance.now();
+        while (window.scrollY !== y && performance.now() - start < timeout) {
+            await new Promise(r => requestAnimationFrame(r));
+        }
+    }
+
+    it('boosted back restores content, then the browser restores scroll', async function() {
+        if (!hasNavigationAPI) this.skip();
+        playground().innerHTML = '<main hx-history-elt><div style="height:3000px">page A</div></main>';
+        htmx.process(playground());
+        history.replaceState({htmx: true}, '', '/scroll-page-a');
+        window.scrollTo(0, 500);
+
+        htmx.__pushUrlIntoHistory('/scroll-page-b');
+        playground().innerHTML = '<main hx-history-elt><p>page B</p></main>';
+        window.scrollTo(0, 0);
+
+        mockResponse('GET', '/scroll-page-a', () => new Promise(resolve =>
+            setTimeout(() => resolve(new MockResponse(
+                '<html><body><main hx-history-elt><div style="height:3000px">page A restored</div></main></body></html>'
+            )), 100)));
+
+        history.back();
+        await forRequest(400);
+        await untilScrollY(500);
+
+        playground().textContent.should.include('page A restored');
+        assert.equal(window.scrollY, 500);
+    });
+
+    it('back returns to the latest scroll position after re-scrolling', async function() {
+        if (!hasNavigationAPI) this.skip();
+        this.timeout(5000);
+        playground().innerHTML = '<main hx-history-elt><div style="height:3000px">page A</div></main>';
+        htmx.process(playground());
+        history.replaceState({htmx: true}, '', '/scroll-page-a');
+        window.scrollTo(0, 500);
+
+        htmx.__pushUrlIntoHistory('/scroll-page-b');
+        playground().innerHTML = '<main hx-history-elt><div style="height:3000px">page B</div></main>';
+        window.scrollTo(0, 0);
+
+        mockResponse('GET', '/scroll-page-a',
+            '<html><body><main hx-history-elt><div style="height:3000px">page A</div></main></body></html>');
+        mockResponse('GET', '/scroll-page-b',
+            '<html><body><main hx-history-elt><div style="height:3000px">page B</div></main></body></html>');
+
+        history.back();
+        await forRequest();
+        await untilScrollY(500);
+
+        window.scrollTo(0, 800);
+        history.forward();
+        await forRequest();
+        await untilScrollY(0);
+
+        history.back();
+        await forRequest();
+        await untilScrollY(800);
+
+        assert.equal(window.scrollY, 800);
+    });
+
+    it('back to an entry created by an anchor jump still restores content', async function() {
+        if (!hasNavigationAPI) this.skip();
+        playground().innerHTML = '<main hx-history-elt><div style="height:3000px">reference page</div></main>';
+        htmx.process(playground());
+        history.replaceState({htmx: true}, '', '/scroll-ref');
+
+        location.hash = '#events';
+        assert.isNull(history.state);
+        window.scrollTo(0, 500);
+
+        htmx.__pushUrlIntoHistory('/scroll-hxget');
+        playground().innerHTML = '<main hx-history-elt><p>hx-get page</p></main>';
+        window.scrollTo(0, 0);
+
+        mockResponse('GET', '/scroll-ref', () => new Promise(resolve =>
+            setTimeout(() => resolve(new MockResponse(
+                '<html><body><main hx-history-elt><div style="height:3000px">reference restored</div></main></body></html>'
+            )), 100)));
+
+        history.back();
+        await forRequest(400);
+        await untilScrollY(500);
+
+        playground().textContent.should.include('reference restored');
+        assert.equal(location.hash, '#events');
+        assert.equal(window.scrollY, 500);
+    });
+
+    it('restores horizontal scroll as well', async function() {
+        if (!hasNavigationAPI) this.skip();
+        playground().innerHTML = '<main hx-history-elt><div style="height:3000px;width:3000px">wide page</div></main>';
+        htmx.process(playground());
+        history.replaceState({htmx: true}, '', '/scroll-wide');
+        window.scrollTo(300, 500);
+
+        htmx.__pushUrlIntoHistory('/scroll-narrow');
+        playground().innerHTML = '<main hx-history-elt><p>narrow page</p></main>';
+        window.scrollTo(0, 0);
+
+        mockResponse('GET', '/scroll-wide', () => new Promise(resolve =>
+            setTimeout(() => resolve(new MockResponse(
+                '<html><body><main hx-history-elt><div style="height:3000px;width:3000px">wide restored</div></main></body></html>'
+            )), 100)));
+
+        history.back();
+        await forRequest(400);
+        await untilScrollY(500);
+
+        assert.equal(window.scrollY, 500);
+        assert.equal(window.scrollX, 300);
+    });
+
+    it('ignores traversal to non-htmx history entries', async function() {
+        history.replaceState({foreign: true}, '', '/foreign-page');
+        history.pushState({htmx: true}, '', '/scroll-page-b');
+
+        history.back();
+        let evt = await forRequest(150);
+
+        assert.isNull(evt);
+    });
+    it('ignores hash-only traversal', async function() {
+        if (!hasNavigationAPI) this.skip();
+        history.replaceState({htmx: true}, '', location.pathname + '#a');
+        history.pushState({htmx: true}, '', location.pathname + '#b');
+
+        history.back();
+        let evt = await forRequest(150);
+
+        assert.isNull(evt);
+        assert.equal(location.hash, '#a');
+    });
+});
+
+describe('history restore edge cases', function() {
+
+    beforeEach(() => { setupTest(this.currentTest); });
+    afterEach(() => { cleanupTest(); });
+
+    it('a second back aborts the in-flight restore', async function() {
+        this.timeout(5000);
+        playground().innerHTML = '<main hx-history-elt><p>page C</p></main>';
+        htmx.process(playground());
+        history.replaceState({htmx: true}, '', '/edge-a');
+        htmx.__pushUrlIntoHistory('/edge-b');
+        htmx.__pushUrlIntoHistory('/edge-c');
+
+        mockResponse('GET', '/edge-a',
+            '<html><body><main hx-history-elt><p>page A</p></main></body></html>');
+        mockResponse('GET', '/edge-b', () => new Promise(resolve =>
+            setTimeout(() => resolve(new MockResponse(
+                '<html><body><main hx-history-elt><p>page B</p></main></body></html>'
+            )), 150)));
+
+        history.back();
+        await new Promise(r => setTimeout(r, 50));
+        history.back();
+        await new Promise(r => setTimeout(r, 500));
+
+        assert.equal(location.pathname, '/edge-a');
+        playground().textContent.should.include('page A');
+    });
+
+    it('restores the replaced URL after a replace', async function() {
+        playground().innerHTML = '<main hx-history-elt><p>replaced page</p></main>';
+        htmx.process(playground());
+        history.replaceState({htmx: true}, '', '/edge-orig');
+        htmx.__pushUrlIntoHistory('/edge-next');
+        htmx.__replaceUrlInHistory('/edge-replaced');
+
+        mockResponse('GET', '/edge-orig',
+            '<html><body><main hx-history-elt><p>original restored</p></main></body></html>');
+        mockResponse('GET', '/edge-replaced',
+            '<html><body><main hx-history-elt><p>replaced restored</p></main></body></html>');
+
+        history.back();
+        await forRequest();
+        playground().textContent.should.include('original restored');
+        assert.equal(location.pathname, '/edge-orig');
+        await new Promise(r => setTimeout(r, 50));
+
+        history.forward();
+        await forRequest();
+        playground().textContent.should.include('replaced restored');
+        assert.equal(location.pathname, '/edge-replaced');
+    });
+
+    it('skips a foreign entry but restores the htmx entry behind it', async function() {
+        playground().innerHTML = '<main hx-history-elt><p>after page</p></main>';
+        htmx.process(playground());
+        history.replaceState({htmx: true}, '', '/edge-mine');
+        history.pushState({vue: true}, '', '/edge-foreign');
+        htmx.__pushUrlIntoHistory('/edge-after');
+
+        mockResponse('GET', '/edge-mine',
+            '<html><body><main hx-history-elt><p>mine restored</p></main></body></html>');
+
+        history.back();
+        let evt = await forRequest(150);
+        assert.isNull(evt);
+        playground().textContent.should.include('after page');
+        assert.equal(location.pathname, '/edge-foreign');
+
+        history.back();
+        await forRequest();
+        playground().textContent.should.include('mine restored');
+        assert.equal(location.pathname, '/edge-mine');
+    });
+});
+

test/tests/ext/hx-alpine-compat-history.js

@@ -78,7 +78,7 @@
         history.replaceState({ htmx: true, htmxId }, '', cachedPath);
         await new Promise(resolve => {
             document.addEventListener('htmx:history:cache:after:restore', resolve, { once: true });
-            htmx.__restoreHistory(cachedPath);
+            htmx.__restoreHistory(history.state, cachedPath);
         });
         await htmx.timeout(50);
         return historyElt;
@@ -108,7 +108,7 @@
         history.replaceState({ htmx: true, htmxId }, '', cachedPath);
         await new Promise(resolve => {
             document.addEventListener('htmx:history:cache:after:restore', resolve, { once: true });
-            htmx.__restoreHistory(cachedPath);
+            htmx.__restoreHistory(history.state, cachedPath);
         });
         await htmx.timeout(50);
 
@@ -138,7 +138,7 @@
         history.replaceState({ htmx: true, htmxId }, '', cachedPath);
         await new Promise(resolve => {
             document.addEventListener('htmx:history:cache:after:restore', resolve, { once: true });
-            htmx.__restoreHistory(cachedPath);
+            htmx.__restoreHistory(history.state, cachedPath);
         });
         await htmx.timeout(50);
 
@@ -183,7 +183,7 @@
         history.replaceState({ htmx: true, htmxId }, '', cachedPath);
         await new Promise(resolve => {
             document.addEventListener('htmx:history:cache:after:restore', resolve, { once: true });
-            htmx.__restoreHistory(cachedPath);
+            htmx.__restoreHistory(history.state, cachedPath);
         });
         await htmx.timeout(50);