@furystack/shades 13.2.2 → 14.0.0

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

@@ -2,11 +2,11 @@ import { Injector } 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 () => {
@@ -14,7 +14,7 @@ describe('nestedNavigate', () => {
       const locationService = injector.getInstance(LocationService)
       const spy = vi.spyOn(locationService, 'navigate')
 
-      nestedNavigate(injector, '/buttons')
+      nestedNavigate(injector, { path: '/buttons' })
 
       expect(spy).toHaveBeenCalledWith('/buttons')
     })
@@ -25,7 +25,7 @@ describe('nestedNavigate', () => {
       const locationService = injector.getInstance(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')
     })
@@ -36,30 +36,105 @@ describe('nestedNavigate', () => {
       const locationService = injector.getInstance(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(new Injector(), async (injector) => {
+      const locationService = injector.getInstance(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(new Injector(), async (injector) => {
+      const locationService = injector.getInstance(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(new Injector(), async (injector) => {
+      const locationService = injector.getInstance(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(new Injector(), async (injector) => {
+      const locationService = injector.getInstance(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 +165,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 +180,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 +197,7 @@ describe('Type utilities', () => {
 
       const appNavigate = createNestedNavigate<Routes>()
       // @ts-expect-error -- '/nonexistent' is not a valid route path
-      appNavigate(new Injector(), '/nonexistent')
+      appNavigate(new Injector(), { path: '/nonexistent' })
     })
 
     it('Should accept routes with typed match parameters (NestedRoute<T>)', () => {
@@ -135,9 +210,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' }>()
     })
   })
 })

package/src/components/nested-navigate.ts

@@ -1,36 +1,85 @@
 import type { Injector } from '@furystack/inject'
+import { serializeToQueryString } from '@furystack/rest'
 import { compileRoute } from '../compile-route.js'
 import { LocationService } from '../services/location-service.js'
-import type { ExtractRouteParams, ExtractRoutePaths } from './nested-route-types.js'
+import type {
+  ExtractRouteHash,
+  ExtractRouteQuery,
+  ExtractRoutePaths,
+  RouteAt,
+  TypedHashArg,
+  TypedParamsArg,
+  TypedQueryArg,
+} from './nested-route-types.js'
 import type { NestedRoute } from './nested-router.js'
 
 /**
- * Arguments for a type-safe nested navigate call.
- * When the path contains parameters (e.g. `:id`), the `params` argument becomes required.
- * @typeParam TPath - A specific route path string
+ * Untyped runtime arguments for a nested navigate call.
+ * Used by the base {@link nestedNavigate} implementation; the typed variants
+ * returned by {@link createNestedNavigate} narrow each field against the route
+ * tree at compile time.
  */
-export type TypedNavigateArgs<TPath extends string> = string extends keyof ExtractRouteParams<TPath>
-  ? [path: TPath, params?: Record<string, string>]
-  : [path: TPath, params: ExtractRouteParams<TPath>]
+export type NestedNavigateArgs = {
+  path: string
+  params?: Record<string, string>
+  query?: Record<string, unknown>
+  hash?: string
+}
+
+/**
+ * Typed arguments for a nested navigate call, derived from the route tree and
+ * the specific target path.
+ *
+ * - `params` is required when the path contains `:param` segments.
+ * - `query` is required when the route's declared query shape has any required
+ *   key, optional when all keys are optional, and forbidden when the route
+ *   declares no `query` validator.
+ * - `hash` is always optional and restricted to the route's declared literal
+ *   tuple; forbidden when the route declares no `hash`.
+ *
+ * @typeParam TRoutes - The route tree
+ * @typeParam TPath - A composed route path within `TRoutes`
+ */
+export type TypedNestedNavigateArgs<
+  TRoutes extends Record<string, NestedRoute<any, any, any>>,
+  TPath extends string,
+> = { path: TPath } & TypedParamsArg<TPath> &
+  TypedQueryArg<ExtractRouteQuery<RouteAt<TRoutes, TPath>>> &
+  TypedHashArg<ExtractRouteHash<RouteAt<TRoutes, TPath>>>
 
 /**
- * Navigates to a route path using the LocationService from the given injector.
- * Compiles parameterized routes (e.g. `/users/:id`) when `params` is provided.
+ * Builds the resolved URL for a nested navigate call, including path parameters,
+ * serialized query string and hash segment. Exported for callers that need the
+ * URL without side effects (e.g. link rendering helpers).
+ */
+export const buildNestedNavigateUrl = (args: NestedNavigateArgs): string => {
+  const { path, params, query, hash } = args
+  const resolvedPath = params && Object.keys(params).length > 0 ? compileRoute(path, params) : path
+  const hasQuery = query && Object.keys(query).length > 0
+  const search = hasQuery ? `?${serializeToQueryString(query)}` : ''
+  const hashPart = hash ? `#${hash}` : ''
+  return `${resolvedPath}${search}${hashPart}`
+}
+
+/**
+ * Navigates to a route using the LocationService resolved from the given injector.
+ * Compiles parameterized routes (e.g. `/users/:id`), serializes the optional
+ * `query` record with the default `@furystack/rest` serializer, and appends the
+ * optional `hash` segment.
  *
  * @param injector - The injector instance to resolve LocationService from
- * @param path - The route path to navigate to
- * @param params - Optional route parameters to compile into the path
+ * @param args - The navigation arguments
  */
-export const nestedNavigate = (injector: Injector, path: string, params?: Record<string, string>): void => {
-  const resolvedUrl = params ? compileRoute(path, params) : path
-  injector.getInstance(LocationService).navigate(resolvedUrl)
+export const nestedNavigate = (injector: Injector, args: NestedNavigateArgs): void => {
+  injector.getInstance(LocationService).navigate(buildNestedNavigateUrl(args))
 }
 
 /**
  * Creates a type-safe navigate function constrained to a specific route tree.
  * The returned function has the same runtime behavior as {@link nestedNavigate}
- * but narrows `path` to only accept valid route paths, and requires `params`
- * when the route has parameters.
+ * but narrows `path` to only accept valid route paths, requires `params` when
+ * the route has parameters, and enforces the route's declared `query` and
+ * `hash` schemas.
  *
  * Unlike {@link createNestedRouteLink}, the injector is passed at call time,
  * not at creation time.
@@ -42,19 +91,19 @@ export const nestedNavigate = (injector: Injector, path: string, params?: Record
  * ```typescript
  * const appNavigate = createNestedNavigate<typeof appRoutes>()
  *
- * // Type-safe: only valid paths accepted
- * appNavigate(injector, '/buttons')
- *
- * // TypeScript error: invalid path
- * appNavigate(injector, '/nonexistent')
- *
- * // Params required for parameterized routes
- * appNavigate(injector, '/users/:id', { id: '123' })
+ * appNavigate(injector, { path: '/buttons' })
+ * appNavigate(injector, { path: '/users/:id', params: { id: '123' } })
+ * appNavigate(injector, {
+ *   path: '/users/:id',
+ *   params: { id: '123' },
+ *   query: { tab: 'profile' },
+ *   hash: 'settings',
+ * })
  * ```
  */
-export const createNestedNavigate = <TRoutes extends Record<string, NestedRoute<any>>>() => {
+export const createNestedNavigate = <TRoutes extends Record<string, NestedRoute<any, any, any>>>() => {
   return nestedNavigate as <TPath extends ExtractRoutePaths<TRoutes>>(
     injector: Injector,
-    ...args: TypedNavigateArgs<TPath>
+    args: TypedNestedNavigateArgs<TRoutes, TPath>,
   ) => void
 }

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

@@ -0,0 +1,88 @@
+import { Injector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { describe, expect, expectTypeOf, it, vi } from 'vitest'
+import { LocationService } from '../services/location-service.js'
+import { createNestedReplace, nestedReplace } from './nested-replace.js'
+import type { NestedRoute } from './nested-router.js'
+
+type TestRoute = Pick<NestedRoute<unknown, any, any>, 'component'>
+
+describe('nestedReplace', () => {
+  it('Should replace the current history entry with a simple path', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const locationService = injector.getInstance(LocationService)
+      const navigateSpy = vi.spyOn(locationService, 'navigate')
+      const replaceSpy = vi.spyOn(locationService, 'replace')
+
+      nestedReplace(injector, { path: '/buttons' })
+
+      expect(replaceSpy).toHaveBeenCalledWith('/buttons')
+      expect(navigateSpy).not.toHaveBeenCalled()
+    })
+  })
+
+  it('Should compile params, query and hash for a replace call', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const locationService = injector.getInstance(LocationService)
+      const replaceSpy = vi.spyOn(locationService, 'replace')
+
+      nestedReplace(injector, {
+        path: '/users/:id',
+        params: { id: '7' },
+        query: { tab: 'profile' },
+        hash: 'notes',
+      })
+
+      expect(replaceSpy).toHaveBeenCalledTimes(1)
+      const replacedUrl = replaceSpy.mock.calls[0][0]
+      expect(replacedUrl.startsWith('/users/7?')).toBe(true)
+      expect(replacedUrl.endsWith('#notes')).toBe(true)
+    })
+  })
+})
+
+describe('createNestedReplace', () => {
+  it('Should constrain path to valid route paths', () => {
+    type Routes = {
+      '/': TestRoute & {
+        children: {
+          '/buttons': TestRoute
+          '/inputs': TestRoute
+        }
+      }
+    }
+
+    const appReplace = createNestedReplace<Routes>()
+    expectTypeOf(appReplace<'/buttons'>)
+      .parameter(0)
+      .toEqualTypeOf<Injector>()
+  })
+
+  it('Should reject invalid paths', () => {
+    type Routes = {
+      '/': TestRoute & {
+        children: {
+          '/buttons': TestRoute
+        }
+      }
+    }
+
+    const appReplace = createNestedReplace<Routes>()
+    // @ts-expect-error -- '/nonexistent' is not a valid route path
+    appReplace(new Injector(), { path: '/nonexistent' })
+  })
+
+  it('Should enforce a 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 appReplace = createNestedReplace<typeof routes>()
+    expectTypeOf(appReplace<'/list'>)
+      .parameter(1)
+      .toExtend<{ query: { page: number } }>()
+  })
+})

package/src/components/nested-replace.ts

@@ -0,0 +1,46 @@
+import type { Injector } from '@furystack/inject'
+import { LocationService } from '../services/location-service.js'
+import type { NestedNavigateArgs, TypedNestedNavigateArgs } from './nested-navigate.js'
+import { buildNestedNavigateUrl } from './nested-navigate.js'
+import type { ExtractRoutePaths } from './nested-route-types.js'
+import type { NestedRoute } from './nested-router.js'
+
+/**
+ * Replaces the current history entry with a route using the LocationService
+ * resolved from the given injector. Has the same URL-composition semantics as
+ * `nestedNavigate`, but calls `history.replaceState` under the hood so the
+ * intermediate URL does not appear in the browser's back / forward stack.
+ *
+ * Use this for SPA redirects (e.g. canonicalization, auth guards) where the
+ * caller's URL should not be recoverable with the Back button.
+ *
+ * @param injector - The injector instance to resolve LocationService from
+ * @param args - The navigation arguments
+ */
+export const nestedReplace = (injector: Injector, args: NestedNavigateArgs): void => {
+  injector.getInstance(LocationService).replace(buildNestedNavigateUrl(args))
+}
+
+/**
+ * Creates a type-safe replace function constrained to a specific route tree.
+ * The returned function has the same runtime behavior as {@link nestedReplace}
+ * but narrows `path` to valid route paths, requires `params` when the route has
+ * parameters, and enforces the route's declared `query` and `hash` schemas.
+ *
+ * @typeParam TRoutes - The route tree type (use `typeof yourRoutes`)
+ * @returns A type-safe replace function
+ *
+ * @example
+ * ```typescript
+ * const appReplace = createNestedReplace<typeof appRoutes>()
+ *
+ * // Redirect an unauthenticated visitor without polluting history
+ * appReplace(injector, { path: '/login' })
+ * ```
+ */
+export const createNestedReplace = <TRoutes extends Record<string, NestedRoute<any, any, any>>>() => {
+  return nestedReplace as <TPath extends ExtractRoutePaths<TRoutes>>(
+    injector: Injector,
+    args: TypedNestedNavigateArgs<TRoutes, TPath>,
+  ) => void
+}