@tristan2828/ui-foundation 4.31.0 → 4.33.0

package/conventions/AGENTS.md

@@ -84,7 +84,8 @@ Every data view handles: loading, empty, error, and success. Use
 `<Skeleton>`, `<Empty>`, and the error boundary — `DataTable` already does,
 and `EntityView` (one record) adds not found: a plain 404, never a retry.
 A small widget on a hub page is a `WidgetCard`, which holds all four for
-its own data, its error inside the card.
+its own data, its error inside the card; a hub's place (a module, with
+one live number) is a `ModuleCard` in a `ModuleStrip`, the same way.
 Every screen has one Playwright test per state, forced via MSW overrides
 (`@tristan2828/ui-foundation/testing`).
 

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

@@ -152,7 +152,15 @@ is a filled-in example while the Widgets demo is still here).
    `<ListEditor>` inside a `FieldSet`/`FieldLegend` on the form, each row's
    controls named by position ("Item 2 text"), a per-item `FieldError`
    (a server 422 at `["body", "checklist", 2, "text"]` arrives as
-   `fieldErrors["checklist.2.text"]` and binds to that row), and a summary
+   `fieldErrors["checklist.2.text"]` and binds to that row). A list whose
+   items are rich (five or six fields each) and run to ten or more also
+   passes `summary={(i) => …}`, one line per item that opens to its
+   fields, one at a time, and `invalid={(i) => !!errors.<list>?.[i]}` so
+   an item the save refuses opens to show why. A list whose items repeat
+   with small changes passes
+   ``onDuplicate={(i) => insert(i + 1, { ...getValues(`<list>.${i}`) })}``,
+   leaving out any saved id; the copy lands after its original and opens.
+   Then a summary
    in the table, never the items (an item with a `reference` field
    copies Pairings, below) — and a `computed` field copies
    Progress (`checklistState`): `readOnly` in `openapi.yaml` and absent
@@ -438,7 +446,10 @@ is a filled-in example while the Widgets demo is still here).
      (`> [!NOTE]`) 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).
+     breaks). Give `<Markdown>` and `RichTextEditor` a `headingLevel` for
+     where they sit: the default (3) in an `EntityView` section,
+     `headingLevel={2}` for a `RichTextEditor` on a form straight under
+     the page's `<h1>`.
    - **Quick actions: only the fields the plan's `Quick actions` line
      names**, each a control that saves on its own (cell pattern 17,
      `widget-quick-actions.tsx`). A `yes/no` is a

package/conventions/docs/cell-patterns.md

@@ -388,6 +388,14 @@ cell: ({ getValue }) => {
 - An API `format: decimal` arrives as a **string**. `Number()` is exact
   enough to display (about 15 significant digits). Never add up money in
   floats on the client: totals come from the backend.
+- **A column's total goes in `DataTable`'s `totals`**:
+  ``totals={data && { label: `Total · ${data.total} items`, cells: { price: usd(data.totals.price) } }}``.
+  One formatted value per column id, from the list endpoint beside
+  `total`, so it covers every matching row, not only the page. It renders
+  as a footer row: the label in a row header in the first visible column,
+  each value under its column in that column's alignment and tabular
+  figures, above a 2px border. A hidden column's value isn't shown, and
+  the row is hidden while loading, on error and when empty.
 - **Right-aligning isn't available yet.** `DataTable`'s `meta.align` only
   supports `'center'`, and a right-aligned cell under a left-aligned header
   looks broken. Stay left-aligned until a real column needs

package/conventions/docs/design-language.md

@@ -221,7 +221,7 @@ room that stays readable.
 
 ## Typography
 
-Five roles cover every screen. Each is one class that sets size, line
+Six roles cover every screen. Each is one class that sets size, line
 height and weight together, from tokens in the package's `styles/theme.css`:
 
 | Class | For | Size / weight |
@@ -231,12 +231,17 @@ height and weight together, from tokens in the package's `styles/theme.css`:
 | `type-body` | running text, table cells, form text, the pagination summary | 14px / 400 |
 | `type-label` | column headers, field labels, a small heading over a group | 14px / 500 |
 | `type-caption` | counts, metadata, helper text under a field | 12px / 400 |
+| `type-numeric` | the one live number on a card (`ModuleCard`'s count), in tabular figures | 22px / 500 |
 
 - **Use a role instead of size and weight classes,** not as well as them.
   `type-page-title` replaces `text-lg font-semibold`. Combining a role with
   `text-sm`, `font-medium` or `leading-*` makes two classes set the same
   property, and which one wins depends on the order of rules in the
   stylesheet, not on the order in `className`.
+- **`type-numeric` sets tabular figures** (`font-variant-numeric:
+  tabular-nums`), so counts line up from card to card and don't change
+  width as they tick. A number in running text or a table cell keeps its
+  row's role; add `tabular-nums` there if a column of them should align.
 - **Colour stays separate:** `type-caption text-muted-foreground`. A role
   never sets a colour, so any text token pairs with it.
 - **Why `type-*` and not `text-*`:** `cn` (tailwind-merge) treats an
@@ -264,6 +269,20 @@ In text with a band, the rest (paragraphs, lists, tables, callouts,
 words in the band rather than its edge; text with no band stays flush. The level reads at a glance: two bands of
 different strength, then a label.
 
+Headings in the text sit under where the text is in the page's outline.
+`headingLevel` on `<Markdown>` and `RichTextEditor` is the HTML level `#`
+renders as: 2 straight under the page's `<h1>` (a form, or a page that is
+the note), 3 under a section's `<h2>` (the default). `##` is one below it
+and `###` two below, never past `<h6>`, so the outline never skips a
+level (axe's heading-order). Only the element moves: each level keeps its
+look, and the editor saves `#` as `#`.
+
+A table wider than the text scrolls sideways. While it does, its box is a
+tab stop and a region named "Table, scrolls sideways: " and its first
+columns ("Item, Size, Colour, …"), so two such tables keep distinct
+names; the arrow keys scroll it (in the editor Home and End too), with
+the `ring` focus ring. A table that fits gets no tab stop and no region.
+
 The same text has four colour tokens of its own: `--link` (`text-link`), a
 link's colour, blue as well as underlined (5.59:1 on white, 8.90:1 on the
 dark page); `--heading-band` (`bg-heading-band`), the `#` band, one step
@@ -294,13 +313,18 @@ set, not a `DataTable` prop:
 
 | `data-density` | Changes | Table cell padding (vertical) | Header height | For |
 |---|---|---|---|---|
-| `compact` | table rows only | 4px | 32px | wide tables people scan, many rows per screen |
+| `compact` | table rows, and a hub's cards (`WidgetCard`, `WidgetList` rows, `ModuleCard`) | 4px | 32px | wide tables people scan, many rows per screen; a dense hub |
 | *(unset)* | — | 8px | 40px | the default |
 | `comfortable` | table rows only | 12px | 48px | short tables, or rows people read rather than scan |
 | `large` | **everything**: type, spacing, control heights, icons, the sidebar, table rows | 12px | 56px | a screen read from a distance: a TV used as the desktop monitor, with a mouse and keyboard |
 
 - `compact` and `comfortable` change padding only. Text keeps
   `type-body`, so compact never drops below a readable size.
+- On a hub, `compact` takes a `WidgetCard`'s padding from 16px to 12px,
+  a `WidgetList` row from 36px to 32px (6px around its line) and a
+  `ModuleCard`'s band and body by 4px each. On a phone a compact row is
+  44px instead, its link filling that height, so it stays a finger's
+  target.
 - `large` grows the whole UI by about a quarter: body text 14 → 18px,
   controls 32 → 40px tall, icons 16 → 20px, the sidebar 256 → 320px.
   Breakpoints and `max-w-*` containers stay where they are, which is
@@ -308,7 +332,8 @@ set, not a `DataTable` prop:
   a wide screen can fall into the phone layout).
 - For `large`, set it on **`<html>`**. Menus, selects, dialogs and
   tooltips are portaled to `<body>`, so a wrapper `<div>` doesn't reach
-  them. `compact` and `comfortable` only touch tables, so a wrapper is fine.
+  them. `compact` and `comfortable` only touch tables and hub cards, so a
+  wrapper is fine.
 - Pick **one density per screen**. Two tables at different densities side
   by side look like a mistake.
 - Size things the way the package does and `large` reaches them for free:
@@ -319,11 +344,17 @@ set, not a `DataTable` prop:
 - Under the hood, the table primitive's cells read `--table-cell-px`,
   `--table-cell-py` and `--table-head-height`. `large` also redefines
   Tailwind's own scale (`--spacing`, `--text-*`, `--radius`), the `--type-*`
-  roles and `--control-text-sm` (the small Button and Toggle). Each
+  roles and `--control-text-sm` (the small Button and Toggle).
+  `DataTable`'s totals row reads the body cells' tokens, so it is a row's
+  height at every density. Each
   default is the value it always had, so a screen without `data-density`
-  doesn't change. The selectors are in `styles/theme.css`. Storybook's
+  doesn't change. The selectors are in `styles/theme.css`. A composite
+  reaches `compact` with the `density-compact:` variant (`styles/index.css`:
+  any ancestor with `data-density="compact"`), the way `WidgetCard` and
+  `ModuleCard` do; an app's own card can use it too. Storybook's
   Density toolbar shows any story at a density, and `patterns/Density`
-  shows the primitives, `DataTable` and the sidebar at each. Its checks
+  shows the primitives, `DataTable`, the sidebar and the hub cards at
+  each. Its checks
   measure that every step changes what it should, and that the default
   keeps today's sizes.
 
@@ -398,6 +429,66 @@ const { data, isLoading, error, refetch } = useReadyTasksQuery() // one page of
   one in each state; its checks run axe and the token and glyph checks in
   both themes and at `large`.
 
+## Module cards (a hub's places)
+
+Above its widgets, a hub shows the app's places: its modules, and the
+sites outside it that it links to. Each is a `ModuleCard` in a
+`ModuleStrip`: a small card that names the place, shows one live number,
+and offers one action.
+
+```tsx
+const { data, isLoading, error, refetch } = useProjectsSummaryQuery()
+
+<ModuleStrip aria-label="Places">
+  <ModuleCard
+    title="Projects"
+    icon={ListTodoIcon}
+    category={1}
+    to="/projects"
+    value={data?.openCount}
+    note="open"
+    action={{ to: '/projects?view=today', label: 'Today' }}
+    isLoading={isLoading}
+    error={error}
+    onRetry={() => refetch()}
+  />
+  <ModuleCard title="Recipes" icon={RecipesMark} category={6} href="https://recipes.example.com" note="Opens its own app" />
+</ModuleStrip>
+```
+
+- **The band names the place and links to it.** The icon takes the
+  place's categorical slot (`category`, 1–12), and the band behind the
+  icon and the name is a 10% wash of the same slot over the card, with
+  `foreground` text on it (axe measures every slot's wash in both themes).
+  Give each place the slot it has elsewhere in the app (its sidebar entry,
+  its badges), so a place is one colour everywhere. Without a `category`
+  the icon is muted and the band plain.
+- **One number, with a short note.** `value` is the one count that says
+  what's live there ("5" open, "2" due today), in `type-numeric`; `note`
+  is a few words under it. A card with no `value` shows no number, and
+  that is not an empty state: a place outside the app usually has none,
+  and its note says what it is ("Opens its own app").
+- **One action** at the foot: the thing most often done next ("Today",
+  "Start", "Add one"). It's described by the place's name, so several
+  "Open" links on one page stay distinct.
+- **A place outside the app** takes `href` instead of `to` (an action
+  can too): it opens in a new tab with the external-link mark. Its icon
+  can be the service's own mark ("Logos and brand marks" above).
+- **States are the number's.** While loading, a skeleton the number's
+  size (the note stays, it doesn't load); on an error, "Couldn't load"
+  and Retry inside the card, so one failing place never hides the
+  others. The band and the action work in every state.
+- **The strip** is a navigation landmark (`aria-label` names it) of
+  equal columns, 170px or wider, that wrap: six to eight across a
+  desktop. On a phone it's three columns of smaller tiles with no action,
+  each tile one link to its place (at least 44px tall); Retry stays its
+  own button above it. Six places make the phone's 3 × 2 grid; past
+  that, put the rest behind one tile ("More") rather than a third row.
+- Storybook's `app/ModuleCard` shows a hub with a strip and a widget,
+  every state, and both at `compact`; its checks run axe and the token and
+  glyph checks in both themes and at `large`, and measure the strip at a
+  desktop and a phone width.
+
 ## Notices
 
 A `Notice` says, across the page, a state that decides what you do with

package/dist/components/app/data-table.d.ts

@@ -97,6 +97,26 @@ export type DataTableProps<TData extends Record<string, unknown>> = {
      * Colour isn't the only signal: say why in the row too (a badge, a word).
      */
     highlightRow?: (row: TData) => boolean;
+    /**
+     * A totals row under the columns it adds up, the way a spreadsheet's
+     * is: `label` in the first visible column ("Total · 18 items"), then
+     * each of `cells` under the column with that id, in its alignment. The
+     * values come from the server, for every row the filters match, never
+     * summed from the page on the client. Shown only with rows: never while
+     * loading, on error or empty. Leave undefined (or null, before the data
+     * has come) for no row.
+     */
+    totals?: DataTableTotals | null;
 };
 export type DataTableWidth = 'full' | 'content';
-export declare function DataTable<TData extends Record<string, unknown>>({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width, groupBy, groupSummary, header: showHeader, highlightRow, }: DataTableProps<TData>): import("react").JSX.Element;
+export type DataTableTotals = {
+    /** Goes in the first visible column, as the row's header. */
+    label: ReactNode;
+    /**
+     * One value per column id, already formatted. A column left out, or
+     * hidden by `visibleColumns`, gets an empty cell or none. The first
+     * visible column holds the label, so a value for it isn't shown.
+     */
+    cells?: Partial<Record<string, ReactNode>>;
+};
+export declare function DataTable<TData extends Record<string, unknown>>({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width, groupBy, groupSummary, header: showHeader, highlightRow, totals, }: DataTableProps<TData>): import("react").JSX.Element;

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

@@ -23,7 +23,7 @@ import { EditInPlaceContext } from './edit-in-place.js';
 import { EditInPlaceStore } from './edit-in-place-store.js';
 import { LeaveGuard } from './editable-value.js';
 import { groupRuns } from './table-groups.js';
-import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow, } from '../ui/table.js';
+import { Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow, } from '../ui/table.js';
 // A column def's id as TanStack resolves it (constructColumn): `id`, then
 // `accessorKey` with dots as underscores, then a string header. Group
 // columns are looked through to their leaves, which visibility is keyed by.
@@ -59,6 +59,9 @@ const PINNED_COLUMN_CLASS = `sticky left-0 border-r ${PINNED_CELL_CLASS} group-h
 // 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}`;
+// The totals row's label, pinned with the first column (`totals`): the
+// same opaque cell, with no hover, since the row isn't one to pick.
+const PINNED_TOTALS_LABEL_CLASS = `sticky left-0 border-r ${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
@@ -82,6 +85,15 @@ const ROW_GROUP_CLASS = 'group/row hover:bg-transparent';
 // Inside, muted text takes the darker grey the wash needs (theme.css).
 const HIGHLIGHTED_ROW_CLASS = '[--muted-foreground:var(--table-highlight-muted-foreground)] [&>td]:bg-(--table-highlight) ' +
     '[&>td:first-child]:shadow-[inset_3px_0_0_0_var(--info-text)]';
+// `totals`: a footer row the way a spreadsheet's totals are, set apart
+// from the rows by a border twice a row divider's width and medium type,
+// on the page's background (table.tsx's footer tint is translucent, so a
+// pinned cell over it couldn't match without bleed-through). Its cells
+// read the body's density tokens, so it's a row's height, not the
+// header's; tabular figures line its numbers up with the column's.
+const TOTALS_FOOTER_CLASS = 'border-t-2 border-border bg-background tabular-nums';
+// Its label is a row header (<th scope="row">), padded as a body cell is.
+const TOTALS_LABEL_CLASS = 'h-auto py-(--table-cell-py)';
 // `header={false}`: the header row stays in the table, so every cell keeps
 // its column header for a screen reader, but takes no room: each header
 // is its name in an sr-only span, in a cell with no height or padding.
@@ -157,7 +169,7 @@ function useBottomScrollbar(containerRef, isSuccessView) {
     }, [containerRef, isSuccessView, isOverflowing]);
     return { barRef, isOverflowing, scrollWidth };
 }
-export function DataTable({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width = 'full', groupBy, groupSummary, header: showHeader = true, highlightRow, }) {
+export function DataTable({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width = 'full', groupBy, groupSummary, header: showHeader = true, highlightRow, totals, }) {
     // Editing in place in the rows (cell pattern 18, "In a table's rows"):
     // a cell that renders an <EditableValue> edits where it's shown, one at
     // a time, with the leave-page prompt while one is open, the same rules
@@ -216,7 +228,8 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     const containerRef = useRef(null);
     const { barRef, isOverflowing, scrollWidth } = useBottomScrollbar(containerRef, Boolean(pinFirstColumn) && isSuccessView);
     const rows = table.getRowModel().rows;
-    const visibleColumnCount = table.getVisibleLeafColumns().length;
+    const visibleLeafColumns = table.getVisibleLeafColumns();
+    const visibleColumnCount = visibleLeafColumns.length;
     // One body row, the same in a plain table and a grouped one.
     const renderRow = (row) => (_jsx(TableRow, { "data-highlighted": highlightRow?.(row.original) || undefined, className: cn(pinFirstColumn && ROW_GROUP_CLASS, highlightRow?.(row.original) && HIGHLIGHTED_ROW_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));
     const content = (_jsxs("div", { ref: root, className: cn('flex flex-col gap-4', width === 'content' && CONTENT_WIDTH_CLASS), "data-width": width, style: width === 'content' && !isSuccessView && lastWidth !== null
@@ -247,6 +260,9 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                                                     : sortDirection === 'desc'
                                                         ? 'descending'
                                                         : 'none', children: !showHeader ? (_jsx("span", { className: "sr-only", children: content })) : pinFirstColumn && index === 0 ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: content })) : (content) }, header.id));
-                                    }) }, headerGroup.id))) }), groupBy ? (groupRuns(rows, (row) => groupBy(row.original)).map((run, runIndex) => (_jsxs(TableBody, { "data-slot": "table-group", children: [_jsx(TableRow, { "data-slot": "table-group-heading", className: "hover:bg-transparent", children: _jsx(TableHead, { scope: "rowgroup", colSpan: visibleColumnCount, className: GROUP_HEADING_CLASS, children: _jsxs("span", { className: "sticky left-(--table-cell-px) inline-flex items-baseline gap-2", children: [_jsx("span", { className: "type-label text-foreground", children: run.label }), groupSummary && (_jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: groupSummary(run.rows.map((row) => row.original)) }))] }) }) }), _jsx("tr", { hidden: true, "aria-hidden": "true", "data-slot": "table-group-stripe-offset" }), run.rows.map(renderRow)] }, `${runIndex}:${run.key}`)))) : (_jsx(TableBody, { children: rows.map(renderRow) }))] }), 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, {}) })] })] })] }))] }));
+                                    }) }, headerGroup.id))) }), groupBy ? (groupRuns(rows, (row) => groupBy(row.original)).map((run, runIndex) => (_jsxs(TableBody, { "data-slot": "table-group", children: [_jsx(TableRow, { "data-slot": "table-group-heading", className: "hover:bg-transparent", children: _jsx(TableHead, { scope: "rowgroup", colSpan: visibleColumnCount, className: GROUP_HEADING_CLASS, children: _jsxs("span", { className: "sticky left-(--table-cell-px) inline-flex items-baseline gap-2", children: [_jsx("span", { className: "type-label text-foreground", children: run.label }), groupSummary && (_jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: groupSummary(run.rows.map((row) => row.original)) }))] }) }) }), _jsx("tr", { hidden: true, "aria-hidden": "true", "data-slot": "table-group-stripe-offset" }), run.rows.map(renderRow)] }, `${runIndex}:${run.key}`)))) : (_jsx(TableBody, { children: rows.map(renderRow) })), totals && (_jsx(TableFooter, { className: TOTALS_FOOTER_CLASS, children: _jsx(TableRow, { "data-slot": "table-totals", className: "hover:bg-transparent", children: visibleLeafColumns.map((column, index) => {
+                                        const className = cn(pinFirstColumn && index === 0 && PINNED_TOTALS_LABEL_CLASS, pinLastColumn && index === visibleColumnCount - 1 && PINNED_LAST_COLUMN_CLASS, column.columnDef.meta?.align === 'center' && 'text-center');
+                                        return index === 0 ? (_jsx(TableHead, { scope: "row", className: cn(TOTALS_LABEL_CLASS, className), children: pinFirstColumn ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: totals.label })) : (totals.label) }, column.id)) : (_jsx(TableCell, { className: className, children: totals.cells?.[column.id] }, column.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, {}) })] })] })] }))] }));
     return (_jsxs(EditInPlaceContext.Provider, { value: store, children: [editing && _jsx(LeaveGuard, { store: store }), width === 'content' ? _jsx("div", { className: "@container/data-table", children: content }) : content] }));
 }

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

@@ -0,0 +1,18 @@
+/**
+ * The open item once the list's ids have changed: the item that just
+ * appeared, when an add or a duplicate asked for it (`opening`), else the
+ * one that was open, if it's still there. A list replaced whole (a form's
+ * `reset`) gives every item a new id, and nothing asked, so nothing opens.
+ */
+export declare function followOpenItem({ before, after, open, opening, }: {
+    before: readonly string[];
+    after: readonly string[];
+    open: string | null;
+    opening: boolean;
+}): string | null;
+/** Whether an item shows its fields: it's the open one, or it has an error to show. */
+export declare function isItemOpen({ id, open, invalid }: {
+    id: string;
+    open: string | null;
+    invalid: boolean;
+}): boolean;

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

@@ -0,0 +1,23 @@
+// Which of ListEditor's items are open, when its items show as summary
+// lines (`summary`, #222). One item is open at a time, held by its stable
+// id (useFieldArray's `field.id`), so it stays open while rows move and
+// closes when it's removed. An item that was just added or duplicated
+// opens, and one with a validation error is open whatever else is.
+/**
+ * The open item once the list's ids have changed: the item that just
+ * appeared, when an add or a duplicate asked for it (`opening`), else the
+ * one that was open, if it's still there. A list replaced whole (a form's
+ * `reset`) gives every item a new id, and nothing asked, so nothing opens.
+ */
+export function followOpenItem({ before, after, open, opening, }) {
+    if (opening) {
+        const added = after.find((id) => !before.includes(id));
+        if (added !== undefined)
+            return added;
+    }
+    return open !== null && after.includes(open) ? open : null;
+}
+/** Whether an item shows its fields: it's the open one, or it has an error to show. */
+export function isItemOpen({ id, open, invalid }) {
+    return invalid || id === open;
+}

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

@@ -1,25 +1,47 @@
-import type { ReactNode } from 'react';
-export declare function ListEditor({ items, renderItem, onAdd, onRemove, onMove, itemName, addLabel, emptyText, max, add, disabled, 'aria-label': ariaLabel, }: {
+import { type ReactNode } from 'react';
+export declare function ListEditor({ items, renderItem, summary, invalid, onAdd, onRemove, onMove, onDuplicate, 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;
+    /**
+     * Shows each item as one line, this text (e.g. "Squat · 3 × 8 at 60 kg"),
+     * that opens to its `renderItem` fields on a click, Enter or Space. One
+     * item is open at a time; one just added or duplicated opens. For a long
+     * list of rich items. Without it, every item shows its fields.
+     */
+    summary?: (index: number) => ReactNode;
+    /**
+     * With `summary`: the item at this index has an error to show, e.g.
+     * (i) => !!errors.steps?.[i]. It opens, beside the open one, until the
+     * error clears, so a refused save never hides why. react-hook-form's
+     * focus on the first error then makes that item the open one.
+     */
+    invalid?: (index: number) => boolean;
     /** The Add button's action. Not needed with `add`. */
     onAdd?: () => void;
     onRemove: (index: number) => void;
     onMove: (from: number, to: number) => void;
+    /**
+     * Puts a Duplicate button beside Remove. The app inserts the copy right
+     * after the original, e.g. (i) => insert(i + 1, { ...getValues(`steps.${i}`) }),
+     * leaving out anything a copy mustn't share (a saved id). With `summary`,
+     * the copy opens. Disabled once `max` is reached, as Add is.
+     */
+    onDuplicate?: (index: number) => void;
     /**
      * How the row buttons name an item for a screen reader, e.g.
      * (i) => `item ${i + 1}` gives "Move item 2 up", "Remove item 2".
+     * A summary line is named by it too: "item 2: Squat · 3 × 8 at 60 kg".
      */
     itemName: (index: number) => string;
     /** The Add button's text, e.g. "Add item". */
     addLabel: string;
     /** Shown instead of the list when it's empty. */
     emptyText?: string;
-    /** The most items allowed; Add is disabled once reached. */
+    /** The most items allowed; Add and Duplicate are disabled once reached. */
     max?: number;
     /** In place of the Add button: what adds an item (editing in place's Add box). */
     add?: ReactNode;

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

@@ -1,10 +1,66 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { ArrowDownIcon, ArrowUpIcon, PlusIcon, Trash2Icon } from 'lucide-react';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// Edits a list of sub-records inside a parent's form: one row per item,
+// each with move up / move down / remove, and an Add button below. The one
+// control for every "sub-records" section of an entity plan
+// (conventions/docs/entity-plan-template.md): Widget's checklist, a task's
+// checklist and links.
+//
+// It owns the row chrome only. Each item's fields are the app's (rendered
+// by `renderItem`), and so is the state: pass react-hook-form's
+// useFieldArray `fields`, `append`, `remove` and `move`, so the items save
+// with the parent's form and their errors bind like any other field.
+//
+// A long list of rich items (#222) can show each item as one line instead
+// (`summary`): the line is a button that opens the item to its fields,
+// one item at a time (list-editor-rows.ts), with the row buttons beside
+// it. And `onDuplicate` puts a Duplicate button beside Remove, for lists
+// whose items repeat with small changes. Without either, every item shows
+// its fields, as before.
+//
+// Editing a list in place on a view (editable-list.tsx) is built on it
+// too, so the rows and their buttons match the form's: there, `add` is the
+// in-place Add box, and `disabled` holds the buttons while a change saves.
+import { useState } from 'react';
+import { ArrowDownIcon, ArrowUpIcon, ChevronRightIcon, CopyIcon, 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, add, disabled = false, 'aria-label': ariaLabel, }) {
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '../ui/collapsible.js';
+import { followOpenItem, isItemOpen } from './list-editor-rows.js';
+export function ListEditor({ items, renderItem, summary, invalid, onAdd, onRemove, onMove, onDuplicate, itemName, addLabel, emptyText = 'Nothing added yet.', max, add, disabled = false, 'aria-label': ariaLabel, }) {
     const atMax = max !== undefined && items.length >= max;
+    // The open item, by id. When the ids change (an add, a move, a remove),
+    // it follows them here, in the render that shows the change, so a new
+    // item's fields are already there when react-hook-form focuses them.
+    const ids = items.map((item) => item.id);
+    const [open, setOpen] = useState(null);
+    const [opening, setOpening] = useState(false);
+    const [seen, setSeen] = useState(ids);
+    if (seen.join('\n') !== ids.join('\n')) {
+        setSeen(ids);
+        setOpen(followOpenItem({ before: seen, after: ids, open, opening }));
+        setOpening(false);
+    }
+    // An add or a duplicate asks for the item it makes to open. The app's
+    // action runs in the same click, so its new id arrives with the ask.
+    const addItem = () => {
+        setOpening(true);
+        onAdd?.();
+    };
+    const duplicate = (index) => {
+        setOpening(true);
+        onDuplicate?.(index);
+    };
+    const rowButtons = (index, name) => (_jsxs(_Fragment, { children: [_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, {}) }), onDuplicate && (_jsx(Button, { type: "button", variant: "ghost", size: "icon-sm", "aria-label": `Duplicate ${name}`, disabled: disabled || atMax, onClick: () => duplicate(index), children: _jsx(CopyIcon, {}) })), _jsx(Button, { type: "button", variant: "ghost", size: "icon-sm", "aria-label": `Remove ${name}`, disabled: disabled, onClick: () => onRemove(index), children: _jsx(Trash2Icon, {}) })] }));
     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: 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] }) }))] }));
+                    if (!summary) {
+                        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) }), rowButtons(index, name)] }, item.id));
+                    }
+                    // A summary line: the whole line is the button (named by the
+                    // item's name, then its summary), the row buttons beside it,
+                    // and the fields under it while it's open. Clicking the line
+                    // again closes it; an item with an error stays open. Going into
+                    // an item's fields makes it the open one, so one opened by its
+                    // error doesn't close under the caret once the error clears.
+                    return (_jsx("li", { children: _jsxs(Collapsible, { open: isItemOpen({ id: item.id, open, invalid: invalid?.(index) ?? false }), onOpenChange: (next) => setOpen((current) => (next ? item.id : current === item.id ? null : current)), className: "flex flex-col gap-2", children: [_jsxs("div", { className: "flex items-start gap-1", children: [_jsxs(CollapsibleTrigger, { className: "group/summary flex min-h-7 min-w-0 flex-1 items-center gap-1.5 rounded-lg px-1.5 py-1 text-left type-body text-foreground outline-none hover:bg-muted focus-visible:ring-3 focus-visible:ring-ring/50", children: [_jsx(ChevronRightIcon, { "aria-hidden": "true", className: "size-4 shrink-0 text-muted-foreground transition-transform group-data-[panel-open]/summary:rotate-90 motion-reduce:transition-none" }), _jsxs("span", { className: "sr-only", children: [name, ": "] }), _jsx("span", { className: "min-w-0 flex-1 truncate", children: summary(index) })] }), rowButtons(index, name)] }), _jsx(CollapsibleContent, { className: "flex min-w-0 items-start gap-2 pl-7", onFocus: () => setOpen(item.id), children: renderItem(index) })] }) }, item.id));
+                }) })), add ?? (_jsx("div", { children: _jsxs(Button, { type: "button", variant: "outline", size: "sm", onClick: addItem, disabled: disabled || atMax, children: [_jsx(PlusIcon, {}), addLabel] }) }))] }));
 }

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

@@ -1,7 +1,15 @@
-import type { ComponentProps } from 'react';
+import { type ComponentProps } from 'react';
+import { type HeadingLevel } from './prose-look.js';
 export type MarkdownProps = {
     /** The Markdown source. Raw HTML in it is shown as text, never rendered. */
     children: string;
+    /**
+     * The HTML level the text's `#` renders as, where the text sits in the
+     * page's outline: 2 straight under the page's <h1>, 3 (the default)
+     * under a section's <h2>. `##` is one below it, `###` two below, never
+     * past <h6>. Only the element changes: each level looks the same.
+     */
+    headingLevel?: HeadingLevel;
     className?: string;
 } & Omit<ComponentProps<'div'>, 'children'>;
-export declare function Markdown({ children, className, ...rest }: MarkdownProps): import("react").JSX.Element;
+export declare function Markdown({ children, headingLevel, className, ...rest }: MarkdownProps): import("react").JSX.Element;