@tristan2828/ui-foundation 3.23.0 → 3.25.0

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

@@ -241,6 +241,13 @@ is a filled-in example while the Widgets demo is still here).
      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.
+   - **Layout.** With the plan's `Layout: rail`, pass `layout="rail"` and
+     give each section its Placement (`placement: 'rail'`; `main` is the
+     default and needs nothing). Without a `Layout` line, drop `layout`
+     and every `placement` from the copied view (one column). Widget's
+     view is `rail`, with Details in the rail. The rail's sections come
+     first in the page (header, rail, main) at every width, so the
+     view's specs find them first too.
    - **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.
@@ -318,9 +325,16 @@ is a filled-in example while the Widgets demo is still here).
      ids as a set). A field gets `edit`, a `content` section gets `edit`,
      the title gets `titleEdit={{ label, ...edit }}`, and a header badge
      wraps itself in `<EditableValue label edit layout="inline">`. The
-     shown value stays exactly as before. **With no `Edit in place` line,
-     nothing is editable in place** and none of this is copied. Never a
-     computed field or a sub-record list.
+     shown value stays exactly as before. A sub-record list the line
+     names is `editInPlace({ kind: 'list', ... })` on its `content`
+     section (cell pattern 18, "A list of sub-items"; copy `checklist` in
+     `widgetEdits`): the form's row as `renderItem`, from one component
+     shared with the form (`WidgetChecklistItemFields`), the item as the
+     view shows it (its quick action, if any) as `renderShown`, the list's
+     schema, and `save: (change) => edit.mutateAsync((current) => ({
+     <field>: change(current.<field>) }))`. **With no `Edit in place`
+     line, nothing is editable in place** and none of this is copied.
+     Never a computed field.
 
    **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
@@ -426,12 +440,21 @@ is a filled-in example while the Widgets demo is still here).
    sent; a 422 (an MSW override, the reason on the field) and a 500 stay
    open with the draft and the reason; opening a second field saves the
    first, or doesn't open if that fails; and leaving the page with
-   unsaved text asks first. Add it to `mobile-chrome`'s `testMatch`. If
+   unsaved text asks first. A list edited in place gets its own block
+   (copy `the checklist edited in place`): three items added by keyboard
+   alone and still there after leaving and coming back, an item edited
+   (Enter) and given up (Esc), move and remove with the PATCH each sends,
+   a blank item never sent, a refused change, and a tick plus an add both
+   landing. Add it to `mobile-chrome`'s `testMatch`. 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.
+   label sits above its value and nothing scrolls sideways. With
+   `Layout: rail`, that test also checks the rail's sections come before
+   the main ones, and another that on a wide screen the main column
+   starts beside the rail (copy `wide screens: …` in
+   `e2e/widget-view.spec.ts`).
    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
@@ -449,8 +472,9 @@ is a filled-in example while the Widgets demo is still here).
    page is picked up from the sidebar automatically; the form and the view
    aren't in it). With fields edited in place, copy `e2e/a11y.spec.ts`'s
    "editing in place" block for them: a field open, saving and refused,
-   the rich-text editor, an open list, and the leave prompt, in both
-   themes.
+   the rich-text editor, an open list, a list edited in place (an item
+   open, one being added, a refused change), and the leave prompt, in
+   both themes.
 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.

package/conventions/docs/cell-patterns.md

@@ -663,11 +663,11 @@ The rule behind every part of it: **nothing typed is ever lost.**
 
 **Which values.** Only those the plan's "View screen" names under `Edit
 in place`; read-only is the default, and a value not named renders
-exactly as it did. Single values only: text, long text, a single choice
-(optional ones with their "not set" option), an integer or a rating, a
-yes/no, a single or multi reference. Never a computed field, and never a
-sub-record list (adding, removing and reordering items stays on the
-form). The view's Edit button and the form stay.
+exactly as it did. Text, long text, a single choice (optional ones with
+their "not set" option), an integer or a rating, a yes/no, a single or
+multi reference, and a sub-record list (its own rules, under "A list of
+sub-items" below). Never a computed field. The view's Edit button and
+the form stay.
 
 **At rest: says it's editable without shouting.** The value reads as it
 always did. Hover tints it (`bg-muted`) and shows a pencil; the pencil is
@@ -769,6 +769,56 @@ const price = editInPlace({
   Keep it to the fields the plan names, and leave the form for everything
   else.
 
+### A list of sub-items
+
+A sub-record list (a checklist, a list of links) on a `content` section,
+edited where it's shown: `editInPlace({ kind: 'list', ... })`. Widget's
+Checklist is the reference (`checklist` in `widgetEdits`). It's built on
+`ListEditor`, so the rows and their buttons are the form's.
+
+- **Each item reads as it always did** (`renderShown`), its own controls
+  included: a done box still ticks it on its own, a quick action. A click
+  on the item (not its box, not a link in it) or its pencil ("Edit item
+  2") turns it into the form's row (`renderItem`, the same fields as the
+  form's `ListEditor` row), an editable value like any above: Enter or
+  leaving saves, Esc gives up, one open at a time.
+- **Add at the end.** "Add item" opens a new row; Enter saves it and
+  opens the next, the caret already in it, so a run of items goes in from
+  the keyboard. Esc on an empty one closes it; nothing is sent.
+- **Move and remove** are `ListEditor`'s buttons, with its names ("Move
+  item 2 up", "Remove item 2"). Each saves at once; whatever is open is
+  saved first. While it saves, the buttons wait and "Saving…" shows under
+  the list; the caret follows the item it moved. A refusal leaves the
+  list as it was, with the reason under it.
+- **One save per change, of the whole list**, built on the record's
+  latest list when it's sent: `save` is given a change, not a list, and
+  hands it to the single-field save as a function of the record, so it
+  never undoes a tick or a change still saving.
+- **The form's rules**, the whole list's schema, run on the list each
+  change would make: a message about an item shows under that item, one
+  about the list (too many items) under the row being added.
+- `content` shows above the items (the done-count) and `emptyLabel` in
+  place of them when there are none.
+
+```tsx
+const checklist = editInPlace<ChecklistItem>({
+  kind: 'list',
+  value: widget.checklist,
+  schema: widgetFormSchema.shape.checklist,                 // the whole list's rule
+  save: (change) => editField.mutateAsync((current) => ({ checklist: change(current.checklist) })),
+  newItem: () => ({ text: '', done: false }),
+  itemName: (index) => `item ${index + 1}`,                 // as the form's ListEditor names them
+  addLabel: 'Add item',
+  renderShown: (_item, index) => <ChecklistItem widget={widget} index={index} />, // the quick action
+  renderItem: (props) => <WidgetChecklistItemFields index={props.index} … />,     // the form's row
+})
+// The section: { title: 'Checklist', content: <ChecklistDoneCount …/>, emptyLabel: 'No items', edit: checklist }
+```
+
+The row's fields are one component shared with the form
+(`WidgetChecklistItemFields` in `widget-fields.tsx`), each field named by
+position ("Item 2 text") as the row buttons name the item.
+
 ## 19. Stage circle for an ordered status
 
 A status that's an ordered lifecycle (each record moves through the same

package/conventions/docs/design-language.md

@@ -105,7 +105,7 @@ lower; say so in a comment.
 
 Tones say good, bad or *notice this*. A value that is merely *different* from its
 neighbours — a genre, a team, a category — needs a different mechanism, and
-it is `--category-1` through `--category-8`.
+it is `--category-1` through `--category-12`.
 
 They are **generic slots, not per-value tokens**. An app maps its enum to a
 slot in its own columns file, so a new enum value costs a line there rather
@@ -120,31 +120,49 @@ const GENRE_COLOR: Record<Genre, string> = {
 ```
 
 Tailwind needs whole class names, so map the value to a complete class —
-never build one by interpolation, or the class won't be generated.
+never build one by interpolation, or the class won't be generated. An app
+that lets people pick a colour stores the slot's name (an enum of
+`category-1` … `category-12` in its contract, with a CHECK on the column)
+and maps each to its whole class the same way.
 
-Four things about them:
+| Slots | What they are | Near info's blue |
+|---|---|---|
+| 1–8 | eight hues, about 25° apart | 1, 6, 8 |
+| 9–12 | deeper shades of four of those hues: 9 teal (4's), 10 plum (5's), 11 olive (3's), 12 violet (2's) | none |
+
+Five things about them:
 
 - **The hues avoid red, green and amber**, which the tones already spend. A
   category drawn in red reads as "this one is bad" even when nothing is
   wrong. Info's blue came later, and slots 1, 6 and 8 sit near it: a table
   that shows an info badge keeps its categories off those three, so a blue
-  genre isn't read as "notice this".
+  genre isn't read as "notice this". That still leaves nine.
 - **They are ordered by distinctness, not by hue angle.** An app using
   three categories gets three obviously different colours. Past about five,
   hue alone stops separating them — slots 3 and 7 are both yellow-greens —
   so the glyph has to carry the meaning and the colour only reinforces it.
+- **Past eight, it's lightness, not hue.** The hues left between the tones
+  are spent, so slots 9–12 are darker shades of four of the first eight, in
+  both themes. Each is at least as far from every other slot as the first
+  eight are from each other (a unit test holds every pair to it), but a
+  deep shade beside its own hue is told apart by how dark it is, which
+  reads less readily than a hue. Use them for a set that really has more
+  than eight values, and keep a shade away from its own hue where you can
+  choose (10 isn't 5's neighbour in a list).
 - **Tint the glyph, never fill behind text.** The label stays
   `text-foreground`, so readability never depends on the hue. A slot used
   as a background needs its own contrast check, which nothing here does
   for you.
-- **The glyph check re-measures them.** All eight clear the 3:1
-  non-text minimum in both themes (recorded in `theme.css`). axe checks
-  text contrast, not icon contrast, so the package's Storybook glyph check
-  draws an icon in each slot (`patterns/CellPatterns`, "Icons with one
-  tooltip") and fails a change that takes one below 3:1.
-
-If you find yourself wanting a ninth, that is usually a sign the column
-should be showing a shape or a label rather than more colours.
+- **The glyph check re-measures them.** All twelve clear the 3:1
+  non-text minimum in both themes, on the page and on a card (recorded in
+  `theme.css`). axe checks text contrast, not icon contrast, so the
+  package's Storybook glyph check draws an icon in each slot on both
+  surfaces (`patterns/CategoricalColour`, which also shows them side by
+  side) and fails a change that takes one below 3:1.
+
+If you find yourself wanting a thirteenth, that is a sign the column should
+be showing a shape or a label rather than more colours: there is no more
+room in hue or lightness that stays readable.
 
 ## Typography
 

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

@@ -81,7 +81,8 @@ per list; delete the section if there are none.
 - On the view: always shown: the done-count, then each item in order (a
   `url` item field opens in a new tab). Read-only, unless the View
   screen's `Quick actions` names the list: then its yes/no item field is a
-  checkbox on each item, ticked in place.
+  checkbox on each item, ticked in place. If its `Edit in place` names
+  the list, its items are also added, edited, moved and removed there.
 
 | Field | Label | Type | Required | Options / rules |
 |---|---|---|---|---|
@@ -123,15 +124,27 @@ except the quick actions, if any.
   linked from the table: `title`.
 - Badges beside the title: a few status-like fields, as badges: `status`,
   `priority`.
+- Layout (optional; delete for one column): `rail` for a record with long
+  content (notes written as Markdown, long lists). The page takes the
+  screen's whole width, the short sections (a summary, label/value fields,
+  a few links) sit in a narrow column on the right that stays in view, and
+  the long ones fill the main column beside it. On a phone: one column,
+  the rail's sections first. Without this line, every section is in one
+  column, as wide as a long read.
+
+  Layout: rail
+
 - 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.
+  it under the section's heading, with no label of its own. With
+  `Layout: rail`, Placement says which column each goes in (`rail` or
+  `main`); otherwise delete the column.
 
-| Section | Fields |
-|---|---|
-| Details | dueDate, project, tags |
-| Checklist | checklist |
-| Notes | notes |
+| Section | Fields | Placement |
+|---|---|---|
+| Details | dueDate, project, tags | rail |
+| Checklist | checklist | main |
+| Notes | notes | main |
 
 - "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
@@ -150,12 +163,12 @@ except the quick actions, if any.
 - Edit in place (optional; delete if none): the fields that turn into
   their form control where the view shows them and save when you leave
   them (cell pattern 18): the title, a badge field, a field row, a long
-  text. Single values only: text, long text, a single choice, an integer
-  or a rating, a yes/no, a single or multi reference. Never a computed
-  field or a sub-records list (those stay on the form). Every value not
-  named here, or under Quick actions, stays read-only. Say any rule the
-  server enforces on one (its refusal shows under the field) and any
-  side effect:
+  text, a sub-records list (its items added, edited, moved and removed on
+  the view). Text, long text, a single choice, an integer or a rating, a
+  yes/no, a single or multi reference, a sub-records list. Never a
+  computed field. Every value not named here, or under Quick actions,
+  stays read-only. Say any rule the server enforces on one (its refusal
+  shows under the field) and any side effect:
 
   Edit in place: title, status (the server refuses Finished while the
   checklist has open items), dueDate, notes

package/dist/components/app/data-table.js

@@ -43,15 +43,18 @@ function TableSkeleton({ columnCount }) {
 // bleed-through a solid background avoids. On an even row it's the stripe
 // pre-mixed onto the page (--table-stripe), so the stripe runs the whole
 // row's width (issue #92); `:where()` keeps that rule's specificity at the
-// background's, so the hover below still wins on every row. The pinned
-// cell carries the hover highlight. --accent is only ~3% off the page
-// background, so a solid left edge marker carries the signal; an inset
-// shadow rather than a border, so nothing reflows.
-const PINNED_CELL_CLASS = 'z-10 bg-background [:where(tbody>tr:nth-child(even))>&]:bg-(--table-stripe) group-hover/row:bg-accent';
-const PINNED_COLUMN_CLASS = `sticky left-0 border-r ${PINNED_CELL_CLASS} group-hover/row:shadow-[inset_3px_0_0_0_var(--primary)]`;
-// The right-edge mirror, opaque for the same reason. Its edge marker points
-// inward from the right, so the two pinned columns bracket the row.
-const PINNED_LAST_COLUMN_CLASS = `sticky right-0 border-l ${PINNED_CELL_CLASS} group-hover/row:shadow-[inset_-3px_0_0_0_var(--primary)]`;
+// background's, so the first column's hover below still wins on every row.
+const PINNED_CELL_CLASS = 'z-10 bg-background [:where(tbody>tr:nth-child(even))>&]:bg-(--table-stripe)';
+// The pinned first cell carries the hover highlight. --accent is only ~3%
+// off the page background, so a solid left edge marker carries the signal;
+// an inset shadow rather than a border, so nothing reflows.
+const PINNED_COLUMN_CLASS = `sticky left-0 border-r ${PINNED_CELL_CLASS} group-hover/row:bg-accent ` +
+    'group-hover/row:shadow-[inset_3px_0_0_0_var(--primary)]';
+// The right-edge mirror, opaque for the same reason, but with no hover
+// highlight (issue #103): it holds the row's actions, which name nothing,
+// so lighting it too read as a second selected thing. Only the first
+// column marks the hovered row.
+const PINNED_LAST_COLUMN_CLASS = `sticky right-0 border-l ${PINNED_CELL_CLASS}`;
 // A pinned first column's content, capped below md at 45% of the table's
 // scroll area (`cqw`: the container is an inline-size query container)
 // and wrapping, so a long title can't widen the column past the screen
@@ -189,7 +192,7 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                                                     : sortDirection === 'desc'
                                                         ? 'descending'
                                                         : 'none', children: pinFirstColumn && index === 0 ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: content })) : (content) }, header.id));
-                                    }) }, headerGroup.id))) }), _jsx(TableBody, { children: table.getRowModel().rows.map((row) => (_jsx(TableRow, { className: cn((pinFirstColumn || pinLastColumn) && ROW_GROUP_CLASS), children: row.getVisibleCells().map((cell, index) => (_jsx(TableCell, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn &&
+                                    }) }, headerGroup.id))) }), _jsx(TableBody, { children: table.getRowModel().rows.map((row) => (_jsx(TableRow, { className: cn(pinFirstColumn && ROW_GROUP_CLASS), children: row.getVisibleCells().map((cell, index) => (_jsx(TableCell, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn &&
                                             index === row.getVisibleCells().length - 1 &&
                                             PINNED_LAST_COLUMN_CLASS, cell.column.columnDef.meta?.align === 'center' && 'text-center'), children: pinFirstColumn && index === 0 ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: flexRender(cell.column.columnDef.cell, cell.getContext()) })) : (flexRender(cell.column.columnDef.cell, cell.getContext())) }, cell.id))) }, row.id))) })] }), pinFirstColumn && isOverflowing && (_jsx("div", { ref: barRef, "aria-hidden": "true", tabIndex: -1, "data-slot": "bottom-scrollbar", className: "sticky bottom-0 z-20 h-4 overflow-x-auto border-t border-border bg-background", children: _jsx("div", { style: { width: scrollWidth, height: 1 } }) })), _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("p", { className: "type-body text-muted-foreground", children: [total === 0 ? 0 : (page - 1) * pageSize + 1, '–', Math.min(page * pageSize, total), " of ", total] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Previous page", disabled: page <= 1, onClick: () => onPageChange(page - 1), children: _jsx(ChevronLeftIcon, {}) }), _jsxs("span", { className: "type-body text-muted-foreground", children: ["Page ", page, " of ", pageCount] }), _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Next page", disabled: page >= pageCount, onClick: () => onPageChange(page + 1), children: _jsx(ChevronRightIcon, {}) })] })] })] }))] }));
 }

package/dist/components/app/edit-in-place-store.d.ts

@@ -36,6 +36,8 @@ export type OpenFieldState = {
     /** A problem the control reports itself (rich text that can't save as it stands). */
     problem: string | null;
 };
+/** Why a save failed, in words to show beside what was being saved. */
+export declare function messageOf(error: unknown): string;
 export declare class EditInPlaceStore {
     private configs;
     private states;

package/dist/components/app/edit-in-place-store.js

@@ -1,7 +1,8 @@
 import { refusalReason } from '../../hooks/use-record-update.js';
 const CLOSED = { status: 'closed' };
 const sameAsJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
-function messageOf(error) {
+/** Why a save failed, in words to show beside what was being saved. */
+export function messageOf(error) {
     if (error && typeof error === 'object' && 'kind' in error)
         return refusalReason(error);
     if (error instanceof Error)

package/dist/components/app/edit-in-place.d.ts

@@ -44,6 +44,7 @@ type SafeParseResult<TValue> = {
     error: {
         issues: readonly {
             message: string;
+            path?: readonly PropertyKey[];
         }[];
     };
 };
@@ -82,6 +83,67 @@ export type EditInPlaceOptions<TDraft, TValue> = {
     /** Whether a draft is still the saved value. Defaults to comparing as JSON. */
     isEqual?: (a: TDraft, b: TDraft) => boolean;
 };
+/** What a list item's fields are given while it's edited: a control's props, plus where the item is. */
+export type EditListItemProps<TItem> = EditControlProps<TItem> & {
+    /** The item's position; for the item being added, the one it will take (the list's length). */
+    index: number;
+    /** The item being added at the end, not one already in the list. */
+    isNew: boolean;
+};
+/**
+ * A list of sub-items edited in place (a checklist, a list of links), on
+ * a `content` section of EntityView. Make one with `editInPlace({ kind:
+ * 'list', ... })`. Every item reads as `renderShown` (a quick action, such
+ * as its done box, still works there); clicking it or its pencil turns it
+ * into `renderItem`, the form's own row. "Add" at the end opens a new item;
+ * move up, move down and remove are ListEditor's buttons. Each change is one
+ * save of the whole list.
+ */
+export type EditInPlaceListOptions<TItem> = {
+    kind: 'list';
+    /** The saved list. */
+    value: readonly TItem[];
+    /**
+     * The item's own fields while it's edited: the form's row (what its
+     * ListEditor's `renderItem` shows), as controls over `props.value`.
+     */
+    renderItem: (props: EditListItemProps<TItem>) => ReactNode;
+    /** How the item reads when it isn't being edited. Its own controls (a done box) keep working. */
+    renderShown: (item: TItem, index: number) => ReactNode;
+    /** A blank item, what "Add" starts from. */
+    newItem: () => TItem;
+    /** How the buttons name an item, as on the form: (i) => `item ${i + 1}` gives "Move item 2 up". */
+    itemName: (index: number) => string;
+    /** The Add button's text, e.g. "Add item". */
+    addLabel: string;
+    /**
+     * The form's schema for the whole list (`widgetFormSchema.shape.checklist`).
+     * Each change is checked as the list it would make; a message about an
+     * item shows under that item.
+     */
+    schema?: {
+        safeParse: (value: unknown) => SafeParseResult<TItem[]>;
+    };
+    /**
+     * Saves a change to the list: call the record's single-field save with
+     * the change applied to the record's latest list, so it builds on any
+     * save still in flight (a tick, a move), e.g.
+     * `(change) => edit.mutateAsync((widget) => ({ checklist: change(widget.checklist) }))`.
+     * Rejects with the AppError; a 422's message shows where the change was made.
+     */
+    save: (change: (current: TItem[]) => TItem[]) => Promise<unknown>;
+};
+/** A list marked editable in place. Make one with `editInPlace({ kind: 'list', ... })`. */
+export type EditInPlaceList = Omit<EditInPlaceListOptions<unknown>, 'renderItem' | 'renderShown' | 'schema' | 'save'> & {
+    renderItem: (props: EditListItemProps<unknown>) => ReactNode;
+    renderShown: (item: unknown, index: number) => ReactNode;
+    schema?: {
+        safeParse: (value: unknown) => SafeParseResult<unknown[]>;
+    };
+    save: (change: (current: unknown[]) => unknown[]) => Promise<unknown>;
+};
+/** Marks a list editable in place: its items added, edited, removed and moved on the view. */
+export declare function editInPlace<TItem>(options: EditInPlaceListOptions<TItem>): EditInPlaceList;
 /** Marks a field editable in place, typed end to end: draft → schema → save. */
 export declare function editInPlace<TDraft, TValue = TDraft>(options: EditInPlaceOptions<TDraft, TValue>): EditInPlace;
 export declare const EditInPlaceContext: import("react").Context<EditInPlaceStore | null>;

package/dist/components/app/edit-in-place.js

@@ -1,9 +1,9 @@
 // Editing in place on a record's view: what a field passes to EntityView
 // (or to an EditableValue in its header) to become editable where it's
 // shown. The rules live in edit-in-place-store.ts; the markup in
-// editable-value.tsx. Design language: cell-patterns.md "Editable value".
+// editable-value.tsx, and a list's in editable-list.tsx. Design language:
+// cell-patterns.md "Editable value" and "Editable list".
 import { createContext } from 'react';
-/** Marks a field editable in place, typed end to end: draft → schema → save. */
 export function editInPlace(options) {
     return options;
 }

package/dist/components/app/editable-list.d.ts

@@ -0,0 +1,6 @@
+import { type EditInPlaceList } from './edit-in-place.js';
+export declare function EditableList({ label, edit, emptyLabel }: {
+    label: string;
+    edit: EditInPlaceList;
+    emptyLabel?: string;
+}): import("react").JSX.Element;

package/dist/components/app/editable-list.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A list of sub-items edited in place on a record's view (cell-patterns.md
+// "Editable list"): editInPlace's `list` kind, on a `content` section of
+// EntityView. Built on ListEditor, so the rows and their buttons are the
+// form's, with the same names ("Move item 2 up", "Remove item 2").
+//
+// - Each item reads as the app's `renderShown`, whose own controls (a
+//   done box) keep working. Clicking it, or its pencil, turns it into the
+//   form's row (`renderItem`), an EditableValue like any field: leaving or
+//   Enter saves, Esc gives up, one field open at a time.
+// - "Add" at the end opens a new item the same way. Enter saves it and
+//   opens the next, so a run of items goes in from the keyboard.
+// - Move and remove save at once. Whatever is open is saved first; while
+//   the change saves, the buttons wait, "Saving…" shows under the list,
+//   and a refusal leaves the list as it was with the reason under it.
+// - Every change is one save of the whole list, built from the record's
+//   latest list when it's sent (`save` takes a change, not a list), so it
+//   never undoes a tick or another change still saving.
+import { PlusIcon } from 'lucide-react';
+import { useContext, useEffect, useId, useRef, useState } from 'react';
+import { Button } from '../ui/button.js';
+import { FieldError } from '../ui/field.js';
+import { Spinner } from '../ui/spinner.js';
+import { EditInPlaceContext } from './edit-in-place.js';
+import { messageOf } from './edit-in-place-store.js';
+import { EditableField } from './editable-value.js';
+import { ListEditor } from './list-editor.js';
+const sameItem = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+// Where the item shown at `index` is in the latest list: still there, or
+// wherever a change saved before this one moved it, or, if it isn't
+// anywhere as shown (it was itself just changed), the same position.
+function locate(current, item, index) {
+    if (index < current.length && sameItem(current[index], item))
+        return index;
+    const found = current.findIndex((other) => sameItem(other, item));
+    return found === -1 ? index : found;
+}
+// The list's schema, run on the list this draft would make. A message
+// about this item comes first, then one about the list as a whole (too
+// many items).
+function checkItem(edit, items, index, draft) {
+    if (!edit.schema)
+        return { success: true, data: draft };
+    const list = index < items.length ? items.map((item, i) => (i === index ? draft : item)) : [...items, draft];
+    const result = edit.schema.safeParse(list);
+    if (result.success)
+        return { success: true, data: result.data[index] };
+    const { issues } = result.error;
+    const issue = issues.find(({ path }) => path?.[0] === index) ?? issues.find(({ path }) => !path?.length) ?? issues[0];
+    return { success: false, error: { issues: issue ? [issue] : [] } };
+}
+export function EditableList({ label, edit, emptyLabel }) {
+    const store = useContext(EditInPlaceContext);
+    if (!store)
+        throw new Error('A list edited in place works inside an <EntityView>, which runs editing in place.');
+    const items = edit.value;
+    const statusId = useId();
+    const [status, setStatus] = useState({ saving: false, error: null });
+    // The buttons are disabled while a change saves, which drops the caret.
+    // Once the list shows the outcome it goes to the first of these buttons
+    // (by name) that's there and enabled, else to Add.
+    const root = useRef(null);
+    const focusNext = useRef(null);
+    useEffect(() => {
+        const names = focusNext.current;
+        if (status.saving || !names)
+            return;
+        focusNext.current = null;
+        const buttons = [...(root.current?.querySelectorAll('button:not(:disabled)') ?? [])];
+        const target = names.map((name) => buttons.find((button) => button.getAttribute('aria-label') === name)).find(Boolean);
+        (target ?? root.current?.querySelector('[data-list-add]:not(:disabled)'))?.focus();
+    }, [items, status.saving]);
+    // Move and remove: save the open field first (if it can't save, it stays
+    // and nothing else happens), then the change.
+    const act = async (change, focusAfter, focusIfRefused) => {
+        if (status.saving)
+            return;
+        const open = store.open;
+        if (open !== null && !(await store.commit(open)))
+            return;
+        setStatus({ saving: true, error: null });
+        try {
+            await edit.save(change);
+            focusNext.current = focusAfter;
+            setStatus({ saving: false, error: null });
+        }
+        catch (error) {
+            focusNext.current = focusIfRefused;
+            setStatus({ saving: false, error: messageOf(error) });
+        }
+    };
+    const move = (from, to) => {
+        const direction = to < from ? 'up' : 'down';
+        const other = direction === 'up' ? 'down' : 'up';
+        void act((current) => {
+            const at = locate(current, items[from], from);
+            const target = at + (to - from);
+            if (target < 0 || target >= current.length)
+                return current;
+            const next = [...current];
+            next.splice(target, 0, ...next.splice(at, 1));
+            return next;
+        }, [`Move ${edit.itemName(to)} ${direction}`, `Move ${edit.itemName(to)} ${other}`], [`Move ${edit.itemName(from)} ${direction}`]);
+    };
+    const remove = (index) => void act((current) => {
+        const at = locate(current, items[index], index);
+        return current.filter((_, i) => i !== at);
+    }, [`Remove ${edit.itemName(index)}`, `Remove ${edit.itemName(index - 1)}`], [`Remove ${edit.itemName(index)}`]);
+    // An item, edited as the form's row.
+    const itemEdit = (index) => ({
+        kind: 'text',
+        value: items[index],
+        control: (props) => edit.renderItem({ ...props, index, isNew: false }),
+        schema: { safeParse: (draft) => checkItem(edit, items, index, draft) },
+        save: (item) => edit.save((current) => {
+            const at = locate(current, items[index], index);
+            return current.map((other, i) => (i === at ? item : other));
+        }),
+    });
+    // The item being added, at the end.
+    const addEdit = {
+        kind: 'text',
+        value: edit.newItem(),
+        control: (props) => edit.renderItem({ ...props, index: items.length, isNew: true }),
+        schema: { safeParse: (draft) => checkItem(edit, items, items.length, draft) },
+        save: (item) => edit.save((current) => [...current, item]),
+    };
+    return (_jsxs("div", { ref: root, className: "flex flex-col gap-2", "data-slot": "editable-list", children: [_jsx(ListEditor, { "aria-label": label, items: items.map((_, index) => ({ id: String(index) })), itemName: edit.itemName, addLabel: edit.addLabel, emptyText: emptyLabel, disabled: status.saving, onRemove: remove, onMove: move, renderItem: (index) => (_jsx(EditableField, { label: edit.itemName(index), edit: itemEdit(index), children: edit.renderShown(items[index], index) })), add: _jsx(EditableField, { label: edit.itemName(items.length), edit: addEdit, reopenAfterKeyboardSave: true, children: null, trigger: (start) => (_jsx("div", { children: _jsxs(Button, { "data-list-add": "", type: "button", variant: "outline", size: "sm", disabled: status.saving, onClick: start, children: [_jsx(PlusIcon, {}), edit.addLabel] }) })) }) }), _jsx("span", { id: statusId, className: "type-body", children: status.saving ? (_jsxs("span", { role: "status", className: "inline-flex items-center gap-1.5 type-caption text-muted-foreground", children: [_jsx(Spinner, { "aria-hidden": "true", className: "size-3.5" }), "Saving\u2026"] })) : (status.error && _jsx(FieldError, { className: "type-caption", children: status.error })) })] }));
+}

package/dist/components/app/editable-value.d.ts

@@ -11,7 +11,19 @@ export type EditableValueProps = {
     layout?: 'inline' | 'block';
     className?: string;
 };
-export declare function EditableValue({ label, edit, children, layout, className }: EditableValueProps): import("react").JSX.Element;
+/** EditableValue's own props, plus what a list's rows and its Add box need (editable-list.tsx). */
+export type EditableFieldProps = EditableValueProps & {
+    /**
+     * The closed field's own trigger, instead of the value and its pencil:
+     * the list's Add button. Given what opens the field; its button is where
+     * the caret goes back to.
+     */
+    trigger?: (start: () => void) => ReactNode;
+    /** Opens again, empty, once a save from the keyboard succeeds: adding one item after another. */
+    reopenAfterKeyboardSave?: boolean;
+};
+export declare function EditableValue(props: EditableValueProps): import("react").JSX.Element;
+export declare function EditableField({ label, edit, children, layout, className, trigger, reopenAfterKeyboardSave, }: EditableFieldProps): import("react").JSX.Element;
 /**
  * While a field holds something unsaved, leaving asks first: an in-app
  * link or Back (React Router's blocker, so the app needs a data router),

package/dist/components/app/editable-value.js

@@ -21,12 +21,14 @@ import { FieldError } from '../ui/field.js';
 import { Spinner } from '../ui/spinner.js';
 import { EditInPlaceContext } from './edit-in-place.js';
 // What a click on the shown value must leave alone: links navigate,
-// buttons do their own thing.
-const INTERACTIVE = 'a[href], button, input, select, textarea, [role="button"], [role="link"]';
+// buttons and boxes do their own thing (a list item's done box ticks it).
+const INTERACTIVE = 'a[href], button, input, select, textarea, label, [role="button"], [role="link"], [role="checkbox"], [role="switch"]';
 // Where the caret goes once the control shows: the first match, in this
-// order (a picker's text box before its chips' remove buttons).
+// order (a picker's text box before its chips' remove buttons). A box's
+// own native input (a checkbox's, hidden and out of the tab order) isn't
+// a place to type: a list item's text box comes first.
 const FOCUS_ORDER = [
-    'input:not([type="hidden"]), textarea, [contenteditable="true"]',
+    'input:not([type="hidden"]):not([tabindex="-1"]):not([aria-hidden="true"]), textarea, [contenteditable="true"]',
     '[role="combobox"], [role="switch"], button, [tabindex]:not([tabindex="-1"])',
 ];
 // Focus moving here doesn't save the field: a link that leaves the page
@@ -42,7 +44,10 @@ function useStore() {
         throw new Error('<EditableValue> works inside an <EntityView>, which runs editing in place.');
     return store;
 }
-export function EditableValue({ label, edit, children, layout = 'block', className }) {
+export function EditableValue(props) {
+    return _jsx(EditableField, { ...props });
+}
+export function EditableField({ label, edit, children, layout = 'block', className, trigger, reopenAfterKeyboardSave = false, }) {
     const store = useStore();
     const key = useId();
     const controlId = `${key}-control`;
@@ -55,6 +60,8 @@ export function EditableValue({ label, edit, children, layout = 'block', classNa
     useEffect(() => store.register(key, () => config.current), [store, key]);
     const state = useSyncExternalStore(store.subscribe, () => store.state(key), () => store.state(key));
     const editButton = useRef(null);
+    // Holds a trigger (the list's Add): its button is the one the caret goes back to.
+    const triggerBox = useRef(null);
     const container = useRef(null);
     // Set by a keyboard save or Esc: the caret goes back to the edit button.
     const refocus = useRef(false);
@@ -76,7 +83,7 @@ export function EditableValue({ label, edit, children, layout = 'block', classNa
         // from a list), so the keyboard never loses its place.
         if (!isOpen && wasOpen.current && (refocus.current || document.activeElement === document.body)) {
             refocus.current = false;
-            editButton.current?.focus();
+            (editButton.current ?? triggerBox.current?.querySelector('button'))?.focus();
         }
         wasOpen.current = isOpen;
     }, [isOpen]);
@@ -102,6 +109,19 @@ export function EditableValue({ label, edit, children, layout = 'block', classNa
         void store.commit(key, value);
     }, [store, key]);
     const cancel = useCallback(() => store.cancel(key), [store, key]);
+    // Enter or Ctrl/Cmd+Enter: the caret goes back to the edit button, or
+    // the field opens again for the next one.
+    const commitFromKeyboard = () => {
+        window.clearTimeout(blurTimer.current);
+        refocus.current = true;
+        void store.commit(key).then((closed) => {
+            if (!closed || !reopenAfterKeyboardSave)
+                return;
+            // The caret stays in (or comes back to) the field opening again.
+            refocus.current = false;
+            void store.start(key);
+        });
+    };
     const onShownClick = (event) => {
         if (event.target.closest(INTERACTIVE))
             return;
@@ -120,13 +140,11 @@ export function EditableValue({ label, edit, children, layout = 'block', classNa
         }
         else if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
             event.preventDefault();
-            refocus.current = true;
-            commit();
+            commitFromKeyboard();
         }
         else if (event.key === 'Enter' && edit.kind === 'text' && !event.shiftKey && !event.altKey) {
             event.preventDefault();
-            refocus.current = true;
-            commit();
+            commitFromKeyboard();
         }
     };
     // Leaving the field saves it. Focus moving into the control's own list
@@ -142,6 +160,8 @@ export function EditableValue({ label, edit, children, layout = 'block', classNa
     };
     const onFocus = () => window.clearTimeout(blurTimer.current);
     if (state.status === 'closed') {
+        if (trigger)
+            return (_jsx("span", { ref: triggerBox, className: "contents", children: trigger(start) }));
         return (_jsxs("span", { "data-slot": "editable-value", onClick: onShownClick, className: cn('group/editable relative -mx-1.5 cursor-text items-start gap-1 rounded-md px-1.5 transition-colors hover:bg-muted has-[[data-edit]:focus-visible]:bg-muted', layout === 'block' ? 'flex w-full' : 'inline-flex max-w-full align-top', className), children: [_jsx("span", { className: "min-w-0 flex-1", children: children }), _jsx(Button, { ref: editButton, "data-edit": "", type: "button", variant: "ghost", size: "icon-xs", "aria-label": `Edit ${label}`, onClick: start, className: "shrink-0 text-muted-foreground opacity-0 group-hover/editable:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100", children: _jsx(PencilIcon, {}) })] }));
     }
     const saving = state.status === 'saving';

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

@@ -1,6 +1,6 @@
 import { type ReactNode } from 'react';
 import type { AppError } from '../../api/contracts.js';
-import { type EditInPlace } from './edit-in-place.js';
+import { type EditInPlace, type EditInPlaceList } from './edit-in-place.js';
 export type EntityViewField = {
     label: string;
     /**
@@ -21,7 +21,7 @@ export type EntityViewField = {
  * only repeat the heading. A block that's empty shows `emptyLabel`, the
  * same rule as a field.
  */
-export type EntityViewSection = {
+export type EntityViewSection = ({
     /** The section's heading (an <h2>). Unique on the page. */
     title: string;
     fields: EntityViewField[];
@@ -29,9 +29,29 @@ export type EntityViewSection = {
     title: string;
     content: ReactNode;
     emptyLabel?: string;
-    /** The block is editable in place (long text), named by the section's title. */
-    edit?: EditInPlace;
+    /**
+     * The block is editable in place, named by the section's title: long
+     * text (`editInPlace({ kind: 'long-text', ... })`), or a list of
+     * sub-items (`editInPlace({ kind: 'list', ... })`). A list shows its
+     * own items, with `content` above them (a done-count, or nothing),
+     * and `emptyLabel` in place of the items when there are none.
+     */
+    edit?: EditInPlace | EditInPlaceList;
+}) & {
+    /**
+     * Where the section goes in the `rail` layout: `rail` for the short ones
+     * (a summary, label/value fields, a few links), `main` (the default) for
+     * long text and long lists. The `column` layout ignores it.
+     */
+    placement?: EntityViewPlacement;
 };
+export type EntityViewPlacement = 'main' | 'rail';
+/**
+ * `column` (the default): one column, at most max-w-4xl wide. `rail`: the
+ * content area's whole width, with the sections placed `rail` in a narrow
+ * column on the right (one column on a narrow screen, rail first).
+ */
+export type EntityViewLayout = 'column' | 'rail';
 export type EntityViewProps = {
     /** The record's name or title, the page's <h1>. */
     title?: string;
@@ -48,6 +68,10 @@ export type EntityViewProps = {
     /** The header's actions: an Edit button, a Delete with its confirm dialog. */
     actions?: ReactNode;
     sections: EntityViewSection[];
+    /** `rail` puts the sections placed `rail` in a column on the right. Defaults to `column`. */
+    layout?: EntityViewLayout;
+    /** The rail's landmark name (its `<aside>`). Defaults to the title + " details". */
+    railLabel?: string;
     isLoading: boolean;
     /** A `notfound` error (including another user's record) shows "Not found" and a way back, never a retry. */
     error?: AppError | null;
@@ -58,4 +82,4 @@ export type EntityViewProps = {
         label: string;
     };
 };
-export declare function EntityView({ title, titleEdit, badges, actions, sections, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;
+export declare function EntityView({ title, titleEdit, badges, actions, sections, layout, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;

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

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } 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
@@ -23,10 +23,21 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // saves when you leave it. This component runs it (one field open at a
 // time, the leave-page prompt); EditableValue is each value's side, and a
 // header badge uses it directly. A field not marked renders exactly as
-// before. Edit, in `actions`, stays for everything else.
-import { useId, useState, useSyncExternalStore } from 'react';
+// before. Edit, in `actions`, stays for everything else. A sub-item list
+// edits in place too (editInPlace's `list` kind, editable-list.tsx): its
+// items added, edited, moved and removed on the page.
+//
+// Two layouts. `column` (the default): every section in one column capped
+// at max-w-4xl. `rail`, for a record with long content: the page takes the
+// content area's whole width, sections placed `rail` go in a narrow column
+// on the right that stays in view while the main column scrolls (an issue
+// tracker's shape), and the rest fill the main column. Below the width two
+// columns need, one column: header, rail, main. The DOM is in that order at
+// every width, so reading and tab order match the screen.
+import { useEffect, useId, useState, useSyncExternalStore } from 'react';
 import { Link } from 'react-router';
 import { ArrowLeftIcon, SearchXIcon } from 'lucide-react';
+import { cn } from 'cn';
 import { ErrorState } from './error-state.js';
 import { Button } from '../ui/button.js';
 import { Card, CardContent, CardHeader } from '../ui/card.js';
@@ -34,6 +45,7 @@ import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTi
 import { Skeleton } from '../ui/skeleton.js';
 import { EditInPlaceContext } from './edit-in-place.js';
 import { EditInPlaceStore } from './edit-in-place-store.js';
+import { EditableList } from './editable-list.js';
 import { EditableValue, LeaveGuard } from './editable-value.js';
 const DEFAULT_EMPTY_LABEL = 'Not set';
 function isEmptyValue(value) {
@@ -50,18 +62,79 @@ 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: field.edit ? (_jsx(EditableValue, { label: field.label, edit: field.edit, children: orEmptyLabel(field.value, field.emptyLabel) })) : (orEmptyLabel(field.value, field.emptyLabel)) })] }));
+// above its value, so nothing is squeezed into a narrow second column. In
+// the rail the list's own width decides instead (a container query on the
+// <dl>): label above value in the narrow rail, beside it once the rail's
+// sections stack full width under the header.
+const FIELD_ROW = {
+    page: 'sm:grid sm:grid-cols-[minmax(8rem,12rem)_1fr] sm:gap-6',
+    rail: '@lg/fields:grid @lg/fields:grid-cols-[minmax(8rem,12rem)_1fr] @lg/fields:gap-6',
+};
+function FieldRow({ field, inRail }) {
+    return (_jsxs("div", { className: cn('flex flex-col gap-1 py-3 first:pt-0 last:pb-0', FIELD_ROW[inRail ? 'rail' : 'page']), 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: field.edit ? (_jsx(EditableValue, { label: field.label, edit: field.edit, children: orEmptyLabel(field.value, field.emptyLabel) })) : (orEmptyLabel(field.value, field.emptyLabel)) })] }));
 }
-function ViewSection({ section }) {
+function ViewSection({ section, inRail = false }) {
     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: section.edit ? (_jsx(EditableValue, { label: section.title, edit: section.edit, children: orEmptyLabel(section.content, section.emptyLabel) })) : (orEmptyLabel(section.content, section.emptyLabel)) })) })] }) }));
+    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: cn('flex flex-col divide-y divide-border', inRail && '@container/fields'), children: section.fields.map((field) => (_jsx(FieldRow, { field: field, inRail: inRail }, field.label))) })) : section.edit?.kind === 'list' ? (_jsxs("div", { className: "flex min-w-0 flex-col gap-2 type-body break-words text-foreground", children: [!isEmptyValue(section.content) && section.content, _jsx(EditableList, { label: section.title, edit: section.edit, emptyLabel: section.emptyLabel ?? DEFAULT_EMPTY_LABEL })] })) : (_jsx("div", { className: "min-w-0 type-body break-words text-foreground", children: section.edit ? (_jsx(EditableValue, { label: section.title, edit: section.edit, children: orEmptyLabel(section.content, section.emptyLabel) })) : (orEmptyLabel(section.content, section.emptyLabel)) })) })] }) }));
+}
+// The rail layout's columns. The view is a container, so the switch to
+// two columns follows the width the page actually has (the sidebar open
+// or not), not the window's: two from 56rem (896px), where the main
+// column still gets ~32rem beside a 22rem rail. Below that, one column in
+// DOM order (header, rail, main); from it, the grid puts the rail on the
+// right of row 1 and main on its left, both starting under the header.
+const RAIL_LAYOUT = {
+    page: '@container/view flex min-w-0 flex-col gap-6',
+    columns: 'flex flex-col gap-6 @4xl/view:grid @4xl/view:grid-cols-[minmax(0,1fr)_22rem] @4xl/view:items-start',
+    rail: '@4xl/view:col-start-2 @4xl/view:row-start-1',
+    main: 'flex min-w-0 flex-col gap-6 @4xl/view:col-start-1 @4xl/view:row-start-1',
+    // Main alone (no rail sections): the whole row.
+    mainAlone: '@4xl/view:col-span-2',
+    // Sticky only beside main, and only while the whole rail fits on screen
+    // (`data-fits`, measured): a taller one scrolls with the page, so its end
+    // is never stuck below the fold.
+    sticky: '@4xl/view:data-[fits]:sticky @4xl/view:data-[fits]:top-6',
+};
+function SkeletonCard({ rows, stacked }) {
+    return (_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: rows }, (_, row) => (_jsxs("div", { className: cn('flex flex-col gap-1', !stacked && 'sm:flex-row sm:gap-6'), children: [_jsx(Skeleton, { className: "h-5 w-32" }), _jsx(Skeleton, { className: cn('h-5', stacked ? 'w-full' : 'flex-1') })] }, row))) })] }));
+}
+// The page's shape before the record arrives, in the layout it will have,
+// so nothing jumps when it loads.
+function EntityViewSkeleton({ layout }) {
+    const header = (_jsxs(_Fragment, { 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" })] })] }));
+    if (layout === 'rail') {
+        return (_jsxs("div", { className: RAIL_LAYOUT.page, "data-state": "loading", "data-layout": "rail", children: [header, _jsxs("div", { className: RAIL_LAYOUT.columns, children: [_jsx("div", { className: cn(RAIL_LAYOUT.rail, 'flex flex-col gap-6'), children: _jsx(SkeletonCard, { rows: 4, stacked: true }) }), _jsx("div", { className: RAIL_LAYOUT.main, children: _jsx(SkeletonCard, { rows: 6, stacked: false }) })] })] }));
+    }
+    return (_jsxs("div", { className: "flex max-w-4xl flex-col gap-6", "data-state": "loading", children: [header, Array.from({ length: 2 }, (_, section) => (_jsx(SkeletonCard, { rows: 4, stacked: false }, section)))] }));
+}
+// The rail's top offset (top-6) plus as much again below it.
+const RAIL_MARGIN_PX = 48;
+// Whether `element` fits in the window with room around it, re-measured
+// whenever it or the window changes size (a field opening in place, a
+// rotated phone).
+function useFitsWindow() {
+    const [element, setElement] = useState(null);
+    const [fits, setFits] = useState(false);
+    useEffect(() => {
+        if (!element)
+            return;
+        const measure = () => setFits(element.offsetHeight + RAIL_MARGIN_PX <= window.innerHeight);
+        // A ResizeObserver reports once as soon as it observes: the first measure.
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        window.addEventListener('resize', measure);
+        return () => {
+            observer.disconnect();
+            window.removeEventListener('resize', measure);
+        };
+    }, [element]);
+    return [setElement, fits];
 }
-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)))] }));
+function Rail({ label, sections }) {
+    const [ref, fits] = useFitsWindow();
+    return (_jsx("aside", { ref: ref, "aria-label": label, "data-fits": fits ? '' : undefined, className: cn(RAIL_LAYOUT.rail, RAIL_LAYOUT.sticky, 'flex min-w-0 flex-col gap-6'), children: sections.map((section) => (_jsx(ViewSection, { section: section, inRail: true }, section.title))) }));
 }
-export function EntityView({ title, titleEdit, badges, actions, sections, isLoading, error, onRetry, back, }) {
+export function EntityView({ title, titleEdit, badges, actions, sections, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
     // Editing in place: one store per view, and the leave-page prompt only
     // while a field is open.
     const [store] = useState(() => new EditInPlaceStore());
@@ -74,6 +147,8 @@ export function EntityView({ title, titleEdit, badges, actions, sections, isLoad
     if (error)
         return _jsx(ErrorState, { error: error, onRetry: onRetry });
     if (isLoading)
-        return _jsx(EntityViewSkeleton, {});
-    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: "flex max-w-4xl flex-col gap-6", "data-state": "success", children: [openField !== null && _jsx(LeaveGuard, { store: store }), _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-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (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)))] }) }));
+        return _jsx(EntityViewSkeleton, { layout: layout });
+    const railSections = sections.filter((section) => section.placement === 'rail');
+    const mainSections = sections.filter((section) => section.placement !== 'rail');
+    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [openField !== null && _jsx(LeaveGuard, { store: store }), _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-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (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 })] }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), _jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) })] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title)))] }) }));
 }

package/dist/components/app/list-editor.d.ts

@@ -1,12 +1,13 @@
 import type { ReactNode } from 'react';
-export declare function ListEditor({ items, renderItem, onAdd, onRemove, onMove, itemName, addLabel, emptyText, max, 'aria-label': ariaLabel, }: {
+export declare function ListEditor({ items, renderItem, onAdd, onRemove, onMove, itemName, addLabel, emptyText, max, add, disabled, 'aria-label': ariaLabel, }: {
     /** One entry per item, with a stable key (useFieldArray's `fields`). */
     items: readonly {
         id: string;
     }[];
     /** The item's own fields, for the item at this index. */
     renderItem: (index: number) => ReactNode;
-    onAdd: () => void;
+    /** The Add button's action. Not needed with `add`. */
+    onAdd?: () => void;
     onRemove: (index: number) => void;
     onMove: (from: number, to: number) => void;
     /**
@@ -20,6 +21,10 @@ export declare function ListEditor({ items, renderItem, onAdd, onRemove, onMove,
     emptyText?: string;
     /** The most items allowed; Add is disabled once reached. */
     max?: number;
+    /** In place of the Add button: what adds an item (editing in place's Add box). */
+    add?: ReactNode;
+    /** The row buttons and Add can't be used (a change is saving). */
+    disabled?: boolean;
     /** Names the list (e.g. the field's label). */
     'aria-label'?: string;
 }): import("react").JSX.Element;

package/dist/components/app/list-editor.js

@@ -1,10 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ArrowDownIcon, ArrowUpIcon, PlusIcon, Trash2Icon } from 'lucide-react';
 import { Button } from '../ui/button.js';
-export function ListEditor({ items, renderItem, onAdd, onRemove, onMove, itemName, addLabel, emptyText = 'Nothing added yet.', max, 'aria-label': ariaLabel, }) {
+export function ListEditor({ items, renderItem, onAdd, onRemove, onMove, itemName, addLabel, emptyText = 'Nothing added yet.', max, add, disabled = false, 'aria-label': ariaLabel, }) {
     const atMax = max !== undefined && items.length >= max;
     return (_jsxs("div", { className: "flex flex-col gap-2", children: [items.length === 0 ? (_jsx("p", { className: "type-caption text-muted-foreground", children: emptyText })) : (_jsx("ul", { "aria-label": ariaLabel, className: "flex flex-col gap-2", children: items.map((item, index) => {
                     const name = itemName(index);
-                    return (_jsxs("li", { className: "flex items-start gap-1", children: [_jsx("div", { className: "flex min-w-0 flex-1 items-start gap-2", children: renderItem(index) }), _jsx(Button, { type: "button", variant: "ghost", size: "icon-sm", "aria-label": `Move ${name} up`, disabled: index === 0, onClick: () => onMove(index, index - 1), children: _jsx(ArrowUpIcon, {}) }), _jsx(Button, { type: "button", variant: "ghost", size: "icon-sm", "aria-label": `Move ${name} down`, disabled: index === items.length - 1, onClick: () => onMove(index, index + 1), children: _jsx(ArrowDownIcon, {}) }), _jsx(Button, { type: "button", variant: "ghost", size: "icon-sm", "aria-label": `Remove ${name}`, onClick: () => onRemove(index), children: _jsx(Trash2Icon, {}) })] }, item.id));
-                }) })), _jsx("div", { children: _jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: onAdd, disabled: atMax, children: [_jsx(PlusIcon, {}), addLabel] }) })] }));
+                    return (_jsxs("li", { className: "flex items-start gap-1", children: [_jsx("div", { className: "flex min-w-0 flex-1 items-start gap-2", children: renderItem(index) }), _jsx(Button, { type: "button", variant: "ghost", size: "icon-sm", "aria-label": `Move ${name} up`, disabled: disabled || index === 0, onClick: () => onMove(index, index - 1), children: _jsx(ArrowUpIcon, {}) }), _jsx(Button, { type: "button", variant: "ghost", size: "icon-sm", "aria-label": `Move ${name} down`, disabled: disabled || index === items.length - 1, onClick: () => onMove(index, index + 1), children: _jsx(ArrowDownIcon, {}) }), _jsx(Button, { type: "button", variant: "ghost", size: "icon-sm", "aria-label": `Remove ${name}`, disabled: disabled, onClick: () => onRemove(index), children: _jsx(Trash2Icon, {}) })] }, item.id));
+                }) })), add ?? (_jsx("div", { children: _jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: onAdd, disabled: disabled || atMax, children: [_jsx(PlusIcon, {}), addLabel] }) }))] }));
 }

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export { AppShell, type AppShellProps, type NavItem } from './components/app/app
 export { CountLink, type CountLinkProps } from './components/app/count-link.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 { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceOptions, type EditKind, } from './components/app/edit-in-place.js';
+export { EntityView, type EntityViewField, type EntityViewLayout, type EntityViewPlacement, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
+export { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceList, type EditInPlaceListOptions, type EditInPlaceOptions, type EditKind, type EditListItemProps, } from './components/app/edit-in-place.js';
 export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
 export { EditableValue, type EditableValueProps } from './components/app/editable-value.js';
 export { ErrorState } from './components/app/error-state.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.23.0",
+  "version": "3.25.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": {

package/styles/index.css

@@ -57,6 +57,10 @@
     --color-category-6: var(--category-6);
     --color-category-7: var(--category-7);
     --color-category-8: var(--category-8);
+    --color-category-9: var(--category-9);
+    --color-category-10: var(--category-10);
+    --color-category-11: var(--category-11);
+    --color-category-12: var(--category-12);
     --color-accent-foreground: var(--accent-foreground);
     --color-accent: var(--accent);
     --color-muted-foreground: var(--muted-foreground);

package/styles/theme.css

@@ -72,12 +72,13 @@
    * later: a table using info keeps its categories off those three. They are ordered by distinctness, not by hue angle, so an app
    * using only the first three gets three obviously different colours.
    * Past about five, hue alone stops separating them and the glyph has to
-   * carry the meaning; see docs/design-language.md.
+   * carry the meaning; see docs/design-language.md. Twelve slots in all.
    *
    * Ratios are against the page, measured (WCAG 2.x, sRGB), and all clear
-   * the 3:1 non-text minimum in both themes with room to spare. Note that
-   * axe does NOT check icon contrast, so unlike the tones nothing
-   * re-measures these automatically.
+   * the 3:1 non-text minimum in both themes with room to spare (4.5:1 at
+   * the least, slots 9-12 on the dark card). axe does NOT check icon
+   * contrast; the Storybook glyph check re-measures every slot on the
+   * page and on a card (design-language/CategoricalColour).
    */
   --category-1-700: oklch(0.5 0.15 240);
   --category-1-400: oklch(0.78 0.12 240);
@@ -95,6 +96,24 @@
   --category-7-400: oklch(0.78 0.12 120);
   --category-8-700: oklch(0.5 0.15 215);
   --category-8-400: oklch(0.78 0.12 215);
+  /*
+   * Slots 9-12 are a second channel, not new hues: the hues left between
+   * the tones' are already spent ~25 degrees apart, so these are deeper
+   * shades of the four that sit furthest from info (teal, plum, olive,
+   * violet), darker than their slot in both themes. Each is at least as
+   * far from its nearest slot (OKLab distance) as slots 1-8 are from each
+   * other; tests/category-slots.test.ts holds every pair to that. A deep
+   * shade of the blues or the yellow-green fell to half that distance, so
+   * twelve is where it stops. Chroma is the most each holds in sRGB.
+   */
+  --category-9-700: oklch(0.36 0.06 190);
+  --category-9-400: oklch(0.62 0.1 190);
+  --category-10-700: oklch(0.36 0.12 330);
+  --category-10-400: oklch(0.62 0.15 330);
+  --category-11-700: oklch(0.36 0.07 95);
+  --category-11-400: oklch(0.62 0.12 95);
+  --category-12-700: oklch(0.36 0.14 300);
+  --category-12-400: oklch(0.62 0.17 300);
   --blue-500: oklch(0.488 0.243 264.376);
 
   --radius-base: 0.625rem;
@@ -198,6 +217,10 @@
   --category-6: var(--category-6-700);
   --category-7: var(--category-7-700);
   --category-8: var(--category-8-700);
+  --category-9: var(--category-9-700);
+  --category-10: var(--category-10-700);
+  --category-11: var(--category-11-700);
+  --category-12: var(--category-12-700);
   /* The zebra stripe (table.tsx: bg-muted/40 on even rows) mixed onto the
      page, opaque: what a pinned table cell paints on an even row, so it
      matches the row without letting scrolled columns show through. Mixed
@@ -274,6 +297,10 @@
   --category-6: var(--category-6-400);
   --category-7: var(--category-7-400);
   --category-8: var(--category-8-400);
+  --category-9: var(--category-9-400);
+  --category-10: var(--category-10-400);
+  --category-11: var(--category-11-400);
+  --category-12: var(--category-12-400);
   --table-stripe: color-mix(in srgb, var(--muted) 40%, var(--background));
   --border: var(--white-a10);
   --input: var(--white-a15);