@furystack/shades 13.2.1 → 14.0.0

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

@@ -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(() => {
@@ -31,7 +31,7 @@ describe('NestedRouteLink', () => {
         injector,
         rootElement,
         jsxElement: (
-          <NestedRouteLink id="link" href="/buttons">
+          <NestedRouteLink id="link" path="/buttons">
             Buttons
           </NestedRouteLink>
         ),
@@ -54,7 +54,7 @@ describe('NestedRouteLink', () => {
         injector,
         rootElement,
         jsxElement: (
-          <NestedRouteLink id="link" href="/buttons">
+          <NestedRouteLink id="link" path="/buttons">
             Buttons
           </NestedRouteLink>
         ),
@@ -75,7 +75,7 @@ describe('NestedRouteLink', () => {
         injector,
         rootElement,
         jsxElement: (
-          <NestedRouteLink id="link" href="/users/:id" params={{ id: '42' }}>
+          <NestedRouteLink id="link" path="/users/:id" params={{ id: '42' }}>
             User 42
           </NestedRouteLink>
         ),
@@ -95,7 +95,7 @@ describe('NestedRouteLink', () => {
         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(new Injector(), 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(new Injector(), 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,
@@ -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
 }

package/src/components/nested-route-types.ts

@@ -12,10 +12,10 @@ export type ConcatPaths<Parent extends string, Child extends string> = Parent ex
  * Recursively extracts all valid full URL paths from a nested route tree.
  * @typeParam T - A record of route patterns to NestedRoute definitions
  */
-export type ExtractRoutePaths<T extends Record<string, NestedRoute<any>>> = {
+export type ExtractRoutePaths<T extends Record<string, NestedRoute<any, any, any>>> = {
   [K in keyof T & string]:
     | K
-    | (T[K] extends { children: infer C extends Record<string, NestedRoute<any>> }
+    | (T[K] extends { children: infer C extends Record<string, NestedRoute<any, any, any>> }
         ? ConcatPaths<K, ExtractRoutePaths<C> & string>
         : never)
 }[keyof T & string]
@@ -40,3 +40,83 @@ export type ExtractRouteParams<T extends string> = T extends `${string}:${infer
 export type UrlTree<TPaths extends string> = {
   [key: string]: TPaths | UrlTree<TPaths>
 }
+
+/**
+ * A query string validator function for a nested route. Receives the deserialized
+ * query string object and returns either the typed query value or `null` when
+ * the URL's query does not match the route's expected shape.
+ * @typeParam TQuery - The typed query shape the route expects
+ */
+export type QueryValidator<TQuery> = (raw: Record<string, unknown>) => TQuery | null
+
+/**
+ * A readonly tuple of string literals describing the allowed URL hash values
+ * for a nested route.
+ */
+export type HashLiterals = readonly string[]
+
+/**
+ * Extracts the typed query shape declared by a {@link NestedRoute}'s `query` validator.
+ * Resolves to `never` when the route has no `query` validator.
+ * @typeParam R - A NestedRoute value type
+ */
+export type ExtractRouteQuery<R> = R extends { query: QueryValidator<infer Q> } ? Q : never
+
+/**
+ * Extracts the typed hash literal union declared by a {@link NestedRoute}'s `hash` tuple.
+ * Resolves to `never` when the route has no `hash` declaration.
+ * @typeParam R - A NestedRoute value type
+ */
+export type ExtractRouteHash<R> = R extends { hash: infer H extends HashLiterals } ? H[number] : never
+
+/**
+ * Walks a nested route tree and resolves the route value at the given composed path.
+ * Used to surface per-route `query` / `hash` metadata to call-site helpers.
+ * @typeParam TRoutes - The route tree
+ * @typeParam TPath - A full composed route path (as produced by {@link ExtractRoutePaths})
+ */
+export type RouteAt<TRoutes extends Record<string, NestedRoute<any, any, any>>, TPath extends string> = {
+  [K in keyof TRoutes & string]: TPath extends K
+    ? TRoutes[K]
+    : K extends '/'
+      ? TRoutes[K] extends { children: infer C extends Record<string, NestedRoute<any, any, any>> }
+        ? RouteAt<C, TPath>
+        : never
+      : TPath extends `${K}${infer Rest}`
+        ? TRoutes[K] extends { children: infer C extends Record<string, NestedRoute<any, any, any>> }
+          ? RouteAt<C, Rest>
+          : never
+        : never
+}[keyof TRoutes & string]
+
+/**
+ * Builds the `params` portion of a typed navigation / link argument.
+ * Resolves to `{ params?: Record<string, string> }` when the path has no `:param`
+ * segments and `{ params: {...} }` when at least one is required.
+ * @typeParam TPath - A URL pattern string
+ */
+export type TypedParamsArg<TPath extends string> = string extends keyof ExtractRouteParams<TPath>
+  ? { params?: Record<string, string> }
+  : { params: ExtractRouteParams<TPath> }
+
+/**
+ * Builds the `query` portion of a typed navigation / link argument.
+ * - `never` (route declared no schema) → property is forbidden.
+ * - All-optional schema → property itself is optional.
+ * - Any required key → property is required.
+ * @typeParam TQuery - The route's typed query shape
+ */
+export type TypedQueryArg<TQuery> = [TQuery] extends [never]
+  ? { query?: never }
+  : // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- `{} extends T` is the idiomatic way to detect "all keys optional" on an arbitrary object shape.
+    {} extends TQuery
+    ? { query?: TQuery }
+    : { query: TQuery }
+
+/**
+ * Builds the `hash` portion of a typed navigation / link argument.
+ * Hash is always optional at the call site (URL fragments are never required
+ * for correctness of navigation).
+ * @typeParam THash - The route's hash literal union
+ */
+export type TypedHashArg<THash> = [THash] extends [never] ? { hash?: never } : { hash?: THash }