@furystack/shades 13.2.2 → 15.0.0

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

@@ -1,5 +1,6 @@
 import type { Injector } from '@furystack/inject'
 
+import type { ExtractRoutePaths } from '../components/nested-route-types.js'
 import type { MatchChainEntry, NestedRoute, NestedRouteMeta } from '../components/nested-router.js'
 
 /**
@@ -57,29 +58,57 @@ export const buildDocumentTitle = (
 
 /**
  * A node in a navigation tree extracted from route definitions.
+ *
+ * When {@link extractNavTree} is called with an explicit route tree type
+ * parameter (e.g. `extractNavTree<typeof appRoutes>(...)`), `pattern` narrows
+ * to the declared route keys and `fullPath` narrows to the union of all
+ * composed paths in the subtree. Without a type parameter the generic falls
+ * back to a widened shape so ad-hoc consumers keep compiling.
+ *
+ * @typeParam TRoutes - The route tree the node was extracted from
  */
-export type NavTreeNode = {
-  pattern: string
-  fullPath: string
+export type NavTreeNode<
+  TRoutes extends Record<string, NestedRoute<any, any, any>> = Record<string, NestedRoute<any, any, any>>,
+> = {
+  pattern: keyof TRoutes & string
+  fullPath: ExtractRoutePaths<TRoutes> & string
   meta?: NestedRouteMeta
-  children?: NavTreeNode[]
+  children?: Array<NavTreeNode<TRoutes>>
 }
 
 /**
  * Extracts a navigation tree from route definitions.
- * Useful for rendering sidebar navigation or sitemap-like structures.
+ *
+ * The returned nodes preserve the route tree's static typing: `pattern` is
+ * narrowed to the declared keys of `TRoutes` and `fullPath` is narrowed to
+ * the union of composed paths reachable from `TRoutes` (as produced by
+ * {@link ExtractRoutePaths}). This makes the output a single, typed source
+ * of truth for sidebar navigation, breadcrumbs and other route-tree-aware
+ * UIs — without requiring `as` casts at the call site.
+ *
+ * Child nodes share their parent's `TRoutes` type parameter; the resulting
+ * union is a safe upper bound of the actual paths at any depth, which keeps
+ * the helper simple while still accepted by `createNestedRouteLink`,
+ * `createNestedNavigate` and `createNestedReplace` factories bound to the
+ * same route tree.
+ *
  * @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,
-    }
-  })
+export const extractNavTree = <TRoutes extends Record<string, NestedRoute<any, any, any>>>(
+  routes: TRoutes,
+  parentPath?: string,
+): Array<NavTreeNode<TRoutes>> => {
+  const build = (rs: Record<string, NestedRoute<any, any, any>>, pp?: string): Array<NavTreeNode<TRoutes>> =>
+    Object.entries(rs).map(([pattern, route]) => {
+      const fullPath = pp ? `${pp === '/' ? '' : pp}${pattern}` : pattern
+      return {
+        pattern,
+        fullPath,
+        meta: route.meta,
+        children: route.children ? build(route.children, fullPath) : undefined,
+      } as NavTreeNode<TRoutes>
+    })
+  return build(routes, parentPath)
 }

package/src/services/screen-service.spec.ts

@@ -1,4 +1,4 @@
-import { Injector } from '@furystack/inject'
+import { createInjector } from '@furystack/inject'
 import { usingAsync } from '@furystack/utils'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { ScreenService, ScreenSizes } from './screen-service.js'
@@ -13,16 +13,17 @@ describe('ScreenService', () => {
   })
 
   it('Should be constructed', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const s = i.getInstance(ScreenService)
-      expect(s).toBeInstanceOf(ScreenService)
+    await usingAsync(createInjector(), async (i) => {
+      const s = i.get(ScreenService)
+      expect(s).toBeDefined()
+      expect(s.breakpoints).toBeDefined()
     })
   })
 
   describe('breakpoints', () => {
     it('Should have correct breakpoint definitions', async () => {
-      await usingAsync(new Injector(), async (i) => {
-        const s = i.getInstance(ScreenService)
+      await usingAsync(createInjector(), async (i) => {
+        const s = i.get(ScreenService)
 
         expect(s.breakpoints.xs.minSize).toBe(0)
         expect(s.breakpoints.sm.minSize).toBe(600)
@@ -35,8 +36,8 @@ describe('ScreenService', () => {
 
   describe('screenSize.atLeast', () => {
     it('Should have observable for each screen size', async () => {
-      await usingAsync(new Injector(), async (i) => {
-        const s = i.getInstance(ScreenService)
+      await usingAsync(createInjector(), async (i) => {
+        const s = i.get(ScreenService)
 
         for (const size of ScreenSizes) {
           expect(s.screenSize.atLeast[size]).toBeDefined()
@@ -46,16 +47,16 @@ describe('ScreenService', () => {
     })
 
     it('Should return true for xs on any screen size', async () => {
-      await usingAsync(new Injector(), async (i) => {
-        const s = i.getInstance(ScreenService)
+      await usingAsync(createInjector(), async (i) => {
+        const s = i.get(ScreenService)
         // xs has minSize 0, so it should always be true
         expect(s.screenSize.atLeast.xs.getValue()).toBe(true)
       })
     })
 
     it('Should update screenSize observables on window resize', async () => {
-      await usingAsync(new Injector(), async (i) => {
-        const s = i.getInstance(ScreenService)
+      await usingAsync(createInjector(), async (i) => {
+        const s = i.get(ScreenService)
 
         // Mock window.innerWidth to simulate a large screen
         vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(1920)
@@ -86,8 +87,8 @@ describe('ScreenService', () => {
 
   describe('orientation', () => {
     it('Should have an orientation observable', async () => {
-      await usingAsync(new Injector(), async (i) => {
-        const s = i.getInstance(ScreenService)
+      await usingAsync(createInjector(), async (i) => {
+        const s = i.get(ScreenService)
         const orientation = s.orientation.getValue()
         expect(['landscape', 'portrait']).toContain(orientation)
       })
@@ -98,10 +99,10 @@ describe('ScreenService', () => {
       const matchMediaMock = vi.fn()
       window.matchMedia = matchMediaMock
 
-      await usingAsync(new Injector(), async (i) => {
+      await usingAsync(createInjector(), async (i) => {
         // Set initial orientation to landscape
         matchMediaMock.mockReturnValue({ matches: true } as MediaQueryList)
-        const s = i.getInstance(ScreenService)
+        const s = i.get(ScreenService)
 
         // Verify initial landscape
         window.dispatchEvent(new Event('resize'))
@@ -119,8 +120,8 @@ describe('ScreenService', () => {
     it('Should remove resize event listener on dispose', async () => {
       const removeEventListenerSpy = vi.spyOn(window, 'removeEventListener')
 
-      await usingAsync(new Injector(), async (i) => {
-        i.getInstance(ScreenService)
+      await usingAsync(createInjector(), async (i) => {
+        i.get(ScreenService)
       })
 
       expect(removeEventListenerSpy).toHaveBeenCalledWith('resize', expect.any(Function))

package/src/services/screen-service.ts

@@ -1,4 +1,5 @@
-import { Injectable } from '@furystack/inject'
+import type { Token } from '@furystack/inject'
+import { defineService } from '@furystack/inject'
 import { ObservableValue } from '@furystack/utils'
 
 /**
@@ -19,134 +20,88 @@ export type Breakpoint = { name: ScreenSize; minSize: number; maxSize?: number }
 /**
  * Service for detecting and subscribing to screen size and orientation changes.
  *
- * This service provides reactive observables for responsive design decisions.
  * Use `screenSize.atLeast[size]` to check if the viewport is at least a certain size.
  *
  * **Breakpoint Thresholds:**
- * - `xs`: 0px+ (all sizes)
- * - `sm`: 600px+ (small tablets and up)
- * - `md`: 960px+ (tablets and up)
- * - `lg`: 1280px+ (desktops and up)
- * - `xl`: 1920px+ (large desktops)
+ * - `xs`: 0px+
+ * - `sm`: 600px+
+ * - `md`: 960px+
+ * - `lg`: 1280px+
+ * - `xl`: 1920px+
  *
  * @example
  * ```typescript
- * const screenService = injector.getInstance(ScreenService);
+ * const screenService = injector.get(ScreenService)
  *
- * // Check if screen is at least medium size
  * if (screenService.screenSize.atLeast.md.getValue()) {
- *   // Show desktop layout
+ *   // Desktop layout
  * }
  *
- * // Subscribe to size changes for responsive behavior
  * screenService.screenSize.atLeast.md.subscribe((isAtLeastMd) => {
- *   if (isAtLeastMd) {
- *     console.log('Desktop or tablet view');
- *   } else {
- *     console.log('Mobile view');
- *   }
- * });
- *
- * // Get current breakpoint by checking from largest to smallest
- * const getCurrentBreakpoint = (): ScreenSize => {
- *   if (screenService.screenSize.atLeast.xl.getValue()) return 'xl';
- *   if (screenService.screenSize.atLeast.lg.getValue()) return 'lg';
- *   if (screenService.screenSize.atLeast.md.getValue()) return 'md';
- *   if (screenService.screenSize.atLeast.sm.getValue()) return 'sm';
- *   return 'xs';
- * };
- *
- * // Subscribe to orientation changes
- * screenService.orientation.subscribe((orientation) => {
- *   console.log(`Screen is now in ${orientation} mode`);
- * });
+ *   // react to breakpoint changes
+ * })
  * ```
  */
-@Injectable({ lifetime: 'singleton' })
-export class ScreenService implements Disposable {
-  private getOrientation = () => (window.matchMedia?.('(orientation:landscape').matches ? 'landscape' : 'portrait')
-
-  /**
-   * The definitions of the breakpoint thresholds in pixels.
-   * Each breakpoint represents the minimum width for that size category.
-   */
-  public readonly breakpoints: { [K in ScreenSize]: { minSize: number } } = {
-    xl: { minSize: 1920 },
-    lg: { minSize: 1280 },
-    md: { minSize: 960 },
-    sm: { minSize: 600 },
-    xs: { minSize: 0 },
+export interface ScreenService {
+  readonly breakpoints: { [K in ScreenSize]: { minSize: number } }
+  readonly screenSize: {
+    atLeast: { [K in ScreenSize]: ObservableValue<boolean> }
   }
+  readonly orientation: ObservableValue<'landscape' | 'portrait'>
+}
 
-  /**
-   * Cleans up event listeners when the service is disposed.
-   */
-  public [Symbol.dispose]() {
-    window.removeEventListener('resize', this.onResizeListener)
-    this.orientation[Symbol.dispose]()
-    Object.values(this.screenSize.atLeast).forEach((observable) => {
-      observable[Symbol.dispose]()
-    })
-  }
+export const ScreenService: Token<ScreenService, 'singleton'> = defineService({
+  name: '@furystack/shades/ScreenService',
+  lifetime: 'singleton',
+  factory: ({ onDispose }) => {
+    const getOrientation = (): 'landscape' | 'portrait' =>
+      window.matchMedia?.('(orientation:landscape').matches ? 'landscape' : 'portrait'
 
-  /**
-   * Observable values for checking if the screen is at least a certain size.
-   *
-   * Each observable emits `true` when the viewport width is >= the breakpoint threshold,
-   * and `false` otherwise. Values update automatically on window resize.
-   *
-   * @example
-   * ```typescript
-   * // Hide sidebar on small screens
-   * screenService.screenSize.atLeast.md.subscribe((isAtLeastMd) => {
-   *   sidebarVisible.setValue(isAtLeastMd);
-   * });
-   * ```
-   */
-  public readonly screenSize: {
-    atLeast: { [K in ScreenSize]: ObservableValue<boolean> }
-  } = {
-    atLeast: {
-      xs: new ObservableValue<boolean>(this.screenSizeAtLeast('xs')),
-      sm: new ObservableValue<boolean>(this.screenSizeAtLeast('sm')),
-      md: new ObservableValue<boolean>(this.screenSizeAtLeast('md')),
-      lg: new ObservableValue<boolean>(this.screenSizeAtLeast('lg')),
-      xl: new ObservableValue<boolean>(this.screenSizeAtLeast('xl')),
-    },
-  }
+    const breakpoints: { [K in ScreenSize]: { minSize: number } } = {
+      xl: { minSize: 1920 },
+      lg: { minSize: 1280 },
+      md: { minSize: 960 },
+      sm: { minSize: 600 },
+      xs: { minSize: 0 },
+    }
 
-  private screenSizeAtLeast(size: ScreenSize) {
-    return window.innerWidth >= this.breakpoints[size].minSize
-  }
+    const screenSizeAtLeast = (size: ScreenSize): boolean => window.innerWidth >= breakpoints[size].minSize
 
-  /**
-   * Observable value for tracking the screen orientation.
-   * Emits 'landscape' or 'portrait' based on the current viewport dimensions.
-   *
-   * @example
-   * ```typescript
-   * screenService.orientation.subscribe((orientation) => {
-   *   if (orientation === 'landscape') {
-   *     // Adjust layout for landscape mode
-   *   }
-   * });
-   * ```
-   */
-  public orientation = new ObservableValue<'landscape' | 'portrait'>(this.getOrientation())
+    const atLeast: { [K in ScreenSize]: ObservableValue<boolean> } = {
+      xs: new ObservableValue<boolean>(screenSizeAtLeast('xs')),
+      sm: new ObservableValue<boolean>(screenSizeAtLeast('sm')),
+      md: new ObservableValue<boolean>(screenSizeAtLeast('md')),
+      lg: new ObservableValue<boolean>(screenSizeAtLeast('lg')),
+      xl: new ObservableValue<boolean>(screenSizeAtLeast('xl')),
+    }
 
-  private onResizeListener = () => {
-    this.refreshValues()
-  }
+    const orientation = new ObservableValue<'landscape' | 'portrait'>(getOrientation())
+
+    const refreshValues = (): void => {
+      orientation.setValue(getOrientation())
+      for (const size of ScreenSizes) {
+        atLeast[size].setValue(screenSizeAtLeast(size))
+      }
+    }
+
+    const onResizeListener = (): void => {
+      refreshValues()
+    }
 
-  private refreshValues() {
-    this.orientation.setValue(this.getOrientation())
-    ScreenSizes.forEach((size) => {
-      this.screenSize.atLeast[size].setValue(this.screenSizeAtLeast(size))
+    window.addEventListener('resize', onResizeListener)
+    refreshValues()
+
+    onDispose(() => {
+      window.removeEventListener('resize', onResizeListener)
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- Disposal is deferred to the injector's onDispose hook.
+      orientation[Symbol.dispose]()
+      Object.values(atLeast).forEach((observable) => observable[Symbol.dispose]())
     })
-  }
 
-  constructor() {
-    window.addEventListener('resize', this.onResizeListener)
-    this.refreshValues()
-  }
-}
+    return {
+      breakpoints,
+      screenSize: { atLeast },
+      orientation,
+    }
+  },
+})