@furystack/shades 12.2.5 → 12.3.0

package/src/services/route-meta-utils.spec.ts

@@ -0,0 +1,243 @@
+import { Injector } from '@furystack/inject'
+import { describe, expect, it } from 'vitest'
+import type { MatchChainEntry, NestedRoute } from '../components/nested-router.js'
+import { buildDocumentTitle, extractNavTree, resolveRouteTitle, resolveRouteTitles } from './route-meta-utils.js'
+
+describe('resolveRouteTitle', () => {
+  const injector = new Injector()
+
+  it('should return undefined when no meta is configured', async () => {
+    const entry: MatchChainEntry = {
+      route: { component: () => ({}) as JSX.Element },
+      match: { path: '/about', params: {} },
+    }
+    expect(await resolveRouteTitle(entry, injector)).toBeUndefined()
+  })
+
+  it('should return undefined when meta has no title', async () => {
+    const entry: MatchChainEntry = {
+      route: { meta: {}, component: () => ({}) as JSX.Element },
+      match: { path: '/about', params: {} },
+    }
+    expect(await resolveRouteTitle(entry, injector)).toBeUndefined()
+  })
+
+  it('should return a static string title', async () => {
+    const entry: MatchChainEntry = {
+      route: { meta: { title: 'About' }, component: () => ({}) as JSX.Element },
+      match: { path: '/about', params: {} },
+    }
+    expect(await resolveRouteTitle(entry, injector)).toBe('About')
+  })
+
+  it('should resolve a synchronous function title', async () => {
+    const entry: MatchChainEntry = {
+      route: {
+        meta: { title: ({ match }) => `User ${(match.params as { id: string }).id}` },
+        component: () => ({}) as JSX.Element,
+      },
+      match: { path: '/users/42', params: { id: '42' } },
+    }
+    expect(await resolveRouteTitle(entry, injector)).toBe('User 42')
+  })
+
+  it('should resolve an async function title', async () => {
+    const entry: MatchChainEntry = {
+      route: {
+        meta: {
+          title: async ({ match }) => {
+            const { id } = match.params as { id: string }
+            return `Movie ${id}`
+          },
+        },
+        component: () => ({}) as JSX.Element,
+      },
+      match: { path: '/movies/7', params: { id: '7' } },
+    }
+    expect(await resolveRouteTitle(entry, injector)).toBe('Movie 7')
+  })
+
+  it('should pass the injector to the title resolver', async () => {
+    const entry: MatchChainEntry = {
+      route: {
+        meta: {
+          title: ({ injector: inj }) => (inj instanceof Injector ? 'has-injector' : 'no-injector'),
+        },
+        component: () => ({}) as JSX.Element,
+      },
+      match: { path: '/test', params: {} },
+    }
+    expect(await resolveRouteTitle(entry, injector)).toBe('has-injector')
+  })
+})
+
+describe('resolveRouteTitles', () => {
+  const injector = new Injector()
+
+  it('should resolve all titles in a mixed chain', async () => {
+    const chain: MatchChainEntry[] = [
+      {
+        route: { meta: { title: 'Media' }, component: () => ({}) as JSX.Element },
+        match: { path: '/media', params: {} },
+      },
+      {
+        route: { meta: { title: 'Movies' }, component: () => ({}) as JSX.Element },
+        match: { path: '/movies', params: {} },
+      },
+      {
+        route: {
+          meta: { title: async ({ match }) => `Movie ${(match.params as { id: string }).id}` },
+          component: () => ({}) as JSX.Element,
+        },
+        match: { path: '/7', params: { id: '7' } },
+      },
+    ]
+    const titles = await resolveRouteTitles(chain, injector)
+    expect(titles).toEqual(['Media', 'Movies', 'Movie 7'])
+  })
+
+  it('should return an empty array for an empty chain', async () => {
+    const titles = await resolveRouteTitles([], injector)
+    expect(titles).toEqual([])
+  })
+
+  it('should include undefined for entries without titles', async () => {
+    const chain: MatchChainEntry[] = [
+      {
+        route: { meta: { title: 'Root' }, component: () => ({}) as JSX.Element },
+        match: { path: '/', params: {} },
+      },
+      {
+        route: { component: () => ({}) as JSX.Element },
+        match: { path: '/child', params: {} },
+      },
+    ]
+    const titles = await resolveRouteTitles(chain, injector)
+    expect(titles).toEqual(['Root', undefined])
+  })
+})
+
+describe('buildDocumentTitle', () => {
+  it('should join titles with default separator', () => {
+    expect(buildDocumentTitle(['Media', 'Movies'])).toBe('Media - Movies')
+  })
+
+  it('should filter out undefined entries', () => {
+    expect(buildDocumentTitle(['Media', undefined, 'Movies'])).toBe('Media - Movies')
+  })
+
+  it('should use a custom separator', () => {
+    expect(buildDocumentTitle(['Media', 'Movies', 'Superman'], { separator: ' / ' })).toBe('Media / Movies / Superman')
+  })
+
+  it('should prepend a prefix', () => {
+    expect(buildDocumentTitle(['Media', 'Movies'], { prefix: 'My App' })).toBe('My App - Media - Movies')
+  })
+
+  it('should combine prefix and custom separator', () => {
+    expect(buildDocumentTitle(['Media', 'Movies', 'Superman'], { prefix: 'My App', separator: ' / ' })).toBe(
+      'My App / Media / Movies / Superman',
+    )
+  })
+
+  it('should return empty string for empty titles', () => {
+    expect(buildDocumentTitle([])).toBe('')
+  })
+
+  it('should return only prefix when all titles are undefined', () => {
+    expect(buildDocumentTitle([undefined, undefined], { prefix: 'My App' })).toBe('My App')
+  })
+
+  it('should return prefix alone when titles is empty', () => {
+    expect(buildDocumentTitle([], { prefix: 'My App' })).toBe('My App')
+  })
+})
+
+describe('extractNavTree', () => {
+  it('should extract a flat route tree', () => {
+    const routes: Record<string, NestedRoute<unknown>> = {
+      '/about': { meta: { title: 'About' }, component: () => ({}) as JSX.Element },
+      '/contact': { meta: { title: 'Contact' }, component: () => ({}) as JSX.Element },
+    }
+    const tree = extractNavTree(routes)
+    expect(tree).toEqual([
+      { pattern: '/about', fullPath: '/about', meta: { title: 'About' }, children: undefined },
+      { pattern: '/contact', fullPath: '/contact', meta: { title: 'Contact' }, children: undefined },
+    ])
+  })
+
+  it('should extract nested routes recursively', () => {
+    const routes: Record<string, NestedRoute<unknown>> = {
+      '/media': {
+        meta: { title: 'Media' },
+        component: () => ({}) as JSX.Element,
+        children: {
+          '/movies': { meta: { title: 'Movies' }, component: () => ({}) as JSX.Element },
+          '/music': { meta: { title: 'Music' }, component: () => ({}) as JSX.Element },
+        },
+      },
+    }
+    const tree = extractNavTree(routes)
+    expect(tree).toHaveLength(1)
+    expect(tree[0].pattern).toBe('/media')
+    expect(tree[0].fullPath).toBe('/media')
+    expect(tree[0].children).toHaveLength(2)
+    expect(tree[0].children![0]).toEqual({
+      pattern: '/movies',
+      fullPath: '/media/movies',
+      meta: { title: 'Movies' },
+      children: undefined,
+    })
+    expect(tree[0].children![1]).toEqual({
+      pattern: '/music',
+      fullPath: '/media/music',
+      meta: { title: 'Music' },
+      children: undefined,
+    })
+  })
+
+  it('should handle root "/" parent path correctly', () => {
+    const routes: Record<string, NestedRoute<unknown>> = {
+      '/': {
+        meta: { title: 'Home' },
+        component: () => ({}) as JSX.Element,
+        children: {
+          '/settings': { meta: { title: 'Settings' }, component: () => ({}) as JSX.Element },
+        },
+      },
+    }
+    const tree = extractNavTree(routes)
+    expect(tree[0].fullPath).toBe('/')
+    expect(tree[0].children![0].fullPath).toBe('/settings')
+  })
+
+  it('should compute correct fullPath for deeply nested routes (3+ levels)', () => {
+    const routes: Record<string, NestedRoute<unknown>> = {
+      '/a': {
+        meta: { title: 'A' },
+        component: () => ({}) as JSX.Element,
+        children: {
+          '/b': {
+            meta: { title: 'B' },
+            component: () => ({}) as JSX.Element,
+            children: {
+              '/c': { meta: { title: 'C' }, component: () => ({}) as JSX.Element },
+            },
+          },
+        },
+      },
+    }
+    const tree = extractNavTree(routes)
+    expect(tree[0].fullPath).toBe('/a')
+    expect(tree[0].children![0].fullPath).toBe('/a/b')
+    expect(tree[0].children![0].children![0].fullPath).toBe('/a/b/c')
+  })
+
+  it('should include routes without meta', () => {
+    const routes: Record<string, NestedRoute<unknown>> = {
+      '/hidden': { component: () => ({}) as JSX.Element },
+    }
+    const tree = extractNavTree(routes)
+    expect(tree[0].meta).toBeUndefined()
+  })
+})

package/src/services/route-meta-utils.ts

@@ -0,0 +1,85 @@
+import type { Injector } from '@furystack/inject'
+
+import type { MatchChainEntry, NestedRoute, NestedRouteMeta } from '../components/nested-router.js'
+
+/**
+ * Resolves the title for a single match chain entry.
+ * If the title is a function, it is called with `{ match, injector }` (supports async).
+ * @param entry - A matched route entry from the match chain
+ * @param injector - The injector instance to pass to dynamic title resolvers
+ * @returns The resolved title string, or undefined if no title is configured
+ */
+export const resolveRouteTitle = async (entry: MatchChainEntry, injector: Injector): Promise<string | undefined> => {
+  const title = entry.route.meta?.title
+  if (typeof title === 'function') return await title({ match: entry.match, injector })
+  return title
+}
+
+/**
+ * Resolves all titles from a match chain in parallel.
+ * @param chain - The match chain from outermost to innermost route
+ * @param injector - The injector instance to pass to dynamic title resolvers
+ * @returns An array of resolved titles (some may be undefined if no title is configured)
+ */
+export const resolveRouteTitles = async (
+  chain: MatchChainEntry[],
+  injector: Injector,
+): Promise<Array<string | undefined>> => {
+  return Promise.all(chain.map((entry) => resolveRouteTitle(entry, injector)))
+}
+
+/**
+ * Composes resolved titles into a single document title string.
+ * Filters out undefined entries before joining.
+ * @param titles - Array of resolved titles (may contain undefined)
+ * @param options - Formatting options
+ * @param options.separator - String placed between title segments (default: `' - '`)
+ * @param options.prefix - Optional app name prepended before all segments
+ * @returns The composed title string
+ *
+ * @example
+ * ```typescript
+ * buildDocumentTitle(['Media', 'Movies', 'Superman'], { prefix: 'My App', separator: ' / ' })
+ * // => 'My App / Media / Movies / Superman'
+ *
+ * buildDocumentTitle(['Settings', undefined, 'Profile'])
+ * // => 'Settings - Profile'
+ * ```
+ */
+export const buildDocumentTitle = (
+  titles: Array<string | undefined>,
+  options?: { separator?: string; prefix?: string },
+): string => {
+  const { separator = ' - ', prefix } = options ?? {}
+  const parts = titles.filter((t): t is string => t != null)
+  return prefix ? [prefix, ...parts].join(separator) : parts.join(separator)
+}
+
+/**
+ * A node in a navigation tree extracted from route definitions.
+ */
+export type NavTreeNode = {
+  pattern: string
+  fullPath: string
+  meta?: NestedRouteMeta
+  children?: NavTreeNode[]
+}
+
+/**
+ * Extracts a navigation tree from route definitions.
+ * Useful for rendering sidebar navigation or sitemap-like structures.
+ * @param routes - The route definitions to extract from
+ * @param parentPath - The parent path prefix (used internally for recursion)
+ * @returns An array of navigation tree nodes
+ */
+export const extractNavTree = (routes: Record<string, NestedRoute<unknown>>, parentPath?: string): NavTreeNode[] => {
+  return Object.entries(routes).map(([pattern, route]) => {
+    const fullPath = parentPath ? `${parentPath === '/' ? '' : parentPath}${pattern}` : pattern
+    return {
+      pattern,
+      fullPath,
+      meta: route.meta,
+      children: route.children ? extractNavTree(route.children, fullPath) : undefined,
+    }
+  })
+}

package/src/shade.spec.tsx

@@ -1,6 +1,6 @@
 import { Injector } from '@furystack/inject'
-import { sleepAsync, usingAsync } from '@furystack/utils'
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { ObservableValue, 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, Shade } from './shade.js'
@@ -98,6 +98,116 @@ describe('Shade edge cases', () => {
     })
   })
 
+  describe('disconnected component should not re-render', () => {
+    it('should not re-render when updateComponent is called after removal', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const renderCounter = vi.fn()
+
+        const ExampleComponent = Shade({
+          shadowDomName: 'shade-no-render-after-disconnect',
+          render: () => {
+            renderCounter()
+            return <div>content</div>
+          },
+        })
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <ExampleComponent />,
+        })
+        await flushUpdates()
+
+        const element = document.querySelector('shade-no-render-after-disconnect') as JSX.Element
+        expect(element.getRenderCount()).toBe(1)
+        expect(renderCounter).toBeCalledTimes(1)
+
+        element.remove()
+        await flushUpdates()
+
+        element.updateComponent()
+        await flushUpdates()
+
+        expect(element.getRenderCount()).toBe(1)
+        expect(renderCounter).toBeCalledTimes(1)
+      })
+    })
+
+    it('should not re-render when updateComponentSync is called after removal', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const renderCounter = vi.fn()
+
+        const ExampleComponent = Shade({
+          shadowDomName: 'shade-no-sync-render-after-disconnect',
+          render: () => {
+            renderCounter()
+            return <div>content</div>
+          },
+        })
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <ExampleComponent />,
+        })
+        await flushUpdates()
+
+        const element = document.querySelector('shade-no-sync-render-after-disconnect') as JSX.Element
+        expect(element.getRenderCount()).toBe(1)
+        expect(renderCounter).toBeCalledTimes(1)
+
+        element.remove()
+        await flushUpdates()
+        ;(element as unknown as { updateComponentSync: () => void }).updateComponentSync()
+
+        expect(element.getRenderCount()).toBe(1)
+        expect(renderCounter).toBeCalledTimes(1)
+      })
+    })
+
+    it('should not re-render when an observable fires during disposal', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const renderCounter = vi.fn()
+        const obs = new ObservableValue(0)
+
+        const ExampleComponent = Shade({
+          shadowDomName: 'shade-no-render-during-disposal',
+          render: ({ useObservable, useDisposable }) => {
+            useObservable('obs', obs)
+            useDisposable('cleanup', () => ({
+              [Symbol.dispose]: () => {
+                obs.setValue(999)
+              },
+            }))
+            renderCounter()
+            return <div>{obs.getValue()}</div>
+          },
+        })
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <ExampleComponent />,
+        })
+        await flushUpdates()
+
+        const element = document.querySelector('shade-no-render-during-disposal') as JSX.Element
+        expect(element.getRenderCount()).toBe(1)
+        expect(renderCounter).toBeCalledTimes(1)
+
+        element.remove()
+        await flushUpdates()
+        await sleepAsync(10)
+
+        expect(element.getRenderCount()).toBe(1)
+        expect(renderCounter).toBeCalledTimes(1)
+      })
+    })
+  })
+
   describe('BroadcastChannel cross-tab communication', () => {
     it('should update stored state when receiving BroadcastChannel message with matching key', async () => {
       const mockedStorage = new Map<string, string>()

package/src/shade.ts

@@ -110,11 +110,19 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
          */
         private _refs = new Map<string, RefObject<Element>>()
 
+        /**
+         * Set to true once disconnectedCallback fires. Prevents ghost re-renders
+         * triggered by observable changes during async disposal.
+         */
+        private _disconnected = false
+
         public connectedCallback() {
+          this._disconnected = false
           this._performUpdate()
         }
 
         public async disconnectedCallback() {
+          this._disconnected = true
           this._refs.clear()
           this._prevVTree = null
           this._prevHostProps = null
@@ -246,10 +254,11 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
          * runs are coalesced into a single render pass.
          */
         public updateComponent() {
+          if (this._disconnected) return
           if (!this._updateScheduled) {
             this._updateScheduled = true
             queueMicrotask(() => {
-              if (!this._updateScheduled) return
+              if (!this._updateScheduled || this._disconnected) return
               this._updateScheduled = false
               this._performUpdate()
             })
@@ -262,6 +271,7 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
          * in a single call frame rather than cascading across microtask ticks.
          */
         public updateComponentSync() {
+          if (this._disconnected) return
           this._updateScheduled = false
           this._performUpdate()
         }