@furystack/shades 13.2.2 → 15.0.0

package/src/components/nested-hooks.spec.ts

@@ -0,0 +1,254 @@
+import { createInjector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { LocationService } from '../services/location-service.js'
+import { createNestedHooks, walkRoute } from './nested-hooks.js'
+import type { NestedRoute } from './nested-router.js'
+
+const makeComponent = () => null as unknown as JSX.Element
+
+describe('walkRoute', () => {
+  it('Should return the route when the pattern matches the path exactly', () => {
+    const leaf = { component: () => makeComponent() }
+    const routes = { '/users': leaf } satisfies Record<string, NestedRoute<any, any, any>>
+    expect(walkRoute(routes, '/users')).toBe(leaf)
+  })
+
+  it('Should return undefined when no pattern matches', () => {
+    const routes = { '/users': { component: () => makeComponent() } } satisfies Record<
+      string,
+      NestedRoute<any, any, any>
+    >
+    expect(walkRoute(routes, '/nonexistent')).toBeUndefined()
+  })
+
+  it('Should descend through a `/` root pattern transparently', () => {
+    const leaf = { component: () => makeComponent() }
+    const routes = {
+      '/': {
+        component: () => makeComponent(),
+        children: {
+          '/home': leaf,
+        },
+      },
+    } satisfies Record<string, NestedRoute<any, any, any>>
+
+    expect(walkRoute(routes, '/home')).toBe(leaf)
+  })
+
+  it('Should resolve a deeply nested path by walking children', () => {
+    const leaf = { component: () => makeComponent() }
+    const routes = {
+      '/navigation': {
+        component: () => makeComponent(),
+        children: {
+          '/tabs': leaf,
+        },
+      },
+    } satisfies Record<string, NestedRoute<any, any, any>>
+
+    expect(walkRoute(routes, '/navigation/tabs')).toBe(leaf)
+  })
+
+  it('Should resolve through two levels of `/` roots', () => {
+    const leaf = { component: () => makeComponent() }
+    const routes = {
+      '/': {
+        component: () => makeComponent(),
+        children: {
+          '/navigation': {
+            component: () => makeComponent(),
+            children: {
+              '/tabs': leaf,
+            },
+          },
+        },
+      },
+    } satisfies Record<string, NestedRoute<any, any, any>>
+
+    expect(walkRoute(routes, '/navigation/tabs')).toBe(leaf)
+  })
+
+  it('Should match a parent prefix when the path is exactly the parent pattern', () => {
+    const parent = {
+      component: () => makeComponent(),
+      children: {
+        '/child': { component: () => makeComponent() },
+      },
+    }
+    const routes = { '/parent': parent } satisfies Record<string, NestedRoute<any, any, any>>
+
+    expect(walkRoute(routes, '/parent')).toBe(parent)
+  })
+
+  it('Should not confuse a prefix pattern that is not followed by a `/`', () => {
+    const routes = {
+      '/users': {
+        component: () => makeComponent(),
+        children: {
+          '/:id': { component: () => makeComponent() },
+        },
+      },
+    } satisfies Record<string, NestedRoute<any, any, any>>
+
+    expect(walkRoute(routes, '/usersextra')).toBeUndefined()
+  })
+})
+
+describe('createNestedHooks', () => {
+  describe('getTypedQuery', () => {
+    it('Should return null when the route has no declared query validator', async () => {
+      const routes = {
+        '/bare': { component: () => makeComponent() },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const { getTypedQuery } = createNestedHooks(routes)
+
+      await usingAsync(createInjector(), async (injector) => {
+        expect(getTypedQuery(injector, '/bare')).toBeNull()
+      })
+    })
+
+    it('Should return the validated query when the current search matches', async () => {
+      const routes = {
+        '/list': {
+          component: () => makeComponent(),
+          query: (raw): { page: number } | null => (typeof raw.page === 'number' ? { page: raw.page } : null),
+        },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const { getTypedQuery } = createNestedHooks(routes)
+
+      await usingAsync(createInjector(), async (injector) => {
+        const locationService = injector.get(LocationService)
+        locationService.onDeserializedLocationSearchChanged.setValue({ page: 3 })
+        expect(getTypedQuery(injector, '/list')).toEqual({ page: 3 })
+      })
+    })
+
+    it('Should return null when the validator rejects the current search', async () => {
+      const routes = {
+        '/list': {
+          component: () => makeComponent(),
+          query: (raw): { page: number } | null => (typeof raw.page === 'number' ? { page: raw.page } : null),
+        },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const { getTypedQuery } = createNestedHooks(routes)
+
+      await usingAsync(createInjector(), async (injector) => {
+        const locationService = injector.get(LocationService)
+        locationService.onDeserializedLocationSearchChanged.setValue({ page: 'not-a-number' })
+        expect(getTypedQuery(injector, '/list')).toBeNull()
+      })
+    })
+  })
+
+  describe('getTypedHash', () => {
+    it('Should return undefined when the route has no declared hash tuple', async () => {
+      const routes = {
+        '/bare': { component: () => makeComponent() },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const { getTypedHash } = createNestedHooks(routes)
+
+      await usingAsync(createInjector(), async (injector) => {
+        expect(getTypedHash(injector, '/bare')).toBeUndefined()
+      })
+    })
+
+    it('Should return the current hash when it matches a declared literal', async () => {
+      const routes = {
+        '/tabs': {
+          component: () => makeComponent(),
+          hash: ['overview', 'details'] as const,
+        },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const { getTypedHash } = createNestedHooks(routes)
+
+      await usingAsync(createInjector(), async (injector) => {
+        const locationService = injector.get(LocationService)
+        locationService.onLocationHashChanged.setValue('details')
+        expect(getTypedHash(injector, '/tabs')).toBe('details')
+      })
+    })
+
+    it('Should return undefined when the current hash is not in the declared tuple', async () => {
+      const routes = {
+        '/tabs': {
+          component: () => makeComponent(),
+          hash: ['overview', 'details'] as const,
+        },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const { getTypedHash } = createNestedHooks(routes)
+
+      await usingAsync(createInjector(), async (injector) => {
+        const locationService = injector.get(LocationService)
+        locationService.onLocationHashChanged.setValue('something-else')
+        expect(getTypedHash(injector, '/tabs')).toBeUndefined()
+      })
+    })
+
+    it('Should resolve hashes through nested routes', async () => {
+      const routes = {
+        '/navigation': {
+          component: () => makeComponent(),
+          children: {
+            '/tabs': {
+              component: () => makeComponent(),
+              hash: ['ctrl-1', 'ctrl-2'] as const,
+            },
+          },
+        },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const { getTypedHash } = createNestedHooks(routes)
+
+      await usingAsync(createInjector(), async (injector) => {
+        const locationService = injector.get(LocationService)
+        locationService.onLocationHashChanged.setValue('ctrl-1')
+        expect(getTypedHash(injector, '/navigation/tabs')).toBe('ctrl-1')
+      })
+    })
+  })
+
+  describe('Type utilities', () => {
+    it('Should narrow getTypedHash against the declared literal tuple', () => {
+      const routes = {
+        '/tabs': {
+          component: () => makeComponent(),
+          hash: ['overview', 'details'] as const,
+        },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const { getTypedHash } = createNestedHooks(routes)
+      expectTypeOf(getTypedHash<'/tabs'>).returns.toEqualTypeOf<'overview' | 'details' | undefined>()
+    })
+
+    it('Should narrow getTypedQuery against the declared validator return type', () => {
+      const routes = {
+        '/list': {
+          component: () => makeComponent(),
+          query: (raw): { page: number } | null => (typeof raw.page === 'number' ? { page: raw.page } : null),
+        },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const { getTypedQuery } = createNestedHooks(routes)
+      expectTypeOf(getTypedQuery<'/list'>).returns.toEqualTypeOf<{ page: number } | null>()
+    })
+
+    it('Should reject paths not present in the route tree', () => {
+      const routes = {
+        '/tabs': {
+          component: () => makeComponent(),
+        },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const { getTypedHash } = createNestedHooks(routes)
+      // @ts-expect-error -- '/nonexistent' is not a valid route path
+      getTypedHash(createInjector(), '/nonexistent')
+    })
+  })
+})

package/src/components/nested-hooks.ts

@@ -0,0 +1,109 @@
+import type { Injector } from '@furystack/inject'
+import { LocationService } from '../services/location-service.js'
+import type { ExtractRouteHash, ExtractRouteQuery, ExtractRoutePaths, RouteAt } from './nested-route-types.js'
+import type { NestedRoute } from './nested-router.js'
+
+/**
+ * A pair of synchronous read helpers bound to a specific route tree. Use the
+ * factory {@link createNestedHooks} to produce one.
+ */
+export type NestedHooks<TRoutes extends Record<string, NestedRoute<any, any, any>>> = {
+  /**
+   * Reads and validates the current URL query string against the declared
+   * validator of the route at `path`. Returns the typed query value, or
+   * `null` when the route has no validator or the current URL's query does
+   * not satisfy it.
+   *
+   * This is a synchronous snapshot — for reactive use, subscribe to
+   * `locationService.onDeserializedLocationSearchChanged` and call this read
+   * on each change.
+   */
+  getTypedQuery: <TPath extends ExtractRoutePaths<TRoutes>>(
+    injector: Injector,
+    path: TPath,
+  ) => ExtractRouteQuery<RouteAt<TRoutes, TPath>> | null
+  /**
+   * Reads the current URL hash and narrows it against the declared literal
+   * tuple of the route at `path`. Returns the hash when it matches one of
+   * the route's declared literals, or `undefined` otherwise.
+   *
+   * This is a synchronous snapshot — for reactive use, subscribe to
+   * `locationService.onLocationHashChanged` and call this read on each change.
+   */
+  getTypedHash: <TPath extends ExtractRoutePaths<TRoutes>>(
+    injector: Injector,
+    path: TPath,
+  ) => ExtractRouteHash<RouteAt<TRoutes, TPath>> | undefined
+}
+
+/**
+ * Walks a route tree and returns the route value declared at the given path,
+ * matching each URL pattern segment-by-segment. The root `/` pattern is
+ * transparent: its children are searched with the full path.
+ *
+ * Exported for unit testing only — consumers should go through
+ * {@link createNestedHooks}.
+ *
+ * @internal
+ */
+export const walkRoute = (
+  routes: Record<string, NestedRoute<any, any, any>>,
+  path: string,
+): NestedRoute<any, any, any> | undefined => {
+  for (const [pattern, route] of Object.entries(routes)) {
+    if (pattern === path) return route
+    if (pattern === '/' && route.children) {
+      const nested = walkRoute(route.children, path)
+      if (nested) return nested
+    } else if (route.children && path.startsWith(pattern)) {
+      const rest = path.slice(pattern.length)
+      if (rest.startsWith('/') || rest === '') {
+        const nested = walkRoute(route.children, rest || '/')
+        if (nested) return nested
+      }
+    }
+  }
+  return undefined
+}
+
+/**
+ * Creates a pair of type-safe synchronous read helpers (`getTypedQuery`,
+ * `getTypedHash`) bound to a specific route tree. The returned functions
+ * validate the current URL's query and hash against the route declared at
+ * the given path, returning typed values or `null`/`undefined` on mismatch.
+ *
+ * The concrete route tree is captured at factory time, so call sites only
+ * pass `(injector, path)`; the type-level narrowing is derived from the
+ * inferred tree generic.
+ *
+ * @typeParam TRoutes - The route tree type (inferred from the `routes` argument)
+ *
+ * @example
+ * ```typescript
+ * const { getTypedQuery, getTypedHash } = createNestedHooks(appRoutes)
+ *
+ * const query = getTypedQuery(injector, '/users') // typed
+ * const hash = getTypedHash(injector, '/users')   // typed
+ * ```
+ */
+export const createNestedHooks = <TRoutes extends Record<string, NestedRoute<any, any, any>>>(
+  routes: TRoutes,
+): NestedHooks<TRoutes> => {
+  return {
+    getTypedQuery: (injector, path) => {
+      const route = walkRoute(routes, path)
+      if (!route?.query) return null
+      const locationService = injector.get(LocationService)
+      const deserialized = locationService.onDeserializedLocationSearchChanged.getValue()
+      return route.query(deserialized) as never
+    },
+    getTypedHash: (injector, path) => {
+      const route = walkRoute(routes, path)
+      const declaredHash = route?.hash as readonly string[] | undefined
+      if (!declaredHash) return undefined
+      const locationService = injector.get(LocationService)
+      const currentHash = locationService.onLocationHashChanged.getValue()
+      return declaredHash.includes(currentHash) ? (currentHash as never) : undefined
+    },
+  }
+}

package/src/components/nested-navigate.spec.ts

@@ -1,65 +1,141 @@
-import { Injector } from '@furystack/inject'
+import type { Injector } from '@furystack/inject'
+import { createInjector } from '@furystack/inject'
 import { usingAsync } from '@furystack/utils'
 import { describe, expect, expectTypeOf, it, vi } from 'vitest'
 import { LocationService } from '../services/location-service.js'
-import type { TypedNavigateArgs } from './nested-navigate.js'
-import { createNestedNavigate, nestedNavigate } from './nested-navigate.js'
+import type { TypedNestedNavigateArgs } from './nested-navigate.js'
+import { buildNestedNavigateUrl, createNestedNavigate, nestedNavigate } from './nested-navigate.js'
 import type { NestedRoute } from './nested-router.js'
 
-type TestRoute = Pick<NestedRoute<unknown>, 'component'>
+type TestRoute = Pick<NestedRoute<unknown, any, any>, 'component'>
 
 describe('nestedNavigate', () => {
   it('Should navigate to a simple path', async () => {
-    await usingAsync(new Injector(), async (injector) => {
-      const locationService = injector.getInstance(LocationService)
+    await usingAsync(createInjector(), async (injector) => {
+      const locationService = injector.get(LocationService)
       const spy = vi.spyOn(locationService, 'navigate')
 
-      nestedNavigate(injector, '/buttons')
+      nestedNavigate(injector, { path: '/buttons' })
 
       expect(spy).toHaveBeenCalledWith('/buttons')
     })
   })
 
   it('Should compile params into the path', async () => {
-    await usingAsync(new Injector(), async (injector) => {
-      const locationService = injector.getInstance(LocationService)
+    await usingAsync(createInjector(), async (injector) => {
+      const locationService = injector.get(LocationService)
       const spy = vi.spyOn(locationService, 'navigate')
 
-      nestedNavigate(injector, '/users/:id', { id: '42' })
+      nestedNavigate(injector, { path: '/users/:id', params: { id: '42' } })
 
       expect(spy).toHaveBeenCalledWith('/users/42')
     })
   })
 
   it('Should compile multiple params into the path', async () => {
-    await usingAsync(new Injector(), async (injector) => {
-      const locationService = injector.getInstance(LocationService)
+    await usingAsync(createInjector(), async (injector) => {
+      const locationService = injector.get(LocationService)
       const spy = vi.spyOn(locationService, 'navigate')
 
-      nestedNavigate(injector, '/users/:userId/posts/:postId', { userId: '1', postId: '99' })
+      nestedNavigate(injector, {
+        path: '/users/:userId/posts/:postId',
+        params: { userId: '1', postId: '99' },
+      })
 
       expect(spy).toHaveBeenCalledWith('/users/1/posts/99')
     })
   })
+
+  it('Should append serialized query string when provided', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const locationService = injector.get(LocationService)
+      const spy = vi.spyOn(locationService, 'navigate')
+
+      nestedNavigate(injector, { path: '/buttons', query: { page: 2 } })
+
+      expect(spy).toHaveBeenCalledTimes(1)
+      const navigatedUrl = spy.mock.calls[0][0]
+      expect(navigatedUrl.startsWith('/buttons?')).toBe(true)
+      const { deserializeQueryString } = locationService
+      const search = navigatedUrl.slice(navigatedUrl.indexOf('?') + 1)
+      expect(deserializeQueryString(search)).toEqual({ page: 2 })
+    })
+  })
+
+  it('Should omit the query string when no keys are provided', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const locationService = injector.get(LocationService)
+      const spy = vi.spyOn(locationService, 'navigate')
+
+      nestedNavigate(injector, { path: '/buttons', query: {} })
+
+      expect(spy).toHaveBeenCalledWith('/buttons')
+    })
+  })
+
+  it('Should append the hash segment when provided', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const locationService = injector.get(LocationService)
+      const spy = vi.spyOn(locationService, 'navigate')
+
+      nestedNavigate(injector, { path: '/buttons', hash: 'overview' })
+
+      expect(spy).toHaveBeenCalledWith('/buttons#overview')
+    })
+  })
+
+  it('Should combine params, query and hash in the correct order', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const locationService = injector.get(LocationService)
+      const spy = vi.spyOn(locationService, 'navigate')
+
+      nestedNavigate(injector, {
+        path: '/users/:id',
+        params: { id: '7' },
+        query: { tab: 'profile' },
+        hash: 'notes',
+      })
+
+      expect(spy).toHaveBeenCalledTimes(1)
+      const navigatedUrl = spy.mock.calls[0][0]
+      expect(navigatedUrl.startsWith('/users/7?')).toBe(true)
+      expect(navigatedUrl.endsWith('#notes')).toBe(true)
+    })
+  })
+})
+
+describe('buildNestedNavigateUrl', () => {
+  it('Should build a bare path URL', () => {
+    expect(buildNestedNavigateUrl({ path: '/buttons' })).toBe('/buttons')
+  })
+
+  it('Should build a URL with compiled params', () => {
+    expect(buildNestedNavigateUrl({ path: '/users/:id', params: { id: '42' } })).toBe('/users/42')
+  })
+
+  it('Should append a hash segment', () => {
+    expect(buildNestedNavigateUrl({ path: '/buttons', hash: 'top' })).toBe('/buttons#top')
+  })
 })
 
 describe('Type utilities', () => {
-  describe('TypedNavigateArgs', () => {
+  describe('TypedNestedNavigateArgs', () => {
     it('Should make params optional for paths without parameters', () => {
-      type Args = TypedNavigateArgs<'/buttons'>
-      expectTypeOf<Args>().toEqualTypeOf<[path: '/buttons', params?: Record<string, string>]>()
+      type Routes = { '/buttons': TestRoute }
+      expectTypeOf<TypedNestedNavigateArgs<Routes, '/buttons'>>().toExtend<{ path: '/buttons' }>()
+      expectTypeOf<TypedNestedNavigateArgs<Routes, '/buttons'>>().toExtend<{ params?: Record<string, string> }>()
     })
 
     it('Should require params for parameterized paths', () => {
-      type Args = TypedNavigateArgs<'/users/:id'>
-      expectTypeOf<Args>().toEqualTypeOf<[path: '/users/:id', params: { id: string }]>()
+      type Routes = { '/users/:id': TestRoute }
+      expectTypeOf<TypedNestedNavigateArgs<Routes, '/users/:id'>>().toExtend<{ params: { id: string } }>()
     })
 
     it('Should require all params for multi-param paths', () => {
-      type Args = TypedNavigateArgs<'/users/:userId/posts/:postId'>
-      expectTypeOf<Args>().toEqualTypeOf<
-        [path: '/users/:userId/posts/:postId', params: { userId: string; postId: string }]
-      >()
+      type Routes = { '/users/:userId/posts/:postId': TestRoute }
+      expectTypeOf<TypedNestedNavigateArgs<Routes, '/users/:userId/posts/:postId'>>().toExtend<{
+        params: { userId: string; postId: string }
+      }>()
     })
   })
 
@@ -90,9 +166,9 @@ describe('Type utilities', () => {
       }
 
       const appNavigate = createNestedNavigate<Routes>()
-      expectTypeOf(appNavigate<'/users/:userId'>).parameters.toEqualTypeOf<
-        [injector: Injector, path: '/users/:userId', params: { userId: string }]
-      >()
+      expectTypeOf(appNavigate<'/users/:userId'>)
+        .parameter(1)
+        .toExtend<{ params: { userId: string } }>()
     })
 
     it('Should make params optional for non-parameterized routes', () => {
@@ -105,9 +181,9 @@ describe('Type utilities', () => {
       }
 
       const appNavigate = createNestedNavigate<Routes>()
-      expectTypeOf(appNavigate<'/buttons'>).parameters.toEqualTypeOf<
-        [injector: Injector, path: '/buttons', params?: Record<string, string>]
-      >()
+      expectTypeOf(appNavigate<'/buttons'>)
+        .parameter(1)
+        .toExtend<{ params?: Record<string, string> }>()
     })
 
     it('Should reject invalid paths', () => {
@@ -122,7 +198,7 @@ describe('Type utilities', () => {
 
       const appNavigate = createNestedNavigate<Routes>()
       // @ts-expect-error -- '/nonexistent' is not a valid route path
-      appNavigate(new Injector(), '/nonexistent')
+      appNavigate(createInjector(), { path: '/nonexistent' })
     })
 
     it('Should accept routes with typed match parameters (NestedRoute<T>)', () => {
@@ -135,9 +211,37 @@ describe('Type utilities', () => {
       }
 
       const appNavigate = createNestedNavigate<typeof routes>()
-      expectTypeOf(appNavigate<'/stacks/:stackName'>).parameters.toEqualTypeOf<
-        [injector: Injector, path: '/stacks/:stackName', params: { stackName: string }]
-      >()
+      expectTypeOf(appNavigate<'/stacks/:stackName'>)
+        .parameter(1)
+        .toExtend<{ params: { stackName: string } }>()
+    })
+
+    it('Should enforce a route-declared required query shape', () => {
+      const routes = {
+        '/list': {
+          component: () => null as unknown as JSX.Element,
+          query: (raw): { page: number } | null => (typeof raw.page === 'number' ? { page: raw.page } : null),
+        },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const appNavigate = createNestedNavigate<typeof routes>()
+      expectTypeOf(appNavigate<'/list'>)
+        .parameter(1)
+        .toExtend<{ query: { page: number } }>()
+    })
+
+    it('Should narrow hash to the declared literal tuple', () => {
+      const routes = {
+        '/tabs': {
+          component: () => null as unknown as JSX.Element,
+          hash: ['overview', 'details'] as const,
+        },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const appNavigate = createNestedNavigate<typeof routes>()
+      expectTypeOf(appNavigate<'/tabs'>)
+        .parameter(1)
+        .toExtend<{ hash?: 'overview' | 'details' }>()
     })
   })
 })