@furystack/shades 13.2.2 → 15.0.0

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.get(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,89 @@
+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 { 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(createInjector(), async (injector) => {
+      const locationService = injector.get(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(createInjector(), async (injector) => {
+      const locationService = injector.get(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(createInjector(), { 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.get(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
+}

package/src/components/nested-route-link.spec.tsx

@@ -1,4 +1,4 @@
-import { Injector } from '@furystack/inject'
+import { createInjector } from '@furystack/inject'
 import { usingAsync } from '@furystack/utils'
 import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi } from 'vitest'
 import { initializeShadeRoot } from '../initialize.js'
@@ -11,9 +11,9 @@ import type { ConcatPaths, ExtractRouteParams, ExtractRoutePaths, UrlTree } from
 import type { NestedRoute } from './nested-router.js'
 
 // Minimal route type for type-level tests. Using Pick avoids the
-// `children?: Record<string, NestedRoute<any>>` from NestedRoute<unknown>
+// `children?: Record<string, NestedRoute<any, any, any>>` from NestedRoute<unknown>
 // which would widen literal keys in intersections.
-type TestRoute = Pick<NestedRoute<unknown>, 'component'>
+type TestRoute = Pick<NestedRoute<unknown, any, any>, 'component'>
 
 describe('NestedRouteLink', () => {
   beforeEach(() => {
@@ -24,14 +24,14 @@ describe('NestedRouteLink', () => {
   })
 
   it('Should render a link with the correct href', async () => {
-    await usingAsync(new Injector(), async (injector) => {
+    await usingAsync(createInjector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       initializeShadeRoot({
         injector,
         rootElement,
         jsxElement: (
-          <NestedRouteLink id="link" href="/buttons">
+          <NestedRouteLink id="link" path="/buttons">
             Buttons
           </NestedRouteLink>
         ),
@@ -44,17 +44,17 @@ describe('NestedRouteLink', () => {
   })
 
   it('Should trigger SPA navigation on click', async () => {
-    await usingAsync(new Injector(), async (injector) => {
+    await usingAsync(createInjector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
       const onRouteChange = vi.fn()
 
-      injector.getInstance(LocationService).onLocationPathChanged.subscribe(onRouteChange)
+      injector.get(LocationService).onLocationPathChanged.subscribe(onRouteChange)
 
       initializeShadeRoot({
         injector,
         rootElement,
         jsxElement: (
-          <NestedRouteLink id="link" href="/buttons">
+          <NestedRouteLink id="link" path="/buttons">
             Buttons
           </NestedRouteLink>
         ),
@@ -68,14 +68,14 @@ describe('NestedRouteLink', () => {
   })
 
   it('Should compile route params in the href', async () => {
-    await usingAsync(new Injector(), async (injector) => {
+    await usingAsync(createInjector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       initializeShadeRoot({
         injector,
         rootElement,
         jsxElement: (
-          <NestedRouteLink id="link" href="/users/:id" params={{ id: '42' }}>
+          <NestedRouteLink id="link" path="/users/:id" params={{ id: '42' }}>
             User 42
           </NestedRouteLink>
         ),
@@ -88,14 +88,14 @@ describe('NestedRouteLink', () => {
   })
 
   it('Should compile route params with multiple segments', async () => {
-    await usingAsync(new Injector(), async (injector) => {
+    await usingAsync(createInjector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       initializeShadeRoot({
         injector,
         rootElement,
         jsxElement: (
-          <NestedRouteLink id="link" href="/users/:userId/posts/:postId" params={{ userId: '1', postId: '99' }}>
+          <NestedRouteLink id="link" path="/users/:userId/posts/:postId" params={{ userId: '1', postId: '99' }}>
             Post
           </NestedRouteLink>
         ),
@@ -106,6 +106,46 @@ describe('NestedRouteLink', () => {
       )
     })
   })
+
+  it('Should append a serialized query string to the rendered href', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <NestedRouteLink id="link" path="/buttons" query={{ page: 2 }}>
+            Buttons
+          </NestedRouteLink>
+        ),
+      })
+      await flushUpdates()
+
+      const link = document.getElementById('link') as HTMLAnchorElement
+      expect(link.getAttribute('href')?.startsWith('/buttons?')).toBe(true)
+    })
+  })
+
+  it('Should append the hash segment to the rendered href', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <NestedRouteLink id="link" path="/buttons" hash="overview">
+            Buttons
+          </NestedRouteLink>
+        ),
+      })
+      await flushUpdates()
+
+      const link = document.getElementById('link') as HTMLAnchorElement
+      expect(link.getAttribute('href')).toBe('/buttons#overview')
+    })
+  })
 })
 
 describe('Type utilities', () => {
@@ -219,13 +259,13 @@ describe('Type utilities', () => {
   describe('TypedNestedRouteLinkProps', () => {
     it('Should make params optional for paths without parameters', () => {
       type Props = TypedNestedRouteLinkProps<'/buttons'>
-      expectTypeOf<Props['href']>().toEqualTypeOf<'/buttons'>()
+      expectTypeOf<Props['path']>().toEqualTypeOf<'/buttons'>()
       expectTypeOf<Props>().toExtend<{ params?: Record<string, string> }>()
     })
 
     it('Should require params for parameterized paths', () => {
       type Props = TypedNestedRouteLinkProps<'/users/:id'>
-      expectTypeOf<Props['href']>().toEqualTypeOf<'/users/:id'>()
+      expectTypeOf<Props['path']>().toEqualTypeOf<'/users/:id'>()
       expectTypeOf<Props>().toExtend<{ params: { id: string } }>()
     })
 
@@ -236,20 +276,20 @@ describe('Type utilities', () => {
   })
 
   describe('NestedRouteLink param inference', () => {
-    it('Should infer params as optional when href has no parameters', () => {
+    it('Should infer params as optional when path has no parameters', () => {
       expectTypeOf(NestedRouteLink).parameter(0).toHaveProperty('params')
       expectTypeOf(NestedRouteLink<'/buttons'>)
         .parameter(0)
         .toExtend<{ params?: Record<string, string> }>()
     })
 
-    it('Should infer params as required when href has a parameter', () => {
+    it('Should infer params as required when path has a parameter', () => {
       expectTypeOf(NestedRouteLink<'/users/:id'>)
         .parameter(0)
         .toExtend<{ params: { id: string } }>()
     })
 
-    it('Should infer multiple params from href', () => {
+    it('Should infer multiple params from path', () => {
       expectTypeOf(NestedRouteLink<'/users/:userId/posts/:postId'>)
         .parameter(0)
         .toExtend<{ params: { userId: string; postId: string } }>()
@@ -257,7 +297,7 @@ describe('Type utilities', () => {
   })
 
   describe('createNestedRouteLink', () => {
-    it('Should constrain href to valid route paths', () => {
+    it('Should constrain path to valid route paths', () => {
       type Routes = {
         '/': TestRoute & {
           children: {
@@ -267,7 +307,7 @@ describe('Type utilities', () => {
       }
 
       const AppLink = createNestedRouteLink<Routes>()
-      expectTypeOf(AppLink).parameter(0).toHaveProperty('href')
+      expectTypeOf(AppLink).parameter(0).toHaveProperty('path')
     })
 
     it('Should reject invalid paths', () => {
@@ -281,7 +321,7 @@ describe('Type utilities', () => {
 
       const AppLink = createNestedRouteLink<Routes>()
       // @ts-expect-error -- '/nonexistent' is not a valid route path
-      AppLink({ href: '/nonexistent' })
+      AppLink({ path: '/nonexistent' })
     })
 
     it('Should require params for parameterized routes in the tree', () => {
@@ -343,13 +383,41 @@ describe('Type utilities', () => {
             '/users/:userId': usersRoute,
           },
         },
-      } satisfies Record<string, NestedRoute<any>>
+      } satisfies Record<string, NestedRoute<any, any, any>>
 
       const AppLink = createNestedRouteLink<typeof routes>()
-      expectTypeOf(AppLink).parameter(0).toHaveProperty('href')
+      expectTypeOf(AppLink).parameter(0).toHaveProperty('path')
       expectTypeOf(AppLink<'/users/:userId'>)
         .parameter(0)
         .toExtend<{ params: { userId: string } }>()
     })
+
+    it('Should enforce a declared required query shape on the link', () => {
+      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 AppLink = createNestedRouteLink<typeof routes>()
+      expectTypeOf(AppLink<'/list'>)
+        .parameter(0)
+        .toExtend<{ query: { page: number } }>()
+    })
+
+    it('Should narrow hash on the link 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 AppLink = createNestedRouteLink<typeof routes>()
+      expectTypeOf(AppLink<'/tabs'>)
+        .parameter(0)
+        .toExtend<{ hash?: 'overview' | 'details' }>()
+    })
   })
 })

package/src/components/nested-route-link.tsx

@@ -1,31 +1,58 @@
-import { compileRoute } from '../compile-route.js'
 import type { ChildrenList } from '../models/children-list.js'
 import type { PartialElement } from '../models/partial-element.js'
 import { LocationService } from '../services/location-service.js'
 import { createComponent } from '../shade-component.js'
 import { Shade } from '../shade.js'
-import type { ExtractRouteParams, ExtractRoutePaths } from './nested-route-types.js'
+import { buildNestedNavigateUrl } from './nested-navigate.js'
+import type {
+  ExtractRouteHash,
+  ExtractRouteQuery,
+  ExtractRoutePaths,
+  RouteAt,
+  TypedHashArg,
+  TypedParamsArg,
+  TypedQueryArg,
+} from './nested-route-types.js'
 import type { NestedRoute } from './nested-router.js'
 
 /**
  * Props for the NestedRouteLink component.
- * Combines SPA navigation from RouteLink with parameter compilation from LinkToRoute.
+ * Combines SPA navigation with parameter compilation for nested routes,
+ * plus optional query string and hash fragment composition.
  */
 export type NestedRouteLinkProps = {
-  href: string
+  path: string
   params?: Record<string, string>
+  query?: Record<string, unknown>
+  hash?: string
 } & PartialElement<Omit<HTMLAnchorElement, 'onclick' | 'href'>>
 
 /**
  * Props for a type-safe nested route link.
  * When the path contains parameters (e.g. `:id`), the `params` prop becomes required.
+ * `query` and `hash` remain loose (untyped) on this variant; use
+ * {@link createNestedRouteLink} to narrow them against a specific route tree.
  * @typeParam TPath - A specific route path string
  */
 export type TypedNestedRouteLinkProps<TPath extends string> = {
-  href: TPath
-} & (string extends keyof ExtractRouteParams<TPath>
-  ? { params?: Record<string, string> }
-  : { params: ExtractRouteParams<TPath> }) &
+  path: TPath
+  query?: Record<string, unknown>
+  hash?: string
+} & TypedParamsArg<TPath> &
+  PartialElement<Omit<HTMLAnchorElement, 'onclick' | 'href'>>
+
+/**
+ * Props for a route-tree-aware nested route link. Narrows `query` and `hash`
+ * against the specific route at `TPath` in `TRoutes`.
+ * @typeParam TRoutes - The route tree
+ * @typeParam TPath - A composed route path within `TRoutes`
+ */
+export type TreeAwareNestedRouteLinkProps<
+  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>>> &
   PartialElement<Omit<HTMLAnchorElement, 'onclick' | 'href'>>
 
 const _NestedRouteLink = Shade<NestedRouteLinkProps>({
@@ -37,8 +64,8 @@ const _NestedRouteLink = Shade<NestedRouteLinkProps>({
     textDecoration: 'inherit',
   },
   render: ({ children, props, injector, useHostProps }) => {
-    const { href, params } = props
-    const resolvedUrl = params ? compileRoute(href, params) : href
+    const { path, params, query, hash } = props
+    const resolvedUrl = buildNestedNavigateUrl({ path, params, query, hash })
 
     useHostProps({
       href: resolvedUrl,
@@ -46,7 +73,7 @@ const _NestedRouteLink = Shade<NestedRouteLinkProps>({
         ev.preventDefault()
         // eslint-disable-next-line furystack/prefer-location-service -- This IS the SPA link component; it must call pushState directly.
         history.pushState('', props.title || '', resolvedUrl)
-        injector.getInstance(LocationService).updateState()
+        injector.get(LocationService).updateState()
       },
     })
     return <>{children}</>
@@ -58,13 +85,15 @@ const _NestedRouteLink = Shade<NestedRouteLinkProps>({
  * type-safe route parameter compilation.
  *
  * Intercepts click events to use `history.pushState` for client-side navigation,
- * and compiles parameterized routes (e.g. `/users/:id`) when `params` is provided.
+ * compiles parameterized routes (e.g. `/users/:id`) when `params` is provided,
+ * serializes `query` to the URL search string and appends `hash` when set.
  *
- * Route parameters are automatically inferred from the `href` pattern:
- * - `href="/buttons"` — `params` is optional
- * - `href="/users/:id"` — `params: { id: string }` is required
+ * Route parameters are automatically inferred from the `path` pattern:
+ * - `path="/buttons"` — `params` is optional
+ * - `path="/users/:id"` — `params: { id: string }` is required
  *
- * For additional URL validation against a route tree, use {@link createNestedRouteLink}.
+ * For additional URL validation against a route tree (including `query` and
+ * `hash` narrowing), use {@link createNestedRouteLink}.
  */
 export const NestedRouteLink = _NestedRouteLink as unknown as <TPath extends string = string>(
   props: TypedNestedRouteLinkProps<TPath>,
@@ -72,9 +101,10 @@ export const NestedRouteLink = _NestedRouteLink as unknown as <TPath extends str
 ) => JSX.Element
 
 /**
- * Creates a type-safe wrapper around NestedRouteLink constrained to a specific route tree.
- * The returned component has the same runtime behavior but narrows `href` to only accept
- * valid route paths, and requires `params` when the route has parameters.
+ * Creates a type-safe wrapper around NestedRouteLink constrained to a specific
+ * route tree. The returned component has the same runtime behavior 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.
  *
  * @typeParam TRoutes - The route tree type (use `typeof yourRoutes`)
  * @returns A narrowed NestedRouteLink component
@@ -83,19 +113,14 @@ export const NestedRouteLink = _NestedRouteLink as unknown as <TPath extends str
  * ```typescript
  * const AppLink = createNestedRouteLink<typeof appRoutes>()
  *
- * // Type-safe: only valid paths accepted
- * <AppLink href="/buttons">Buttons</AppLink>
- *
- * // TypeScript error: invalid path
- * <AppLink href="/nonexistent">Error!</AppLink>
- *
- * // Params required for parameterized routes
- * <AppLink href="/users/:id" params={{ id: '123' }}>User</AppLink>
+ * <AppLink path="/buttons">Buttons</AppLink>
+ * <AppLink path="/users/:id" params={{ id: '123' }}>User</AppLink>
+ * <AppLink path="/users/:id" params={{ id: '1' }} query={{ tab: 'profile' }} hash="notes">User</AppLink>
  * ```
  */
-export const createNestedRouteLink = <TRoutes extends Record<string, NestedRoute<any>>>() => {
+export const createNestedRouteLink = <TRoutes extends Record<string, NestedRoute<any, any, any>>>() => {
   return _NestedRouteLink as unknown as <TPath extends ExtractRoutePaths<TRoutes>>(
-    props: TypedNestedRouteLinkProps<TPath>,
+    props: TreeAwareNestedRouteLinkProps<TRoutes, TPath>,
     children?: ChildrenList,
   ) => JSX.Element
 }