@furystack/shades 12.3.0 → 12.5.0

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/components/route-link.tsx

@@ -19,6 +19,7 @@ export const RouteLink = Shade<RouteLinkProps>({
     useHostProps({
       onclick: (ev: MouseEvent) => {
         ev.preventDefault()
+        // eslint-disable-next-line furystack/prefer-location-service -- Deprecated framework component; must call pushState directly.
         history.pushState('', props.title || '', props.href)
         injector.getInstance(LocationService).updateState()
       },

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/location-service.tsx

@@ -39,10 +39,11 @@ export class LocationService implements Disposable {
   public [Symbol.dispose]() {
     window.removeEventListener('popstate', this.popStateListener)
     window.removeEventListener('hashchange', this.hashChangeListener)
-    this.onLocationPathChanged[Symbol.dispose]()
     this.onLocationSearchChanged[Symbol.dispose]()
     this.onDeserializedLocationSearchChanged[Symbol.dispose]()
     this.locationDeserializerObserver[Symbol.dispose]()
+    this.onLocationPathChanged[Symbol.dispose]()
+    this.onLocationHashChanged[Symbol.dispose]()
 
     window.history.pushState = this.originalPushState
     window.history.replaceState = this.originalReplaceState
@@ -69,6 +70,10 @@ export class LocationService implements Disposable {
     this.onDeserializedLocationSearchChanged.setValue(this.deserializeQueryString(search))
   })
 
+  /**
+   * Synchronizes the observable state with the current browser location.
+   * Called internally after navigation events and history state changes.
+   */
   public updateState = (() => {
     this.onLocationPathChanged.setValue(location.pathname)
     this.onLocationHashChanged.setValue(location.hash.replace('#', ''))
@@ -80,10 +85,25 @@ export class LocationService implements Disposable {
    * The LocationService interceptor ensures routing state is updated correctly.
    */
   public navigate(path: string): void {
+    // eslint-disable-next-line furystack/prefer-location-service -- This IS the LocationService.navigate() implementation.
     history.pushState(null, '', path)
     this.updateState()
   }
 
+  /**
+   * Replace the current history entry with a new path. Use this instead of
+   * raw history.replaceState for SPA redirects (e.g. the intermediate URL
+   * should not appear in the browser's back/forward stack).
+   */
+  public replace(path: string): void {
+    // eslint-disable-next-line furystack/prefer-location-service -- This IS the LocationService.replace() implementation.
+    history.replaceState(null, '', path)
+    this.updateState()
+  }
+
+  /**
+   * Internal cache of per-key search parameter observables created by {@link useSearchParam}.
+   */
   public readonly searchParamObservables = new Map<string, ObservableValue<any>>()
 
   /**
@@ -110,6 +130,7 @@ export class LocationService implements Disposable {
         if (currentQueryStringObject[key] !== value) {
           const params = this.serializeToQueryString({ ...currentQueryStringObject, [key]: value })
           const newUrl = `${location.pathname}?${params}`
+          // eslint-disable-next-line furystack/prefer-location-service -- Internal LocationService plumbing for search param sync.
           history.pushState({}, '', newUrl)
         }
       })

package/src/services/screen-service.ts

@@ -83,6 +83,10 @@ export class ScreenService implements Disposable {
    */
   public [Symbol.dispose]() {
     window.removeEventListener('resize', this.onResizeListener)
+    this.orientation[Symbol.dispose]()
+    Object.values(this.screenSize.atLeast).forEach((observable) => {
+      observable[Symbol.dispose]()
+    })
   }
 
   /**

package/src/shade-resources.integration.spec.tsx

@@ -162,6 +162,7 @@ describe('Shade Resources integration tests', () => {
           renderCounter()
           return (
             <div ref={valRef} id="manual-val">
+              {/* eslint-disable-next-line furystack/no-direct-get-value-in-render -- Test: verifying manual DOM update pattern with onChange callback */}
               {obs.getValue()}
             </div>
           )

package/src/shade.spec.tsx

@@ -183,6 +183,7 @@ describe('Shade edge cases', () => {
               },
             }))
             renderCounter()
+            // eslint-disable-next-line furystack/no-direct-get-value-in-render -- Test: verifying no re-render during disposal; already subscribed via useObservable above
             return <div>{obs.getValue()}</div>
           },
         })