@terpjs/react-core 0.5.10 → 0.6.0

package/README.md

@@ -72,10 +72,46 @@ runtime, fail closed (ADR 0059), so every screen keeps the breadcrumb/title/erro
 | `DetailPage` | One record's screen (level 3); breadcrumb trail = ancestors + record title. |
 | `Breadcrumbs` | The trail itself (used by the archetypes; rarely composed directly). Ancestor crumbs use the router's `Link` by default — `renderLink` is only for rendering outside a Terp router. |
 | `NavLinkContext`, `useNavLink` | The ambient link renderer `buildAppRouter` publishes (and the layout components default to); provide it yourself in a standalone story/test tree or a bespoke shell. |
-| `useRouteParam` | Read one route param, fail closed: the declared param comes back as a string, an undeclared name throws a directive error instead of silently yielding `undefined`. Routes are realised at runtime from manifests, so TanStack's type registry cannot check param names in any app — this replaces the unchecked `useParams({ strict: false }) as {…}` cast (ADR 0092). |
+| `useRouteParam` | Read one route param, fail closed: the declared param comes back as a string, an undeclared name throws a directive error instead of silently yielding `undefined`. Replaces the unchecked `useParams({ strict: false }) as {…}` cast (ADR 0092). Checked against the generated route table when the app has one. |
+| `useRouteParams` | Read a whole declared route's params, typed exactly: `const { recordId } = useRouteParams("/records/:recordId")`. With a generated route table, a typo in the path *or* a param name is a typecheck error. |
+| `useTerpNavigate` | Navigate by manifest path: `navigate({ to: "/records/:recordId", params: { recordId } })`. An undeclared path is a typecheck error and a parameterised route requires its params — a typo'd path used to be a dead link that shipped green. Takes the manifest's `:id` spelling and translates to the router's `$id`. |
 | `ModuleNav` | Secondary horizontal tabs for intra-module sub-pages (real routes, not state). |
 | `PageActions` | Primary action + overflow menu for a page header. |
 
+### Typed route paths and params (generated, ADR 0092)
+
+`buildAppRouter` realises routes at runtime from manifest data, which leaves TanStack
+Router's type registry empty: nothing checks a route path or a param name, so a typo'd
+path is a dead link and a typo'd param silently reads `undefined`. The manifests are
+static data, so the check is generated from them:
+
+```bash
+npm --prefix frontend run routes     # or: uv run terp routes
+```
+
+`terp-routes` reads every `src/modules/<name>/module.tsx` manifest and writes a
+**committed** `src/routes.gen.d.ts` that augments `TerpRouteTable`:
+
+```ts
+declare module "@terpjs/react-core" {
+  interface TerpRouteTable {
+    "/records": Record<never, never>;
+    "/records/:recordId": { recordId: string };
+  }
+}
+```
+
+From then on `useRouteParams("/records/:recordId")` is exact, `useRouteParam` refuses a
+param no route declares, and `useTerpNavigate` refuses an undeclared path. Regenerate
+after changing a manifest route — `terp verify`'s `routes-drift` check refuses a stale
+table and names the command (it runs before the typecheck, so a stale table reads as
+"regenerate", not as errors in your own screens). A route whose `path` is not a plain
+string literal is refused with its file and line rather than silently omitted: a partial
+table would turn a real path into a type error. Routes a packaged area mounts (the admin
+area) are not keyed — the file stays a pure function of the app's own manifests. Without
+a generated file every helper falls back to `string`, so adopting is opt-in: add the
+`routes` script, generate, commit.
+
 ### Slot-typed layout contracts (opt-in, ADR 0079)
 
 An app can ratchet the archetype control further with a named **layout contract**:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/react-core",
-  "version": "0.5.10",
+  "version": "0.6.0",
   "type": "module",
   "description": "Terp React stack core — typed @terpjs/contract client provider, auth session, capability gates, TanStack Router adapter, app shell, page archetypes, DataView and token-styled UI primitives. First frontend stack; see README.md for the component catalog.",
   "exports": {
@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "@tanstack/react-router": "^1.170.16",
-    "@terpjs/contract": "^0.5.10"
+    "@terpjs/contract": "^0.6.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/admin/GroupDetail.tsx

@@ -12,7 +12,7 @@ import { DataView, HttpDataViewRepository } from "../dataview";
 import type { DataViewColumn } from "../dataview";
 import { DetailList, Stack } from "../layout";
 import { PageActions } from "../PageActions";
-import { useRouteParam } from "../router";
+import { useDeclaredParam } from "../router";
 import { useRecord } from "../useRecord";
 import { useToast } from "../toast";
 import { Button } from "../ui/Button";
@@ -40,7 +40,7 @@ const SEARCH_DEBOUNCE_MS = 250;
  * backend resolved for them.
  */
 export function GroupDetail() {
-  const groupId = useRouteParam("groupId");
+  const groupId = useDeclaredParam("groupId");
   const client = useTerpClient();
   const navigate = useNavigate();
   const toast = useToast();

package/src/admin/UserDetail.tsx

@@ -7,7 +7,7 @@ import { Field } from "../Field";
 import { Icon } from "../icons";
 import { DetailList } from "../layout";
 import { PageActions } from "../PageActions";
-import { useRouteParam } from "../router";
+import { useDeclaredParam } from "../router";
 import { useTerpClient } from "../TerpProvider";
 import { useRecord } from "../useRecord";
 import { useToast } from "../toast";
@@ -27,7 +27,7 @@ type PendingLifecycle =
 
 /** Dedicated account detail and lifecycle page (`/admin/users/$userId`). */
 export function UserDetail() {
-  const userId = useRouteParam("userId");
+  const userId = useDeclaredParam("userId");
   const client = useTerpClient();
   const strings = useStrings();
   const toast = useToast();

package/src/index.ts

@@ -116,8 +116,24 @@ export { Field } from "./Field";
 export type { FieldProps } from "./Field";
 export { Stack, DetailList } from "./layout";
 export type { StackProps, DetailListProps, DetailItem, SpaceToken } from "./layout";
-export { buildAppRouter, DEFAULT_ROLE_RANKS, PROFILE_PATH, useRouteParam } from "./router";
+export {
+  buildAppRouter,
+  DEFAULT_ROLE_RANKS,
+  PROFILE_PATH,
+  useRouteParam,
+  useRouteParams,
+  useTerpNavigate,
+} from "./router";
 export type { BuildAppRouterOptions } from "./router";
+// The generated `routes.gen.d.ts` augments TerpRouteTable (ADR 0092); the derived types
+// are exported so an app can name a route path or a param object in its own signatures.
+export type {
+  TerpNavigateTarget,
+  TerpRouteParamName,
+  TerpRouteParams,
+  TerpRoutePath,
+  TerpRouteTable,
+} from "./routeTypes";
 export { LoginView } from "./LoginView";
 export type { DevCredentials, LoginViewProps } from "./LoginView";
 export {

package/src/routeTypes.ts

@@ -0,0 +1,63 @@
+/**
+ * The type-level route table an app's generated `routes.gen.d.ts` augments (ADR 0092).
+ *
+ * `buildAppRouter` realises routes at runtime from manifest data, so TanStack Router's
+ * own type registry is empty for every Terp app: no route path and no param name is
+ * checked anywhere, and a typo ships green. The information to check them is already
+ * checked in — the manifests are static data — so `terp routes` extracts it and emits a
+ * committed declaration file that augments this interface:
+ *
+ * ```ts
+ * declare module "@terpjs/react-core" {
+ *   interface TerpRouteTable {
+ *     "/records": Record<never, never>;
+ *     "/records/:recordId": { recordId: string };
+ *   }
+ * }
+ * ```
+ *
+ * Paths are keyed in the manifest's stack-agnostic spelling (`:recordId`, not `$recordId`),
+ * which is the spelling {@link useTerpNavigate} accepts and translates.
+ *
+ * Deliberately empty here: with no generated file the table has no keys, every helper
+ * below falls back to `string`, and an app that has not generated keeps exactly today's
+ * behavior. Generating is what turns these checks on.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmentation target
+export interface TerpRouteTable {}
+
+/** True when no `routes.gen.d.ts` has augmented {@link TerpRouteTable}. */
+type Ungenerated = keyof TerpRouteTable extends never ? true : false;
+
+/** Every route path the app's manifests declare — or `string` before generating. */
+export type TerpRoutePath = Ungenerated extends true ? string : keyof TerpRouteTable & string;
+
+/** The params of one declared route (`Record<never, never>` for a paramless route). */
+export type TerpRouteParams<P extends TerpRoutePath> = P extends keyof TerpRouteTable
+  ? TerpRouteTable[P]
+  : Record<string, string>;
+
+/**
+ * Every param name declared by any route — or `string` before generating.
+ *
+ * This is the union across all routes, not per route: it refuses a name no route
+ * declares (the reported failure mode, where a typo silently yielded `undefined`),
+ * while a name belonging to a *different* route stays a runtime refusal. Read params
+ * through {@link useRouteParams} when you want the exact, per-route check.
+ */
+export type TerpRouteParamName = Ungenerated extends true
+  ? string
+  : { [P in keyof TerpRouteTable]: keyof TerpRouteTable[P] }[keyof TerpRouteTable] & string;
+
+/**
+ * A navigation target: a declared path, plus that path's params when it takes any.
+ * A paramless route refuses a `params` object; a parameterised one requires it, with
+ * the names the manifest declared. Before generating, this is the loose shape.
+ */
+export type TerpNavigateTarget = Ungenerated extends true
+  ? { to: string; params?: Record<string, string> }
+  : {
+      [P in keyof TerpRouteTable & string]: keyof TerpRouteTable[P] extends never
+        ? { to: P; params?: undefined }
+        : { to: P; params: TerpRouteTable[P] };
+    }[keyof TerpRouteTable & string];

package/src/router.test.tsx

@@ -5,7 +5,7 @@ import { useEffect, useState } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { ModuleManifest } from "@terpjs/contract";
 
-import { buildAppRouter, useRouteParam } from "./router";
+import { buildAppRouter, useRouteParam, useRouteParams, useTerpNavigate } from "./router";
 import { Page } from "./Page";
 import { TerpProvider, useAuth } from "./TerpProvider";
 
@@ -16,6 +16,22 @@ function jsonResponse(body: unknown): Response {
   });
 }
 
+/** The login + session-probe fetch a routed test needs to reach a guarded view. */
+function sessionFetch() {
+  return vi.fn<typeof fetch>(async (input) => {
+    const url = (input as Request).url;
+    if (url.endsWith("/api/v1/auth/login")) {
+      return jsonResponse({ access_token: "t", token_type: "bearer" });
+    }
+    return jsonResponse({
+      id: "1",
+      email: "editor@example.com",
+      role_rank: 20,
+      role_name: "editor",
+    });
+  });
+}
+
 afterEach(() => {
   cleanup();
   vi.restoreAllMocks();
@@ -187,6 +203,106 @@ describe("buildAppRouter", () => {
     expect(screen.queryByRole("heading", { name: /Wrong/ })).not.toBeInTheDocument();
   });
 
+  it("useRouteParams reads a whole declared route's params, and refuses a stale one", async () => {
+    // The exact read (ADR 0092): keyed by the manifest path, every param that path
+    // declares must be present. A generated table that no longer matches the manifest
+    // therefore fails closed naming the param, instead of leaking undefined into a request.
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    vi.stubGlobal("fetch", sessionFetch());
+
+    function PairView() {
+      const { spaceId, itemId } = useRouteParams("/spaces/:spaceId/items/:itemId");
+      return <Page title={`${spaceId}/${itemId}`}>pair body</Page>;
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter(
+            [{ name: "spaces", routes: [{ path: "/spaces/:spaceId/items/:itemId", view: "Pair" }] }],
+            {
+              views: { Pair: PairView },
+              title: "Terp",
+              history: createMemoryHistory({ initialEntries: ["/spaces/s1/items/i9"] }),
+            },
+          )}
+        />
+      </TerpProvider>,
+    );
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "s1/i9" })).toBeInTheDocument(),
+    );
+    cleanup();
+
+    // The same view under a route that declares only one of the two params.
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter(
+            [{ name: "spaces", routes: [{ path: "/spaces/:spaceId", view: "Pair" }] }],
+            {
+              views: { Pair: PairView },
+              title: "Terp",
+              history: createMemoryHistory({ initialEntries: ["/spaces/s1"] }),
+            },
+          )}
+        />
+      </TerpProvider>,
+    );
+    await waitFor(() => expect(console.error).toHaveBeenCalled());
+    expect(screen.queryByRole("heading", { name: /s1/ })).not.toBeInTheDocument();
+  });
+
+  it("useTerpNavigate navigates by the manifest's path spelling, carrying params", async () => {
+    // The manifest spells a param `:id`; TanStack wants `$id`. useTerpNavigate takes the
+    // manifest spelling (what the generated table is keyed by) and translates, so a caller
+    // never holds two spellings — and the params ride along.
+    vi.stubGlobal("fetch", sessionFetch());
+
+    function ListView() {
+      const navigate = useTerpNavigate();
+      return (
+        <Page title="Things view">
+          <button type="button" onClick={() => void navigate({ to: "/things/:thingId", params: { thingId: "abc" } })}>
+            open abc
+          </button>
+        </Page>
+      );
+    }
+    function DetailView() {
+      return <Page title={`Thing ${useRouteParam("thingId")}`}>thing body</Page>;
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter(
+            [
+              {
+                name: "things",
+                routes: [
+                  { path: "/things", view: "ThingsList" },
+                  { path: "/things/:thingId", view: "ThingDetail" },
+                ],
+              },
+            ],
+            {
+              views: { ThingsList: ListView, ThingDetail: DetailView },
+              title: "Terp",
+              history: createMemoryHistory({ initialEntries: ["/things"] }),
+            },
+          )}
+        />
+      </TerpProvider>,
+    );
+
+    fireEvent.click(await screen.findByRole("button", { name: "open abc" }));
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "Thing abc" })).toBeInTheDocument(),
+    );
+  });
+
   it("gives breadcrumbs and hub cards the router's link without being asked", async () => {
     // A crumb rendered without `renderLink` used to fall back to a raw <a href>: a full
     // page reload, silently, with nothing to catch it. Inside a Terp router the default

package/src/router.tsx

@@ -4,6 +4,7 @@ import {
   createRouter,
   Link,
   Outlet,
+  useNavigate,
   useParams,
   useRouter,
   type AnyRoute,
@@ -15,6 +16,12 @@ import type { ModuleManifest } from "@terpjs/contract";
 
 import { AppShell } from "./AppShell";
 import { ProfileView } from "./ProfileView";
+import type {
+  TerpNavigateTarget,
+  TerpRouteParamName,
+  TerpRouteParams,
+  TerpRoutePath,
+} from "./routeTypes";
 import { LAYOUT_CONTRACTS, LayoutContractContext } from "./layoutContract";
 import { visibleNav } from "./nav";
 import { NavLinkContext } from "./navLink";
@@ -48,33 +55,123 @@ export function routerPath(path: string): string {
   return path.replace(/(^|\/):([A-Za-z_][A-Za-z0-9_]*)/g, "$1$$$2");
 }
 
+/** Read the router's params bag, whatever route matched (a hook: it reads router state). */
+function useCurrentParams(): Record<string, string | undefined> {
+  return useParams({ strict: false }) as Record<string, string | undefined>;
+}
+
+/** The shared refusal both param reads raise, phrased as a directive. */
+function missingParam(name: string, params: Record<string, string | undefined>): Error {
+  const seen = Object.keys(params);
+  return new Error(
+    `Route param "${name}" is not present on the current route (params seen: ` +
+      `${seen.length > 0 ? seen.join(", ") : "none"}). A param is declared in the ` +
+      `module manifest's route path (e.g. "/records/:${name}") and must be read ` +
+      "under that route — check the name against the manifest, and run `terp routes` " +
+      "if the manifest changed.",
+  );
+}
+
 /**
- * Read one route param, fail closed when it is absent.
+ * Read one route param by name, fail closed — the untyped core.
  *
- * {@link buildAppRouter} realises routes at runtime from manifest data, so TanStack's
- * type-level route registry is empty for every Terp app: `useParams` cannot check a
- * param name anywhere, and the raw idiom is an unchecked cast —
- * `useParams({ strict: false }) as { recordId?: string }` — whose typo typechecks
- * green and renders a broken screen. Until route params are generated as types
- * (ADR 0092), this is the sanctioned read: the param the manifest route path declared
- * (`/records/:recordId`) comes back as a string, and a name the current route did not
- * declare throws a directive error instead of silently yielding undefined.
+ * Internal on purpose. The app-facing {@link useRouteParam} checks the name against the
+ * app's generated route table, and this package's own packaged screens (the admin area)
+ * must NOT be checked against it: their routes come from this package's manifest, not
+ * from the app's, so constraining them to the app's declared params would fail an app
+ * that simply declares no params of its own. A packaged screen's route correctness is
+ * this package's own test surface.
  */
-export function useRouteParam(name: string): string {
-  const params = useParams({ strict: false }) as Record<string, string | undefined>;
+export function useDeclaredParam(name: string): string {
+  const params = useCurrentParams();
   const value = params[name];
   if (value === undefined) {
-    const seen = Object.keys(params);
-    throw new Error(
-      `Route param "${name}" is not present on the current route (params seen: ` +
-        `${seen.length > 0 ? seen.join(", ") : "none"}). A param is declared in the ` +
-        `module manifest's route path (e.g. "/records/:${name}") and must be read ` +
-        "under that route — check the name against the manifest.",
-    );
+    throw missingParam(name, params);
   }
   return value;
 }
 
+/**
+ * Read one route param, fail closed when it is absent.
+ *
+ * The name is checked against the app's generated route table when there is one
+ * ({@link TerpRouteParamName} — every param name any manifest route declares), and is
+ * a plain `string` before `terp routes` has generated. Either way a name the *current*
+ * route did not declare throws a directive error instead of silently yielding
+ * `undefined`, which is what the raw `useParams({ strict: false }) as {…}` cast did.
+ *
+ * Reach for {@link useRouteParams} when you want the exact, per-route check: keyed by
+ * the route path, it refuses a param that route does not declare, not merely one no
+ * route declares.
+ */
+export function useRouteParam(name: TerpRouteParamName): string {
+  return useDeclaredParam(name);
+}
+
+/**
+ * Read a declared route's params as a typed object — the exact read (ADR 0092).
+ *
+ * ```tsx
+ * const { recordId } = useRouteParams("/records/:recordId");
+ * ```
+ *
+ * Once `terp routes` has generated the app's route table, the path must be one the
+ * manifests declare and the returned object carries exactly that route's params, so a
+ * typo in either the path or a param name is a typecheck error rather than a runtime
+ * surprise. Before generating, the path is a plain `string` and the result is a
+ * string-keyed record.
+ *
+ * The path is the manifest's stack-agnostic spelling (`:recordId`). Every declared
+ * param must be present at runtime; a missing one fails closed, which is how a stale
+ * generated table (manifest changed, `terp routes` not re-run) surfaces as an error
+ * naming the param instead of `undefined` flowing into a request.
+ */
+export function useRouteParams<P extends TerpRoutePath>(path: P): TerpRouteParams<P> {
+  const params = useCurrentParams();
+  const declared = declaredParamNames(path);
+  const resolved: Record<string, string> = {};
+  for (const name of declared) {
+    const value = params[name];
+    if (value === undefined) {
+      throw missingParam(name, params);
+    }
+    resolved[name] = value;
+  }
+  return resolved as TerpRouteParams<P>;
+}
+
+/** The param names a manifest path declares, in declaration order (`:name` segments). */
+function declaredParamNames(path: string): string[] {
+  return [...path.matchAll(/(?:^|\/)[:$]([A-Za-z_][A-Za-z0-9_]*)/g)].map((match) => match[1]!);
+}
+
+/**
+ * Navigate to a declared route, with that route's params (ADR 0092).
+ *
+ * ```tsx
+ * const navigate = useTerpNavigate();
+ * void navigate({ to: "/records/:recordId", params: { recordId: row.id } });
+ * ```
+ *
+ * The reason to prefer this over the router's own `navigate`: once the route table is
+ * generated, an undeclared path is a typecheck error, a parameterised route *requires*
+ * its params, and the param names are the manifest's. A typo'd path was previously a
+ * dead link that shipped green — nothing checked it, because the route tree is built at
+ * runtime. Paths are written in the manifest spelling and translated to the router's
+ * dialect here ({@link routerPath}), so callers never hold two spellings.
+ */
+export function useTerpNavigate(): (target: TerpNavigateTarget) => Promise<void> {
+  const navigate = useNavigate();
+  return (target: TerpNavigateTarget) =>
+    navigate({
+      to: routerPath(target.to),
+      // The reducer form, not a bare object: on a router whose route tree is built at
+      // runtime TanStack types `params` as a reducer (or `true`), and merging over the
+      // previous params is also the honest semantic for an in-place param change.
+      params: (previous: Record<string, unknown>) => ({ ...previous, ...(target.params ?? {}) }),
+    });
+}
+
 export interface BuildAppRouterOptions {
   /** Maps a manifest route's `view` id to the component that renders it. */
   views: Record<string, ComponentType>;