@terpjs/react-core 0.5.9 → 0.6.0

package/README.md

@@ -71,9 +71,47 @@ runtime, fail closed (ADR 0059), so every screen keeps the breadcrumb/title/erro
 | `OverviewPage` | A module's top-level listing screen (level 2); detail pages crumb back to it. |
 | `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`. 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**:
@@ -82,11 +120,13 @@ An app can ratchet the archetype control further with a named **layout contract*
 `terp/layout-contract` lint half — keep the two in sync; the project template generates
 both). Each governed archetype's body slot then accepts **only** the contract's
 components — `standard`: hub bodies hold `HubCard` only; overview bodies hold
-`DataView` / `ResourceList` / `ModuleNav` / `Stack` plus the framework states
+`DataView` / `ResourceList` / `ModuleNav` / `Stack` / `Card` plus the framework states
 (`EmptyState` / `ErrorState` / `LoadingState` / `Alert`) and `ConfirmDialog`; detail
-bodies hold `DetailList` / `Stack` / `Tabs` / `ModuleNav` / `DataView` plus the same
-states. The plain `Page` stays unconstrained (the sanctioned home for a bespoke
-screen). Enforcement is two-layer and fail-closed: the lint rule checks static JSX
+bodies hold `DetailList` / `Stack` / `Tabs` / `ModuleNav` / `DataView` / `Card` plus
+the same states. The plain `Page` stays unconstrained (the sanctioned home for a
+bespoke screen). Only the slot's **direct** children are governed — an allowed
+container's own subtree (a `Card` body, a `Stack` of rows) is the app's to compose.
+Enforcement is two-layer and fail-closed: the lint rule checks static JSX
 children; the archetypes verify the rendered DOM (sanctioned components stamp a
 `data-terp` marker) and refuse a non-conforming view with the **same directive
 message** — contract, slot, what was found, what is allowed, and the fix — so a
@@ -103,9 +143,10 @@ marker, counted by the escape-hatch budget.
 | `InMemoryDataViewRepository`, `HttpDataViewRepository` | Data repositories (client-side / server-side); `useServerDataView` keeps server query state in the URL. |
 | `InMemoryViewStateRepository`, `LocalStorageViewStateRepository` | Preference persistence seam. |
 | `useResource` | An async collection: rows + loading/error + reload + create-then-reload. |
+| `useRecord` | The singleton counterpart of `useResource` — the one record a detail screen shows: `item` (or `null`) + loading/error + reload + mutate. Deletes the one-element-list wart (`list: async () => [unwrap(…)]` then `items[0]`). |
 | `useRealtimeChannel` | The sanctioned typed SSE/WebSocket seam for the optional realtime capability: mints a short-lived one-use ticket via the authenticated generated client, validates every inbound JSON payload with the channel's runtime type guard, and exposes connection state / last message / WebSocket send. App modules never touch raw transports. |
 | `ResourceList` | The standard simple CRUD list screen: titled section, write-gated create form, loading/error/empty states. Composable — screens needing more render their own React. |
-| `unwrap`, `ApiError` | Turn a generated-client result into data-or-throw; `ApiError` carries the envelope's `code` / `status` / `requestId`. |
+| `unwrap`, `unwrapOptional`, `ApiError` | Turn a generated-client result into data-or-throw; `ApiError` carries the envelope's `code` / `status` / `requestId`. `unwrapOptional` returns `null` on a 404 instead — for resources whose absence is a normal state (a `/latest` snapshot not yet published), the client-side analog of `BaseService.find` beside `get`. |
 | `FileUpload`, `useFileDownload` | The files-capability surface (ADR 0056/0057): a token-styled attachment picker that uploads through the typed client, and an authenticated download helper (a raw `<a href>` would carry no bearer token). |
 
 ## Feedback & states

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/react-core",
-  "version": "0.5.9",
+  "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.9"
+    "@terpjs/contract": "^0.6.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/DetailPage.tsx

@@ -17,7 +17,7 @@ export interface DetailPageProps extends Omit<PageProps, "breadcrumbs"> {
  * `Page` whose breadcrumb trail is the ancestor layers plus the record itself (`title`), so
  * users can always navigate back up — the shell -> overview -> detail layering by construction.
  * With a layout contract active (ADR 0079), the body slot accepts only the contract's record
- * components (e.g. `DetailList` / `Stack` / `Tabs`) — refused fail closed otherwise.
+ * components (e.g. `DetailList` / `Stack` / `Tabs` / `Card`) — refused fail closed otherwise.
  */
 export function DetailPage({ parents, ...page }: DetailPageProps) {
   return (

package/src/OverviewPage.tsx

@@ -15,7 +15,7 @@ export interface OverviewPageProps extends Omit<PageProps, "breadcrumbs"> {
  * without a redundant current-page-only crumb; detail pages under it link back here — so every
  * module's overview is constructed the same. Compose the body from `ResourceList` (or any listing UI).
  * With a layout contract active (ADR 0079), the body slot accepts only the contract's
- * listing components (e.g. `DataView` / `ResourceList`) — refused fail closed otherwise.
+ * listing components (e.g. `DataView` / `ResourceList` / `Card`) — refused fail closed otherwise.
  */
 export function OverviewPage({ parents, ...page }: OverviewPageProps): ReactNode {
   return (

package/src/admin/GroupDetail.tsx

@@ -1,4 +1,4 @@
-import { useNavigate, useParams } from "@tanstack/react-router";
+import { useNavigate } from "@tanstack/react-router";
 import { useEffect, useId, useMemo, useState } from "react";
 import type { FormEvent } from "react";
 import type { components } from "@terpjs/contract";
@@ -12,7 +12,8 @@ import { DataView, HttpDataViewRepository } from "../dataview";
 import type { DataViewColumn } from "../dataview";
 import { DetailList, Stack } from "../layout";
 import { PageActions } from "../PageActions";
-import { useResource } from "../useResource";
+import { useDeclaredParam } from "../router";
+import { useRecord } from "../useRecord";
 import { useToast } from "../toast";
 import { Button } from "../ui/Button";
 import { Input } from "../ui/Input";
@@ -39,8 +40,7 @@ const SEARCH_DEBOUNCE_MS = 250;
  * backend resolved for them.
  */
 export function GroupDetail() {
-  const params = useParams({ strict: false }) as { groupId?: string };
-  const groupId = params.groupId ?? "";
+  const groupId = useDeclaredParam("groupId");
   const client = useTerpClient();
   const navigate = useNavigate();
   const toast = useToast();
@@ -75,16 +75,14 @@ export function GroupDetail() {
     setRevoking(false);
   }, [groupId]);
 
-  const group = useResource<GroupRead>(
+  const group = useRecord<GroupRead>(
     {
-      list: async () => {
-        const row = unwrap(
+      get: async () =>
+        unwrap(
           await client.GET("/api/v1/groups/{group_id}", {
             params: { path: { group_id: groupId } },
           }),
-        );
-        return [row];
-      },
+        ),
     },
     // Reload when navigating between group detail pages in place.
     [groupId],
@@ -306,7 +304,7 @@ export function GroupDetail() {
     }
   }
 
-  const record = group.items[0];
+  const record = group.item;
   return (
     <DetailPage
       title={record?.name ?? strings.adminGroups}
@@ -317,7 +315,7 @@ export function GroupDetail() {
       renderLink={renderAdminCrumb}
       isLoading={group.loading}
       error={group.cause ?? group.error ?? undefined}
-      actions={record !== undefined ? (
+      actions={record !== null ? (
         <PageActions
           overflow={[
             {
@@ -331,7 +329,7 @@ export function GroupDetail() {
       ) : undefined}
     >
       <Stack gap={6}>
-        {record !== undefined && (
+        {record !== null && (
           <DetailList
             items={[
               { label: strings.description, value: record.description || "-" },

package/src/admin/UserDetail.tsx

@@ -1,4 +1,3 @@
-import { useParams } from "@tanstack/react-router";
 import { useEffect, useState } from "react";
 import type { components } from "@terpjs/contract";
 
@@ -8,8 +7,9 @@ import { Field } from "../Field";
 import { Icon } from "../icons";
 import { DetailList } from "../layout";
 import { PageActions } from "../PageActions";
+import { useDeclaredParam } from "../router";
 import { useTerpClient } from "../TerpProvider";
-import { useResource } from "../useResource";
+import { useRecord } from "../useRecord";
 import { useToast } from "../toast";
 import { Button } from "../ui/Button";
 import { Input } from "../ui/Input";
@@ -27,8 +27,7 @@ type PendingLifecycle =
 
 /** Dedicated account detail and lifecycle page (`/admin/users/$userId`). */
 export function UserDetail() {
-  const params = useParams({ strict: false }) as { userId?: string };
-  const userId = params.userId ?? "";
+  const userId = useDeclaredParam("userId");
   const client = useTerpClient();
   const strings = useStrings();
   const toast = useToast();
@@ -47,26 +46,25 @@ export function UserDetail() {
     setResetting(false);
   }, [userId]);
 
-  const user = useResource<UserRead>(
+  const user = useRecord<UserRead>(
     {
-      list: async () => [
+      get: async () =>
         unwrap(
           await client.GET("/api/v1/users/{user_id}", {
             params: { path: { user_id: userId } },
           }),
         ),
-      ],
     },
     [userId],
   );
-  const record = user.items[0];
+  const record = user.item;
 
   function failed(error: unknown): void {
     toast.warning(error instanceof Error ? error.message : strings.requestFailed);
   }
 
   async function onConfirmLifecycle() {
-    if (record === undefined || pendingLifecycle === null) return;
+    if (record === null || pendingLifecycle === null) return;
     setMutating(true);
     try {
       if (pendingLifecycle.kind === "role") {
@@ -93,7 +91,7 @@ export function UserDetail() {
   }
 
   async function onConfirmReset() {
-    if (record === undefined || resetPassword.trim() === "") return;
+    if (record === null || resetPassword.trim() === "") return;
     setResetting(true);
     try {
       unwrap(
@@ -132,7 +130,7 @@ export function UserDetail() {
       renderLink={renderAdminCrumb}
       isLoading={user.loading}
       error={user.cause ?? user.error ?? undefined}
-      actions={record !== undefined ? (
+      actions={record !== null ? (
         <PageActions
           secondary={
             <Button
@@ -166,7 +164,7 @@ export function UserDetail() {
         />
       ) : undefined}
     >
-      {record !== undefined && (
+      {record !== null && (
         <DetailList
           items={[
             { label: strings.email, value: record.email },

package/src/dataview/DataView.test.tsx

@@ -69,6 +69,20 @@ describe("DataView states", () => {
     render(<DataView repository={failing} columns={COLUMNS} />);
     expect(await screen.findByRole("alert")).toHaveTextContent("Could not load data.");
   });
+
+  it("tints and stamps a row whose getRowTone returns a tone (row-level state)", async () => {
+    render(
+      <DataView
+        repository={inMemoryRepo()}
+        columns={COLUMNS}
+        getRowTone={(t) => (t.status === "closed" ? "danger" : null)}
+      />,
+    );
+    const toned = (await screen.findByText("VPN access")).closest("tr");
+    expect(toned).toHaveAttribute("data-tone", "danger");
+    const untinted = screen.getByText("Broken printer").closest("tr");
+    expect(untinted).not.toHaveAttribute("data-tone");
+  });
 });
 
 describe("DataView server-side mode", () => {

package/src/dataview/DataView.tsx

@@ -3,6 +3,7 @@ import type { ReactNode } from "react";
 
 import { EmptyState } from "../EmptyState";
 import { ErrorState } from "../ErrorState";
+import type { BadgeTone } from "../ui/Badge";
 import type { UiText } from "../uiText";
 import { DataViewCardList } from "./DataViewCardList";
 import { DataViewPagination } from "./DataViewPagination";
@@ -49,6 +50,14 @@ interface DataViewBaseProps<T> {
   pageSizeOptions?: number[];
   initialPageSize?: number;
   renderExpanded?: (row: T) => ReactNode;
+  /**
+   * Row-level status tone: the *row* is in that state (a refused link, a failed run),
+   * not one of its cells — the right altitude for a validation-driven table, where a
+   * Badge cell would misattribute the verdict to a column. Tints the row/card with the
+   * tone's soft token (the same one `Badge` uses) and stamps `data-tone` on it;
+   * `null`/`undefined` leaves the row untinted.
+   */
+  getRowTone?: (row: T) => BadgeTone | null;
   /** Fully custom cards in the responsive card layout. */
   renderCard?: (row: T) => ReactNode;
   /** Custom filter controls, rendered in the toolbar. */
@@ -303,6 +312,7 @@ function DataViewInner<T>(props: DataViewProps<T>) {
           getRowId={getRowId}
           onRowClick={props.onRowClick}
           getRowLabel={props.getRowLabel}
+          getRowTone={props.getRowTone}
           renderCard={props.renderCard}
           selectionEnabled={props.enableSelection === true}
           isSelected={(id) => selectedIds.has(id)}
@@ -322,6 +332,7 @@ function DataViewInner<T>(props: DataViewProps<T>) {
           getRowId={getRowId}
           onRowClick={props.onRowClick}
           getRowLabel={props.getRowLabel}
+          getRowTone={props.getRowTone}
           isMobile={isMobile}
           sorting={state.sorting}
           onToggleSort={state.toggleSort}

package/src/dataview/DataViewCardList.tsx

@@ -1,5 +1,7 @@
 import type { CSSProperties, ReactNode } from "react";
 
+import type { BadgeTone } from "../ui/Badge";
+import { toneSoftColors } from "../ui/Badge";
 import type { UiText } from "../uiText";
 
 import { DataViewExpandToggle } from "./DataViewExpandableRow";
@@ -13,6 +15,7 @@ export interface DataViewCardListProps<T> {
   getRowId: (row: T) => string;
   onRowClick?: (row: T) => void;
   getRowLabel?: (row: T) => UiText;
+  getRowTone?: (row: T) => BadgeTone | null;
   /** Escape hatch for fully custom cards. */
   renderCard?: (row: T) => ReactNode;
   // Selection
@@ -70,16 +73,18 @@ export function DataViewCardList<T>(props: DataViewCardListProps<T>) {
         const rowId = props.getRowId(row);
         const expanded = props.isExpanded(rowId);
         const clickable = props.onRowClick !== undefined;
+        const tone = props.getRowTone?.(row) ?? null;
         return (
           <li key={rowId}>
             <div
               onClick={clickable ? () => props.onRowClick?.(row) : undefined}
               data-terp={clickable ? "dataview-card" : undefined}
+              data-tone={tone ?? undefined}
               style={{
                 display: "grid",
                 gap: "var(--space-2)",
                 padding: "var(--space-3)",
-                background: "var(--color-neutral-0)",
+                background: tone !== null ? toneSoftColors[tone] : "var(--color-neutral-0)",
                 border: "1px solid var(--color-neutral-200)",
                 borderRadius: "var(--radius-lg)",
                 boxShadow: "var(--shadow-sm)",

package/src/dataview/DataViewTable.tsx

@@ -2,6 +2,8 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import type { CSSProperties, ReactNode } from "react";
 
 import { injectTerpStyles } from "../styles";
+import type { BadgeTone } from "../ui/Badge";
+import { toneSoftColors } from "../ui/Badge";
 import type { UiText } from "../uiText";
 import { DataViewExpandToggle, DataViewExpandableRow } from "./DataViewExpandableRow";
 import { DataViewRowActions } from "./DataViewRowActions";
@@ -20,6 +22,7 @@ export interface DataViewTableProps<T> {
   getRowId: (row: T) => string;
   onRowClick?: (row: T) => void;
   getRowLabel?: (row: T) => UiText;
+  getRowTone?: (row: T) => BadgeTone | null;
   isMobile: boolean;
   // Sorting
   sorting: { id: string; desc: boolean }[];
@@ -275,15 +278,24 @@ export function DataViewTable<T>(props: DataViewTableProps<T>) {
           const rowId = props.getRowId(row);
           const expanded = props.isExpanded(rowId);
           const clickable = props.onRowClick !== undefined;
+          const tone = props.getRowTone?.(row) ?? null;
           return (
             <RowGroup key={rowId}>
               <tr
                 onClick={clickable ? () => props.onRowClick?.(row) : undefined}
                 data-terp={clickable ? "dataview-row" : undefined}
                 data-selected={props.isSelected(rowId) || undefined}
+                data-tone={tone ?? undefined}
                 style={{
                   cursor: clickable ? "pointer" : undefined,
-                  background: props.isSelected(rowId) ? "var(--color-neutral-50)" : undefined,
+                  // A row's own state outranks the selection tint — selection still
+                  // shows via the checkbox and data-selected.
+                  background:
+                    tone !== null
+                      ? toneSoftColors[tone]
+                      : props.isSelected(rowId)
+                        ? "var(--color-neutral-50)"
+                        : undefined,
                 }}
               >
                 {hasExpand && (

package/src/dataview/README.md

@@ -36,7 +36,11 @@ const columns: DataViewColumn<Ticket>[] = [
 
 const repository = new InMemoryDataViewRepository(tickets, {
   getRowId: (t) => t.id,
-  getValue: (t, col) => t[col as keyof Ticket],
+  // Annotate the field parameter and `searchFields` is checked at compile time —
+  // a misspelled entry otherwise resolves to undefined for every row, so search
+  // silently never matches it. searchFields entries are the names getValue
+  // understands (typically column ids).
+  getValue: (t, col: keyof Ticket & string) => t[col],
   searchFields: ["title", "status"],
 });
 
@@ -115,6 +119,12 @@ versioned envelope; corrupt data falls back to defaults) and
 - **Column resizing**: drag the header handle; widths update live with no persistence
   writes per pointermove and are persisted once, on pointer-up. Width precedence:
   pinned system columns → user-resized → static `meta.width` hint → auto.
+- **Row tone**: `getRowTone={(row) => tone | null}` marks the *row* as being in a
+  state (a refused link, a failed run) — the right altitude when the verdict belongs
+  to the record, not to one of its cells. The row/card is tinted with the tone's soft
+  token (the same one `Badge` uses) and stamped `data-tone`; a toned row's tint
+  outranks the selection tint. Keep cell-level `Badge`s for statuses that belong to a
+  column.
 - **Select-all-across-pages**: after selecting the whole page the toolbar offers
   "Select all N results"; batch actions then invoke their `onSelectAll` variant. The
   mode resets whenever the page selection is broken.

package/src/dataview/repositories/InMemoryDataViewRepository.ts

@@ -4,22 +4,32 @@ import type {
   DataViewResult,
 } from "../types";
 
-/** How {@link InMemoryDataViewRepository} reads and matches rows. */
-export interface InMemoryDataViewRepositoryOptions<T> {
+/**
+ * How {@link InMemoryDataViewRepository} reads and matches rows.
+ *
+ * `TField` is the union of field names `getValue` understands. Annotate getValue's
+ * field parameter (`(row, field: keyof Ticket & string) => row[field]`) and
+ * `searchFields` is checked against it at compile time — without the annotation a
+ * misspelled entry resolves to `undefined` for every row, so search silently never
+ * matches it (no error at any layer). Leaving the parameter untyped keeps today's
+ * unchecked `string` behavior.
+ */
+export interface InMemoryDataViewRepositoryOptions<T, TField extends string = string> {
   /** Stable row identity. */
   getRowId: (row: T) => string;
   /** The raw sortable/filterable value of a column for a row. */
-  getValue: (row: T, columnId: string) => unknown;
+  getValue: (row: T, columnId: TField) => unknown;
   /**
    * Column ids the free-text search matches against (case-insensitive substring).
-   * Omit to disable search (`capabilities.search` becomes false).
+   * Omit to disable search (`capabilities.search` becomes false). Checked against
+   * getValue's declared field union (`NoInfer` keeps a typo here from widening it).
    */
-  searchFields?: string[];
+  searchFields?: NoInfer<TField>[];
   /**
    * Custom filter match; the default is faceted equality (`value` is the filter value or,
    * when an array, any-of).
    */
-  matchesFilter?: (row: T, columnId: string, value: unknown) => boolean;
+  matchesFilter?: (row: T, columnId: TField, value: unknown) => boolean;
 }
 
 function defaultMatchesFilter(cell: unknown, value: unknown): boolean {
@@ -57,18 +67,21 @@ function compareValues(a: unknown, b: unknown): number {
  * ```ts
  * const repo = new InMemoryDataViewRepository(tickets, {
  *   getRowId: (t) => t.id,
- *   getValue: (t, col) => t[col as keyof Ticket],
+ *   // Annotating the field parameter makes searchFields compile-checked.
+ *   getValue: (t, col: keyof Ticket & string) => t[col],
  *   searchFields: ["title", "assignee"],
  * });
  * ```
  */
-export class InMemoryDataViewRepository<T> implements DataViewRepository<T> {
+export class InMemoryDataViewRepository<T, TField extends string = string>
+  implements DataViewRepository<T>
+{
   readonly capabilities: DataViewRepository<T>["capabilities"];
 
   private rows: T[];
-  private readonly options: InMemoryDataViewRepositoryOptions<T>;
+  private readonly options: InMemoryDataViewRepositoryOptions<T, TField>;
 
-  constructor(rows: T[], options: InMemoryDataViewRepositoryOptions<T>) {
+  constructor(rows: T[], options: InMemoryDataViewRepositoryOptions<T, TField>) {
     this.rows = rows;
     this.options = options;
     this.capabilities = {
@@ -87,11 +100,21 @@ export class InMemoryDataViewRepository<T> implements DataViewRepository<T> {
     this.rows = rows;
   }
 
+  /**
+   * Query ids arrive as plain strings ({@link DataViewQuery} is column-agnostic); the
+   * `TField` union is an authoring-time contract for the options, so the one narrowing
+   * lives here rather than at every call site. (Deliberately not named `valueOf` —
+   * that shadows `Object.prototype.valueOf`, which JS calls with no arguments.)
+   */
+  private fieldValue(row: T, columnId: string): unknown {
+    return this.options.getValue(row, columnId as TField);
+  }
+
   /** Distinct values of one column across the full (unfiltered) data set. */
   getFacetedValues(columnId: string): unknown[] {
     const seen = new Set<unknown>();
     for (const row of this.rows) {
-      seen.add(this.options.getValue(row, columnId));
+      seen.add(this.fieldValue(row, columnId));
     }
     return [...seen];
   }
@@ -102,9 +125,9 @@ export class InMemoryDataViewRepository<T> implements DataViewRepository<T> {
     for (const filter of q.filters) {
       result = result.filter((row) => {
         if (this.options.matchesFilter !== undefined) {
-          return this.options.matchesFilter(row, filter.id, filter.value);
+          return this.options.matchesFilter(row, filter.id as TField, filter.value);
         }
-        return defaultMatchesFilter(this.options.getValue(row, filter.id), filter.value);
+        return defaultMatchesFilter(this.fieldValue(row, filter.id), filter.value);
       });
     }
 
@@ -113,7 +136,7 @@ export class InMemoryDataViewRepository<T> implements DataViewRepository<T> {
     if (search !== "" && searchFields.length > 0) {
       result = result.filter((row) =>
         searchFields.some((field) =>
-          String(this.options.getValue(row, field) ?? "")
+          String(this.fieldValue(row, field) ?? "")
             .toLowerCase()
             .includes(search),
         ),
@@ -124,8 +147,8 @@ export class InMemoryDataViewRepository<T> implements DataViewRepository<T> {
       result = [...result].sort((a, b) => {
         for (const sort of q.sorting) {
           const order = compareValues(
-            this.options.getValue(a, sort.id),
-            this.options.getValue(b, sort.id),
+            this.fieldValue(a, sort.id),
+            this.fieldValue(b, sort.id),
           );
           if (order !== 0) {
             return sort.desc ? -order : order;

package/src/dataview/repositories/repositories.test.ts

@@ -74,6 +74,26 @@ describe("InMemoryDataViewRepository", () => {
     expect(repo().getFacetedValues("status")).toEqual(["open", "closed"]);
   });
 
+  it("compile-checks searchFields against getValue's declared field union", async () => {
+    // With getValue's field parameter annotated, a misspelled searchFields entry is a
+    // typecheck error instead of a search that silently never matches (the field would
+    // resolve to undefined for every row, with no error at any layer).
+    const checked = new InMemoryDataViewRepository(TICKETS, {
+      getRowId: (t) => t.id,
+      getValue: (t, col: keyof Ticket & string) => t[col],
+      searchFields: ["title", "status"],
+    });
+    const result = await checked.query(query({ search: "open" }));
+    expect(result.totalCount).toBe(3);
+
+    void new InMemoryDataViewRepository(TICKETS, {
+      getRowId: (t) => t.id,
+      getValue: (t, col: keyof Ticket & string) => t[col],
+      // @ts-expect-error — "titel" is not a field getValue understands
+      searchFields: ["titel"],
+    });
+  });
+
   it("advertises client-side capabilities (search only when fields are configured)", () => {
     expect(repo().capabilities).toEqual({ serverSide: false, search: true, searchScope: false });
     const noSearch = new InMemoryDataViewRepository(TICKETS, {

package/src/dataview/types.ts

@@ -30,6 +30,8 @@ export interface DataViewResult<T> {
  * ```ts
  * const repo = new InMemoryDataViewRepository(tickets, {
  *   getRowId: (t) => t.id,
+ *   // Annotating the field parameter makes searchFields compile-checked.
+ *   getValue: (t, col: keyof Ticket & string) => t[col],
  *   searchFields: ["title", "assignee"],
  * });
  * <DataView repository={repo} columns={columns} />

package/src/index.ts

@@ -12,6 +12,8 @@ export { Authorized, useCan } from "./Authorized";
 export type { AuthorizedProps } from "./Authorized";
 export { useResource } from "./useResource";
 export type { Resource, ResourceSource } from "./useResource";
+export { useRecord } from "./useRecord";
+export type { RecordResource, RecordSource } from "./useRecord";
 export { useRealtimeChannel } from "./realtime";
 export type {
   RealtimeChannelOptions,
@@ -19,7 +21,7 @@ export type {
   RealtimeStatus,
   RealtimeTransport,
 } from "./realtime";
-export { unwrap, ApiError } from "./unwrap";
+export { unwrap, unwrapOptional, ApiError } from "./unwrap";
 export type { FetchResult } from "./unwrap";
 export { ResourceList } from "./ResourceList";
 export type { ResourceListProps } from "./ResourceList";
@@ -44,6 +46,10 @@ export type { IconProps, NavIconProps } from "./icons";
 export { ProfileView } from "./ProfileView";
 export { Breadcrumbs } from "./Breadcrumbs";
 export type { BreadcrumbItem, BreadcrumbsProps, RenderBreadcrumbLink } from "./Breadcrumbs";
+// Published by buildAppRouter; exported so a standalone story/test tree (or a bespoke
+// shell) can provide the ambient link renderer the layout components default to.
+export { NavLinkContext, useNavLink } from "./navLink";
+export type { NavLinkRenderer } from "./navLink";
 export { Page } from "./Page";
 export type { PageProps } from "./Page";
 export { LAYOUT_CONTRACTS } from "./layoutContract";
@@ -110,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 } 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 {