@furystack/shades 13.2.1 → 14.0.0

package/esm/components/nested-router.spec.js

@@ -1,11 +1,13 @@
 import { Injector } from '@furystack/inject';
+import { serializeValue } from '@furystack/rest';
 import { sleepAsync, usingAsync } from '@furystack/utils';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { initializeShadeRoot } from '../initialize.js';
 import { createComponent } from '../shade-component.js';
 import { flushUpdates } from '../shade.js';
 import { RouteMatchService } from '../services/route-match-service.js';
-import { buildMatchChain, findDivergenceIndex, NestedRouter, renderMatchChain, resolveViewTransition, } from './nested-router.js';
+import { LocationService } from '../services/location-service.js';
+import { buildMatchChain, enrichMatchChain, findDivergenceIndex, hasQueryOrHashChanged, NestedRouter, renderMatchChain, resolveViewTransition, } from './nested-router.js';
 import { NestedRouteLink } from './nested-route-link.js';
 describe('buildMatchChain', () => {
     it('should match a simple leaf route', () => {
@@ -122,6 +124,8 @@ describe('findDivergenceIndex', () => {
     const makeEntry = (id, params = {}) => ({
         route: { component: () => createComponent("div", null, id) },
         match: { path: '/', params },
+        query: null,
+        hash: undefined,
     });
     it('should return 0 for completely different chains', () => {
         const oldChain = [makeEntry(1)];
@@ -142,10 +146,106 @@ describe('findDivergenceIndex', () => {
     });
     it('should detect divergence from changed params', () => {
         const route = { component: () => createComponent("div", null) };
-        const oldChain = [{ route, match: { path: '/', params: { id: '1' } } }];
-        const newChain = [{ route, match: { path: '/', params: { id: '2' } } }];
+        const oldChain = [
+            { route, match: { path: '/', params: { id: '1' } }, query: null, hash: undefined },
+        ];
+        const newChain = [
+            { route, match: { path: '/', params: { id: '2' } }, query: null, hash: undefined },
+        ];
         expect(findDivergenceIndex(oldChain, newChain)).toBe(0);
     });
+    it('should ignore query and hash differences when deciding divergence', () => {
+        const route = { component: () => createComponent("div", null) };
+        const oldChain = [{ route, match: { path: '/', params: {} }, query: { page: 1 }, hash: 'a' }];
+        const newChain = [{ route, match: { path: '/', params: {} }, query: { page: 2 }, hash: 'b' }];
+        expect(findDivergenceIndex(oldChain, newChain)).toBe(1);
+    });
+});
+describe('enrichMatchChain', () => {
+    it('should return the input chain unchanged when no entry declares query or hash', () => {
+        const route = { component: () => createComponent("div", null) };
+        const chain = [{ route, match: { path: '/', params: {} }, query: null, hash: undefined }];
+        const result = enrichMatchChain(chain, {}, '');
+        expect(result).toBe(chain);
+    });
+    it('should populate query from the route validator', () => {
+        const route = {
+            component: () => createComponent("div", null),
+            query: (raw) => (typeof raw.page === 'number' ? { page: raw.page } : null),
+        };
+        const chain = [{ route, match: { path: '/', params: {} }, query: null, hash: undefined }];
+        const result = enrichMatchChain(chain, { page: 3 }, '');
+        expect(result).not.toBe(chain);
+        expect(result[0].query).toEqual({ page: 3 });
+    });
+    it('should set query to null when the validator rejects the current search', () => {
+        const route = {
+            component: () => createComponent("div", null),
+            query: (raw) => (typeof raw.page === 'number' ? { page: raw.page } : null),
+        };
+        const chain = [{ route, match: { path: '/', params: {} }, query: null, hash: undefined }];
+        const result = enrichMatchChain(chain, { page: 'nope' }, '');
+        expect(result[0].query).toBeNull();
+    });
+    it('should populate hash only when the current hash is listed in the declared tuple', () => {
+        const route = {
+            component: () => createComponent("div", null),
+            hash: ['a', 'b'],
+        };
+        const chain = [{ route, match: { path: '/', params: {} }, query: null, hash: undefined }];
+        expect(enrichMatchChain(chain, {}, 'a')[0].hash).toBe('a');
+        expect(enrichMatchChain(chain, {}, 'unknown')[0].hash).toBeUndefined();
+    });
+    it('should leave entries without a declared schema as null/undefined', () => {
+        const bareRoute = { component: () => createComponent("div", null) };
+        const declaringRoute = {
+            component: () => createComponent("div", null),
+            hash: ['a'],
+        };
+        const chain = [
+            { route: bareRoute, match: { path: '/', params: {} }, query: null, hash: undefined },
+            { route: declaringRoute, match: { path: '/', params: {} }, query: null, hash: undefined },
+        ];
+        const result = enrichMatchChain(chain, {}, 'a');
+        expect(result[0].query).toBeNull();
+        expect(result[0].hash).toBeUndefined();
+        expect(result[1].hash).toBe('a');
+    });
+});
+describe('hasQueryOrHashChanged', () => {
+    const makeEntry = (query, hash) => ({
+        route: { component: () => createComponent("div", null) },
+        match: { path: '/', params: {} },
+        query,
+        hash,
+    });
+    it('should return false when both chains are empty', () => {
+        expect(hasQueryOrHashChanged([], [])).toBe(false);
+    });
+    it('should return false for identical chains', () => {
+        const oldChain = [makeEntry({ page: 1 }, 'a')];
+        const newChain = [makeEntry({ page: 1 }, 'a')];
+        expect(hasQueryOrHashChanged(oldChain, newChain)).toBe(false);
+    });
+    it('should return true when the hash differs', () => {
+        expect(hasQueryOrHashChanged([makeEntry(null, 'a')], [makeEntry(null, 'b')])).toBe(true);
+    });
+    it('should return true when the query differs', () => {
+        expect(hasQueryOrHashChanged([makeEntry({ page: 1 }, undefined)], [makeEntry({ page: 2 }, undefined)])).toBe(true);
+    });
+    it('should treat equal query objects as unchanged regardless of key order', () => {
+        const oldChain = [makeEntry({ a: 1, b: 2 }, undefined)];
+        const newChain = [makeEntry({ b: 2, a: 1 }, undefined)];
+        expect(hasQueryOrHashChanged(oldChain, newChain)).toBe(false);
+    });
+    it('should detect query diffs on arrays', () => {
+        expect(hasQueryOrHashChanged([makeEntry([1, 2], undefined)], [makeEntry([1, 3], undefined)])).toBe(true);
+    });
+    it('should ignore chain entries beyond the shorter length', () => {
+        const oldChain = [makeEntry(null, 'a')];
+        const newChain = [makeEntry(null, 'a'), makeEntry({ x: 1 }, 'b')];
+        expect(hasQueryOrHashChanged(oldChain, newChain)).toBe(false);
+    });
 });
 describe('renderMatchChain', () => {
     it('should render a single leaf route with outlet undefined', () => {
@@ -156,6 +256,8 @@ describe('renderMatchChain', () => {
             {
                 route: { component: componentFn },
                 match: { path: '/leaf', params: {} },
+                query: null,
+                hash: undefined,
             },
         ];
         const result = renderMatchChain(chain, '/leaf');
@@ -163,6 +265,8 @@ describe('renderMatchChain', () => {
         expect(componentFn).toHaveBeenCalledWith({
             currentUrl: '/leaf',
             match: { path: '/leaf', params: {} },
+            query: null,
+            hash: undefined,
             outlet: undefined,
         });
         expect(result.chainElements).toHaveLength(1);
@@ -186,10 +290,14 @@ describe('renderMatchChain', () => {
             {
                 route: { component: parentComponent },
                 match: { path: '/parent', params: {} },
+                query: null,
+                hash: undefined,
             },
             {
                 route: { component: childComponent },
                 match: { path: '/child', params: {} },
+                query: null,
+                hash: undefined,
             },
         ];
         const result = renderMatchChain(chain, '/parent/child');
@@ -210,9 +318,9 @@ describe('renderMatchChain', () => {
         const child = makeComponent();
         const parent = makeComponent();
         const chain = [
-            { route: { component: parent }, match: { path: '/a', params: {} } },
-            { route: { component: child }, match: { path: '/b', params: {} } },
-            { route: { component: grandchild }, match: { path: '/c', params: {} } },
+            { route: { component: parent }, match: { path: '/a', params: {} }, query: null, hash: undefined },
+            { route: { component: child }, match: { path: '/b', params: {} }, query: null, hash: undefined },
+            { route: { component: grandchild }, match: { path: '/c', params: {} }, query: null, hash: undefined },
         ];
         renderMatchChain(chain, '/a/b/c');
         expect(urls).toEqual(['/a/b/c', '/a/b/c', '/a/b/c']);
@@ -226,9 +334,9 @@ describe('renderMatchChain', () => {
             "parent",
             outlet));
         const chain = [
-            { route: { component: parentComponent }, match: { path: '/a', params: {} } },
-            { route: { component: childComponent }, match: { path: '/b', params: {} } },
-            { route: { component: () => grandchildEl }, match: { path: '/c', params: {} } },
+            { route: { component: parentComponent }, match: { path: '/a', params: {} }, query: null, hash: undefined },
+            { route: { component: childComponent }, match: { path: '/b', params: {} }, query: null, hash: undefined },
+            { route: { component: () => grandchildEl }, match: { path: '/c', params: {} }, query: null, hash: undefined },
         ];
         const result = renderMatchChain(chain, '/a/b/c');
         expect(result.chainElements).toHaveLength(3);
@@ -283,10 +391,10 @@ describe('NestedRouter lifecycle hooks', () => {
                 injector,
                 rootElement,
                 jsxElement: (createComponent("div", null,
-                    createComponent(NestedRouteLink, { id: "child-a", href: "/parent/child-a" }, "child-a"),
-                    createComponent(NestedRouteLink, { id: "child-b", href: "/parent/child-b" }, "child-b"),
-                    createComponent(NestedRouteLink, { id: "other", href: "/other" }, "other"),
-                    createComponent(NestedRouteLink, { id: "nowhere", href: "/nowhere" }, "nowhere"),
+                    createComponent(NestedRouteLink, { id: "child-a", path: "/parent/child-a" }, "child-a"),
+                    createComponent(NestedRouteLink, { id: "child-b", path: "/parent/child-b" }, "child-b"),
+                    createComponent(NestedRouteLink, { id: "other", path: "/other" }, "other"),
+                    createComponent(NestedRouteLink, { id: "nowhere", path: "/nowhere" }, "nowhere"),
                     createComponent(NestedRouter, { routes: {
                             '/parent': {
                                 component: ({ outlet }) => createComponent("div", { id: "wrapper" }, outlet ?? createComponent("div", { id: "content" }, "parent-index")),
@@ -358,6 +466,127 @@ describe('NestedRouter lifecycle hooks', () => {
         });
     });
 });
+describe('NestedRouter query / hash re-render', () => {
+    beforeEach(() => {
+        document.body.innerHTML = '<div id="root"></div>';
+    });
+    afterEach(() => {
+        document.body.innerHTML = '';
+    });
+    it('should re-render the chain on a hash-only change without firing lifecycle hooks', async () => {
+        history.pushState(null, '', '/tabs');
+        const onVisit = vi.fn(async () => { });
+        const onLeave = vi.fn(async () => { });
+        const componentFn = vi.fn(({ hash }) => createComponent("div", { id: "content" },
+            "hash=",
+            hash ?? 'none'));
+        await usingAsync(new Injector(), async (injector) => {
+            const rootElement = document.getElementById('root');
+            initializeShadeRoot({
+                injector,
+                rootElement,
+                jsxElement: (createComponent(NestedRouter, { routes: {
+                        '/tabs': {
+                            component: componentFn,
+                            onVisit,
+                            onLeave,
+                            hash: ['a', 'b'],
+                        },
+                    } })),
+            });
+            await flushUpdates();
+            expect(document.getElementById('content')?.innerHTML).toBe('hash=none');
+            expect(onVisit).toBeCalledTimes(1);
+            expect(onLeave).not.toBeCalled();
+            const locationService = injector.getInstance(LocationService);
+            locationService.navigate('/tabs#a');
+            await flushUpdates();
+            await flushUpdates();
+            expect(document.getElementById('content')?.innerHTML).toBe('hash=a');
+            expect(onVisit).toBeCalledTimes(1);
+            expect(onLeave).not.toBeCalled();
+            locationService.navigate('/tabs#b');
+            await flushUpdates();
+            await flushUpdates();
+            expect(document.getElementById('content')?.innerHTML).toBe('hash=b');
+            expect(onVisit).toBeCalledTimes(1);
+            expect(onLeave).not.toBeCalled();
+        });
+    });
+    it('should re-render the chain on a query-only change without firing lifecycle hooks', async () => {
+        history.pushState(null, '', '/list');
+        const onVisit = vi.fn(async () => { });
+        const onLeave = vi.fn(async () => { });
+        const componentFn = vi.fn(({ query }) => (createComponent("div", { id: "content" },
+            "page=",
+            query?.page ?? 'none')));
+        await usingAsync(new Injector(), async (injector) => {
+            const rootElement = document.getElementById('root');
+            initializeShadeRoot({
+                injector,
+                rootElement,
+                jsxElement: (createComponent(NestedRouter, { routes: {
+                        '/list': {
+                            component: componentFn,
+                            onVisit,
+                            onLeave,
+                            query: (raw) => (typeof raw.page === 'number' ? { page: raw.page } : null),
+                        },
+                    } })),
+            });
+            await flushUpdates();
+            expect(document.getElementById('content')?.innerHTML).toBe('page=none');
+            expect(onVisit).toBeCalledTimes(1);
+            const locationService = injector.getInstance(LocationService);
+            locationService.navigate(`/list?page=${serializeValue(2)}`);
+            await flushUpdates();
+            await flushUpdates();
+            expect(document.getElementById('content')?.innerHTML).toBe('page=2');
+            expect(onVisit).toBeCalledTimes(1);
+            expect(onLeave).not.toBeCalled();
+            locationService.navigate(`/list?page=${serializeValue(5)}`);
+            await flushUpdates();
+            await flushUpdates();
+            expect(document.getElementById('content')?.innerHTML).toBe('page=5');
+            expect(onVisit).toBeCalledTimes(1);
+            expect(onLeave).not.toBeCalled();
+        });
+    });
+    it('should coalesce path + query + hash bursts into a single updateUrl', async () => {
+        history.pushState(null, '', '/a');
+        const aComponent = vi.fn(() => createComponent("div", { id: "content" }, "a"));
+        const bComponent = vi.fn(({ query, hash }) => (createComponent("div", { id: "content" },
+            "b-page=",
+            query?.page ?? 'none',
+            "-hash=",
+            hash ?? 'none')));
+        await usingAsync(new Injector(), async (injector) => {
+            const rootElement = document.getElementById('root');
+            initializeShadeRoot({
+                injector,
+                rootElement,
+                jsxElement: (createComponent(NestedRouter, { routes: {
+                        '/a': { component: aComponent },
+                        '/b': {
+                            component: bComponent,
+                            hash: ['x'],
+                            query: (raw) => (typeof raw.page === 'number' ? { page: raw.page } : null),
+                        },
+                    } })),
+            });
+            await flushUpdates();
+            expect(document.getElementById('content')?.innerHTML).toBe('a');
+            bComponent.mockClear();
+            injector.getInstance(LocationService).navigate(`/b?page=${serializeValue(7)}#x`);
+            await flushUpdates();
+            await flushUpdates();
+            expect(document.getElementById('content')?.innerHTML).toBe('b-page=7-hash=x');
+            // A single logical navigation should render the /b component exactly once,
+            // not three times (once per observable subscription).
+            expect(bComponent).toHaveBeenCalledTimes(1);
+        });
+    });
+});
 describe('NestedRouter latest-wins on rapid navigation', () => {
     beforeEach(() => {
         document.body.innerHTML = '<div id="root"></div>';
@@ -393,9 +622,9 @@ describe('NestedRouter latest-wins on rapid navigation', () => {
                 injector,
                 rootElement,
                 jsxElement: (createComponent("div", null,
-                    createComponent(NestedRouteLink, { id: "go-a", href: "/route-a" }, "a"),
-                    createComponent(NestedRouteLink, { id: "go-b", href: "/route-b" }, "b"),
-                    createComponent(NestedRouteLink, { id: "go-c", href: "/route-c" }, "c"),
+                    createComponent(NestedRouteLink, { id: "go-a", path: "/route-a" }, "a"),
+                    createComponent(NestedRouteLink, { id: "go-b", path: "/route-b" }, "b"),
+                    createComponent(NestedRouteLink, { id: "go-c", path: "/route-c" }, "c"),
                     createComponent(NestedRouter, { routes: {
                             '/route-a': {
                                 component: () => createComponent("div", { id: "content" }, "route-a"),
@@ -453,8 +682,8 @@ describe('NestedRouter lifecycle element scope', () => {
                 injector,
                 rootElement,
                 jsxElement: (createComponent("div", null,
-                    createComponent(NestedRouteLink, { id: "child-a", href: "/parent/child-a" }, "child-a"),
-                    createComponent(NestedRouteLink, { id: "child-b", href: "/parent/child-b" }, "child-b"),
+                    createComponent(NestedRouteLink, { id: "child-a", path: "/parent/child-a" }, "child-a"),
+                    createComponent(NestedRouteLink, { id: "child-b", path: "/parent/child-b" }, "child-b"),
                     createComponent(NestedRouter, { routes: {
                             '/parent': {
                                 component: ({ outlet }) => createComponent("div", { id: "wrapper" }, outlet ?? createComponent("span", null, "index")),
@@ -528,9 +757,9 @@ describe('NestedRouter flat routes', () => {
                 injector,
                 rootElement,
                 jsxElement: (createComponent("div", null,
-                    createComponent(NestedRouteLink, { id: "home", href: "/" }, "home"),
-                    createComponent(NestedRouteLink, { id: "about", href: "/about" }, "about"),
-                    createComponent(NestedRouteLink, { id: "contact", href: "/contact" }, "contact"),
+                    createComponent(NestedRouteLink, { id: "home", path: "/" }, "home"),
+                    createComponent(NestedRouteLink, { id: "about", path: "/about" }, "about"),
+                    createComponent(NestedRouteLink, { id: "contact", path: "/contact" }, "contact"),
                     createComponent(NestedRouter, { routes: {
                             '/about': { component: () => createComponent("div", { id: "content" }, "about-page") },
                             '/contact': { component: () => createComponent("div", { id: "content" }, "contact-page") },
@@ -640,9 +869,9 @@ describe('NestedRouter route param changes', () => {
                 injector,
                 rootElement,
                 jsxElement: (createComponent("div", null,
-                    createComponent(NestedRouteLink, { id: "user-1", href: "/users/1" }, "User 1"),
-                    createComponent(NestedRouteLink, { id: "user-2", href: "/users/2" }, "User 2"),
-                    createComponent(NestedRouteLink, { id: "user-3", href: "/users/3" }, "User 3"),
+                    createComponent(NestedRouteLink, { id: "user-1", path: "/users/1" }, "User 1"),
+                    createComponent(NestedRouteLink, { id: "user-2", path: "/users/2" }, "User 2"),
+                    createComponent(NestedRouteLink, { id: "user-3", path: "/users/3" }, "User 3"),
                     createComponent(NestedRouter, { routes: {
                             '/users/:id': {
                                 component: ({ match }) => createComponent("div", { id: "content" },
@@ -698,8 +927,8 @@ describe('NestedRouter route param changes', () => {
                 injector,
                 rootElement,
                 jsxElement: (createComponent("div", null,
-                    createComponent(NestedRouteLink, { id: "alpha-dash", href: "/org/alpha/dashboard" }, "Alpha Dashboard"),
-                    createComponent(NestedRouteLink, { id: "beta-dash", href: "/org/beta/dashboard" }, "Beta Dashboard"),
+                    createComponent(NestedRouteLink, { id: "alpha-dash", path: "/org/alpha/dashboard" }, "Alpha Dashboard"),
+                    createComponent(NestedRouteLink, { id: "beta-dash", path: "/org/beta/dashboard" }, "Beta Dashboard"),
                     createComponent(NestedRouter, { routes: {
                             '/org/:orgId': {
                                 component: ({ match, outlet }) => (createComponent("div", { id: "org" },
@@ -768,9 +997,9 @@ describe('NestedRouter + RouteMatchService integration', () => {
                 injector,
                 rootElement,
                 jsxElement: (createComponent("div", null,
-                    createComponent(NestedRouteLink, { id: "child-a", href: "/parent/child-a" }, "child-a"),
-                    createComponent(NestedRouteLink, { id: "child-b", href: "/parent/child-b" }, "child-b"),
-                    createComponent(NestedRouteLink, { id: "nowhere", href: "/nowhere" }, "nowhere"),
+                    createComponent(NestedRouteLink, { id: "child-a", path: "/parent/child-a" }, "child-a"),
+                    createComponent(NestedRouteLink, { id: "child-b", path: "/parent/child-b" }, "child-b"),
+                    createComponent(NestedRouteLink, { id: "nowhere", path: "/nowhere" }, "nowhere"),
                     createComponent(NestedRouter, { routes: { '/parent': parentRoute }, notFound: createComponent("div", { id: "content" }, "not found") }))),
             });
             // Initial load
@@ -823,6 +1052,8 @@ describe('resolveViewTransition', () => {
     const makeEntry = (viewTransition) => ({
         route: { component: () => createComponent("div", null), viewTransition },
         match: { path: '/', params: {} },
+        query: null,
+        hash: undefined,
     });
     it('should return false when router config is undefined and route has no override', () => {
         expect(resolveViewTransition(undefined, [makeEntry()])).toBe(false);
@@ -881,7 +1112,7 @@ describe('NestedRouter view transitions', () => {
                 injector,
                 rootElement,
                 jsxElement: (createComponent("div", null,
-                    createComponent(NestedRouteLink, { id: "go-about", href: "/about" }, "about"),
+                    createComponent(NestedRouteLink, { id: "go-about", path: "/about" }, "about"),
                     createComponent(NestedRouter, { viewTransition: true, routes: {
                             '/about': { component: () => createComponent("div", { id: "content" }, "about") },
                             '/': { component: () => createComponent("div", { id: "content" }, "home") },
@@ -903,7 +1134,7 @@ describe('NestedRouter view transitions', () => {
                 injector,
                 rootElement,
                 jsxElement: (createComponent("div", null,
-                    createComponent(NestedRouteLink, { id: "go-about", href: "/about" }, "about"),
+                    createComponent(NestedRouteLink, { id: "go-about", path: "/about" }, "about"),
                     createComponent(NestedRouter, { routes: {
                             '/about': { component: () => createComponent("div", { id: "content" }, "about") },
                             '/': { component: () => createComponent("div", { id: "content" }, "home") },
@@ -925,7 +1156,7 @@ describe('NestedRouter view transitions', () => {
                 injector,
                 rootElement,
                 jsxElement: (createComponent("div", null,
-                    createComponent(NestedRouteLink, { id: "go-about", href: "/about" }, "about"),
+                    createComponent(NestedRouteLink, { id: "go-about", path: "/about" }, "about"),
                     createComponent(NestedRouter, { viewTransition: { types: ['slide'] }, routes: {
                             '/about': { component: () => createComponent("div", { id: "content" }, "about") },
                             '/': { component: () => createComponent("div", { id: "content" }, "home") },
@@ -946,7 +1177,7 @@ describe('NestedRouter view transitions', () => {
                 injector,
                 rootElement,
                 jsxElement: (createComponent("div", null,
-                    createComponent(NestedRouteLink, { id: "go-about", href: "/about" }, "about"),
+                    createComponent(NestedRouteLink, { id: "go-about", path: "/about" }, "about"),
                     createComponent(NestedRouter, { viewTransition: true, routes: {
                             '/about': {
                                 component: () => createComponent("div", { id: "content" }, "about"),
@@ -972,7 +1203,7 @@ describe('NestedRouter view transitions', () => {
                 injector,
                 rootElement,
                 jsxElement: (createComponent("div", null,
-                    createComponent(NestedRouteLink, { id: "go-about", href: "/about" }, "about"),
+                    createComponent(NestedRouteLink, { id: "go-about", path: "/about" }, "about"),
                     createComponent(NestedRouter, { viewTransition: true, routes: {
                             '/about': { component: () => createComponent("div", { id: "content" }, "about") },
                             '/': { component: () => createComponent("div", { id: "content" }, "home") },