@tristan2828/ui-foundation 3.8.0 → 3.10.0

package/README.md

@@ -4,8 +4,8 @@
 [![release](https://github.com/Tristan2828/ui-foundation/actions/workflows/release.yml/badge.svg)](https://github.com/Tristan2828/ui-foundation/actions/workflows/release.yml)
 
 The shared layer of a family of small, contract-first, database-backed React
-apps: shadcn primitives, the `DataTable`/`EntityForm` composites, an app
-shell with session-cookie auth, the gateway's error seam, design tokens,
+apps: shadcn primitives, the `DataTable`/`EntityView`/`EntityForm`
+composites, an app shell with session-cookie auth, the gateway's error seam, design tokens,
 lint rules, Playwright suites, and the conventions an AI agent follows to
 build on it. Apps upgrade by bumping the version.
 
@@ -18,7 +18,7 @@ than installing this by hand:
 
 | Import | What |
 |---|---|
-| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityForm`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
+| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView`, `EntityForm`, `Markdown`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
 | `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, checkbox, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, switch, table, textarea, tooltip |
 | `@tristan2828/ui-foundation/gateway` | `safeFetch`, `toAppError`, `networkError` — for an app's `src/api/gateway/` only |
 | `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `resetMockAuth`, `getMockCurrentUser`, `MOCK_USER`, `exposeMswForE2E` |

package/conventions/AGENTS.md

@@ -3,8 +3,8 @@
 ## Stack
 Vite + React 19 + TypeScript, Tailwind v4, shadcn/ui (Base UI primitives),
 React Router v7, TanStack Query. The shared layer — primitives, the
-`DataTable`/`EntityForm` composites, the app shell, auth, the gateway error
-seam, design tokens, lint rules — is the npm package
+`DataTable`/`EntityView`/`EntityForm` composites, the app shell, auth,
+the gateway error seam, design tokens, lint rules — is the npm package
 `@tristan2828/ui-foundation`, updated by bumping its version. Everything in
 `src/` is this app's own.
 
@@ -75,7 +75,8 @@ is right. Do not disable, skip, or work around it.
 
 ## Required States
 Every data view handles: loading, empty, error, and success. Use
-`<Skeleton>`, `<Empty>`, and the error boundary — `DataTable` already does.
+`<Skeleton>`, `<Empty>`, and the error boundary — `DataTable` already does,
+and `EntityView` (one record) adds not found: a plain 404, never a retry.
 Every screen has one Playwright test per state, forced via MSW overrides
 (`@tristan2828/ui-foundation/testing`).
 
@@ -132,7 +133,9 @@ net.
 Follow `docs/foundation/add-an-entity.md` (in Claude Code, `/new-entity
 <Name>` is a shortcut to it). It builds from the entity's plan,
 `docs/entities/<entity>.md`; if there's no plan, work one out with the
-developer first. Never guess the fields.
+developer first. Never guess the fields. The files it copies are the
+Widgets demo's until the app removes it; after that, the `### Reference
+files` section below names the app's own.
 
 ## Upgrading the Foundation
 ```bash

package/conventions/agents/skills/new-entity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: new-entity
-description: This skill should be used when the user asks to "add an entity", "add a new entity", "scaffold a CRUD screen", "add a resource screen", or names a new domain object (e.g. "add Invoice") that needs a spec, gateway, mocks, table, and form built following this repo's widgets reference pattern.
+description: This skill should be used when the user asks to "add an entity", "add a new entity", "scaffold a CRUD screen", "add a resource screen", or names a new domain object (e.g. "add Invoice") that needs a spec, gateway, mocks, table, view and form built following this repo's widgets reference pattern.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
 ---
 

package/conventions/docs/add-an-entity.md

@@ -1,7 +1,7 @@
 # Add an Entity
 
 The most-repeated task in this system: add a full CRUD entity — spec, mocks,
-gateway, tests, table, form, routes — following the patterns in
+gateway, tests, table, view, form, routes — following the patterns in
 `src/routes/widgets/`. This file is the only copy of the steps, written for
 **any AI coding tool or a person**: follow it directly ("add a Game entity
 following docs/foundation/add-an-entity.md"). In Claude Code,
@@ -12,6 +12,30 @@ Do not skip steps or reorder them. Replace `<Entity>` with the PascalCase
 entity name (e.g. `Invoice`) and `<entity>` with its kebab-case form
 (`invoice`) throughout.
 
+## The reference files
+
+The steps name the template's Widgets demo as the code to copy:
+`src/routes/widgets/`, `src/api/gateway/widgets.ts` and
+`widget-categories.ts`, their mocks and tests. An app deletes the demo
+once its own entity works, and from then on those names point at nothing.
+So the app's `AGENTS.md`, below the foundation block, has a
+**`### Reference files`** section: for each pattern (a table, a form, a
+reference field, a multi choice and the rest), the app's own file to copy.
+
+- **That section exists:** it wins. Wherever a step below names a demo
+  file, copy the file the section names for that pattern instead. A
+  pattern it doesn't list, and the demo is gone: stop and ask which file
+  to copy. Never rebuild a pattern from this file's prose alone.
+- **It doesn't, and the demo is still here:** copy the demo, as written.
+- **When the app removes the demo:** write the section first, naming the
+  file that now holds each pattern the demo showed. The template's own
+  `AGENTS.md` has the section, filled in for the demo, as the shape.
+
+The demo's referenced entity is `WidgetCategory` (`/widget-categories`,
+the `widget_categories` table), named for its widget so it never collides
+with an app's own entity. An app whose entity is a Category builds it
+alongside the demo with no rename.
+
 ## Before anything: the entity plan
 
 **Never guess what an entity is.** Every field, type, option list and rule
@@ -32,6 +56,11 @@ is a filled-in example while the Widgets demo is still here).
   unresolved item under "Open questions", or needs a field type or screen
   shape the foundation doesn't support yet (the supported list is in the
   template). Write the case in `docs/BLOCKERS.md`.
+- **The plan's "Screens" line names a view** (`list, view, create, edit,
+  delete`), and its "View screen" section says what the view shows. A plan
+  written before the view existed has neither: ask the developer whether
+  to add them before step 1. The reference files build the table *with* a
+  view, where Edit and Delete live, so the table has no row actions.
 
 1. **Add `<Entity>` to `openapi.yaml`** — schema, list, get, create, update,
    delete — exactly as the plan specifies: its fields, types, required
@@ -64,14 +93,14 @@ is a filled-in example while the Widgets demo is still here).
    a raw sentinel instead of a "not set" label, passes `verify` unnoticed.
    One row costs nothing and step 8 asserts it. Extend `tests/mocks/conformance.test.ts` so the
    new handlers are validated against `openapi.yaml`, the same way
-   `widgets`/`categories` already are.
+   `widgets`/`widget-categories` already are.
 5. **Add a gateway module in `src/api/gateway/<entity>.ts`** until step 3's
    tests pass, built on `safeFetch`/`toAppError` from
    `@tristan2828/ui-foundation/gateway` (see `src/api/gateway/widgets.ts`).
    Wire → `Page<T>` / `AppError` translation only; no hand-written types
    (everything comes from `schema.d.ts`).
-6. **Copy the widgets reference files, one for one, not just the two
-   screens** — shaped by the plan: table columns and sortable columns from
+6. **Copy the reference files, one for one, not just the two screens**
+   (the Widgets demo's, or the ones the app's `### Reference files` names) — shaped by the plan: table columns and sortable columns from
    its "List" column, toolbar filters from its "Filter" column, form fields
    and labels from its field table, and field types by pattern (a
    `reference` field copies Category's searchable combobox, a
@@ -85,12 +114,14 @@ is a filled-in example while the Widgets demo is still here).
    `<MultiChoice>` control from the foundation on the
    form and as a toolbar filter via `useTableUrlState`'s multi filters,
    badges in the table, and a `filters` array the gateway sends as a
-   repeated parameter — and a `multi reference` copies Extra Categories:
+   repeated parameter; each option shows its label, never its wire value
+   (`quick_win` reads "Quick win"): one `Record<value, label>`
+   (`WIDGET_TAG_LABELS`) feeds `MultiChoice`'s `getLabel` and the badges — and a `multi reference` copies Extra Categories:
    the `<MultiReference>` control on the form and as a toolbar filter, an
    array of ids on the wire, a repeated any-of list filter, and names from
    a **lookup by id** on the referenced entity
-   (`GET /categories?ids=1&ids=3`, `getCategoriesByIds`,
-   `useCategoriesByIdsQuery`). Add that `ids` parameter to the referenced
+   (`GET /widget-categories?ids=1&ids=3`, `getWidgetCategoriesByIds`,
+   `useWidgetCategoriesByIdsQuery`). Add that `ids` parameter to the referenced
    entity's list endpoint if it lacks one. Never name a picked id from
    search results alone: a saved pick the current search doesn't return
    would show without a name. The table looks up every id on its page in
@@ -128,7 +159,7 @@ is a filled-in example while the Widgets demo is still here).
    once and is restored if the save fails, with a toast naming the row),
    then refetches the lists. Its specs cover a flip that saves, the
    keyboard, and a failed save putting the switch back.
-   - `src/routes/widgets/use-widgets.ts`, `use-categories.ts` →
+   - `src/routes/widgets/use-widgets.ts`, `use-widget-categories.ts` →
      `src/routes/<entity>/use-<entity>.ts` (TanStack Query hooks over the
      new gateway module)
    - `src/routes/widgets/widget-schema.ts` →
@@ -136,18 +167,85 @@ is a filled-in example while the Widgets demo is still here).
      `<Entity>Create`/`<Entity>Update`, plus the form ↔ wire conversion
      functions — see `widgetToFormValues`/`formValuesToWidgetCreate` for
      the shape)
+   - `src/routes/widgets/widget-format.ts` →
+     `src/routes/<entity>/<entity>-format.ts` (the lookups and formatters
+     both the columns and the view render values with: badge variant maps,
+     date and number formatters, the done-count)
    - `src/routes/widgets/widgets-columns.tsx` →
-     `src/routes/<entity>/<entity>-columns.tsx` (column defs; split any
-     row-action dialogs into their own file, as
-     `delete-widget-action.tsx` does — a fast-refresh hazard otherwise)
+     `src/routes/<entity>/<entity>-columns.tsx` (column defs: the plan's
+     title field is a link to the record's view, cell pattern 16, and
+     there is no row-actions column)
    - `src/routes/widgets/widgets-table.tsx` →
      `src/routes/<entity>/<entity>-table.tsx` — thin consumer of the
      foundation's `<DataTable>`. Swap the type, columns, and toolbar
      filters.
+   - `src/routes/widgets/widget-view.tsx` →
+     `src/routes/<entity>/<entity>-view.tsx` — thin consumer of the
+     foundation's `<EntityView>`. Swap the title, badges and sections for
+     the plan's "View screen" (below).
+   - `src/routes/widgets/delete-widget-action.tsx` →
+     `src/routes/<entity>/delete-<entity>-action.tsx` (Delete in the
+     view's header: the confirm dialog, then `onDeleted` leaves for the
+     list; its own file, a fast-refresh hazard otherwise)
    - `src/routes/widgets/widget-form.tsx` →
      `src/routes/<entity>/<entity>-form.tsx` — thin consumer of the
      foundation's `<EntityForm>` (its `danger` slot takes an edit-only
-     delete). Swap the zod schema and fields.
+     delete). Swap the zod schema and fields. Every way out lands on a
+     view (below).
+
+   **The view** is the read-only page for one record, at `/<entity>/:id`.
+   `<EntityView>` owns its loading skeleton, its not-found state (another
+   user's record is the same plain 404, with a way back to the list and
+   no retry) and its error state with retry. The screen supplies what the
+   plan's "View screen" section lists:
+
+   - **Title and badges.** The plan's title field is the page's `<h1>`.
+     Its badge fields sit beside it, each the same `Badge` and variant map
+     as its table cell. Edit (a `Button` rendering a `Link` to
+     `/<entity>/:id/edit`) and the delete action go in `actions`.
+   - **Sections**, one per row of the plan's section table, in order.
+     Fields are label/value rows (`fields`), labelled as on the form. A
+     section that holds one long text or one sub-record list is a block
+     (`content`) with no label of its own, since a label would only repeat
+     the heading.
+   - **Every value renders the way its table cell does**: badges, names
+     of linked records, a done-count, from the shared lookups in
+     `<entity>-format.ts`. Never re-derive one for the view.
+   - **An empty value is passed through as it is** (`null`, `''`, or
+     `list.length > 0 && …`), and `EntityView` shows the field's
+     `emptyLabel`, the plan's "not set" label, never a blank. A yes/no is
+     never empty: it reads Yes or No (cell pattern 12).
+   - **A reference links to the referenced record's view** when that
+     entity has one: the name, from the same lookup by id the table uses,
+     inside `<Link to={`/<other>/${id}`}>`. Without a view, the plain name
+     (Widget's categories have none).
+   - **Sub-records are read-only**: the done-count, then each item in
+     order with its state as a glyph and words, never a checkbox
+     (`ChecklistItems` in `widget-view.tsx`). A list of links: each an
+     `<a target="_blank" rel="noreferrer">` with an `ExternalLinkIcon`
+     and a visually hidden "(opens in a new tab)".
+   - **Long text the plan marks Markdown** renders through the
+     foundation's `<Markdown>`: headings, lists, tables and links, links
+     opening in a new tab; raw HTML shows as the characters typed, never
+     as markup. The app needs no Markdown dependency of its own. Plain
+     long text renders as text (`whitespace-pre-line` keeps its line
+     breaks).
+   - **Quick actions and editing in place aren't in the playbook yet**
+     (flipping a yes/no, changing a status or ticking an item from the
+     view). Don't build them on your own: a row's value can hold a control
+     and `actions` takes any buttons, so they'll slot in once a release
+     adds them.
+
+   **The table opens the view, and the form returns to it.** The title
+   column's link is the way in (a `yes/no` marked `toggle` stays in its
+   row). Saving an edit, or cancelling one, goes back to the record's view;
+   creating opens the new record's view (the id the create returns);
+   cancelling a create goes back to the list. Each navigates with
+   `{ replace: true }`, so Back from the view doesn't reopen the form. The
+   create and update mutations put the saved record into its detail cache
+   (`setQueryData`), so the view shows the save at once, and the delete
+   mutation drops it (`removeQueries`), so the view it leaves never
+   refetches a record that's gone (`use-widgets.ts`).
 
    **`<SelectValue>` shows the value, not the label.** Base UI renders the
    raw *value*, and `placeholder` only applies when the value is `null`.
@@ -213,14 +311,26 @@ is a filled-in example while the Widgets demo is still here).
      them choose. That is how every pattern in the catalogue was picked.
    - Any colour involved: [`design-language.md`](design-language.md). Most
      values should stay grey, and colour is never the only signal.
-7. **Register routes** for `/<entity>`, `/<entity>/new`,
-   `/<entity>/:id/edit` in `src/App.tsx`, and add a nav entry to
-   `src/nav.ts`.
-8. **Add Playwright specs for both screens**, one test per state
+7. **Register routes** for `/<entity>`, `/<entity>/new`, `/<entity>/:id`
+   (the view) and `/<entity>/:id/edit` in `src/App.tsx`, and add a nav
+   entry to `src/nav.ts`.
+8. **Add Playwright specs for all three screens**, one test per state
    (`loading`, `empty`, `error`, `validation`, `success`), forced through
    MSW overrides — `forceMswOverride`, `waitForMswReady` and the
    `window.__msw` handle from `@tristan2828/ui-foundation/testing`, and
-   `e2e/widgets-table.spec.ts`/`e2e/widget-form.spec.ts` for the pattern.
+   `e2e/widgets-table.spec.ts`/`e2e/widget-form.spec.ts`/
+   `e2e/widget-view.spec.ts` for the pattern. The view's states are
+   loading, not found (a 404: "Not found", the way back, no retry), error
+   (a failed load, then Try again recovering) and success (every section,
+   each value as its cell shows it), plus the sparse record showing its
+   "not set" labels and no blank value. Its flows: the table's title link
+   opens it, saving and cancelling the form return to it, creating opens
+   the new record's view, and Delete confirms then lands on the list. If
+   the plan has Markdown long text, a test forces a record whose text has
+   a heading, a list, a table, a link and raw HTML, and asserts the HTML
+   shows as text. Add the view's spec to `playwright.config.ts`'s
+   `mobile-chrome` `testMatch`, with a test that at phone width each
+   label sits above its value and nothing scrolls sideways.
    States forced via a first-load init script (loading, load-time error)
    need `page.addInitScript` before navigation; states forced after the
    page is already up (a mutation's error response) can use a
@@ -232,9 +342,11 @@ is a filled-in example while the Widgets demo is still here).
    which cannot see requests the MSW service worker makes
    (`e2e/msw-contract.spec.ts` has an example).
 9. **Register the nav entry and route names** in `e2e/shell.spec.ts`'s
-   `NAV_ENTRIES` so the shell smoke test covers the new screen, and add
-   `/<entity>/new` to `e2e/a11y.spec.ts`'s `formRoutes` (the table page is
-   picked up from the sidebar automatically; the form isn't in it).
+   `NAV_ENTRIES` so the shell smoke test covers the new screen, add
+   `/<entity>/new` to `e2e/a11y.spec.ts`'s `formRoutes`, and add the view
+   of a full record and of the sparse one to its `viewRoutes` (the table
+   page is picked up from the sidebar automatically; the form and the view
+   aren't in it).
 10. **`npm run verify`.** Fix until it passes. Then stop — do not add
     anything beyond what this list covers; note ideas in the app's
     backlog instead.
@@ -244,8 +356,8 @@ is a filled-in example while the Widgets demo is still here).
 - `src/api/gateway/widgets.ts`, `src/mocks/data.ts`, `src/mocks/handlers.ts`
   are demo-domain content — write the entity's own versions rather than
   adapting these by find-and-replace.
-- The composites (`DataTable`, `EntityForm`, `ErrorState`, `AppShell`)
-  are the foundation's and shared by every app. If a new entity needs a
+- The composites (`DataTable`, `EntityForm`, `EntityView`, `Markdown`,
+  `ErrorState`, `AppShell`) are the foundation's and shared by every app. If a new entity needs a
   capability they don't have (a new field-type widget, say), don't copy
   one into `src/` to change it: raise it for the foundation (AGENTS.md
   "Changing the Foundation") and build the screen once the release ships.

package/conventions/docs/cell-patterns.md

@@ -7,8 +7,9 @@ per-entity, and only the shape is reusable. Copy the markup into your
 
 Patterns 1–10 were each chosen for a real column, from a page of
 alternatives ([`column-options.md`](column-options.md)), not designed in the abstract.
-Pattern 12 (boolean) is the template's own reference: Widget's In Stock
-column renders it and its specs pin it. The other patterns from 11 on are
+Patterns 12 (boolean) and 16 (title linking to its view) are the
+template's own references: Widget's In Stock and Name columns render them
+and their specs pin them. The other patterns from 11 on are
 marked **Unproven**: written ahead of a real
 column, so no app has tested them on real data yet. Prefer a proven
 pattern when one fits. When you use an unproven one, say so in the
@@ -350,3 +351,40 @@ now", "happened"). Widget's In Stock column is the reference
   stable").
 - **Cost:** one click changes data, with no confirmation. Only for values
   that are cheap to flip back; never for anything destructive.
+
+## 16. Title linking to the record's view
+
+The column that names a record (its name or title), when the entity has a
+view (`/<entity>/:id`). Widget's Name column is the reference
+(`src/routes/widgets/widgets-columns.tsx`).
+
+```tsx
+const TITLE_LINK_CLASS =
+  'rounded-sm font-medium text-foreground underline-offset-4 outline-none hover:underline ' +
+  'focus-visible:underline focus-visible:ring-3 focus-visible:ring-ring/50'
+
+cell: ({ row }) => (
+  <Link to={`/widgets/${row.original.id}`} className={TITLE_LINK_CLASS}>
+    {row.original.name}
+  </Link>
+)
+```
+
+- **A plain `Link`, not a `Button`.** It goes somewhere and does nothing
+  else; a button-styled title down every row is a wall of buttons
+  (pattern 7's cost).
+- **The record's own name is the link text**, so each row's link is
+  already distinct for a screen reader, with no `aria-label`.
+- `font-medium` marks it as the row's name; the underline appears on hover
+  and keyboard focus. Foreground, not `text-primary`: it's the row's
+  heading, and a column of coloured text pulls the eye from every other
+  column.
+- **The view replaces the row actions.** Edit and Delete live in the
+  view's header, so a table whose title links to a view has no actions
+  column. A `yes/no` marked `toggle` (pattern 15) stays in its row.
+- **A reference to another record** (a cell showing a linked record's
+  name) uses the same link when *that* entity has a view, pointing at
+  `/<other>/${id}`, on the table and on the view alike.
+- **Cost:** none to speak of. Specs that match the title as a cell still
+  work (`getByRole('cell', { name })` reads the link's text); ones that
+  opened the form from a row button go through the view's Edit instead.

package/conventions/docs/entity-plan-template.md

@@ -23,12 +23,15 @@ One or two sentences: what one record is, and who uses the screens.
 - **Field**: camelCase, as it appears in the API (`releaseDate`).
 - **Type** — what the foundation supports today:
   - *Demonstrated by the Widget reference* (copied directly): `text` (one
-    line), `long text`, `decimal` (fixed places — say how many),
+    line), `long text` (say `Markdown` when it's written in Markdown, like
+    notes or a write-up: the view renders its headings, lists, tables and
+    links, and it's never a table column), `decimal` (fixed places — say how many),
     `date-time`, `email`, `yes/no` (a boolean that is always yes or no:
     say its default and the filter's three labels, e.g. Any stock /
     In stock / Out of stock), `single choice` (list the options, in display
     order; see the note below if it is *optional*), `multi choice` (list
-    the options; any number can be picked —
+    the options, with a label for any whose wire value isn't fit to show,
+    e.g. `quick_win` (Quick win); any number can be picked —
     chips on the form, badges in the table, an any-of filter), `reference`
     (to another entity — name it; a searchable combobox), `multi reference`
     (to any number of records of another entity — name it; chips with a
@@ -55,7 +58,8 @@ One or two sentences: what one record is, and who uses the screens.
   a screen — a Base UI `Select` can't take `""` as an item value, so the
   pattern needs a sentinel and gets the display wrong without one.
 - **List**: `column` if it shows in the table, and `sortable` if you can
-  sort by it; blank if it's form-only. A `yes/no` can also say `toggle`:
+  sort by it; blank if it's only on the form and the view. The title
+  field's column links to the record's view. A `yes/no` can also say `toggle`:
   flipped straight from its row, saved on its own (cell pattern 15).
 - **Filter**: `search` (the text search box), `yes` (a filter control), or
   blank.
@@ -71,6 +75,8 @@ per list; delete the section if there are none.
 - Most items: 50.
 - In the table: a done-count (`2/6 done`), or blank if the list isn't
   shown.
+- On the view: always shown, read-only: the done-count, then each item in
+  order (a `url` item field opens in a new tab).
 
 | Field | Label | Type | Required | Options / rules |
 |---|---|---|---|---|
@@ -88,10 +94,34 @@ per list; delete the section if there are none.
 - Page size: 10 unless there's a reason.
 - Anything else the table must show or do:
 
+## View screen
+
+The read-only page for one record (`/<entity>/:id`), opened by clicking
+its title in the table. Edit and Delete live in its header, so the table
+has no row actions. Every field it shows renders as its table cell does.
+
+- Title: the field that names a record, shown as the page heading and
+  linked from the table: `title`.
+- Badges beside the title: a few status-like fields, as badges: `status`,
+  `priority`.
+- Sections, in order. Each lists its fields in the order they show. A
+  section holding a single long text or a single sub-records list shows
+  it under the section's heading, with no label of its own.
+
+| Section | Fields |
+|---|---|
+| Details | dueDate, project, tags |
+| Checklist | checklist |
+| Notes | notes |
+
+- "Not set" labels: what an empty optional field reads as on the view
+  (`dueDate`: No due date; `checklist`: No items). A field not listed here
+  reads "Not set". A `yes/no` is never empty: it reads Yes or No.
+
 ## Screens and access
 
-- Screens: list, create, edit, delete (the only shape the playbook builds
-  today).
+- Screens: list, view, create, edit, delete (the shape the playbook
+  builds).
 - Ownership: **shared** (every signed-in user sees every record) or
   **per-user** (each user sees only their own).
 

package/dist/components/app/entity-view.d.ts

@@ -0,0 +1,48 @@
+import { type ReactNode } from 'react';
+import type { AppError } from '../../api/contracts.js';
+export type EntityViewField = {
+    label: string;
+    /**
+     * The value as the screen renders it. `null`, `undefined`, `false`, `''`
+     * and an empty array all count as empty and show `emptyLabel` instead,
+     * so `{tags.map(...)}` or `{email}` can be passed as they are.
+     */
+    value: ReactNode;
+    /** What an empty value reads as: the plan's "not set" label. Defaults to "Not set". */
+    emptyLabel?: string;
+};
+/**
+ * A titled card on the view: either label/value rows (`fields`), or one
+ * block of content under the heading with no label of its own (`content`),
+ * for long text (`<Markdown>`) or a sub-record list, where a label would
+ * only repeat the heading. A block that's empty shows `emptyLabel`, the
+ * same rule as a field.
+ */
+export type EntityViewSection = {
+    /** The section's heading (an <h2>). Unique on the page. */
+    title: string;
+    fields: EntityViewField[];
+} | {
+    title: string;
+    content: ReactNode;
+    emptyLabel?: string;
+};
+export type EntityViewProps = {
+    /** The record's name or title, the page's <h1>. */
+    title?: string;
+    /** A few status-like values beside the title, as `<Badge>`s. */
+    badges?: ReactNode;
+    /** The header's actions: an Edit button, a Delete with its confirm dialog. */
+    actions?: ReactNode;
+    sections: EntityViewSection[];
+    isLoading: boolean;
+    /** A `notfound` error (including another user's record) shows "Not found" and a way back, never a retry. */
+    error?: AppError | null;
+    onRetry?: () => void;
+    /** The entity's list: a link above the title, and the not-found state's way out. */
+    back: {
+        to: string;
+        label: string;
+    };
+};
+export declare function EntityView({ title, badges, actions, sections, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;

package/dist/components/app/entity-view.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Generic read-only view of one record, the read-side partner of
+// EntityForm: the record's title with a few status badges beside it, an
+// actions area (Edit, Delete), and sections of label/value rows laid out to
+// read rather than as a form. It owns the loading, not-found and error
+// states, the way DataTable does for a list.
+//
+// Deliberately thin, like EntityForm: each value is the screen's own
+// markup, built with the same cell patterns as the table's columns
+// (badges, names of linked records, a done-count), and <Markdown> for
+// long text. This component never formats a field. What it does guarantee
+// is that an empty value reads as the plan's "not set" label, never a
+// blank.
+//
+// A value can be any markup, a control included, and `actions` takes any
+// buttons: that's the room left for quick actions on this page (a toggle,
+// a status change, ticking a checklist item) without the form.
+import { useId } from 'react';
+import { Link } from 'react-router';
+import { ArrowLeftIcon, SearchXIcon } from 'lucide-react';
+import { ErrorState } from './error-state.js';
+import { Button } from '../ui/button.js';
+import { Card, CardContent, CardHeader } from '../ui/card.js';
+import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from '../ui/empty.js';
+import { Skeleton } from '../ui/skeleton.js';
+const DEFAULT_EMPTY_LABEL = 'Not set';
+function isEmptyValue(value) {
+    return (value === null ||
+        value === undefined ||
+        value === false ||
+        value === '' ||
+        (Array.isArray(value) && value.length === 0));
+}
+function BackLink({ back }) {
+    return (_jsxs(Link, { to: back.to, className: "inline-flex w-fit items-center gap-1 rounded-sm type-label text-muted-foreground outline-none hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50", children: [_jsx(ArrowLeftIcon, { "aria-hidden": "true", className: "size-4" }), back.label] }));
+}
+function orEmptyLabel(value, emptyLabel) {
+    return isEmptyValue(value) ? (_jsx("span", { className: "text-muted-foreground", children: emptyLabel ?? DEFAULT_EMPTY_LABEL })) : (value);
+}
+// Label beside value from `sm` up; below it (a phone) the label sits
+// above its value, so nothing is squeezed into a narrow second column.
+function FieldRow({ field }) {
+    return (_jsxs("div", { className: "flex flex-col gap-1 py-3 first:pt-0 last:pb-0 sm:grid sm:grid-cols-[minmax(8rem,12rem)_1fr] sm:gap-6", children: [_jsx("dt", { className: "type-label text-muted-foreground", children: field.label }), _jsx("dd", { className: "min-w-0 type-body break-words text-foreground", children: orEmptyLabel(field.value, field.emptyLabel) })] }));
+}
+function ViewSection({ section }) {
+    const headingId = useId();
+    return (_jsx("section", { "aria-labelledby": headingId, children: _jsxs(Card, { children: [_jsx(CardHeader, { children: _jsx("h2", { id: headingId, className: "type-section-title text-foreground", children: section.title }) }), _jsx(CardContent, { children: 'fields' in section ? (_jsx("dl", { className: "flex flex-col divide-y divide-border", children: section.fields.map((field) => (_jsx(FieldRow, { field: field }, field.label))) })) : (_jsx("div", { className: "min-w-0 type-body break-words text-foreground", children: orEmptyLabel(section.content, section.emptyLabel) })) })] }) }));
+}
+function EntityViewSkeleton() {
+    return (_jsxs("div", { className: "flex max-w-4xl flex-col gap-6", "data-state": "loading", children: [_jsx(Skeleton, { className: "h-5 w-24" }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Skeleton, { className: "h-7 w-64 max-w-full" }), _jsx(Skeleton, { className: "h-5 w-40" })] }), Array.from({ length: 2 }, (_, section) => (_jsxs(Card, { children: [_jsx(CardHeader, { children: _jsx(Skeleton, { className: "h-5 w-32" }) }), _jsx(CardContent, { className: "flex flex-col gap-4", children: Array.from({ length: 4 }, (_, row) => (_jsxs("div", { className: "flex flex-col gap-1 sm:flex-row sm:gap-6", children: [_jsx(Skeleton, { className: "h-5 w-32" }), _jsx(Skeleton, { className: "h-5 flex-1" })] }, row))) })] }, section)))] }));
+}
+export function EntityView({ title, badges, actions, sections, isLoading, error, onRetry, back, }) {
+    if (error?.kind === 'notfound') {
+        // A record that doesn't exist and one that belongs to another user are
+        // the same plain 404, so this never says which. Retrying can't help.
+        return (_jsxs(Empty, { "data-state": "notfound", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyMedia, { variant: "icon", children: _jsx(SearchXIcon, {}) }), _jsx(EmptyTitle, { children: "Not found" }), _jsx(EmptyDescription, { children: error.message })] }), _jsx(EmptyContent, { children: _jsxs(Button, { size: "sm", variant: "outline", nativeButton: false, render: _jsx(Link, { to: back.to }), children: ["Back to ", back.label] }) })] }));
+    }
+    if (error)
+        return _jsx(ErrorState, { error: error, onRetry: onRetry });
+    if (isLoading)
+        return _jsx(EntityViewSkeleton, {});
+    return (_jsxs("div", { className: "flex max-w-4xl flex-col gap-6", "data-state": "success", children: [_jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: title }), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), sections.map((section) => (_jsx(ViewSection, { section: section }, section.title)))] }));
+}

package/dist/components/app/markdown.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentProps } from 'react';
+export type MarkdownProps = {
+    /** The Markdown source. Raw HTML in it is shown as text, never rendered. */
+    children: string;
+    className?: string;
+} & Omit<ComponentProps<'div'>, 'children'>;
+export declare function Markdown({ children, className, ...rest }: MarkdownProps): import("react").JSX.Element;

package/dist/components/app/markdown.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import ReactMarkdown, {} from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { cn } from 'cn';
+import { ExternalLinkIcon, SquareCheckIcon, SquareIcon } from 'lucide-react';
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../ui/table.js';
+const REMARK_PLUGINS = [remarkGfm];
+// Every element react-markdown hands over carries `node` (the syntax tree
+// node). It isn't a DOM attribute, so it's dropped before spreading.
+function omitNode(props) {
+    const rest = { ...props };
+    delete rest.node;
+    return rest;
+}
+const COMPONENTS = {
+    h1: (props) => _jsx("h3", { ...omitNode(props), className: "type-section-title mt-2 text-foreground" }),
+    h2: (props) => _jsx("h4", { ...omitNode(props), className: "type-section-title mt-2 text-foreground" }),
+    h3: (props) => _jsx("h5", { ...omitNode(props), className: "type-label mt-1 text-foreground" }),
+    h4: (props) => _jsx("h6", { ...omitNode(props), className: "type-label mt-1 text-foreground" }),
+    h5: (props) => _jsx("h6", { ...omitNode(props), className: "type-label mt-1 text-foreground" }),
+    h6: (props) => _jsx("h6", { ...omitNode(props), className: "type-label mt-1 text-foreground" }),
+    a: (props) => {
+        const { href, children, ...rest } = omitNode(props);
+        if (!href)
+            return _jsx("span", { children: children });
+        return (_jsxs("a", { ...rest, href: href, target: "_blank", rel: "noreferrer", className: "text-primary underline underline-offset-4 hover:text-primary/80", children: [children, _jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "ml-0.5 inline size-3 align-baseline" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] }));
+    },
+    ul: (props) => {
+        const { className, ...rest } = omitNode(props);
+        const isTaskList = className?.includes('contains-task-list');
+        return _jsx("ul", { ...rest, className: cn('flex flex-col gap-1', isTaskList ? 'list-none' : 'list-disc pl-6') });
+    },
+    ol: (props) => _jsx("ol", { ...omitNode(props), className: "flex list-decimal flex-col gap-1 pl-6" }),
+    li: (props) => {
+        const { className, ...rest } = omitNode(props);
+        return _jsx("li", { ...rest, className: cn(className?.includes('task-list-item') && 'flex items-start gap-2') });
+    },
+    // A GitHub task-list box (`- [x] done`). Read-only, so a glyph with its
+    // state in words, never a checkbox someone will try to tick.
+    input: ({ checked }) => checked ? (_jsx(SquareCheckIcon, { role: "img", "aria-label": "Done", className: "mt-0.5 size-4 shrink-0 text-foreground" })) : (_jsx(SquareIcon, { role: "img", "aria-label": "Not done", className: "mt-0.5 size-4 shrink-0 text-muted-foreground" })),
+    blockquote: (props) => (_jsx("blockquote", { ...omitNode(props), className: "flex flex-col gap-3 border-l-2 border-border pl-4 text-muted-foreground" })),
+    hr: () => _jsx("hr", { className: "border-border" }),
+    pre: (props) => (_jsx("pre", { ...omitNode(props), className: "overflow-x-auto rounded-lg bg-muted p-3 font-mono text-foreground [&_code]:bg-transparent [&_code]:p-0" })),
+    code: (props) => _jsx("code", { ...omitNode(props), className: "rounded bg-muted px-1 py-0.5 font-mono text-foreground" }),
+    img: (props) => {
+        const { alt, ...rest } = omitNode(props);
+        return _jsx("img", { ...rest, alt: alt ?? '', loading: "lazy", className: "max-w-full rounded-md" });
+    },
+    // GFM tables use the package's own table, zebra stripes and density
+    // tokens included, so a table in the notes reads like every other table.
+    table: (props) => _jsx(Table, { ...omitNode(props) }),
+    thead: (props) => _jsx(TableHeader, { ...omitNode(props) }),
+    tbody: (props) => _jsx(TableBody, { ...omitNode(props) }),
+    tr: (props) => _jsx(TableRow, { ...omitNode(props) }),
+    th: (props) => _jsx(TableHead, { ...omitNode(props) }),
+    td: (props) => _jsx(TableCell, { ...omitNode(props) }),
+};
+export function Markdown({ children, className, ...rest }) {
+    return (_jsx("div", { "data-slot": "markdown", ...rest, className: cn('flex min-w-0 flex-col gap-3 type-body text-foreground break-words', className), children: _jsx(ReactMarkdown, { remarkPlugins: REMARK_PLUGINS, components: COMPONENTS, children: children }) }));
+}

package/dist/components/app/multi-choice.d.ts

@@ -1,9 +1,14 @@
 import * as React from 'react';
-export declare function MultiChoice<T extends string>({ options, value, onValueChange, id, placeholder, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }: {
+export declare function MultiChoice<T extends string>({ options, value, onValueChange, getLabel, id, placeholder, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }: {
     /** Every allowed option, in display order. */
     options: readonly T[];
     value: T[];
     onValueChange: (value: T[]) => void;
+    /**
+     * The text shown for an option: on its chip, in the dropdown, and what
+     * typing matches against. Defaults to the value itself.
+     */
+    getLabel?: (value: T) => string;
     /** Id for the text input, so a <FieldLabel htmlFor> labels it. */
     id?: string;
     placeholder?: string;

package/dist/components/app/multi-choice.js

@@ -5,9 +5,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // filter — so entities reuse it rather than re-assembling the combobox
 // primitive each time. Built on shadcn's Combobox `multiple` mode, following
 // its own ComboboxMultiple example.
+//
+// Values are the wire's enum strings; `getLabel` names them when those
+// aren't fit to show (`quick_win` → "Quick win"). Chips, options and the
+// typed-text match all use the label, and the value is what's emitted.
 import * as React from 'react';
 import { Combobox, ComboboxChip, ComboboxChips, ComboboxChipsInput, ComboboxContent, ComboboxEmpty, ComboboxItem, ComboboxList, ComboboxValue, useComboboxAnchor, } from '../ui/combobox.js';
-export function MultiChoice({ options, value, onValueChange, id, placeholder, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }) {
+export function MultiChoice({ options, value, onValueChange, getLabel = String, id, placeholder, 'aria-label': ariaLabel, 'aria-invalid': ariaInvalid, className, }) {
     const anchor = useComboboxAnchor();
-    return (_jsxs(Combobox, { multiple: true, autoHighlight: true, items: options, value: value, onValueChange: (next) => onValueChange(next), children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: option }, option))), _jsx(ComboboxChipsInput, { id: id, "aria-label": ariaLabel, "aria-invalid": ariaInvalid, placeholder: selected.length === 0 ? placeholder : undefined })] })) }) }), _jsxs(ComboboxContent, { anchor: anchor, children: [_jsx(ComboboxEmpty, { children: "No options found." }), _jsx(ComboboxList, { children: (option) => (_jsx(ComboboxItem, { value: option, children: option }, option)) })] })] }));
+    return (_jsxs(Combobox, { multiple: true, autoHighlight: true, items: options, value: value, onValueChange: (next) => onValueChange(next), itemToStringLabel: getLabel, children: [_jsx(ComboboxChips, { ref: anchor, className: className, children: _jsx(ComboboxValue, { children: (selected) => (_jsxs(React.Fragment, { children: [selected.map((option) => (_jsx(ComboboxChip, { children: getLabel(option) }, option))), _jsx(ComboboxChipsInput, { id: id, "aria-label": ariaLabel, "aria-invalid": ariaInvalid, placeholder: selected.length === 0 ? placeholder : undefined })] })) }) }), _jsxs(ComboboxContent, { anchor: anchor, children: [_jsx(ComboboxEmpty, { children: "No options found." }), _jsx(ComboboxList, { children: (option) => (_jsx(ComboboxItem, { value: option, children: getLabel(option) }, option)) })] })] }));
 }

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export { AppShell, type AppShellProps, type NavItem } from './components/app/app-shell.js';
 export { DataTable, type DataTableProps, type SortingState } from './components/app/data-table.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
+export { EntityView, type EntityViewField, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
 export { ErrorState } from './components/app/error-state.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
+export { Markdown, type MarkdownProps } from './components/app/markdown.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.js';
 export { MultiReference } from './components/app/multi-reference.js';

package/dist/index.js

@@ -6,8 +6,10 @@
 export { AppShell } from './components/app/app-shell.js';
 export { DataTable } from './components/app/data-table.js';
 export { EntityForm } from './components/app/entity-form.js';
+export { EntityView, } from './components/app/entity-view.js';
 export { ErrorState } from './components/app/error-state.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
+export { Markdown } from './components/app/markdown.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.js';
 export { MultiReference } from './components/app/multi-reference.js';

package/dist/testing/index.d.ts

@@ -18,6 +18,12 @@ export type A11ySuiteOptions = {
      * plus an edit route when the form shows something only existing data has.
      */
     formRoutes: readonly string[];
+    /**
+     * Record views (`/<entity>/:id`, built on EntityView), which aren't in
+     * the sidebar either: each entity's view of a full record, plus its
+     * sparse one, so both filled values and "not set" labels are checked.
+     */
+    viewRoutes?: readonly string[];
     /** Screens outside the app shell, e.g. '/login' (and '/register' if the app has it). */
     loggedOutRoutes: readonly string[];
 };
@@ -29,7 +35,7 @@ export type A11ySuiteOptions = {
  * dark-mode tokens readable. The theme follows the OS setting, so
  * emulateMedia switches it.
  */
-export declare function defineA11ySuite({ formRoutes, loggedOutRoutes }: A11ySuiteOptions): void;
+export declare function defineA11ySuite({ formRoutes, viewRoutes, loggedOutRoutes }: A11ySuiteOptions): void;
 export type MockModeBannerSuiteOptions = {
     /** Screens to check, logged-out ones included (e.g. '/login'). */
     routes: readonly string[];

package/dist/testing/index.js

@@ -68,7 +68,7 @@ async function navRoutes(page, isMobile) {
  * dark-mode tokens readable. The theme follows the OS setting, so
  * emulateMedia switches it.
  */
-export function defineA11ySuite({ formRoutes, loggedOutRoutes }) {
+export function defineA11ySuite({ formRoutes, viewRoutes = [], loggedOutRoutes }) {
     for (const colorScheme of ['light', 'dark']) {
         test.describe(`accessibility (${colorScheme})`, () => {
             test.beforeEach(async ({ page }) => {
@@ -90,6 +90,14 @@ export function defineA11ySuite({ formRoutes, loggedOutRoutes }) {
                     await expectNoAxeViolations(page);
                 });
             }
+            for (const route of viewRoutes) {
+                test(`${route} has zero axe violations`, async ({ page }) => {
+                    await page.goto(route);
+                    // EntityView's loaded state, not its skeleton or an error.
+                    await expect(page.locator('[data-state="success"]')).toBeVisible();
+                    await expectNoAxeViolations(page);
+                });
+            }
         });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.8.0",
+  "version": "3.10.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {
@@ -134,6 +134,8 @@
     "js-yaml": "^5.4.2",
     "lucide-react": "^1.47.0",
     "react-day-picker": "^10.0.1",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
     "shadcn": "^4.21.0",
     "tw-animate-css": "^1.4.0"
   },