@furystack/shades 13.2.1 → 14.0.0

package/src/components/nested-router.spec.tsx

@@ -1,13 +1,17 @@
 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 { LocationService } from '../services/location-service.js'
 import {
   buildMatchChain,
+  enrichMatchChain,
   findDivergenceIndex,
+  hasQueryOrHashChanged,
   NestedRouter,
   renderMatchChain,
   resolveViewTransition,
@@ -138,6 +142,8 @@ describe('findDivergenceIndex', () => {
   const makeEntry = (id: number, params: Record<string, string> = {}): MatchChainEntry => ({
     route: { component: () => <div>{id}</div> },
     match: { path: '/', params },
+    query: null,
+    hash: undefined,
   })
 
   it('should return 0 for completely different chains', () => {
@@ -162,10 +168,120 @@ describe('findDivergenceIndex', () => {
 
   it('should detect divergence from changed params', () => {
     const route: NestedRoute = { component: () => <div /> }
-    const oldChain: MatchChainEntry[] = [{ route, match: { path: '/', params: { id: '1' } } }]
-    const newChain: MatchChainEntry[] = [{ route, match: { path: '/', params: { id: '2' } } }]
+    const oldChain: MatchChainEntry[] = [
+      { route, match: { path: '/', params: { id: '1' } }, query: null, hash: undefined },
+    ]
+    const newChain: MatchChainEntry[] = [
+      { 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: NestedRoute = { component: () => <div /> }
+    const oldChain: MatchChainEntry[] = [{ route, match: { path: '/', params: {} }, query: { page: 1 }, hash: 'a' }]
+    const newChain: MatchChainEntry[] = [{ 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: NestedRoute = { component: () => <div /> }
+    const chain: MatchChainEntry[] = [{ 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: NestedRoute<unknown, { page: number }> = {
+      component: () => <div />,
+      query: (raw): { page: number } | null => (typeof raw.page === 'number' ? { page: raw.page } : null),
+    }
+    const chain: MatchChainEntry[] = [{ 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: NestedRoute<unknown, { page: number }> = {
+      component: () => <div />,
+      query: (raw): { page: number } | null => (typeof raw.page === 'number' ? { page: raw.page } : null),
+    }
+    const chain: MatchChainEntry[] = [{ 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: NestedRoute<unknown, any, readonly ['a', 'b']> = {
+      component: () => <div />,
+      hash: ['a', 'b'] as const,
+    }
+    const chain: MatchChainEntry[] = [{ 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: NestedRoute = { component: () => <div /> }
+    const declaringRoute: NestedRoute<unknown, any, readonly ['a']> = {
+      component: () => <div />,
+      hash: ['a'] as const,
+    }
+    const chain: MatchChainEntry[] = [
+      { 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: unknown, hash: string | undefined): MatchChainEntry => ({
+    route: { component: () => <div /> },
+    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', () => {
@@ -177,6 +293,8 @@ describe('renderMatchChain', () => {
       {
         route: { component: componentFn },
         match: { path: '/leaf', params: {} },
+        query: null,
+        hash: undefined,
       },
     ]
 
@@ -186,6 +304,8 @@ describe('renderMatchChain', () => {
     expect(componentFn).toHaveBeenCalledWith({
       currentUrl: '/leaf',
       match: { path: '/leaf', params: {} },
+      query: null,
+      hash: undefined,
       outlet: undefined,
     })
     expect(result.chainElements).toHaveLength(1)
@@ -208,10 +328,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,
       },
     ]
 
@@ -240,9 +364,9 @@ describe('renderMatchChain', () => {
     const parent = makeComponent()
 
     const chain: MatchChainEntry[] = [
-      { 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')
@@ -256,9 +380,9 @@ describe('renderMatchChain', () => {
     const parentComponent = vi.fn(({ outlet }: { outlet?: JSX.Element }) => <main>parent{outlet}</main>)
 
     const chain: MatchChainEntry[] = [
-      { 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')
@@ -322,16 +446,16 @@ describe('NestedRouter lifecycle hooks', () => {
         rootElement,
         jsxElement: (
           <div>
-            <NestedRouteLink id="child-a" href="/parent/child-a">
+            <NestedRouteLink id="child-a" path="/parent/child-a">
               child-a
             </NestedRouteLink>
-            <NestedRouteLink id="child-b" href="/parent/child-b">
+            <NestedRouteLink id="child-b" path="/parent/child-b">
               child-b
             </NestedRouteLink>
-            <NestedRouteLink id="other" href="/other">
+            <NestedRouteLink id="other" path="/other">
               other
             </NestedRouteLink>
-            <NestedRouteLink id="nowhere" href="/nowhere">
+            <NestedRouteLink id="nowhere" path="/nowhere">
               nowhere
             </NestedRouteLink>
             <NestedRouter
@@ -417,6 +541,163 @@ 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 }: { hash: string | undefined }) => <div id="content">hash={hash ?? 'none'}</div>)
+
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <NestedRouter
+            routes={{
+              '/tabs': {
+                component: componentFn,
+                onVisit,
+                onLeave,
+                hash: ['a', 'b'] as const,
+              },
+            }}
+          />
+        ),
+      })
+
+      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 }: { query: { page: number } | null }) => (
+      <div id="content">page={query?.page ?? 'none'}</div>
+    ))
+
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <NestedRouter
+            routes={{
+              '/list': {
+                component: componentFn,
+                onVisit,
+                onLeave,
+                query: (raw): { page: number } | null => (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(() => <div id="content">a</div>)
+    const bComponent = vi.fn(({ query, hash }: { query: { page: number } | null; hash: string | undefined }) => (
+      <div id="content">
+        b-page={query?.page ?? 'none'}-hash={hash ?? 'none'}
+      </div>
+    ))
+
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <NestedRouter
+            routes={{
+              '/a': { component: aComponent },
+              '/b': {
+                component: bComponent,
+                hash: ['x'] as const,
+                query: (raw): { page: number } | null => (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>'
@@ -458,13 +739,13 @@ describe('NestedRouter latest-wins on rapid navigation', () => {
         rootElement,
         jsxElement: (
           <div>
-            <NestedRouteLink id="go-a" href="/route-a">
+            <NestedRouteLink id="go-a" path="/route-a">
               a
             </NestedRouteLink>
-            <NestedRouteLink id="go-b" href="/route-b">
+            <NestedRouteLink id="go-b" path="/route-b">
               b
             </NestedRouteLink>
-            <NestedRouteLink id="go-c" href="/route-c">
+            <NestedRouteLink id="go-c" path="/route-c">
               c
             </NestedRouteLink>
             <NestedRouter
@@ -540,10 +821,10 @@ describe('NestedRouter lifecycle element scope', () => {
         rootElement,
         jsxElement: (
           <div>
-            <NestedRouteLink id="child-a" href="/parent/child-a">
+            <NestedRouteLink id="child-a" path="/parent/child-a">
               child-a
             </NestedRouteLink>
-            <NestedRouteLink id="child-b" href="/parent/child-b">
+            <NestedRouteLink id="child-b" path="/parent/child-b">
               child-b
             </NestedRouteLink>
             <NestedRouter
@@ -633,13 +914,13 @@ describe('NestedRouter flat routes', () => {
         rootElement,
         jsxElement: (
           <div>
-            <NestedRouteLink id="home" href="/">
+            <NestedRouteLink id="home" path="/">
               home
             </NestedRouteLink>
-            <NestedRouteLink id="about" href="/about">
+            <NestedRouteLink id="about" path="/about">
               about
             </NestedRouteLink>
-            <NestedRouteLink id="contact" href="/contact">
+            <NestedRouteLink id="contact" path="/contact">
               contact
             </NestedRouteLink>
             <NestedRouter
@@ -792,13 +1073,13 @@ describe('NestedRouter route param changes', () => {
         rootElement,
         jsxElement: (
           <div>
-            <NestedRouteLink id="user-1" href="/users/1">
+            <NestedRouteLink id="user-1" path="/users/1">
               User 1
             </NestedRouteLink>
-            <NestedRouteLink id="user-2" href="/users/2">
+            <NestedRouteLink id="user-2" path="/users/2">
               User 2
             </NestedRouteLink>
-            <NestedRouteLink id="user-3" href="/users/3">
+            <NestedRouteLink id="user-3" path="/users/3">
               User 3
             </NestedRouteLink>
             <NestedRouter
@@ -868,10 +1149,10 @@ describe('NestedRouter route param changes', () => {
         rootElement,
         jsxElement: (
           <div>
-            <NestedRouteLink id="alpha-dash" href="/org/alpha/dashboard">
+            <NestedRouteLink id="alpha-dash" path="/org/alpha/dashboard">
               Alpha Dashboard
             </NestedRouteLink>
-            <NestedRouteLink id="beta-dash" href="/org/beta/dashboard">
+            <NestedRouteLink id="beta-dash" path="/org/beta/dashboard">
               Beta Dashboard
             </NestedRouteLink>
             <NestedRouter
@@ -957,13 +1238,13 @@ describe('NestedRouter + RouteMatchService integration', () => {
         rootElement,
         jsxElement: (
           <div>
-            <NestedRouteLink id="child-a" href="/parent/child-a">
+            <NestedRouteLink id="child-a" path="/parent/child-a">
               child-a
             </NestedRouteLink>
-            <NestedRouteLink id="child-b" href="/parent/child-b">
+            <NestedRouteLink id="child-b" path="/parent/child-b">
               child-b
             </NestedRouteLink>
-            <NestedRouteLink id="nowhere" href="/nowhere">
+            <NestedRouteLink id="nowhere" path="/nowhere">
               nowhere
             </NestedRouteLink>
             <NestedRouter routes={{ '/parent': parentRoute }} notFound={<div id="content">not found</div>} />
@@ -1030,6 +1311,8 @@ describe('resolveViewTransition', () => {
   const makeEntry = (viewTransition?: boolean | { types?: string[] }): MatchChainEntry => ({
     route: { component: () => <div />, viewTransition },
     match: { path: '/', params: {} },
+    query: null,
+    hash: undefined,
   })
 
   it('should return false when router config is undefined and route has no override', () => {
@@ -1103,7 +1386,7 @@ describe('NestedRouter view transitions', () => {
         rootElement,
         jsxElement: (
           <div>
-            <NestedRouteLink id="go-about" href="/about">
+            <NestedRouteLink id="go-about" path="/about">
               about
             </NestedRouteLink>
             <NestedRouter
@@ -1139,7 +1422,7 @@ describe('NestedRouter view transitions', () => {
         rootElement,
         jsxElement: (
           <div>
-            <NestedRouteLink id="go-about" href="/about">
+            <NestedRouteLink id="go-about" path="/about">
               about
             </NestedRouteLink>
             <NestedRouter
@@ -1174,7 +1457,7 @@ describe('NestedRouter view transitions', () => {
         rootElement,
         jsxElement: (
           <div>
-            <NestedRouteLink id="go-about" href="/about">
+            <NestedRouteLink id="go-about" path="/about">
               about
             </NestedRouteLink>
             <NestedRouter
@@ -1209,7 +1492,7 @@ describe('NestedRouter view transitions', () => {
         rootElement,
         jsxElement: (
           <div>
-            <NestedRouteLink id="go-about" href="/about">
+            <NestedRouteLink id="go-about" path="/about">
               about
             </NestedRouteLink>
             <NestedRouter
@@ -1250,7 +1533,7 @@ describe('NestedRouter view transitions', () => {
         rootElement,
         jsxElement: (
           <div>
-            <NestedRouteLink id="go-about" href="/about">
+            <NestedRouteLink id="go-about" path="/about">
               about
             </NestedRouteLink>
             <NestedRouter