feat(router): useParams_UNSTABLE (#2151)

## Motivation

Page components get their route params through `PageProps`, but client
and shared components that do not receive page props had no typed way to
read them.

## API

`useParams_UNSTABLE({ from })` (from `waku/router/client`) returns the
current route's params typed from the pattern, or `null` when the path
does not match:

```tsx
'use client';

import { useParams_UNSTABLE as useParams } from 'waku/router/client';

const params = useParams({ from: '/posts/[slug]' });
// { slug: string } | null  (a catch-all gives { path: string[] })
```

`from` is type-checked against your routes the same way `router.push({
to })` is, so an unknown pattern (`{ from: 'foo' }`) is a type error,
and the params are typed from it. The `_UNSTABLE` suffix is intentional
while we collect feedback.

Author: dai-shi

docs/guides/typed-routes.mdx

@@ -43,3 +43,26 @@ export const PostButton = ({ slug }: { slug: string }) => {
 - `to` is a route pattern (e.g. `/posts/[slug]`, `/docs/[...path]`). `params` is required when the pattern has slugs and is typed from it; a catch-all takes a `string[]`.
 - `search` is an object of string query values (use an array for repeated keys); `undefined` values are omitted. `hash` is optional.
 - The plain string form (`router.push('/posts/hello')`) keeps working.
+
+## Reading Route Params
+
+`useParams()` reads the current route's params, typed from the route pattern you pass. It returns `null` when the current path does not match that pattern, so it is safe to call from a component rendered under more than one route.
+
+```tsx
+'use client';
+
+import { useParams_UNSTABLE as useParams } from 'waku/router/client';
+
+export const PostTitle = () => {
+  const params = useParams({ from: '/posts/[slug]' });
+  if (!params) {
+    return null;
+  }
+  return <h1>{params.slug}</h1>;
+};
+```
+
+- The result is typed from the pattern: `/posts/[slug]` gives `{ slug: string }`, and a catch-all like `/docs/[...path]` gives `{ path: string[] }`.
+- Values are URL-decoded, mirroring how `router.push` encodes them.
+- It re-renders when the current route path changes.
+- Page components already receive their params through props; `useParams()` is for client and shared components that do not.

…/router/common-utils/build-route-href.ts …/router/client-utils/build-route-href.tspackages/waku/src/router/common-utils/build-route-href.ts renamed to packages/waku/src/router/client-utils/build-route-href.ts packages/waku/src/router/common-utils/build-route-href.ts renamed to packages/waku/src/router/client-utils/build-route-href.ts

@@ -2,18 +2,18 @@ import { getGrouplessPath } from '../../lib/utils/create-pages.js';
 import { getPathMapping, parsePathWithSlug } from '../../lib/utils/path.js';
 import type { CreatePagesConfig } from '../base-types.js';
 import type {
-  ApiParams,
   PagePath,
+  RouteParams,
 } from '../create-pages-utils/inferred-path-types.js';
 
 export type RoutePattern = [PagePath<CreatePagesConfig>] extends [never]
   ? string
   : PagePath<CreatePagesConfig>;
 
-type RouteParams<Pattern extends RoutePattern> = {
-  [Key in keyof ApiParams<Pattern>]: ApiParams<Pattern>[Key] extends string[]
+type RouteParamsInput<Pattern extends RoutePattern> = {
+  [Key in keyof RouteParams<Pattern>]: RouteParams<Pattern>[Key] extends string[]
     ? readonly string[]
-    : ApiParams<Pattern>[Key];
+    : RouteParams<Pattern>[Key];
 };
 
 type SearchValue = string | readonly string[] | undefined;
@@ -24,9 +24,9 @@ export type BuildRouteHrefTarget<Pattern extends RoutePattern> = {
   to: Pattern;
   search?: BuildRouteHrefSearch;
   hash?: string;
-} & (keyof RouteParams<Pattern> extends never
+} & (keyof RouteParamsInput<Pattern> extends never
   ? { params?: never }
-  : { params: RouteParams<Pattern> });
+  : { params: RouteParamsInput<Pattern> });
 
 const serializeSearch = (search: BuildRouteHrefSearch | undefined): string => {
   if (search === undefined) {

packages/waku/src/router/client-utils/match-route-params.ts

@@ -0,0 +1,55 @@
+import { getGrouplessPath } from '../../lib/utils/create-pages.js';
+import { getPathMapping, parsePathWithSlug } from '../../lib/utils/path.js';
+import type { RouteParams } from '../create-pages-utils/inferred-path-types.js';
+import type { RoutePattern } from './build-route-href.js';
+
+const safeDecodeURIComponent = (value: string): string | null => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Match a concrete pathname against a route pattern and return its params, or
+ * null when the pathname does not match. This is the inverse of buildRouteHref:
+ * route groups are stripped, the existing matcher decides the match, and each
+ * matched segment is decoded once. The pathname must be the encoded form stored
+ * by the router (e.g. useRouter().path); a pre-decoded path would double-decode
+ * values containing "%". Malformed percent-encoding yields null rather than
+ * throwing, since this runs during render. Catch-all matching follows the
+ * router: a prefixed terminal catch-all (/docs/[...path]) does not match its
+ * base (/docs), while a root catch-all (/[...path]) matches / as { path: [] }.
+ */
+export const matchRouteParams = <Pattern extends RoutePattern>(
+  pattern: Pattern,
+  pathname: string,
+): RouteParams<Pattern> | null => {
+  const pathSpec = parsePathWithSlug(getGrouplessPath(pattern));
+  const mapping = getPathMapping(pathSpec, pathname);
+  if (mapping === null) {
+    return null;
+  }
+  const params: Record<string, string | string[]> = {};
+  for (const [key, value] of Object.entries(mapping)) {
+    if (Array.isArray(value)) {
+      const decoded: string[] = [];
+      for (const part of value) {
+        const decodedPart = safeDecodeURIComponent(part);
+        if (decodedPart === null) {
+          return null;
+        }
+        decoded.push(decodedPart);
+      }
+      params[key] = decoded;
+    } else {
+      const decodedValue = safeDecodeURIComponent(value);
+      if (decodedValue === null) {
+        return null;
+      }
+      params[key] = decodedValue;
+    }
+  }
+  return params as RouteParams<Pattern>;
+};

packages/waku/src/router/client.tsx

@@ -35,11 +35,12 @@ import {
   useRefetch,
 } from '../minimal/client.js';
 import type { RouteConfig } from './base-types.js';
-import { buildRouteHref } from './common-utils/build-route-href.js';
+import { buildRouteHref } from './client-utils/build-route-href.js';
 import type {
   BuildRouteHrefTarget,
   RoutePattern,
-} from './common-utils/build-route-href.js';
+} from './client-utils/build-route-href.js';
+import { matchRouteParams } from './client-utils/match-route-params.js';
 import {
   ETAG_ID_PREFIX,
   HAS404_ID,
@@ -51,6 +52,7 @@ import {
   pathnameToRoutePath,
 } from './common-utils/route-path.js';
 import type { RouteProps } from './common-utils/route-path.js';
+import type { RouteParams } from './create-pages-utils/inferred-path-types.js';
 
 type AllowTrailingSlash<Path extends string> = Path extends '/'
   ? Path
@@ -316,6 +318,22 @@ export function useRouter() {
   };
 }
 
+/**
+ * Read the current route's params, typed from the `from` pattern, or null when
+ * the current path does not match it. Re-renders when the route path changes.
+ * The result is memoized by path, so its identity changes on navigation to a
+ * different path; read its fields rather than using the object itself as an
+ * effect dependency.
+ */
+export function useParams_UNSTABLE<Pattern extends RoutePattern>({
+  from,
+}: {
+  from: Pattern;
+}): RouteParams<Pattern> | null {
+  const { path } = useRouter();
+  return useMemo(() => matchRouteParams(from, path), [from, path]);
+}
+
 function useSharedRef<T>(
   ref: Ref<T | null> | undefined,
 ): [RefObject<T | null>, (node: T | null) => void | (() => void)] {

packages/waku/src/router/create-pages-utils/inferred-path-types.ts

@@ -199,12 +199,12 @@ type SlugTypes<Path extends string> =
       }
     : never;
 
-/** Extracts route parameters from an API path pattern. */
-export type ApiParams<Path extends string> = Prettify<SlugTypes<Path>>;
+/** Extracts route parameters from a route path pattern. */
+export type RouteParams<Path extends string> = Prettify<SlugTypes<Path>>;
 
 /** Context object passed to API route handlers with typed route parameters. */
 export interface ApiContext<Path extends string> {
-  readonly params: ApiParams<Path>;
+  readonly params: RouteParams<Path>;
 }
 
 export type PropsForPages<Path extends string> = Prettify<

packages/waku/tests/build-route-href.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest';
-import { buildRouteHref } from '../src/router/common-utils/build-route-href.js';
+import { buildRouteHref } from '../src/router/client-utils/build-route-href.js';
 
 describe('buildRouteHref', () => {
   test('static routes', () => {

packages/waku/tests/match-route-params.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from 'vitest';
+import { buildRouteHref } from '../src/router/client-utils/build-route-href.js';
+import { matchRouteParams } from '../src/router/client-utils/match-route-params.js';
+
+describe('matchRouteParams', () => {
+  test('matches a static route', () => {
+    expect(matchRouteParams('/about', '/about')).toEqual({});
+    expect(matchRouteParams('/about', '/posts')).toBeNull();
+  });
+
+  test('matches a slug', () => {
+    expect(matchRouteParams('/posts/[slug]', '/posts/hello')).toEqual({
+      slug: 'hello',
+    });
+  });
+
+  test('returns null on mismatch', () => {
+    expect(matchRouteParams('/posts/[slug]', '/about')).toBeNull();
+    expect(matchRouteParams('/posts/[slug]', '/posts/a/b')).toBeNull();
+  });
+
+  test('URL-decodes matched values', () => {
+    expect(matchRouteParams('/posts/[slug]', '/posts/a%20b%2Fc')).toEqual({
+      slug: 'a b/c',
+    });
+  });
+
+  test('returns null for malformed percent-encoding', () => {
+    expect(matchRouteParams('/posts/[slug]', '/posts/%E0%A4%A')).toBeNull();
+    expect(matchRouteParams('/docs/[...path]', '/docs/ok/%E0%A4%A')).toBeNull();
+  });
+
+  test('matches a prefixed slug', () => {
+    expect(matchRouteParams('/@[name]', '/@foo')).toEqual({ name: 'foo' });
+  });
+
+  test('matches a catch-all and decodes each part', () => {
+    expect(matchRouteParams('/docs/[...path]', '/docs/a/b')).toEqual({
+      path: ['a', 'b'],
+    });
+    expect(matchRouteParams('/docs/[...path]', '/docs/a%20b/c')).toEqual({
+      path: ['a b', 'c'],
+    });
+  });
+
+  test('catch-all empty behavior matches the matcher', () => {
+    expect(matchRouteParams('/[...path]', '/')).toEqual({ path: [] });
+    expect(matchRouteParams('/docs/[...path]', '/docs')).toBeNull();
+  });
+
+  test('strips route groups', () => {
+    expect(matchRouteParams('/(marketing)/about', '/about')).toEqual({});
+    expect(
+      matchRouteParams('/(marketing)/posts/[slug]', '/posts/hello'),
+    ).toEqual({ slug: 'hello' });
+  });
+
+  test('round-trips with buildRouteHref', () => {
+    const slugHref = buildRouteHref({
+      to: '/posts/[slug]',
+      params: { slug: 'a b/c' },
+    }).split(/[?#]/, 1)[0]!;
+    expect(matchRouteParams('/posts/[slug]', slugHref)).toEqual({
+      slug: 'a b/c',
+    });
+
+    const catchAllHref = buildRouteHref({
+      to: '/docs/[...path]',
+      params: { path: ['a b', 'c'] },
+    }).split(/[?#]/, 1)[0]!;
+    expect(matchRouteParams('/docs/[...path]', catchAllHref)).toEqual({
+      path: ['a b', 'c'],
+    });
+  });
+});
+
+describe('matchRouteParams types', () => {
+  test('params are derived from the route pattern', () => {
+    // Type-level assertions; the closure is never invoked.
+    const assertTypes = () => {
+      const slugParams = matchRouteParams('/posts/[slug]', '/posts/x');
+      if (slugParams) {
+        const slug: string = slugParams.slug;
+        void slug;
+        // @ts-expect-error unknown param name
+        void slugParams.id;
+      }
+      const catchAllParams = matchRouteParams('/docs/[...path]', '/docs/x');
+      if (catchAllParams) {
+        const path: string[] = catchAllParams.path;
+        void path;
+      }
+    };
+    expect(typeof assertTypes).toBe('function');
+  });
+});