@tristan2828/ui-foundation 4.32.0 → 4.33.0

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

@@ -269,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
@@ -330,7 +344,9 @@ 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`. A composite
   reaches `compact` with the `density-compact:` variant (`styles/index.css`:

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;

package/dist/components/app/markdown.js

@@ -1,11 +1,50 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Long text written as Markdown, rendered to read: headings, lists, links,
+// tables (GitHub-flavoured), code and quotes, in the design language's
+// type roles and tokens. A record's notes on its view (EntityView) are the
+// first use.
+//
+// Safe by default, and kept that way on purpose:
+// - Raw HTML is never rendered. react-markdown escapes it, so `<b>` in the
+//   text shows as the characters `<b>`, never as markup, and nothing the
+//   author typed silently disappears. Never add rehype-raw.
+// - URLs go through react-markdown's default urlTransform, which drops
+//   `javascript:` and other unsafe protocols. A link left with no URL
+//   renders as its text.
+// - Links open in a new tab, so following one never leaves the record.
+//
+// Headings start at <h3> by default: the page owns the <h1> (the
+// record's title) and each section its <h2>, so a `# Heading` in the text
+// sits under them instead of competing with the page's own outline. Text
+// that sits elsewhere says so with `headingLevel`, the level `#` renders
+// as (2 straight under the page's <h1>), each level below it one deeper,
+// never past <h6>, so the page's outline never skips a level (axe's
+// heading-order). They look like what they are in the text, wherever they
+// sit: `#` and `##` on a tinted band, `###` a small uppercase label, and
+// the text under them lined up with the words in the band (prose-look.ts).
+//
+// A table wider than the text scrolls sideways, and while it does, its
+// box is a tab stop, named for its columns, that the arrow keys scroll
+// (prose-table-scroll.ts). Its cells wrap first, so that's only a table
+// with many columns, or a long word in one.
+//
+// An image (`![alt](url)`, one the rich-text editor uploaded) stays inside
+// the text's width, loads only as it nears the screen, and keeps its alt
+// text; with none (`![](url)`) it's decorative to a screen reader. Its
+// address goes through the same urlTransform: a web address or a path on
+// the site (`/api/files/7/content`), never `javascript:` or `data:`.
+//
+// A quote that starts `[!NOTE]` (GitHub's alert syntax) is a callout: a
+// tinted box with its kind's icon (src/lib/markdown-callout.ts).
+import { useEffect, useMemo, useRef } from 'react';
 import ReactMarkdown, {} from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import { cn } from 'cn';
 import { ExternalLinkIcon, SquareCheckIcon, SquareIcon } from 'lucide-react';
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../ui/table.js';
 import { CALLOUT_KINDS, remarkCallouts } from '../../lib/markdown-callout.js';
-import { CALLOUT_BOX, CALLOUT_LOOK, headingClass, PROSE, PROSE_INSET } from './prose-look.js';
+import { CALLOUT_BOX, CALLOUT_LOOK, DEFAULT_HEADING_LEVEL, headingBand, headingClass, headingTag, PROSE, PROSE_INSET, } from './prose-look.js';
+import { headerTexts, TABLE_SCROLL_FOCUS, watchTableScroll } from './prose-table-scroll.js';
 const REMARK_PLUGINS = [remarkGfm, remarkCallouts];
 function isCalloutKind(value) {
     return CALLOUT_KINDS.includes(value);
@@ -17,14 +56,31 @@ function omitNode(props) {
     delete rest.node;
     return rest;
 }
-// The text's colour first, so a level's own (`###`'s muted label) wins.
+// A GFM table in the package's own table, in its box that scrolls
+// sideways: a tab stop and a named region only while the table overflows
+// it. Watched again after each render, so a header row with new words
+// renames it.
+function NotesTable(props) {
+    const boxRef = useRef(null);
+    useEffect(() => {
+        const box = boxRef.current;
+        if (!box)
+            return;
+        const table = box.querySelector('table');
+        const region = watchTableScroll(box, table, headerTexts(table));
+        return () => region.destroy();
+    });
+    return (_jsx(Table, { ...props, containerRef: boxRef, containerClassName: cn('rounded-lg border border-border', TABLE_SCROLL_FOCUS) }));
+}
+// A heading by its Markdown level: the element the page's outline gives
+// it (headingTag), the look its level has. The text's colour first, so a
+// level's own (`###`'s muted label) wins.
+function heading(level, top) {
+    const Tag = headingTag(level, top);
+    return (props) => (_jsx(Tag, { ...omitNode(props), "data-band": headingBand(level) || undefined, className: cn('text-foreground', headingClass(level)) }));
+}
+// Everything but the headings, which follow `headingLevel` (componentsFor).
 const COMPONENTS = {
-    h1: (props) => _jsx("h3", { ...omitNode(props), className: cn('text-foreground', headingClass(1)) }),
-    h2: (props) => _jsx("h4", { ...omitNode(props), className: cn('text-foreground', headingClass(2)) }),
-    h3: (props) => _jsx("h5", { ...omitNode(props), className: cn('text-foreground', headingClass(3)) }),
-    h4: (props) => _jsx("h6", { ...omitNode(props), className: cn('text-foreground', headingClass(4)) }),
-    h5: (props) => _jsx("h6", { ...omitNode(props), className: cn('text-foreground', headingClass(5)) }),
-    h6: (props) => _jsx("h6", { ...omitNode(props), className: cn('text-foreground', headingClass(6)) }),
     a: (props) => {
         const { href, children, ...rest } = omitNode(props);
         if (!href)
@@ -65,7 +121,7 @@ const COMPONENTS = {
     },
     // GFM tables use the package's own table, zebra stripes and density
     // tokens included, so a table in the notes reads like every other table.
-    table: (props) => _jsx(Table, { ...omitNode(props), containerClassName: "rounded-lg border border-border" }),
+    table: (props) => _jsx(NotesTable, { ...omitNode(props) }),
     thead: (props) => _jsx(TableHeader, { ...omitNode(props), className: "bg-muted" }),
     tbody: (props) => _jsx(TableBody, { ...omitNode(props) }),
     tr: (props) => _jsx(TableRow, { ...omitNode(props) }),
@@ -74,6 +130,19 @@ const COMPONENTS = {
     th: (props) => _jsx(TableHead, { ...omitNode(props), className: "border-r border-border whitespace-normal last:border-r-0" }),
     td: (props) => _jsx(TableCell, { ...omitNode(props), className: "border-r border-border whitespace-normal last:border-r-0" }),
 };
-export function Markdown({ children, className, ...rest }) {
-    return (_jsx("div", { "data-slot": "markdown", ...rest, className: cn('flex min-w-0 flex-col gap-3 type-body text-foreground break-words', PROSE_INSET, className), children: _jsx(ReactMarkdown, { remarkPlugins: REMARK_PLUGINS, components: COMPONENTS, children: children }) }));
+// The components for each `headingLevel`, made once each.
+const BY_LEVEL = new Map();
+function componentsFor(top) {
+    let components = BY_LEVEL.get(top);
+    if (!components) {
+        components = { ...COMPONENTS };
+        for (const level of [1, 2, 3, 4, 5, 6])
+            components[`h${level}`] = heading(level, top);
+        BY_LEVEL.set(top, components);
+    }
+    return components;
+}
+export function Markdown({ children, headingLevel = DEFAULT_HEADING_LEVEL, className, ...rest }) {
+    const components = useMemo(() => componentsFor(headingLevel), [headingLevel]);
+    return (_jsx("div", { "data-slot": "markdown", ...rest, className: cn('flex min-w-0 flex-col gap-3 type-body text-foreground break-words', PROSE_INSET, className), children: _jsx(ReactMarkdown, { remarkPlugins: REMARK_PLUGINS, components: components, children: children }) }));
 }

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

@@ -1,2 +1,2 @@
 import type { RichTextEditorProps } from './rich-text-editor.js';
-export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly, autoFocus, placeholder, maxLength, toolbar, inline, upload, imageAccept, imageMaxSize, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }: RichTextEditorProps): import("react").JSX.Element;
+export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly, autoFocus, placeholder, maxLength, toolbar, inline, upload, imageAccept, imageMaxSize, headingLevel, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }: RichTextEditorProps): import("react").JSX.Element;

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

@@ -13,11 +13,15 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 //   in the text shows as its characters (an uneditable chip, Milkdown's
 //   html node), and HTML pasted as such a chip becomes plain text.
 // - Headings render from <h3>, like <Markdown>: the page owns <h1> and
-//   <h2>; they look like <Markdown>'s (prose-look.ts). A task-list item
-//   renders a real checkbox that toggles it.
+//   <h2>. `headingLevel` moves them to where the field sits in the page's
+//   outline, as it does <Markdown>'s; only the element moves, never the
+//   level the Markdown is saved with (a node view draws it, from the
+//   node's own level). They look like <Markdown>'s (prose-look.ts). A
+//   task-list item renders a real checkbox that toggles it.
 // - Callouts (`> [!NOTE]`, src/lib/markdown-callout.ts): a node of their
 //   own, drawn as <Markdown> draws them, the icon a menu of kinds.
-// - Tables in a box that scrolls sideways, with Notion's "add a row" and
+// - Tables in a box that scrolls sideways (a tab stop the arrow keys
+//   scroll while it does: rich-text-node-views.ts), with Notion's "add a row" and
 //   "add a column" bars, Tab in the last cell adding a row and Enter going
 //   down a column (rich-text-table.ts); the toolbar's Table menu does the
 //   rest.
@@ -66,7 +70,7 @@ import { linkHref, linkRefusal } from '../../lib/link-href.js';
 import { passEscapeThrough } from './escape-passthrough.js';
 import { calloutHandler, remarkCalloutNodes } from '../../lib/markdown-callout.js';
 import { MarkdownMergeError, markdownStyle, mergeMarkdown } from '../../lib/markdown-merge.js';
-import { headingClass } from './prose-look.js';
+import { DEFAULT_HEADING_LEVEL, headingBand, headingClass, headingTag } from './prose-look.js';
 import { RichTextFloatingToolbar } from './rich-text-floating-toolbar.js';
 import { tableAt, toggleFormat } from './rich-text-formats.js';
 import { calloutKind, calloutView, tableView } from './rich-text-node-views.js';
@@ -138,10 +142,14 @@ function htmlToText(fragment) {
     });
     return Fragment.fromArray(nodes);
 }
-function headingView(node) {
+// A heading: the element `headingLevel` gives its level, the look its
+// level has. Marked as a band for PROSE_INSET (`#` and `##`).
+function headingView(node, top) {
     const level = Number(node.attrs.level);
-    const dom = document.createElement(`h${Math.min(level + 2, 6)}`);
+    const dom = document.createElement(headingTag(level, top));
     dom.className = headingClass(level);
+    if (headingBand(level))
+        dom.dataset.band = '';
     return {
         dom,
         contentDOM: dom,
@@ -253,7 +261,7 @@ function applyLink(view, target, href) {
     }
     view.dispatch(tr.scrollIntoView());
 }
-export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly = false, autoFocus = false, placeholder, maxLength, toolbar = true, inline = false, upload, imageAccept, imageMaxSize, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }) {
+export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly = false, autoFocus = false, placeholder, maxLength, toolbar = true, inline = false, upload, imageAccept, imageMaxSize, headingLevel = DEFAULT_HEADING_LEVEL, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }) {
     const rootRef = useRef(null);
     const editorRef = useRef(null);
     const [linkBox, setLinkBox] = useState(null);
@@ -616,9 +624,10 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                     return mod && !event.shiftKey && !event.altKey && event.key === 'Enter' && isInTable(view.state);
                 },
                 nodeViews: {
-                    heading: headingView,
+                    // The level when it mounts, as with defaultValue.
+                    heading: (node) => headingView(node, headingLevel),
                     callout: (node, _view, getPos) => calloutView(node, getPos, registry),
-                    table: (_node, _view, getPos) => tableView(getPos, registry),
+                    table: (node, view, getPos) => tableView(node, view, getPos, registry),
                     list_item: (node, view, getPos) => node.attrs.checked == null ? undefined : taskItemView(node, view, getPos),
                 },
             }));
@@ -792,7 +801,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                         '[&_.ProseMirror]:flex [&_.ProseMirror]:flex-col [&_.ProseMirror]:gap-3', 
                         // PROSE_INSET, on the editable element: with a heading's band
                         // in the text, the rest lines up with the words in it.
-                        '[&_.ProseMirror:has(>:is(h3,h4))>:not(h3,h4)]:mx-3', !inline && '[&_.ProseMirror]:min-h-20', 
+                        '[&_.ProseMirror:has(>[data-band])>:not([data-band])]:mx-3', !inline && '[&_.ProseMirror]:min-h-20', 
                         // ProseMirror's own required style (prosemirror-view's CSS): spaces
                         // as typed, so one at the end of a line isn't kept as &nbsp;.
                         '[&_.ProseMirror]:whitespace-pre-wrap [&_.ProseMirror]:break-words', '[&_ul]:flex [&_ul]:list-disc [&_ul]:flex-col [&_ul]:gap-1 [&_ul]:pl-6', '[&_ol]:flex [&_ol]:list-decimal [&_ol]:flex-col [&_ol]:gap-1 [&_ol]:pl-6', '[&_li[data-item-type=task]]:-ml-6 [&_li[data-item-type=task]]:flex [&_li[data-item-type=task]]:list-none [&_li[data-item-type=task]]:items-start [&_li[data-item-type=task]]:gap-2', '[&_li[data-item-type=task]>input]:mt-1 [&_li[data-item-type=task]>input]:size-4 [&_li[data-item-type=task]>input]:accent-primary', 

package/dist/components/app/prose-look.d.ts

@@ -27,13 +27,33 @@ export declare const PROSE: {
     readonly rule: "my-2 h-0.5 rounded-full border-0 bg-rule";
 };
 /**
- * On the text's container: when it has a band (the `<h3>` or `<h4>` a `#`
- * or `##` renders as), everything else is inset by the band's 12px
- * padding, so the text lines up with the words in the band. Text with no
- * band stays flush, where the section's own text starts. A margin, so a
- * list's own indent and a table's or callout's box keep theirs.
+ * On the text's container: when it has a band (a `#` or `##`, marked
+ * `data-band`, whatever element its `headingLevel` makes it), everything
+ * else is inset by the band's 12px padding, so the text lines up with the
+ * words in the band. Text with no band stays flush, where the section's
+ * own text starts. A margin, so a list's own indent and a table's or
+ * callout's box keep theirs.
  */
-export declare const PROSE_INSET = "[&:has(>:is(h3,h4))>:not(h3,h4)]:mx-3";
+export declare const PROSE_INSET = "[&:has(>[data-band])>:not([data-band])]:mx-3";
+/**
+ * The HTML level a heading in the text can render as. `headingLevel` on
+ * <Markdown> and the editor is the one `#` renders as: where the text
+ * sits in the page's outline (2 straight under the page's <h1>, 3 under a
+ * section's <h2>, the default).
+ */
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/** `#` renders as an <h3>: the page owns the <h1> and each section its <h2>. */
+export declare const DEFAULT_HEADING_LEVEL: HeadingLevel;
+/**
+ * The element a heading renders as, by its Markdown level (1 for `#`) and
+ * the level `#` renders as: `##` one below it, `###` two below, and so on,
+ * never past <h6>. Only the element follows the page; the look (the band,
+ * the label) stays the Markdown level's (headingClass), so a `#` looks
+ * like a `#` wherever it sits.
+ */
+export declare function headingTag(level: number, top?: HeadingLevel): `h${HeadingLevel}`;
+/** Whether a heading sits on a band (`#` and `##`): the text beside it is inset (PROSE_INSET). */
+export declare function headingBand(level: number): boolean;
 /** A heading's classes by its Markdown level (1 for `#`). */
 export declare function headingClass(level: number): string;
 export type CalloutLook = {

package/dist/components/app/prose-look.js

@@ -33,13 +33,31 @@ export const PROSE = {
     rule: 'my-2 h-0.5 rounded-full border-0 bg-rule',
 };
 /**
- * On the text's container: when it has a band (the `<h3>` or `<h4>` a `#`
- * or `##` renders as), everything else is inset by the band's 12px
- * padding, so the text lines up with the words in the band. Text with no
- * band stays flush, where the section's own text starts. A margin, so a
- * list's own indent and a table's or callout's box keep theirs.
+ * On the text's container: when it has a band (a `#` or `##`, marked
+ * `data-band`, whatever element its `headingLevel` makes it), everything
+ * else is inset by the band's 12px padding, so the text lines up with the
+ * words in the band. Text with no band stays flush, where the section's
+ * own text starts. A margin, so a list's own indent and a table's or
+ * callout's box keep theirs.
  */
-export const PROSE_INSET = '[&:has(>:is(h3,h4))>:not(h3,h4)]:mx-3';
+export const PROSE_INSET = '[&:has(>[data-band])>:not([data-band])]:mx-3';
+/** `#` renders as an <h3>: the page owns the <h1> and each section its <h2>. */
+export const DEFAULT_HEADING_LEVEL = 3;
+/**
+ * The element a heading renders as, by its Markdown level (1 for `#`) and
+ * the level `#` renders as: `##` one below it, `###` two below, and so on,
+ * never past <h6>. Only the element follows the page; the look (the band,
+ * the label) stays the Markdown level's (headingClass), so a `#` looks
+ * like a `#` wherever it sits.
+ */
+export function headingTag(level, top = DEFAULT_HEADING_LEVEL) {
+    const markdown = Math.max(1, Math.floor(level) || 1);
+    return `h${Math.min(top + markdown - 1, 6)}`;
+}
+/** Whether a heading sits on a band (`#` and `##`): the text beside it is inset (PROSE_INSET). */
+export function headingBand(level) {
+    return level <= 2;
+}
 /** A heading's classes by its Markdown level (1 for `#`). */
 export function headingClass(level) {
     return level === 1 ? PROSE.heading1 : level === 2 ? PROSE.heading2 : level === 3 ? PROSE.heading3 : PROSE.heading4;

package/dist/components/app/prose-table-scroll.d.ts

@@ -0,0 +1,33 @@
+/** The box's focus ring, from the semantic tokens: on the box's own classes. */
+export declare const TABLE_SCROLL_FOCUS = "outline-none focus-visible:ring-3 focus-visible:ring-ring/50";
+/**
+ * The region's accessible name: "Table, scrolls sideways", then the
+ * header row's first few columns ("…: Part, Width, Depth"). Empty
+ * headers are skipped; with none, the phrase alone.
+ */
+export declare function tableScrollName(columns: readonly string[]): string;
+/** What the box needs of its element: as much as tests can fake. */
+type ScrollBox = Pick<HTMLElement, 'scrollWidth' | 'clientWidth' | 'setAttribute' | 'removeAttribute' | 'getAttribute'>;
+export type TableScrollRegion = {
+    /** The header row's texts, for the name: called again when they change (the editor's edits). */
+    setColumns: (columns: readonly string[]) => void;
+    /** Checks again whether the table overflows. The observers call it; a test can too. */
+    check: () => void;
+    /**
+     * Takes the tab stop off until `resume`, the rest kept: for a press in
+     * the editor's box, whose focus belongs to the text, not the box.
+     */
+    suspend: () => void;
+    resume: () => void;
+    /** Stops watching. The box keeps whatever it last was. */
+    destroy: () => void;
+};
+/**
+ * Watches a table's scroll box: a tab stop and a named region while the
+ * table is wider than the box, nothing while it fits. `table` is what
+ * scrolls in it (observed for its size; the box alone when absent).
+ */
+export declare function watchTableScroll(box: ScrollBox, table?: Element | null, columns?: readonly string[]): TableScrollRegion;
+/** A rendered table's header row, as texts: the header cells of its first row. */
+export declare function headerTexts(table: Element | null | undefined): string[];
+export {};

package/dist/components/app/prose-table-scroll.js

@@ -0,0 +1,87 @@
+// A table in written text, <Markdown>'s or the editor's, sits in a box
+// that scrolls sideways when the table is wider than the text. A box that
+// scrolls has to be reachable from the keyboard (axe's
+// scrollable-region-focusable), or someone without a mouse can never see
+// its right-hand columns. So, only while the table overflows, the box is
+// a tab stop and a named region: "Table, scrolls sideways", then its
+// columns, which tell two tables on a page apart (two regions with one
+// name are axe's landmark-unique) and say which table it is. With the
+// arrow keys it then scrolls. A table that fits is left alone: no tab
+// stop and no region, nothing to reach that does nothing.
+//
+// It follows the table: a ResizeObserver on the box (the text's width
+// changing) and on the table (a column added, a cell's text growing)
+// checks again each time either changes size.
+/** The box's focus ring, from the semantic tokens: on the box's own classes. */
+export const TABLE_SCROLL_FOCUS = 'outline-none focus-visible:ring-3 focus-visible:ring-ring/50';
+// The columns named in the region's name; past them, an ellipsis.
+const NAMED_COLUMNS = 3;
+/**
+ * The region's accessible name: "Table, scrolls sideways", then the
+ * header row's first few columns ("…: Part, Width, Depth"). Empty
+ * headers are skipped; with none, the phrase alone.
+ */
+export function tableScrollName(columns) {
+    const named = columns.map((column) => column.replace(/\s+/g, ' ').trim()).filter(Boolean);
+    if (named.length === 0)
+        return 'Table, scrolls sideways';
+    const shown = named.slice(0, NAMED_COLUMNS).join(', ');
+    return `Table, scrolls sideways: ${shown}${named.length > NAMED_COLUMNS ? ', …' : ''}`;
+}
+// Set only when it differs, so a check that finds nothing new writes
+// nothing (the editor reads its own DOM's mutations).
+function set(box, name, value) {
+    if (box.getAttribute(name) === value)
+        return;
+    if (value === null)
+        box.removeAttribute(name);
+    else
+        box.setAttribute(name, value);
+}
+/**
+ * Watches a table's scroll box: a tab stop and a named region while the
+ * table is wider than the box, nothing while it fits. `table` is what
+ * scrolls in it (observed for its size; the box alone when absent).
+ */
+export function watchTableScroll(box, table, columns = []) {
+    let name = tableScrollName(columns);
+    let suspended = false;
+    const check = () => {
+        // scrollWidth counts what's hidden past the right edge; the two are
+        // whole pixels, so a table that just fits measures equal.
+        const overflows = box.scrollWidth > box.clientWidth;
+        set(box, 'tabindex', overflows && !suspended ? '0' : null);
+        set(box, 'role', overflows ? 'region' : null);
+        set(box, 'aria-label', overflows ? name : null);
+    };
+    // Server rendering and tests have no ResizeObserver: one check, then
+    // whatever the box was.
+    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(check);
+    if (observer) {
+        observer.observe(box);
+        if (table)
+            observer.observe(table);
+    }
+    check();
+    return {
+        setColumns: (next) => {
+            name = tableScrollName(next);
+            check();
+        },
+        check,
+        suspend: () => {
+            suspended = true;
+            check();
+        },
+        resume: () => {
+            suspended = false;
+            check();
+        },
+        destroy: () => observer?.disconnect(),
+    };
+}
+/** A rendered table's header row, as texts: the header cells of its first row. */
+export function headerTexts(table) {
+    const row = table?.querySelector('tr');
+    return row ? Array.from(row.querySelectorAll('th'), (cell) => cell.textContent ?? '') : [];
+}

package/dist/components/app/rich-text-editor.d.ts

@@ -1,4 +1,5 @@
 import type { ImageUpload } from '../../lib/image-file.js';
+import type { HeadingLevel } from './prose-look.js';
 export type RichTextEditorProps = {
     /** The editable element's id, for a label's `htmlFor` or a test. */
     id?: string;
@@ -52,6 +53,15 @@ export type RichTextEditorProps = {
     imageAccept?: readonly string[];
     /** The largest image `upload` takes, in bytes: a bigger one is refused before it's sent, with its size and the limit. */
     imageMaxSize?: number;
+    /**
+     * The HTML level the text's `#` renders as, where the field sits in the
+     * page's outline: 2 straight under the page's <h1> (a form), 3 (the
+     * default) under a section's <h2>. `##` is one below it, `###` two
+     * below, never past <h6>, as in `<Markdown>`. Only the element changes:
+     * the look, and the Markdown saved (`#` stays `#`), don't. Read once,
+     * when it mounts.
+     */
+    headingLevel?: HeadingLevel;
     className?: string;
     /** The field's label. A rich-text area must have one: this, or `aria-labelledby`. */
     'aria-label'?: string;

package/dist/components/app/rich-text-editor.js

@@ -13,6 +13,11 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Raw HTML in the text shows as its characters, as <Markdown> shows it,
 // and nothing pasted or typed can add markup.
 //
+// Headings in the text sit under the page's outline (`headingLevel`, from
+// <h3> by default), as <Markdown>'s do. A table wider than the field
+// scrolls sideways, and while it does, its box is a tab stop the arrow
+// keys scroll.
+//
 // Images in the text (`![alt](url)`) show, at most the field's width.
 // With `upload`, an image pasted, dropped or picked with the toolbar's
 // Image button is uploaded through the app's own storage and goes in as

package/dist/components/app/rich-text-node-views.d.ts

@@ -1,5 +1,5 @@
 import type { Node as ProseNode } from '@milkdown/kit/prose/model';
-import type { NodeView } from '@milkdown/kit/prose/view';
+import type { EditorView, NodeView } from '@milkdown/kit/prose/view';
 import { type CalloutKind } from '../../lib/markdown-callout.js';
 /** A slot a node view has, for the editor to render its widget into. */
 export type Widget = {
@@ -26,6 +26,9 @@ export declare function calloutView(node: ProseNode, getPos: () => number | unde
 /**
  * A table: in a box that scrolls sideways when it's wider than the text,
  * with an "add a column" bar along its right and an "add a row" bar under
- * it (widgets), Notion's way.
+ * it (widgets), Notion's way. While it scrolls, the box is a tab stop and
+ * a region named for its columns (prose-table-scroll.ts), which the arrow
+ * keys, Home and End scroll; a click in it still puts the caret in the
+ * cell clicked.
  */
-export declare function tableView(getPos: () => number | undefined, registry: WidgetRegistry): NodeView;
+export declare function tableView(node: ProseNode, view: EditorView, getPos: () => number | undefined, registry: WidgetRegistry): NodeView;

package/dist/components/app/rich-text-node-views.js

@@ -1,6 +1,7 @@
 import { cn } from 'cn';
 import { CALLOUT_KINDS } from '../../lib/markdown-callout.js';
 import { CALLOUT_BOX, CALLOUT_LOOK } from './prose-look.js';
+import { TABLE_SCROLL_FOCUS, watchTableScroll } from './prose-table-scroll.js';
 // Each slot's key for its portal, for as long as the node view lives.
 let made = 0;
 const nextKey = () => `widget-${++made}`;
@@ -49,17 +50,55 @@ export function calloutView(node, getPos, registry) {
         destroy: () => registry.remove(icon),
     };
 }
+// A table's header row, as texts, from the node (its first row's cells).
+function columnsOf(node) {
+    const header = node.firstChild;
+    if (!header)
+        return [];
+    const columns = [];
+    header.forEach((cell) => columns.push(cell.textContent));
+    return columns;
+}
+// How far an arrow key scrolls the table's box.
+const SCROLL_STEP = 40;
+// The keys a focused table box takes: the arrow keys, Home and End scroll
+// it, as a box that isn't editable scrolls by itself, and any other plain
+// key adds nothing (the text can't be typed into from the table's frame).
+// Tab, Esc and shortcuts are left alone: Tab leaves the box, Esc and the
+// shortcuts go on to the field. True when it took the key.
+function scrollKey(box, event) {
+    if (event.ctrlKey || event.metaKey || event.altKey || event.key === 'Tab' || event.key === 'Escape')
+        return false;
+    const max = box.scrollWidth - box.clientWidth;
+    const to = {
+        ArrowLeft: box.scrollLeft - SCROLL_STEP,
+        ArrowRight: box.scrollLeft + SCROLL_STEP,
+        Home: 0,
+        End: max,
+    };
+    const target = to[event.key];
+    if (target !== undefined)
+        box.scrollLeft = Math.min(Math.max(target, 0), max);
+    event.preventDefault();
+    return true;
+}
+// How long a press keeps the box out of the tab order: until the click it
+// starts, or this long for one that never clicks (a touch that pans).
+const PRESS_MS = 1000;
 /**
  * A table: in a box that scrolls sideways when it's wider than the text,
  * with an "add a column" bar along its right and an "add a row" bar under
- * it (widgets), Notion's way.
+ * it (widgets), Notion's way. While it scrolls, the box is a tab stop and
+ * a region named for its columns (prose-table-scroll.ts), which the arrow
+ * keys, Home and End scroll; a click in it still puts the caret in the
+ * cell clicked.
  */
-export function tableView(getPos, registry) {
+export function tableView(node, view, getPos, registry) {
     const dom = document.createElement('div');
     dom.dataset.slot = 'rich-text-table';
     dom.className = 'group/table grid grid-cols-[minmax(0,1fr)_auto] gap-1';
     const scroll = document.createElement('div');
-    scroll.className = 'overflow-x-auto rounded-lg border border-border';
+    scroll.className = cn('overflow-x-auto rounded-lg border border-border', TABLE_SCROLL_FOCUS);
     const table = document.createElement('table');
     const contentDOM = document.createElement('tbody');
     table.append(contentDOM);
@@ -68,12 +107,76 @@ export function tableView(getPos, registry) {
     const row = slot('col-start-1 flex h-5');
     dom.append(scroll, column, row);
     registry.set({ type: 'table', key: nextKey(), slot: row, column, getPos });
+    const region = watchTableScroll(scroll, table, columnsOf(node));
+    // A press in the box is the text's: a click in a cell puts the caret
+    // there. The browser focuses the nearest focusable ancestor of what was
+    // pressed, which would be the box while it's a tab stop, so the box
+    // leaves the tab order from the press to its click.
+    let pressing;
+    const released = () => {
+        clearTimeout(pressing);
+        pressing = undefined;
+        document.removeEventListener('click', releasedSoon, true);
+        region.resume();
+    };
+    const releasedSoon = () => setTimeout(released);
+    const onPointerDown = (event) => {
+        if (event.target === scroll && event.pointerType === 'mouse')
+            return; // its own scrollbar
+        region.suspend();
+        clearTimeout(pressing);
+        pressing = setTimeout(released, PRESS_MS);
+        document.addEventListener('click', releasedSoon, { capture: true, once: true });
+    };
+    scroll.addEventListener('pointerdown', onPointerDown);
+    // A key pressed while the box has focus is the box's (scrollKey), never
+    // ProseMirror's. It comes one of two ways. To the box itself, when the
+    // text's selection is outside it. Or, when the browser first moves
+    // focus to the editable text around it (as it can for a box inside
+    // editable text), to the text: then the box's blur to the text marks
+    // the key that follows in the same moment as the box's, and focus goes
+    // back to it.
+    const onBoxKey = (event) => {
+        if (event.target === scroll && scrollKey(scroll, event))
+            event.stopPropagation();
+    };
+    let bounced = false;
+    const onBlur = (event) => {
+        if (event.relatedTarget !== view.dom)
+            return;
+        bounced = true;
+        setTimeout(() => (bounced = false));
+    };
+    const onKeyDown = (event) => {
+        if (!bounced)
+            return;
+        bounced = false;
+        scroll.focus({ preventScroll: true });
+        if (scrollKey(scroll, event))
+            event.stopImmediatePropagation();
+    };
+    scroll.addEventListener('keydown', onBoxKey);
+    scroll.addEventListener('blur', onBlur);
+    view.dom.addEventListener('keydown', onKeyDown, true);
     return {
         dom,
         contentDOM,
-        update: (next) => next.type.name === 'table',
+        update: (next) => {
+            if (next.type.name !== 'table')
+                return false;
+            region.setColumns(columnsOf(next));
+            return true;
+        },
         stopEvent: (event) => row.contains(event.target) || column.contains(event.target),
         ignoreMutation: outside(contentDOM),
-        destroy: () => registry.remove(row),
+        destroy: () => {
+            released();
+            region.destroy();
+            scroll.removeEventListener('pointerdown', onPointerDown);
+            scroll.removeEventListener('blur', onBlur);
+            scroll.removeEventListener('keydown', onBoxKey);
+            view.dom.removeEventListener('keydown', onKeyDown, true);
+            registry.remove(row);
+        },
     };
 }

package/dist/components/ui/collapsible.d.ts

@@ -0,0 +1,5 @@
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible";
+declare function Collapsible({ ...props }: CollapsiblePrimitive.Root.Props): import("react").JSX.Element;
+declare function CollapsibleTrigger({ ...props }: CollapsiblePrimitive.Trigger.Props): import("react").JSX.Element;
+declare function CollapsibleContent({ ...props }: CollapsiblePrimitive.Panel.Props): import("react").JSX.Element;
+export { Collapsible, CollapsibleTrigger, CollapsibleContent };

package/dist/components/ui/collapsible.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible";
+function Collapsible({ ...props }) {
+    return _jsx(CollapsiblePrimitive.Root, { "data-slot": "collapsible", ...props });
+}
+function CollapsibleTrigger({ ...props }) {
+    return (_jsx(CollapsiblePrimitive.Trigger, { "data-slot": "collapsible-trigger", ...props }));
+}
+function CollapsibleContent({ ...props }) {
+    return (_jsx(CollapsiblePrimitive.Panel, { "data-slot": "collapsible-content", ...props }));
+}
+export { Collapsible, CollapsibleTrigger, CollapsibleContent };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { AppShell, type AppShellProps, type AppShellVersion, type NavEntry, type NavItem, type NavSection } from './components/app/app-shell.js';
 export type { IconComponent } from './components/app/icon-component.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
-export { DataTable, type DataTableProps, type DataTableWidth, type SortingState } from './components/app/data-table.js';
+export { DataTable, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';
 export { type RowGroup } from './components/app/table-groups.js';
 export { byDay, type ByDayOptions } from './lib/group-by-day.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
@@ -13,6 +13,7 @@ export { ErrorState } from './components/app/error-state.js';
 export { InlineCreate, type InlineCreateProps } from './components/app/inline-create.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';
 export { Markdown, type MarkdownProps } from './components/app/markdown.js';
+export type { HeadingLevel } from './components/app/prose-look.js';
 export { MockModeBanner } from './components/app/mock-mode-banner.js';
 export { MultiChoice } from './components/app/multi-choice.js';
 export { MultiPick, type MultiPickOption, type MultiPickProps } from './components/app/multi-pick.js';

package/dist/index.js

@@ -5,7 +5,7 @@
 // Composites
 export { AppShell } from './components/app/app-shell.js';
 export { CountLink } from './components/app/count-link.js';
-export { DataTable } from './components/app/data-table.js';
+export { DataTable, } from './components/app/data-table.js';
 export {} from './components/app/table-groups.js';
 export { byDay } from './lib/group-by-day.js';
 export { EntityForm } from './components/app/entity-form.js';

package/package.json

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