@terpjs/react-core 0.5.9 → 0.5.10

package/README.md

@@ -71,6 +71,8 @@ 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`. 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). |
 | `ModuleNav` | Secondary horizontal tabs for intra-module sub-pages (real routes, not state). |
 | `PageActions` | Primary action + overflow menu for a page header. |
 
@@ -82,11 +84,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 +107,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.5.10",
   "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.5.10"
   },
   "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 { useRouteParam } 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 = useRouteParam("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 { useRouteParam } 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 = useRouteParam("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,7 +116,7 @@ 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 } from "./router";
 export type { BuildAppRouterOptions } from "./router";
 export { LoginView } from "./LoginView";
 export type { DevCredentials, LoginViewProps } from "./LoginView";

package/src/layoutContract.test.tsx

@@ -21,6 +21,7 @@ import {
 import { OverviewPage } from "./OverviewPage";
 import { Page } from "./Page";
 import { DetailList, Stack } from "./layout";
+import { Card } from "./ui/Card";
 
 afterEach(cleanup);
 
@@ -120,6 +121,7 @@ describe("runtime slot enforcement", () => {
   it("passes a DetailPage of record sections and refuses a rogue one", async () => {
     underContract(
       <DetailPage title="Record 1" parents={[{ label: "Records", to: "/records" }]}>
+        <Card title="A section">the sanctioned visual separation, directly in the slot</Card>
         <Stack>
           <DetailList items={[{ label: "Status", value: "open" }]} />
         </Stack>

package/src/layoutContract.ts

@@ -9,6 +9,10 @@ import { createContext, useContext } from "react";
  * a `data-terp` marker on its root — and refuses the view, fail closed, with the same
  * agent-directive message the `terp/layout-contract` lint rule phrases.
  *
+ * Both halves govern the slot's DIRECT children only: an allowed container's own
+ * subtree (a Card's body, a Stack's rows) is the app's to compose — nesting content
+ * inside an allowed component is sanctioned composition, not an escape hatch.
+ *
  * This table is the TypeScript mirror of the spec-as-data source in
  * `@terpjs/eslint-boundaries/src/layouts.js` (react-core ships standalone, so it cannot
  * import a lint package); the parity test in ./layoutContract.test.tsx keeps the two
@@ -33,8 +37,9 @@ export const LAYOUT_CONTRACTS: Readonly<Record<string, LayoutContractSpec>> = {
       "The standard three-level shape: hub bodies are card grids (HubCard only), " +
       "overview bodies are data collections (DataView / ResourceList + framework " +
       "states), detail bodies are record sections (DetailList / Stack / Tabs + " +
-      "framework states). A bespoke screen composes the plain Page, which the " +
-      "contract deliberately leaves unconstrained.",
+      "framework states); Card is allowed in overview and detail bodies as the " +
+      "sanctioned visual separation between sections. A bespoke screen composes " +
+      "the plain Page, which the contract deliberately leaves unconstrained.",
     slots: {
       HubPage: {
         components: { HubCard: "hubcard" },
@@ -45,6 +50,7 @@ export const LAYOUT_CONTRACTS: Readonly<Record<string, LayoutContractSpec>> = {
           ResourceList: "resource-list",
           ModuleNav: "module-nav",
           Stack: "stack",
+          Card: "card",
           EmptyState: "empty-state",
           ErrorState: "error-state",
           LoadingState: "loading-state",
@@ -59,6 +65,7 @@ export const LAYOUT_CONTRACTS: Readonly<Record<string, LayoutContractSpec>> = {
           Tabs: "tabs",
           ModuleNav: "module-nav",
           DataView: "dataview",
+          Card: "card",
           EmptyState: "empty-state",
           ErrorState: "error-state",
           LoadingState: "loading-state",

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 } from "./router";
+import { buildAppRouter, useRouteParam } from "./router";
 import { Page } from "./Page";
 import { TerpProvider, useAuth } from "./TerpProvider";
 
@@ -126,6 +126,67 @@ describe("buildAppRouter", () => {
     }
   });
 
+  it("useRouteParam reads a declared param and refuses an undeclared name, fail closed", async () => {
+    // buildAppRouter realises routes at runtime, so TanStack's type registry cannot
+    // check a param name for any app — useRouteParam is the sanctioned read: the
+    // declared param comes back, an undeclared name throws a directive error instead
+    // of silently yielding undefined (the failure mode of the raw `as {...}` cast).
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const fetchMock = 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" });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    function ThingView() {
+      const thingId = useRouteParam("thingId");
+      return <Page title={`Thing ${thingId}`}>thing body</Page>;
+    }
+    const router = buildAppRouter(
+      [{ name: "things", routes: [{ path: "/things/:thingId", view: "Thing" }], nav: [] }],
+      {
+        views: { Thing: ThingView },
+        title: "Terp",
+        history: createMemoryHistory({ initialEntries: ["/things/abc"] }),
+      },
+    );
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider router={router} />
+      </TerpProvider>,
+    );
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "Thing abc" })).toBeInTheDocument(),
+    );
+    cleanup();
+
+    function WrongParamView() {
+      const nope = useRouteParam("thisParamDoesNotExist");
+      return <Page title={`Wrong ${nope}`}>wrong body</Page>;
+    }
+    const wrongRouter = buildAppRouter(
+      [{ name: "things", routes: [{ path: "/things/:thingId", view: "Thing" }], nav: [] }],
+      {
+        views: { Thing: WrongParamView },
+        title: "Terp",
+        history: createMemoryHistory({ initialEntries: ["/things/abc"] }),
+      },
+    );
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider router={wrongRouter} />
+      </TerpProvider>,
+    );
+    // The view throws before it can render; the screen never shows the wrong body.
+    await waitFor(() => expect(console.error).toHaveBeenCalled());
+    expect(screen.queryByRole("heading", { name: /Wrong/ })).not.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,
+  useParams,
   useRouter,
   type AnyRoute,
   type RouterHistory,
@@ -47,6 +48,33 @@ export function routerPath(path: string): string {
   return path.replace(/(^|\/):([A-Za-z_][A-Za-z0-9_]*)/g, "$1$$$2");
 }
 
+/**
+ * Read one route param, fail closed when it is absent.
+ *
+ * {@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.
+ */
+export function useRouteParam(name: string): string {
+  const params = useParams({ strict: false }) as Record<string, string | undefined>;
+  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.",
+    );
+  }
+  return value;
+}
+
 export interface BuildAppRouterOptions {
   /** Maps a manifest route's `view` id to the component that renders it. */
   views: Record<string, ComponentType>;

package/src/ui/Badge.tsx

@@ -26,7 +26,11 @@ const toneColor: Record<BadgeTone, string> = {
   danger: "var(--color-status-danger)",
 };
 
-const toneSoft: Record<BadgeTone, string> = {
+/**
+ * Soft tint per tone — exported (not via the package barrel) so DataView's row/card
+ * tinting resolves a tone to the exact same tokens the Badge pill uses.
+ */
+export const toneSoftColors: Record<BadgeTone, string> = {
   neutral: "var(--color-neutral-100)",
   info: "var(--color-status-info-soft)",
   success: "var(--color-status-success-soft)",
@@ -37,11 +41,11 @@ const toneSoft: Record<BadgeTone, string> = {
 const badgeStyle = (tone: BadgeTone): CSSProperties => ({
   display: "inline-flex",
   alignItems: "center",
-  border: `1px solid ${toneSoft[tone]}`,
+  border: `1px solid ${toneSoftColors[tone]}`,
   borderRadius: "var(--radius-full)",
   padding: "2px var(--space-2)",
   color: toneColor[tone],
-  background: toneSoft[tone],
+  background: toneSoftColors[tone],
   fontSize: "var(--font-size-xs)",
   fontWeight: "var(--font-weight-semibold)" as never,
   lineHeight: 1.4,

package/src/ui/Card.tsx

@@ -52,9 +52,11 @@ const descriptionStyle: CSSProperties = {
 
 /**
  * A token-styled surface that groups one block of a page — the sanctioned way to give
- * sections visual separation (border + background + padding) without module CSS. An
- * optional header row carries a semantic `<h3>` title, a muted description and an
- * `actions` slot; the body stacks its children on the token spacing scale.
+ * sections visual separation (border + background + padding) without module CSS, and
+ * allowed directly in `OverviewPage` / `DetailPage` body slots under the `standard`
+ * layout contract. An optional header row carries a semantic `<h3>` title, a muted
+ * description and an `actions` slot; the body stacks its children on the token
+ * spacing scale.
  */
 export function Card({
   title,

package/src/unwrap.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { ApiError, unwrap } from "./unwrap";
+import { ApiError, unwrap, unwrapOptional } from "./unwrap";
 
 function response(status: number): Response {
   return new Response(null, { status });
@@ -65,3 +65,34 @@ describe("unwrap", () => {
     expect(apiError.message).toBe("Row changed.");
   });
 });
+
+describe("unwrapOptional", () => {
+  it("returns the data on a 2xx result, like unwrap", () => {
+    expect(unwrapOptional({ data: { id: "s1" }, response: response(200) })).toEqual({
+      id: "s1",
+    });
+  });
+
+  it("returns null on a 404 — absence is a normal state, not a failure", () => {
+    expect(
+      unwrapOptional({
+        error: { code: "not_found", detail: "No snapshot published yet." },
+        response: response(404),
+      }),
+    ).toBeNull();
+  });
+
+  it("throws the same ApiError as unwrap for every other failure", () => {
+    let caught: unknown;
+    try {
+      unwrapOptional({
+        error: { code: "permission_denied", detail: "You do not have permission." },
+        response: response(403),
+      });
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(ApiError);
+    expect((caught as ApiError).status).toBe(403);
+  });
+});

package/src/unwrap.ts

@@ -40,6 +40,22 @@ export class ApiError extends Error {
   }
 }
 
+/**
+ * {@link unwrap} for a resource whose absence is a normal state, not a failure: returns
+ * the data on success, `null` on a 404, and throws the same {@link ApiError} for every
+ * other failure. The client-side analog of the backend's `BaseService.find` beside
+ * `get` — reach for `unwrap` when a missing record ends the request, `unwrapOptional`
+ * when "not there yet" is an answer (a `/latest` snapshot that has not been published,
+ * an optional singleton). Without it, expressing that state means exception control
+ * flow around `unwrap` at every call site.
+ */
+export function unwrapOptional<T>(result: FetchResult<T>): T | null {
+  if (result.response.status === 404) {
+    return null;
+  }
+  return unwrap(result);
+}
+
 /** Return the result's `data` on success, or throw an {@link ApiError} describing the failure. */
 export function unwrap<T>(result: FetchResult<T>): T {
   if (result.error !== undefined || !result.response.ok) {

package/src/useRecord.test.tsx

@@ -0,0 +1,81 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useRecord } from "./useRecord";
+
+afterEach(cleanup);
+
+describe("useRecord", () => {
+  it("loads on mount and exposes the record", async () => {
+    const { result } = renderHook(() =>
+      useRecord<{ id: string }>({ get: async () => ({ id: "r1" }) }),
+    );
+    expect(result.current.loading).toBe(true);
+    expect(result.current.item).toBeNull();
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.item).toEqual({ id: "r1" });
+    expect(result.current.error).toBeNull();
+  });
+
+  it("treats a null get as a normal absent state, not an error (unwrapOptional composes)", async () => {
+    const { result } = renderHook(() => useRecord<{ id: string }>({ get: async () => null }));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.item).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+
+  it("reloads when a declared dependency changes (in-place route-param navigation)", async () => {
+    const get = vi.fn(async (id: string) => ({ id }));
+    const { result, rerender } = renderHook(
+      ({ id }: { id: string }) => useRecord({ get: () => get(id) }, [id]),
+      { initialProps: { id: "r1" } },
+    );
+    await waitFor(() => expect(result.current.item).toEqual({ id: "r1" }));
+
+    rerender({ id: "r2" });
+    await waitFor(() => expect(result.current.item).toEqual({ id: "r2" }));
+    expect(get).toHaveBeenCalledTimes(2);
+
+    // A rerender with the same dependency does not refetch.
+    rerender({ id: "r2" });
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(get).toHaveBeenCalledTimes(2);
+  });
+
+  it("captures a get error as a message and its cause", async () => {
+    const { result } = renderHook(() =>
+      useRecord<string>({
+        get: async () => {
+          throw new Error("boom");
+        },
+      }),
+    );
+    await waitFor(() => expect(result.current.error).toBe("boom"));
+    expect(result.current.cause).toBeInstanceOf(Error);
+    expect(result.current.item).toBeNull();
+  });
+
+  it("mutate surfaces write failures, rejects, and reloads on success", async () => {
+    let label = "before";
+    const { result } = renderHook(() => useRecord({ get: async () => ({ label }) }));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    await act(async () => {
+      await expect(
+        result.current.mutate(async () => {
+          throw new Error("Save failed.");
+        }),
+      ).rejects.toThrow("Save failed.");
+    });
+    expect(result.current.error).toBe("Save failed.");
+
+    await act(async () => {
+      await result.current.mutate(async () => {
+        label = "after";
+      });
+    });
+    expect(result.current.item).toEqual({ label: "after" });
+    expect(result.current.error).toBeNull();
+  });
+});

package/src/useRecord.ts

@@ -0,0 +1,64 @@
+import { useRef } from "react";
+
+import { useResource } from "./useResource";
+
+/** One async record: the loaded row (or `null`) plus loading/error state and a reload. */
+export interface RecordResource<T> {
+  /** The loaded record, or `null` until the load resolves / when it does not exist. */
+  item: T | null;
+  /** True while the initial load or a reload is in flight. */
+  loading: boolean;
+  /** The last error message, or `null` when the most recent load succeeded. */
+  error: string | null;
+  /**
+   * The last caught failure itself, or `null` — typically the `ApiError` thrown by
+   * `unwrap`, whose stable `code` lets `useErrorMessage` map it to client-owned copy.
+   */
+  cause?: unknown;
+  /** Re-run the get query. */
+  reload: () => Promise<void>;
+  /** Run any record-specific mutation (patch, delete, action), surface failures, then reload. */
+  mutate: (operation: () => Promise<void>) => Promise<void>;
+}
+
+/** How a detail screen fetches its one record — typically a typed contract-client call. */
+export interface RecordSource<T> {
+  /**
+   * Fetch the record. Return `null` for "does not exist and that is a normal state"
+   * (compose with `unwrapOptional`); let `unwrap` throw when absence is an error.
+   */
+  get: () => Promise<T | null>;
+}
+
+/**
+ * The singleton counterpart of {@link useResource}: the one record a detail screen
+ * shows, instead of a collection. Before it existed every detail page spelled the
+ * record as a one-element list — `list: async () => [unwrap(await client.GET(...))]`
+ * then `items[0]` — a wart this hook deletes wherever detail pages exist.
+ *
+ * Same contract as `useResource`: `source` may be rebuilt each render (read through a
+ * ref), and `deps` (e.g. the route param the query closes over) reloads on in-place
+ * navigation between records. Implemented over `useResource` so the two state
+ * machines cannot drift.
+ */
+export function useRecord<T>(
+  source: RecordSource<T>,
+  deps: readonly unknown[] = [],
+): RecordResource<T> {
+  const sourceRef = useRef(source);
+  sourceRef.current = source;
+
+  const resource = useResource<T | null>(
+    { list: async () => [await sourceRef.current.get()] },
+    deps,
+  );
+
+  return {
+    item: resource.items[0] ?? null,
+    loading: resource.loading,
+    error: resource.error,
+    cause: resource.cause,
+    reload: resource.reload,
+    mutate: resource.mutate,
+  };
+}