@furystack/shades 11.1.0 → 12.0.0

package/src/components/nested-router.tsx

@@ -0,0 +1,256 @@
+import { ObservableAlreadyDisposedError } from '@furystack/utils'
+import type { MatchOptions, MatchResult } from 'path-to-regexp'
+import { match } from 'path-to-regexp'
+import { Lock } from 'semaphore-async-await'
+import type { RenderOptions } from '../models/render-options.js'
+import { LocationService } from '../services/location-service.js'
+import { createComponent, setRenderMode } from '../shade-component.js'
+import { Shade } from '../shade.js'
+
+/**
+ * A single route entry in a NestedRouter configuration.
+ * Unlike flat `Route`, the URL is the Record key (not a field), and the
+ * `component` receives an `outlet` for rendering matched child content.
+ * @typeParam TMatchResult - The type of matched URL parameters
+ */
+export type NestedRoute<TMatchResult = unknown> = {
+  component: (options: {
+    currentUrl: string
+    match: MatchResult<TMatchResult extends object ? TMatchResult : object>
+    outlet?: JSX.Element
+  }) => JSX.Element
+  routingOptions?: MatchOptions
+  onVisit?: (options: RenderOptions<unknown> & { element: JSX.Element }) => Promise<void>
+  onLeave?: (options: RenderOptions<unknown> & { element: JSX.Element }) => Promise<void>
+  children?: Record<string, NestedRoute<any>>
+}
+
+/**
+ * Props for the NestedRouter component.
+ * Routes are defined as a Record where keys are URL patterns.
+ */
+export type NestedRouterProps = {
+  routes: Record<string, NestedRoute<any>>
+  notFound?: JSX.Element
+}
+
+/**
+ * A single entry in a match chain, pairing a matched route with its match result.
+ */
+export type MatchChainEntry = {
+  route: NestedRoute<unknown>
+  match: MatchResult<object>
+}
+
+/**
+ * Internal state for the NestedRouter component.
+ * `matchChain` is `null` when a notFound fallback has been rendered,
+ * distinguishing it from the initial empty array (not yet processed).
+ */
+export type NestedRouterState = {
+  matchChain: MatchChainEntry[] | null
+  jsx: JSX.Element
+  chainElements: JSX.Element[]
+}
+
+/**
+ * Recursively builds a match chain from outermost to innermost matched route.
+ *
+ * For routes with children, a prefix match (`end: false`) is attempted first.
+ * If a child matches the remaining URL, the parent and child chain are combined.
+ * If no child matches, an exact match on the parent alone is attempted.
+ *
+ * For leaf routes (no children), only exact matching is used.
+ *
+ * @param routes - The route definitions to match against
+ * @param currentUrl - The URL path to match
+ * @returns An array of matched chain entries from outermost to innermost, or null if no match
+ */
+export const buildMatchChain = (
+  routes: Record<string, NestedRoute<any>>,
+  currentUrl: string,
+): MatchChainEntry[] | null => {
+  for (const [pattern, route] of Object.entries(routes)) {
+    if (route.children) {
+      const prefixMatchFn = match(pattern, { ...route.routingOptions, end: false })
+      let prefixResult = prefixMatchFn(currentUrl)
+
+      // In path-to-regexp v8, match('/', { end: false }) only matches exact '/'.
+      // For the root pattern, any URL is logically under '/', so force a prefix match.
+      if (!prefixResult && pattern === '/') {
+        prefixResult = { path: '/', params: {} }
+      }
+
+      if (prefixResult) {
+        let remainingUrl = currentUrl.slice(prefixResult.path.length)
+        if (!remainingUrl.startsWith('/')) {
+          remainingUrl = `/${remainingUrl}`
+        }
+
+        const childChain = buildMatchChain(route.children, remainingUrl)
+        if (childChain) {
+          return [{ route, match: prefixResult }, ...childChain]
+        }
+      }
+
+      const exactMatchFn = match(pattern, route.routingOptions)
+      const exactResult = exactMatchFn(currentUrl)
+      if (exactResult) {
+        return [{ route, match: exactResult }]
+      }
+    } else {
+      const matchFn = match(pattern, route.routingOptions)
+      const matchResult = matchFn(currentUrl)
+      if (matchResult) {
+        return [{ route, match: matchResult }]
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Finds the first index where two match chains diverge.
+ * Returns the length of the shorter chain if one is a prefix of the other.
+ */
+export const findDivergenceIndex = (oldChain: MatchChainEntry[], newChain: MatchChainEntry[]): number => {
+  const minLength = Math.min(oldChain.length, newChain.length)
+  for (let i = 0; i < minLength; i++) {
+    if (
+      oldChain[i].route !== newChain[i].route ||
+      JSON.stringify(oldChain[i].match.params) !== JSON.stringify(newChain[i].match.params)
+    ) {
+      return i
+    }
+  }
+  return minLength
+}
+
+/**
+ * The result of rendering a match chain, containing both the fully composed
+ * JSX tree and per-entry elements for scoped lifecycle animations.
+ */
+export type RenderMatchChainResult = {
+  jsx: JSX.Element
+  chainElements: JSX.Element[]
+}
+
+/**
+ * Renders a match chain inside-out: starts with the innermost (leaf) route
+ * rendered with `outlet: undefined`, then passes its JSX as `outlet` to
+ * each successive parent up the chain.
+ *
+ * Returns per-entry elements so that lifecycle hooks (`onLeave`/`onVisit`)
+ * receive only the element for their own route level, not the full tree.
+ *
+ * @param chain - The match chain from outermost to innermost
+ * @param currentUrl - The current URL path
+ * @returns The fully composed JSX element and per-entry rendered elements
+ */
+export const renderMatchChain = (chain: MatchChainEntry[], currentUrl: string): RenderMatchChainResult => {
+  let outlet: JSX.Element | undefined
+  const chainElements: JSX.Element[] = new Array<JSX.Element>(chain.length)
+
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const entry = chain[i]
+    outlet = entry.route.component({
+      currentUrl,
+      match: entry.match,
+      outlet,
+    })
+    chainElements[i] = outlet
+  }
+
+  return { jsx: outlet as JSX.Element, chainElements }
+}
+
+/**
+ * A nested router component that supports hierarchical route definitions
+ * with parent/child relationships. Parent routes receive an `outlet` prop
+ * containing the rendered child route, enabling layout composition.
+ *
+ * Routes are defined as a Record where keys are URL patterns (following the
+ * RestApi pattern). The matching algorithm builds a chain from outermost to
+ * innermost route, then renders inside-out so each parent wraps its child.
+ */
+export const NestedRouter = Shade<NestedRouterProps>({
+  shadowDomName: 'shade-nested-router',
+  render: (options) => {
+    const { useState, useObservable, injector } = options
+    const [lock] = useState('lock', new Lock())
+    const [state, setState] = useState<NestedRouterState>('routerState', {
+      matchChain: [],
+      jsx: <div />,
+      chainElements: [],
+    })
+
+    const updateUrl = async (currentUrl: string) => {
+      const [lastState] = useState<NestedRouterState>('routerState', state)
+      const { matchChain: lastChain, chainElements: lastChainElements } = lastState
+      try {
+        await lock.acquire()
+        const newChain = buildMatchChain(options.props.routes, currentUrl)
+
+        if (newChain) {
+          const lastChainEntries = lastChain ?? []
+          const divergeIndex = findDivergenceIndex(lastChainEntries, newChain)
+          const hasChanged =
+            divergeIndex < lastChainEntries.length ||
+            divergeIndex < newChain.length ||
+            lastChainEntries.length !== newChain.length
+
+          if (hasChanged) {
+            // 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] })
+            }
+
+            let newResult: RenderMatchChainResult
+            setRenderMode(true)
+            try {
+              newResult = renderMatchChain(newChain, currentUrl)
+            } finally {
+              setRenderMode(false)
+            }
+            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)
+            for (let i = divergeIndex; i < newChain.length; i++) {
+              await newChain[i].route.onVisit?.({ ...options, element: newResult.chainElements[i] })
+            }
+          }
+        } else if (lastChain !== null) {
+          // 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] })
+          }
+          setState({
+            matchChain: null,
+            jsx: options.props.notFound || <div />,
+            chainElements: [],
+          })
+        }
+      } catch (e) {
+        if (!(e instanceof ObservableAlreadyDisposedError)) {
+          throw e
+        }
+      } finally {
+        lock?.release()
+      }
+    }
+
+    const [locationPath] = useObservable(
+      'locationPathChanged',
+      injector.getInstance(LocationService).onLocationPathChanged,
+      {
+        onChange: (newValue) => {
+          void updateUrl(newValue)
+        },
+      },
+    )
+    void updateUrl(locationPath)
+    return state.jsx
+  },
+})

package/src/components/route-link.spec.tsx

@@ -1,8 +1,10 @@
 import { Injector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { initializeShadeRoot } from '../initialize.js'
 import { LocationService } from '../services/location-service.js'
 import { createComponent } from '../shade-component.js'
+import { flushUpdates } from '../shade.js'
 import { RouteLink } from './route-link.js'
 
 describe('RouteLink', () => {
@@ -14,27 +16,29 @@ describe('RouteLink', () => {
   })
 
   it('Shuld display the loader and completed state', async () => {
-    const injector = new Injector()
-    const rootElement = document.getElementById('root') as HTMLDivElement
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
 
-    const onRouteChange = vi.fn()
+      const onRouteChange = vi.fn()
 
-    injector.getInstance(LocationService).onLocationPathChanged.subscribe(onRouteChange)
+      injector.getInstance(LocationService).onLocationPathChanged.subscribe(onRouteChange)
 
-    initializeShadeRoot({
-      injector,
-      rootElement,
-      jsxElement: (
-        <RouteLink id="route" href="/subroute">
-          Link
-        </RouteLink>
-      ),
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <RouteLink id="route" href="/subroute">
+            Link
+          </RouteLink>
+        ),
+      })
+      await flushUpdates()
+      expect(document.body.innerHTML).toMatchInlineSnapshot(
+        `"<div id="root"><a is="route-link" id="route" href="/subroute">Link</a></div>"`,
+      )
+      expect(onRouteChange).not.toBeCalled()
+      document.getElementById('route')?.click()
+      expect(onRouteChange).toBeCalledTimes(1)
     })
-    expect(document.body.innerHTML).toMatchInlineSnapshot(
-      `"<div id="root"><a is="route-link" id="route" href="/subroute">Link</a></div>"`,
-    )
-    expect(onRouteChange).not.toBeCalled()
-    document.getElementById('route')?.click()
-    expect(onRouteChange).toBeCalledTimes(1)
   })
 })

package/src/components/route-link.tsx

@@ -1,10 +1,12 @@
-import { Shade } from '../shade.js'
 import type { PartialElement } from '../models/partial-element.js'
 import { LocationService } from '../services/location-service.js'
-import { attachProps, createComponent } from '../shade-component.js'
+import { createComponent } from '../shade-component.js'
+import { Shade } from '../shade.js'
 
+/** @deprecated Use `NestedRouteLinkProps` from `nested-route-link` instead */
 export type RouteLinkProps = PartialElement<Omit<HTMLAnchorElement, 'onclick'>>
 
+/** @deprecated Use `NestedRouteLink` from `nested-route-link` instead */
 export const RouteLink = Shade<RouteLinkProps>({
   shadowDomName: 'route-link',
   elementBase: HTMLAnchorElement,
@@ -13,9 +15,8 @@ export const RouteLink = Shade<RouteLinkProps>({
     color: 'inherit',
     textDecoration: 'inherit',
   },
-  render: ({ children, props, injector, element }) => {
-    attachProps(element, {
-      ...props,
+  render: ({ children, props, injector, useHostProps }) => {
+    useHostProps({
       onclick: (ev: MouseEvent) => {
         ev.preventDefault()
         history.pushState('', props.title || '', props.href)

package/src/components/router.spec.tsx

@@ -1,5 +1,5 @@
 import { Injector } from '@furystack/inject'
-import { sleepAsync } from '@furystack/utils'
+import { sleepAsync, usingAsync } from '@furystack/utils'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { initializeShadeRoot } from '../initialize.js'
 import { LocationService } from '../services/location-service.js'
@@ -16,113 +16,114 @@ describe('Router', () => {
   })
 
   it('Shuld display the loader and completed state', async () => {
-    history.pushState(null, '', '/')
-
-    const onVisit = vi.fn()
-    const onLeave = vi.fn()
-    const onLastLeave = vi.fn()
-
-    const injector = new Injector()
-    const rootElement = document.getElementById('root') as HTMLDivElement
-
-    const onRouteChange = vi.fn()
-
-    injector.getInstance(LocationService).onLocationPathChanged.subscribe(onRouteChange)
-
-    const route1: Route = {
-      url: '/route-a',
-      component: () => <div id="content">route-a</div>,
-      onVisit,
-      onLeave,
-    }
-
-    const route2: Route<{ id: string }> = {
-      url: '/route-b{/:id}',
-      component: ({ match }) => <div id="content">route-b{match.params.id}</div>,
-    }
-
-    const route3: Route = {
-      url: '/route-c',
-      component: () => <div id="content">route-c</div>,
-      onLeave: onLastLeave,
-    }
-
-    const route4 = { url: '/', component: () => <div id="content">home</div> }
-
-    initializeShadeRoot({
-      injector,
-      rootElement,
-      jsxElement: (
-        <div>
-          <RouteLink id="home" href="/">
-            home
-          </RouteLink>
-          <RouteLink id="a" href="/route-a">
-            a
-          </RouteLink>
-          <RouteLink id="b" href="/route-b">
-            b
-          </RouteLink>
-          <RouteLink id="b-with-id" href="/route-b/123">
-            b-with-id
-          </RouteLink>
-          <RouteLink id="c" href="/route-c">
-            c
-          </RouteLink>
-          <RouteLink id="x" href="/route-x">
-            x
-          </RouteLink>
-          <Router routes={[route1, route2, route3, route4]} notFound={<div id="content">not found</div>} />
-        </div>
-      ),
+    await usingAsync(new Injector(), async (injector) => {
+      history.pushState(null, '', '/')
+
+      const onVisit = vi.fn()
+      const onLeave = vi.fn()
+      const onLastLeave = vi.fn()
+
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      const onRouteChange = vi.fn()
+
+      injector.getInstance(LocationService).onLocationPathChanged.subscribe(onRouteChange)
+
+      const route1: Route = {
+        url: '/route-a',
+        component: () => <div id="content">route-a</div>,
+        onVisit,
+        onLeave,
+      }
+
+      const route2: Route<{ id: string }> = {
+        url: '/route-b{/:id}',
+        component: ({ match }) => <div id="content">route-b{match.params.id}</div>,
+      }
+
+      const route3: Route = {
+        url: '/route-c',
+        component: () => <div id="content">route-c</div>,
+        onLeave: onLastLeave,
+      }
+
+      const route4 = { url: '/', component: () => <div id="content">home</div> }
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <div>
+            <RouteLink id="home" href="/">
+              home
+            </RouteLink>
+            <RouteLink id="a" href="/route-a">
+              a
+            </RouteLink>
+            <RouteLink id="b" href="/route-b">
+              b
+            </RouteLink>
+            <RouteLink id="b-with-id" href="/route-b/123">
+              b-with-id
+            </RouteLink>
+            <RouteLink id="c" href="/route-c">
+              c
+            </RouteLink>
+            <RouteLink id="x" href="/route-x">
+              x
+            </RouteLink>
+            <Router routes={[route1, route2, route3, route4]} notFound={<div id="content">not found</div>} />
+          </div>
+        ),
+      })
+
+      const getContent = () => document.getElementById('content')?.innerHTML
+      const getLocation = () => location.pathname
+
+      const clickOn = (name: string) => document.getElementById(name)?.click()
+
+      await sleepAsync(100)
+
+      expect(getLocation()).toBe('/')
+      expect(getContent()).toBe('home')
+
+      expect(onVisit).not.toBeCalled()
+
+      clickOn('a')
+      await sleepAsync(100)
+      expect(getContent()).toBe('route-a')
+      expect(getLocation()).toBe('/route-a')
+      expect(onRouteChange).toBeCalledTimes(1)
+      expect(onVisit).toBeCalledTimes(1)
+
+      clickOn('a')
+      await sleepAsync(100)
+      expect(onVisit).toBeCalledTimes(1)
+      expect(onLeave).not.toBeCalled()
+
+      clickOn('b')
+      await sleepAsync(100)
+      expect(onLeave).toBeCalledTimes(1)
+
+      expect(getContent()).toBe('route-b')
+      expect(getLocation()).toBe('/route-b')
+
+      clickOn('b-with-id')
+      await sleepAsync(100)
+      expect(getContent()).toBe('route-b123')
+      expect(getLocation()).toBe('/route-b/123')
+
+      clickOn('c')
+      await sleepAsync(100)
+      expect(getContent()).toBe('route-c')
+      expect(getLocation()).toBe('/route-c')
+
+      expect(onLastLeave).not.toBeCalled()
+      clickOn('x')
+      await sleepAsync(100)
+      expect(getContent()).toBe('not found')
+      expect(getLocation()).toBe('/route-x')
+      expect(onLastLeave).toBeCalledTimes(1)
     })
-
-    const getContent = () => document.getElementById('content')?.innerHTML
-    const getLocation = () => location.pathname
-
-    const clickOn = (name: string) => document.getElementById(name)?.click()
-
-    await sleepAsync(100)
-
-    expect(getLocation()).toBe('/')
-    expect(getContent()).toBe('home')
-
-    expect(onVisit).not.toBeCalled()
-
-    clickOn('a')
-    await sleepAsync(100)
-    expect(getContent()).toBe('route-a')
-    expect(getLocation()).toBe('/route-a')
-    expect(onRouteChange).toBeCalledTimes(1)
-    expect(onVisit).toBeCalledTimes(1)
-
-    clickOn('a')
-    await sleepAsync(100)
-    expect(onVisit).toBeCalledTimes(1)
-    expect(onLeave).not.toBeCalled()
-
-    clickOn('b')
-    await sleepAsync(100)
-    expect(onLeave).toBeCalledTimes(1)
-
-    expect(getContent()).toBe('route-b')
-    expect(getLocation()).toBe('/route-b')
-
-    clickOn('b-with-id')
-    await sleepAsync(100)
-    expect(getContent()).toBe('route-b123')
-    expect(getLocation()).toBe('/route-b/123')
-
-    clickOn('c')
-    await sleepAsync(100)
-    expect(getContent()).toBe('route-c')
-    expect(getLocation()).toBe('/route-c')
-
-    expect(onLastLeave).not.toBeCalled()
-    clickOn('x')
-    await sleepAsync(100)
-    expect(getContent()).toBe('not found')
-    expect(getLocation()).toBe('/route-x')
-    expect(onLastLeave).toBeCalledTimes(1)
   })
 })

package/src/components/router.tsx

@@ -7,6 +7,9 @@ import { LocationService } from '../services/location-service.js'
 import { createComponent } from '../shade-component.js'
 import { Shade } from '../shade.js'
 
+/**
+ * @deprecated Use NestedRouter instead
+ */
 export interface Route<TMatchResult = unknown> {
   url: string
   component: (options: {
@@ -14,21 +17,31 @@ export interface Route<TMatchResult = unknown> {
     match: MatchResult<TMatchResult extends object ? TMatchResult : object>
   }) => JSX.Element
   routingOptions?: MatchOptions
-  onVisit?: (options: RenderOptions<unknown>) => Promise<void>
-  onLeave?: (options: RenderOptions<unknown>) => Promise<void>
+  onVisit?: (options: RenderOptions<unknown> & { element: JSX.Element }) => Promise<void>
+  onLeave?: (options: RenderOptions<unknown> & { element: JSX.Element }) => Promise<void>
 }
 
+/**
+ * @deprecated Use NestedRouterProps instead
+ */
 export interface RouterProps {
   style?: CSSStyleDeclaration
   routes: Array<Route<any>>
   notFound?: JSX.Element
 }
 
+/**
+ * @deprecated Use NestedRouterState instead
+ */
 export interface RouterState {
   activeRoute?: Route<unknown> | null
   activeRouteParams?: unknown
   jsx: JSX.Element
 }
+
+/**
+ * @deprecated Use NestedRouter instead
+ */
 export const Router = Shade<RouterProps>({
   shadowDomName: 'shade-router',
   render: (options) => {

package/src/initialize.ts

@@ -1,10 +1,22 @@
 import type { Injector } from '@furystack/inject'
 
+/**
+ * Options for bootstrapping a Shades application.
+ */
 export interface InitializeOptions {
+  /** The DOM element that will host the application */
   rootElement: HTMLElement
+  /** The root JSX element to render */
   jsxElement: JSX.Element
+  /** The root injector instance for dependency injection */
   injector: Injector
 }
+
+/**
+ * Bootstraps a Shades application by attaching the root JSX element to a DOM node
+ * and wiring up the dependency injection context.
+ * @param options The initialization options
+ */
 export const initializeShadeRoot = (options: InitializeOptions) => {
   options.jsxElement.injector = options.injector
   options.rootElement.appendChild(options.jsxElement)