@furystack/shades 12.2.5 → 12.4.0

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

@@ -4,15 +4,17 @@ 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,
   type MatchChainEntry,
   type NestedRoute,
 } from './nested-router.js'
-import { RouteLink } from './route-link.js'
+import { NestedRouteLink } from './nested-route-link.js'
 
 describe('buildMatchChain', () => {
   it('should match a simple leaf route', () => {
@@ -320,18 +322,18 @@ describe('NestedRouter lifecycle hooks', () => {
         rootElement,
         jsxElement: (
           <div>
-            <RouteLink id="child-a" href="/parent/child-a">
+            <NestedRouteLink id="child-a" href="/parent/child-a">
               child-a
-            </RouteLink>
-            <RouteLink id="child-b" href="/parent/child-b">
+            </NestedRouteLink>
+            <NestedRouteLink id="child-b" href="/parent/child-b">
               child-b
-            </RouteLink>
-            <RouteLink id="other" href="/other">
+            </NestedRouteLink>
+            <NestedRouteLink id="other" href="/other">
               other
-            </RouteLink>
-            <RouteLink id="nowhere" href="/nowhere">
+            </NestedRouteLink>
+            <NestedRouteLink id="nowhere" href="/nowhere">
               nowhere
-            </RouteLink>
+            </NestedRouteLink>
             <NestedRouter
               routes={{
                 '/parent': {
@@ -456,15 +458,15 @@ describe('NestedRouter latest-wins on rapid navigation', () => {
         rootElement,
         jsxElement: (
           <div>
-            <RouteLink id="go-a" href="/route-a">
+            <NestedRouteLink id="go-a" href="/route-a">
               a
-            </RouteLink>
-            <RouteLink id="go-b" href="/route-b">
+            </NestedRouteLink>
+            <NestedRouteLink id="go-b" href="/route-b">
               b
-            </RouteLink>
-            <RouteLink id="go-c" href="/route-c">
+            </NestedRouteLink>
+            <NestedRouteLink id="go-c" href="/route-c">
               c
-            </RouteLink>
+            </NestedRouteLink>
             <NestedRouter
               routes={{
                 '/route-a': {
@@ -538,12 +540,12 @@ describe('NestedRouter lifecycle element scope', () => {
         rootElement,
         jsxElement: (
           <div>
-            <RouteLink id="child-a" href="/parent/child-a">
+            <NestedRouteLink id="child-a" href="/parent/child-a">
               child-a
-            </RouteLink>
-            <RouteLink id="child-b" href="/parent/child-b">
+            </NestedRouteLink>
+            <NestedRouteLink id="child-b" href="/parent/child-b">
               child-b
-            </RouteLink>
+            </NestedRouteLink>
             <NestedRouter
               routes={{
                 '/parent': {
@@ -631,15 +633,15 @@ describe('NestedRouter flat routes', () => {
         rootElement,
         jsxElement: (
           <div>
-            <RouteLink id="home" href="/">
+            <NestedRouteLink id="home" href="/">
               home
-            </RouteLink>
-            <RouteLink id="about" href="/about">
+            </NestedRouteLink>
+            <NestedRouteLink id="about" href="/about">
               about
-            </RouteLink>
-            <RouteLink id="contact" href="/contact">
+            </NestedRouteLink>
+            <NestedRouteLink id="contact" href="/contact">
               contact
-            </RouteLink>
+            </NestedRouteLink>
             <NestedRouter
               routes={{
                 '/about': { component: () => <div id="content">about-page</div> },
@@ -790,15 +792,15 @@ describe('NestedRouter route param changes', () => {
         rootElement,
         jsxElement: (
           <div>
-            <RouteLink id="user-1" href="/users/1">
+            <NestedRouteLink id="user-1" href="/users/1">
               User 1
-            </RouteLink>
-            <RouteLink id="user-2" href="/users/2">
+            </NestedRouteLink>
+            <NestedRouteLink id="user-2" href="/users/2">
               User 2
-            </RouteLink>
-            <RouteLink id="user-3" href="/users/3">
+            </NestedRouteLink>
+            <NestedRouteLink id="user-3" href="/users/3">
               User 3
-            </RouteLink>
+            </NestedRouteLink>
             <NestedRouter
               routes={{
                 '/users/:id': {
@@ -866,12 +868,12 @@ describe('NestedRouter route param changes', () => {
         rootElement,
         jsxElement: (
           <div>
-            <RouteLink id="alpha-dash" href="/org/alpha/dashboard">
+            <NestedRouteLink id="alpha-dash" href="/org/alpha/dashboard">
               Alpha Dashboard
-            </RouteLink>
-            <RouteLink id="beta-dash" href="/org/beta/dashboard">
+            </NestedRouteLink>
+            <NestedRouteLink id="beta-dash" href="/org/beta/dashboard">
               Beta Dashboard
-            </RouteLink>
+            </NestedRouteLink>
             <NestedRouter
               routes={{
                 '/org/:orgId': {
@@ -919,3 +921,355 @@ describe('NestedRouter route param changes', () => {
     })
   })
 })
+
+describe('NestedRouter + RouteMatchService integration', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="root"></div>'
+  })
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  it('should update RouteMatchService with the current match chain on navigation', async () => {
+    history.pushState(null, '', '/parent/child-a')
+
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const routeMatchService = injector.getInstance(RouteMatchService)
+
+      const parentRoute: NestedRoute = {
+        meta: { title: 'Parent' },
+        component: ({ outlet }) => <div>{outlet ?? <div>parent-index</div>}</div>,
+        children: {
+          '/child-a': {
+            meta: { title: 'Child A' },
+            component: () => <div id="content">child-a</div>,
+          },
+          '/child-b': {
+            meta: { title: 'Child B' },
+            component: () => <div id="content">child-b</div>,
+          },
+        },
+      }
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <div>
+            <NestedRouteLink id="child-a" href="/parent/child-a">
+              child-a
+            </NestedRouteLink>
+            <NestedRouteLink id="child-b" href="/parent/child-b">
+              child-b
+            </NestedRouteLink>
+            <NestedRouteLink id="nowhere" href="/nowhere">
+              nowhere
+            </NestedRouteLink>
+            <NestedRouter routes={{ '/parent': parentRoute }} notFound={<div id="content">not found</div>} />
+          </div>
+        ),
+      })
+
+      // Initial load
+      await flushUpdates()
+      const initialChain = routeMatchService.currentMatchChain.getValue()
+      expect(initialChain).toHaveLength(2)
+      expect(initialChain[0].route.meta?.title).toBe('Parent')
+      expect(initialChain[1].route.meta?.title).toBe('Child A')
+
+      // Navigate to sibling child
+      document.getElementById('child-b')?.click()
+      await flushUpdates()
+      const updatedChain = routeMatchService.currentMatchChain.getValue()
+      expect(updatedChain).toHaveLength(2)
+      expect(updatedChain[0].route.meta?.title).toBe('Parent')
+      expect(updatedChain[1].route.meta?.title).toBe('Child B')
+
+      // Navigate to not-found
+      document.getElementById('nowhere')?.click()
+      await flushUpdates()
+      const notFoundChain = routeMatchService.currentMatchChain.getValue()
+      expect(notFoundChain).toEqual([])
+    })
+  })
+
+  it('should expose match params through RouteMatchService', async () => {
+    history.pushState(null, '', '/users/42')
+
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const routeMatchService = injector.getInstance(RouteMatchService)
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <NestedRouter
+            routes={{
+              '/users/:id': {
+                meta: {
+                  title: ({ match }: { match: { params: Record<string, string> } }) => `User ${match.params.id}`,
+                },
+                component: ({ match }) => <div id="content">user-{(match.params as { id: string }).id}</div>,
+              },
+            }}
+          />
+        ),
+      })
+
+      await flushUpdates()
+      const chain = routeMatchService.currentMatchChain.getValue()
+      expect(chain).toHaveLength(1)
+      expect(chain[0].match.params).toEqual({ id: '42' })
+    })
+  })
+})
+
+describe('resolveViewTransition', () => {
+  const makeEntry = (viewTransition?: boolean | { types?: string[] }): MatchChainEntry => ({
+    route: { component: () => <div />, viewTransition },
+    match: { path: '/', params: {} },
+  })
+
+  it('should return false when router config is undefined and route has no override', () => {
+    expect(resolveViewTransition(undefined, [makeEntry()])).toBe(false)
+  })
+
+  it('should return false when router config is false', () => {
+    expect(resolveViewTransition(false, [makeEntry()])).toBe(false)
+  })
+
+  it('should return config when router config is true', () => {
+    expect(resolveViewTransition(true, [makeEntry()])).toEqual({ types: undefined })
+  })
+
+  it('should return false when router is true but leaf route opts out', () => {
+    expect(resolveViewTransition(true, [makeEntry(false)])).toBe(false)
+  })
+
+  it('should use router-level types when route has no override', () => {
+    expect(resolveViewTransition({ types: ['slide'] }, [makeEntry()])).toEqual({ types: ['slide'] })
+  })
+
+  it('should prefer route-level types over router-level types', () => {
+    expect(resolveViewTransition({ types: ['slide'] }, [makeEntry({ types: ['fade'] })])).toEqual({
+      types: ['fade'],
+    })
+  })
+
+  it('should enable transitions when only the leaf route enables it', () => {
+    expect(resolveViewTransition(undefined, [makeEntry(true)])).toEqual({ types: undefined })
+  })
+
+  it('should use types from the innermost (leaf) route in a chain', () => {
+    const parent = makeEntry({ types: ['parent-type'] })
+    const child = makeEntry({ types: ['child-type'] })
+    expect(resolveViewTransition(true, [parent, child])).toEqual({ types: ['child-type'] })
+  })
+})
+
+describe('NestedRouter view transitions', () => {
+  let startViewTransitionSpy: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="root"></div>'
+    startViewTransitionSpy = vi.fn((optionsOrCallback: StartViewTransitionOptions | (() => void)) => {
+      const update = typeof optionsOrCallback === 'function' ? optionsOrCallback : optionsOrCallback.update
+      update?.()
+      return {
+        finished: Promise.resolve(),
+        ready: Promise.resolve(),
+        updateCallbackDone: Promise.resolve(),
+        skipTransition: vi.fn(),
+      } as unknown as ViewTransition
+    })
+    document.startViewTransition = startViewTransitionSpy as typeof document.startViewTransition
+  })
+
+  afterEach(() => {
+    document.body.innerHTML = ''
+    delete (document as unknown as Record<string, unknown>).startViewTransition
+  })
+
+  it('should call startViewTransition when viewTransition is enabled', async () => {
+    history.pushState(null, '', '/')
+
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <div>
+            <NestedRouteLink id="go-about" href="/about">
+              about
+            </NestedRouteLink>
+            <NestedRouter
+              viewTransition
+              routes={{
+                '/about': { component: () => <div id="content">about</div> },
+                '/': { component: () => <div id="content">home</div> },
+              }}
+            />
+          </div>
+        ),
+      })
+
+      await flushUpdates()
+      startViewTransitionSpy.mockClear()
+
+      document.getElementById('go-about')?.click()
+      await flushUpdates()
+
+      expect(startViewTransitionSpy).toHaveBeenCalledTimes(1)
+      expect(document.getElementById('content')?.innerHTML).toBe('about')
+    })
+  })
+
+  it('should not call startViewTransition when viewTransition is not set', async () => {
+    history.pushState(null, '', '/')
+
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <div>
+            <NestedRouteLink id="go-about" href="/about">
+              about
+            </NestedRouteLink>
+            <NestedRouter
+              routes={{
+                '/about': { component: () => <div id="content">about</div> },
+                '/': { component: () => <div id="content">home</div> },
+              }}
+            />
+          </div>
+        ),
+      })
+
+      await flushUpdates()
+      startViewTransitionSpy.mockClear()
+
+      document.getElementById('go-about')?.click()
+      await flushUpdates()
+
+      expect(startViewTransitionSpy).not.toHaveBeenCalled()
+      expect(document.getElementById('content')?.innerHTML).toBe('about')
+    })
+  })
+
+  it('should pass types to startViewTransition when configured', async () => {
+    history.pushState(null, '', '/')
+
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <div>
+            <NestedRouteLink id="go-about" href="/about">
+              about
+            </NestedRouteLink>
+            <NestedRouter
+              viewTransition={{ types: ['slide'] }}
+              routes={{
+                '/about': { component: () => <div id="content">about</div> },
+                '/': { component: () => <div id="content">home</div> },
+              }}
+            />
+          </div>
+        ),
+      })
+
+      await flushUpdates()
+      startViewTransitionSpy.mockClear()
+
+      document.getElementById('go-about')?.click()
+      await flushUpdates()
+
+      expect(startViewTransitionSpy).toHaveBeenCalledWith(expect.objectContaining({ types: ['slide'] }))
+    })
+  })
+
+  it('should respect per-route viewTransition: false override', async () => {
+    history.pushState(null, '', '/')
+
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <div>
+            <NestedRouteLink id="go-about" href="/about">
+              about
+            </NestedRouteLink>
+            <NestedRouter
+              viewTransition
+              routes={{
+                '/about': {
+                  component: () => <div id="content">about</div>,
+                  viewTransition: false,
+                },
+                '/': { component: () => <div id="content">home</div> },
+              }}
+            />
+          </div>
+        ),
+      })
+
+      await flushUpdates()
+      startViewTransitionSpy.mockClear()
+
+      document.getElementById('go-about')?.click()
+      await flushUpdates()
+
+      expect(startViewTransitionSpy).not.toHaveBeenCalled()
+      expect(document.getElementById('content')?.innerHTML).toBe('about')
+    })
+  })
+
+  it('should fall back gracefully when startViewTransition is not available', async () => {
+    delete (document as unknown as Record<string, unknown>).startViewTransition
+
+    history.pushState(null, '', '/')
+
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <div>
+            <NestedRouteLink id="go-about" href="/about">
+              about
+            </NestedRouteLink>
+            <NestedRouter
+              viewTransition
+              routes={{
+                '/about': { component: () => <div id="content">about</div> },
+                '/': { component: () => <div id="content">home</div> },
+              }}
+            />
+          </div>
+        ),
+      })
+
+      await flushUpdates()
+
+      document.getElementById('go-about')?.click()
+      await flushUpdates()
+
+      expect(document.getElementById('content')?.innerHTML).toBe('about')
+    })
+  })
+})

package/src/components/nested-router.tsx

@@ -1,10 +1,47 @@
+import type { Injector } from '@furystack/inject'
 import { ObservableAlreadyDisposedError } from '@furystack/utils'
 import type { MatchOptions, MatchResult } from 'path-to-regexp'
 import { match } from 'path-to-regexp'
 import type { RenderOptions } from '../models/render-options.js'
 import { LocationService } from '../services/location-service.js'
+import { RouteMatchService } from '../services/route-match-service.js'
 import { createComponent, setRenderMode } from '../shade-component.js'
 import { Shade } from '../shade.js'
+import type { ViewTransitionConfig } from '../view-transition.js'
+import { maybeViewTransition } from '../view-transition.js'
+
+/**
+ * Options passed to a dynamic title resolver function.
+ * @typeParam TMatchResult - The type of matched URL parameters
+ */
+export type TitleResolverOptions<TMatchResult = unknown> = {
+  match: MatchResult<TMatchResult extends object ? TMatchResult : object>
+  injector: Injector
+}
+
+/**
+ * Metadata associated with a route entry.
+ * Used by consumers (breadcrumbs, document title, navigation trees) to
+ * derive display information from the route hierarchy.
+ *
+ * This is an `interface` so that applications can augment it with custom fields
+ * via declaration merging:
+ *
+ * @example
+ * ```typescript
+ * declare module '@furystack/shades' {
+ *   interface NestedRouteMeta {
+ *     icon?: IconDefinition
+ *     hidden?: boolean
+ *   }
+ * }
+ * ```
+ *
+ * @typeParam TMatchResult - The type of matched URL parameters
+ */
+export interface NestedRouteMeta<TMatchResult = unknown> {
+  title?: string | ((options: TitleResolverOptions<TMatchResult>) => string | Promise<string>)
+}
 
 /**
  * A single route entry in a NestedRouter configuration.
@@ -13,15 +50,28 @@ import { Shade } from '../shade.js'
  * @typeParam TMatchResult - The type of matched URL parameters
  */
 export type NestedRoute<TMatchResult = unknown> = {
+  meta?: NestedRouteMeta<TMatchResult>
   component: (options: {
     currentUrl: string
     match: MatchResult<TMatchResult extends object ? TMatchResult : object>
     outlet?: JSX.Element
   }) => JSX.Element
   routingOptions?: MatchOptions
+  /**
+   * Called after the route's DOM has been mounted. When view transitions are enabled,
+   * this runs after the transition's update callback has completed and the new DOM is in place.
+   * Use for imperative side effects like data fetching or focus management — not for visual
+   * animations, which are handled by the View Transition API when `viewTransition` is enabled.
+   */
   onVisit?: (options: RenderOptions<unknown> & { element: JSX.Element }) => Promise<void>
+  /**
+   * Called before the route's DOM is removed (and before the view transition starts, if enabled).
+   * Use for cleanup or teardown logic — not for exit animations, which are handled by the
+   * View Transition API when `viewTransition` is enabled.
+   */
   onLeave?: (options: RenderOptions<unknown> & { element: JSX.Element }) => Promise<void>
   children?: Record<string, NestedRoute<any>>
+  viewTransition?: boolean | ViewTransitionConfig
 }
 
 /**
@@ -31,6 +81,7 @@ export type NestedRoute<TMatchResult = unknown> = {
 export type NestedRouterProps = {
   routes: Record<string, NestedRoute<any>>
   notFound?: JSX.Element
+  viewTransition?: boolean | ViewTransitionConfig
 }
 
 /**
@@ -164,6 +215,29 @@ export const renderMatchChain = (chain: MatchChainEntry[], currentUrl: string):
   return { jsx: outlet as JSX.Element, chainElements }
 }
 
+/**
+ * Resolves the effective view transition config for a navigation by merging
+ * the router-level default with the innermost (leaf) route's override.
+ * A per-route `false` disables transitions even when the router default is on.
+ */
+export const resolveViewTransition = (
+  routerConfig: boolean | ViewTransitionConfig | undefined,
+  newChain: MatchChainEntry[],
+): ViewTransitionConfig | false => {
+  if (!routerConfig && routerConfig !== undefined) return false
+
+  const leafRoute = newChain[newChain.length - 1]?.route
+  const routeConfig = leafRoute?.viewTransition
+
+  if (routeConfig === false) return false
+  if (!routerConfig && !routeConfig) return false
+
+  const baseTypes = typeof routerConfig === 'object' ? routerConfig.types : undefined
+  const routeTypes = typeof routeConfig === 'object' ? routeConfig.types : undefined
+
+  return { types: routeTypes ?? baseTypes }
+}
+
 /**
  * A nested router component that supports hierarchical route definitions
  * with parent/child relationships. Parent routes receive an `outlet` prop
@@ -201,7 +275,6 @@ export const NestedRouter = Shade<NestedRouterProps>({
           if (hasChanged) {
             const version = ++versionRef.current
 
-            // Call onLeave for routes that are being left (from divergence point to end of old chain)
             for (let i = lastChainEntries.length - 1; i >= divergeIndex; i--) {
               await lastChainEntries[i].route.onLeave?.({ ...options, element: lastChainElements[i] })
               if (version !== versionRef.current) return
@@ -215,9 +288,15 @@ export const NestedRouter = Shade<NestedRouterProps>({
               setRenderMode(false)
             }
             if (version !== versionRef.current) return
-            setState({ matchChain: newChain, jsx: newResult.jsx, chainElements: newResult.chainElements })
 
-            // Call onVisit for routes that are being entered (from divergence point to end of new chain)
+            const applyUpdate = () => {
+              setState({ matchChain: newChain, jsx: newResult.jsx, chainElements: newResult.chainElements })
+              injector.getInstance(RouteMatchService).currentMatchChain.setValue(newChain)
+            }
+
+            const vtConfig = resolveViewTransition(options.props.viewTransition, newChain)
+            await maybeViewTransition(vtConfig === false ? undefined : vtConfig, applyUpdate)
+
             for (let i = divergeIndex; i < newChain.length; i++) {
               await newChain[i].route.onVisit?.({ ...options, element: newResult.chainElements[i] })
               if (version !== versionRef.current) return
@@ -226,17 +305,21 @@ export const NestedRouter = Shade<NestedRouterProps>({
         } else if (lastChain !== null) {
           const version = ++versionRef.current
 
-          // No match found — call onLeave for all active routes and show notFound.
-          // The null sentinel prevents re-entering this block on re-render.
           for (let i = (lastChain?.length ?? 0) - 1; i >= 0; i--) {
             await lastChain[i].route.onLeave?.({ ...options, element: lastChainElements[i] })
             if (version !== versionRef.current) return
           }
-          setState({
-            matchChain: null,
-            jsx: options.props.notFound || <div />,
-            chainElements: [],
-          })
+
+          const applyNotFound = () => {
+            setState({
+              matchChain: null,
+              jsx: options.props.notFound || <div />,
+              chainElements: [],
+            })
+            injector.getInstance(RouteMatchService).currentMatchChain.setValue([])
+          }
+
+          await maybeViewTransition(options.props.viewTransition, applyNotFound)
         }
       } catch (e) {
         if (!(e instanceof ObservableAlreadyDisposedError)) {

package/src/index.ts

@@ -9,4 +9,5 @@ export * from './shade.js'
 export * from './style-manager.js'
 export * from './styled-element.js'
 export * from './styled-shade.js'
+export * from './view-transition.js'
 import './jsx.js'

package/src/services/index.ts

@@ -1,2 +1,4 @@
 export * from './location-service.js'
+export * from './route-match-service.js'
+export * from './route-meta-utils.js'
 export * from './screen-service.js'