@furystack/shades 12.3.0 → 12.4.0

package/src/components/lazy-load.tsx

@@ -1,9 +1,12 @@
 import { Shade } from '../shade.js'
+import type { ViewTransitionConfig } from '../view-transition.js'
+import { maybeViewTransition } from '../view-transition.js'
 
 export interface LazyLoadProps {
   loader: JSX.Element
   error?: (error: unknown, retry: () => Promise<void>) => JSX.Element
   component: () => Promise<JSX.Element>
+  viewTransition?: boolean | ViewTransitionConfig
 }
 
 export const LazyLoad = Shade<LazyLoadProps>({
@@ -36,8 +39,10 @@ export const LazyLoad = Shade<LazyLoadProps>({
       factory()
         .then((loaded) => {
           if (tracker.active && tracker.factory === factory) {
-            setError(undefined)
-            setComponent(loaded)
+            void maybeViewTransition(props.viewTransition, () => {
+              setError(undefined)
+              setComponent(loaded)
+            })
           }
         })
         .catch((err: unknown) => {
@@ -60,7 +65,9 @@ export const LazyLoad = Shade<LazyLoadProps>({
           setComponent(undefined)
           const loaded = await factory()
           if (tracker.active && tracker.factory === factory) {
-            setComponent(loaded)
+            void maybeViewTransition(props.viewTransition, () => {
+              setComponent(loaded)
+            })
           }
         } catch (e) {
           if (tracker.active && tracker.factory === factory) {

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

@@ -10,6 +10,7 @@ import {
   findDivergenceIndex,
   NestedRouter,
   renderMatchChain,
+  resolveViewTransition,
   type MatchChainEntry,
   type NestedRoute,
 } from './nested-router.js'
@@ -1024,3 +1025,251 @@ describe('NestedRouter + RouteMatchService integration', () => {
     })
   })
 })
+
+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

@@ -7,6 +7,8 @@ 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.
@@ -55,9 +57,21 @@ export type NestedRoute<TMatchResult = unknown> = {
     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
 }
 
 /**
@@ -67,6 +81,7 @@ export type NestedRoute<TMatchResult = unknown> = {
 export type NestedRouterProps = {
   routes: Record<string, NestedRoute<any>>
   notFound?: JSX.Element
+  viewTransition?: boolean | ViewTransitionConfig
 }
 
 /**
@@ -200,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
@@ -237,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
@@ -251,10 +288,15 @@ export const NestedRouter = Shade<NestedRouterProps>({
               setRenderMode(false)
             }
             if (version !== versionRef.current) return
-            setState({ matchChain: newChain, jsx: newResult.jsx, chainElements: newResult.chainElements })
-            injector.getInstance(RouteMatchService).currentMatchChain.setValue(newChain)
 
-            // 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
@@ -263,18 +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: [],
-          })
-          injector.getInstance(RouteMatchService).currentMatchChain.setValue([])
+
+          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/view-transition.spec.ts

@@ -0,0 +1,218 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { ViewTransitionConfig } from './view-transition.js'
+import { maybeViewTransition, transitionedValue } from './view-transition.js'
+
+describe('maybeViewTransition', () => {
+  afterEach(() => {
+    delete (document as unknown as Record<string, unknown>).startViewTransition
+  })
+
+  const mockStartViewTransition = () => {
+    const spy = 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 = spy as typeof document.startViewTransition
+    return spy
+  }
+
+  it('should call update directly when config is undefined', () => {
+    const spy = mockStartViewTransition()
+    const update = vi.fn()
+    const result = maybeViewTransition(undefined, update)
+    expect(update).toHaveBeenCalledTimes(1)
+    expect(spy).not.toHaveBeenCalled()
+    expect(result).toBeUndefined()
+  })
+
+  it('should call update directly when config is false', () => {
+    const spy = mockStartViewTransition()
+    const update = vi.fn()
+    const result = maybeViewTransition(false, update)
+    expect(update).toHaveBeenCalledTimes(1)
+    expect(spy).not.toHaveBeenCalled()
+    expect(result).toBeUndefined()
+  })
+
+  it('should call update directly when startViewTransition is not available', () => {
+    const update = vi.fn()
+    const result = maybeViewTransition(true, update)
+    expect(update).toHaveBeenCalledTimes(1)
+    expect(result).toBeUndefined()
+  })
+
+  it('should call startViewTransition when config is true and API is available', () => {
+    const spy = mockStartViewTransition()
+    const update = vi.fn()
+    const result = maybeViewTransition(true, update)
+    expect(spy).toHaveBeenCalledTimes(1)
+    expect(update).toHaveBeenCalledTimes(1)
+    expect(result).toBeInstanceOf(Promise)
+  })
+
+  it('should use callback form when config is true', () => {
+    const spy = mockStartViewTransition()
+    const update = vi.fn()
+    void maybeViewTransition(true, update)
+    expect(spy).toHaveBeenCalledWith(update)
+  })
+
+  it('should pass types when config is an object with types', () => {
+    const spy = mockStartViewTransition()
+    const update = vi.fn()
+    const config: ViewTransitionConfig = { types: ['slide', 'fade'] }
+    void maybeViewTransition(config, update)
+    expect(spy).toHaveBeenCalledWith({ update, types: ['slide', 'fade'] })
+  })
+
+  it('should use callback form when config object has empty types array', () => {
+    const spy = mockStartViewTransition()
+    const update = vi.fn()
+    const config: ViewTransitionConfig = { types: [] }
+    void maybeViewTransition(config, update)
+    expect(spy).toHaveBeenCalledWith(update)
+  })
+
+  it('should use callback form when config object has no types', () => {
+    const spy = mockStartViewTransition()
+    const update = vi.fn()
+    const config: ViewTransitionConfig = {}
+    void maybeViewTransition(config, update)
+    expect(spy).toHaveBeenCalledWith(update)
+  })
+
+  it('should return updateCallbackDone promise when transition is started', async () => {
+    mockStartViewTransition()
+    const update = vi.fn()
+    const result = maybeViewTransition(true, update)
+    expect(result).toBeInstanceOf(Promise)
+    await expect(result).resolves.toBeUndefined()
+  })
+})
+
+describe('transitionedValue', () => {
+  afterEach(() => {
+    delete (document as unknown as Record<string, unknown>).startViewTransition
+  })
+
+  const mockStartViewTransition = () => {
+    const spy = 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 = spy as typeof document.startViewTransition
+    return spy
+  }
+
+  const createMockUseState = () => {
+    const store = new Map<string, unknown>()
+    const setters = new Map<string, (v: unknown) => void>()
+    const mockUseState = <S>(key: string, initialValue: S): [S, (v: S) => void] => {
+      if (!store.has(key)) {
+        store.set(key, initialValue)
+      }
+      const setValue = (v: S) => {
+        store.set(key, v)
+      }
+      setters.set(key, setValue as (v: unknown) => void)
+      return [store.get(key) as S, setValue]
+    }
+    return { mockUseState, store }
+  }
+
+  it('should return the value when it equals the displayed value', () => {
+    const { mockUseState } = createMockUseState()
+    const result = transitionedValue(mockUseState, 'key', 'hello', true)
+    expect(result).toBe('hello')
+  })
+
+  it('should not call startViewTransition when value has not changed', () => {
+    const spy = mockStartViewTransition()
+    const { mockUseState } = createMockUseState()
+    transitionedValue(mockUseState, 'key', 'hello', true)
+    expect(spy).not.toHaveBeenCalled()
+  })
+
+  it('should call startViewTransition when value changes and config is truthy', () => {
+    const spy = mockStartViewTransition()
+    const { mockUseState, store } = createMockUseState()
+
+    transitionedValue(mockUseState, 'key', 'initial', true)
+    store.set('key', 'initial')
+
+    transitionedValue(mockUseState, 'key', 'updated', true)
+    expect(spy).toHaveBeenCalledTimes(1)
+    expect(store.get('key')).toBe('updated')
+  })
+
+  it('should not call startViewTransition when config is falsy', () => {
+    const spy = mockStartViewTransition()
+    const { mockUseState, store } = createMockUseState()
+
+    transitionedValue(mockUseState, 'key', 'initial', undefined)
+    store.set('key', 'initial')
+
+    transitionedValue(mockUseState, 'key', 'updated', undefined)
+    expect(spy).not.toHaveBeenCalled()
+    expect(store.get('key')).toBe('updated')
+  })
+
+  it('should not call startViewTransition when shouldTransition returns false', () => {
+    const spy = mockStartViewTransition()
+    const { mockUseState, store } = createMockUseState()
+
+    transitionedValue(mockUseState, 'key', 'initial', true, () => false)
+    store.set('key', 'initial')
+
+    transitionedValue(mockUseState, 'key', 'updated', true, () => false)
+    expect(spy).not.toHaveBeenCalled()
+    expect(store.get('key')).toBe('updated')
+  })
+
+  it('should call startViewTransition when shouldTransition returns true', () => {
+    const spy = mockStartViewTransition()
+    const { mockUseState, store } = createMockUseState()
+
+    transitionedValue(mockUseState, 'key', 'initial', true, () => true)
+    store.set('key', 'initial')
+
+    transitionedValue(mockUseState, 'key', 'updated', true, () => true)
+    expect(spy).toHaveBeenCalledTimes(1)
+    expect(store.get('key')).toBe('updated')
+  })
+
+  it('should pass prev and next values to shouldTransition', () => {
+    mockStartViewTransition()
+    const { mockUseState, store } = createMockUseState()
+    const shouldTransition = vi.fn(() => true)
+
+    transitionedValue(mockUseState, 'key', 'initial', true, shouldTransition)
+    store.set('key', 'initial')
+
+    transitionedValue(mockUseState, 'key', 'updated', true, shouldTransition)
+    expect(shouldTransition).toHaveBeenCalledWith('initial', 'updated')
+  })
+
+  it('should default shouldTransition to always true', () => {
+    const spy = mockStartViewTransition()
+    const { mockUseState, store } = createMockUseState()
+
+    transitionedValue(mockUseState, 'key', 'a', true)
+    store.set('key', 'a')
+
+    transitionedValue(mockUseState, 'key', 'b', true)
+    expect(spy).toHaveBeenCalledTimes(1)
+  })
+})