@tristan2828/ui-foundation 4.57.0 → 4.59.0

package/README.md

@@ -18,7 +18,7 @@ than installing this by hand:
 
 | Import | What |
 |---|---|
-| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView` (with `EditableValue`, `editInPlace`), `EntityForm`, `Markdown`, `RichTextEditor`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `DataEnvironmentBanner`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useRecordUpdate`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec`. For timed screens (`docs/foundation/timed-screens.md`): `SessionView`, `useSessionClock`, `useWakeLock`, `useMuted`, `usePrefersReducedMotion`, and the audio cues `unlockAudio`, `chime`, `sequence`, `cancelCues`, `onCuesRecovered`, `cuesInSync`, `keepAudioAlive`, `say`, `hush`, `vibrate`, `canVibrate`. For reminders (`docs/foundation/reminders.md`): `AllowReminders`, `usePushPermission` |
+| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView` (with `EditableValue`, `editInPlace`), `EntityForm`, `Markdown`, `RichTextEditor`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `DataEnvironmentBanner`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useRecordUpdate`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec`. For timed screens (`docs/foundation/timed-screens.md`): `SessionView`, `useSessionClock`, `useWakeLock`, `useMuted`, `usePrefersReducedMotion`, and the audio cues `unlockAudio`, `chime`, `sequence`, `cancelCues`, `onCuesRecovered`, `cuesInSync`, `keepAudioAlive`, `say`, `hush`, `vibrate`, `canVibrate`. For reminders (`docs/foundation/reminders.md`): `AllowReminders`, `usePushPermission`. For a record opened in a dialog over its list (`docs/foundation/add-an-entity.md`): `RecordDialogRoute`, `RecordLink`, `useOpenRecord`, `useRecordDialog`, `recordDialogState` |
 | `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, checkbox, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, switch, table, textarea, tooltip |
 | `@tristan2828/ui-foundation/gateway` | `safeFetch`, `toAppError`, `networkError` — for an app's `src/api/gateway/` only |
 | `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `environmentHandlers`, `resetMockAuth`, `getMockCurrentUser`, `MOCK_USER`, `exposeMswForE2E` |

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

@@ -3,22 +3,23 @@
 <!-- index: written by `npm run docs:index` in the package from the headings below; never edit it by hand -->
 ## Index
 
-- [The reference files](#the-reference-files) · lines 37–59
-- [Before anything: the entity plan](#before-anything-the-entity-plan) · lines 61–720
-  - Step 1: Add `<Entity>` to `openapi.yaml` · lines 99–106
-  - Step 2: `npm run gen:api` · lines 107–108
-  - Step 3: Add gateway tests in `tests/gateway/<entity>.test.ts`, derived from the spec · lines 109–120
-  - Step 4: Add MSW handlers in `src/mocks/<entity>.ts` · lines 121–130
-  - Step 5: Add a gateway module in `src/api/gateway/<entity>.ts` · lines 131–135
-  - Step 6: Copy the reference files, one for one, not just the two screens · lines 136–612
-  - Step 7: Register routes · lines 613–623
-  - Step 8: Add Playwright specs for all three screens · lines 624–702
-  - Step 9: Register the nav entry and route names · lines 703–717
-  - Step 10: `npm run verify`. · lines 718–720
-- [What not to copy](#what-not-to-copy) · lines 722–748
-- [After a commit, in the backend](#after-a-commit-in-the-backend) · lines 750–767
-- [Deleting](#deleting) · lines 769–798
-- [Fields only a script writes](#fields-only-a-script-writes) · lines 800–821
+- [The reference files](#the-reference-files) · lines 38–60
+- [Before anything: the entity plan](#before-anything-the-entity-plan) · lines 62–724
+  - Step 1: Add `<Entity>` to `openapi.yaml` · lines 100–107
+  - Step 2: `npm run gen:api` · lines 108–109
+  - Step 3: Add gateway tests in `tests/gateway/<entity>.test.ts`, derived from the spec · lines 110–121
+  - Step 4: Add MSW handlers in `src/mocks/<entity>.ts` · lines 122–131
+  - Step 5: Add a gateway module in `src/api/gateway/<entity>.ts` · lines 132–136
+  - Step 6: Copy the reference files, one for one, not just the two screens · lines 137–613
+  - Step 7: Register routes · lines 614–627
+  - Step 8: Add Playwright specs for all three screens · lines 628–706
+  - Step 9: Register the nav entry and route names · lines 707–721
+  - Step 10: `npm run verify`. · lines 722–724
+- [Opening a record over its list](#opening-a-record-over-its-list) · lines 726–782
+- [What not to copy](#what-not-to-copy) · lines 784–810
+- [After a commit, in the backend](#after-a-commit-in-the-backend) · lines 812–829
+- [Deleting](#deleting) · lines 831–860
+- [Fields only a script writes](#fields-only-a-script-writes) · lines 862–883
 
 <!-- /index -->
 
@@ -621,6 +622,9 @@ is a filled-in example while the Widgets demo is still here).
    belongs to a module already in the nav (its categories, its channels)
    goes in that module's entry's `children`, not a new top-level entry:
    it shows under the module while you're in it.
+   If the plan says records **open over the list** (a board, a list read
+   one record at a time), the view's route is the list route's child
+   instead: see [Opening a record over its list](#opening-a-record-over-its-list).
 8. **Add Playwright specs for all three screens**, one test per state
    (`loading`, `empty`, `error`, `validation`, `success`), forced through
    MSW overrides — `forceMswOverride`, `waitForMswReady` and the
@@ -719,6 +723,64 @@ is a filled-in example while the Widgets demo is still here).
     anything beyond what this list covers; note ideas in the app's
     backlog instead.
 
+## Opening a record over its list
+
+By default a record opens on its own page, `/<entity>/:id`. A list read
+one record at a time (a board's cards, a backlog) can open it in a
+centered dialog over the list instead (4.58): the address is still the
+record's, so it can be copied and shared, but the list stays underneath
+as it was. Only when the plan asks for it; the full page stays the
+default.
+
+```tsx
+// src/App.tsx: the list route wraps its element, and the view becomes its child.
+{
+  path: '<entity>',
+  element: <RecordDialogRoute list={<<Entity>sTableRoute />} label="<Entity>" />,
+  errorElement: <RouteErrorBoundary />,
+  children: [{ path: ':id', element: <<Entity>ViewRoute />, errorElement: <RouteErrorBoundary /> }],
+},
+{ path: '<entity>/new', element: <<Entity>FormRoute /> },        // unchanged siblings
+{ path: '<entity>/:id/edit', element: <<Entity>FormRoute /> },
+
+// The list: a row click, or a link on a card, opens the record over it.
+const openRecord = useOpenRecord()
+<DataTable onRowClick={(row) => openRecord(`/<entity>/${row.id}`)} … />
+<Board renderCard={(item) => <RecordLink to={`/<entity>/${item.id}`}>{item.name}</RecordLink>} … />
+```
+
+- **The history entry decides.** `useOpenRecord`, `<RecordLink>` (a
+  `<Link>`) and `recordDialogState(location)` (for a `<Link>`'s own
+  `state`) put the list's address in the entry's state; the record's
+  route then draws as a dialog over the list. **A deep link** (pasted,
+  bookmarked, reloaded in a new tab) has no such state and **is the full
+  page**, back link and all, as is a record opened from a page other
+  than its list (a link on the home page).
+- **The list stays as it was**: mounted underneath, reading the address
+  it was opened from, so its search, filters, sort, page and scroll are
+  unchanged when the dialog closes.
+- **Closing**: Back, Esc, the backdrop and the dialog's Close all go
+  back to the list's entry (over every record opened inside the dialog,
+  a linked one included). Focus goes back to the row or link that
+  opened it.
+- **Open full page**, in the dialog's bar, swaps the entry for the same
+  address as the full page; Back from there is the list.
+- **The view is unchanged.** `EntityView` sees the dialog: its title
+  names the dialog (`label` names it while loading or on an error), the
+  back link gives way to the dialog's bar, and not found's "Back to …"
+  closes the dialog. Loading, error with Try again, and the plain 404
+  show inside it. A screen that isn't an `EntityView` can read
+  `useRecordDialog()` (null on the full page) for its `close`, as a
+  Delete should, rather than navigating to the list:
+  `onDeleted={() => (dialog ? dialog.close() : navigate('/<entity>'))}`.
+- **Edit** still goes to `/<entity>/:id/edit`, the form's full page.
+- `DataTable`'s `onRowClick` alone makes rows open: a pointer, Enter,
+  ↑/↓ between rows (4.58; it used to need a `detailPanel`). A link or
+  control in a cell keeps its own click.
+- Specs: the package's own (`e2e/record-dialog.spec.ts`) cover the
+  dialog. An app's spec opens a record from the list, checks the
+  address, closes it with Escape, and checks the list's filter survived.
+
 ## What not to copy
 
 - `widget-quick-actions.tsx`, its `quick action: …` specs and

package/conventions/docs/cell-patterns.md

@@ -34,7 +34,7 @@
 - [20. Count linking to the related records](#20-count-linking-to-the-related-records) · lines 1288–1352
 - [21. Rows grouped under headings, and a pill filter](#21-rows-grouped-under-headings-and-a-pill-filter) · lines 1354–1422
 - [22. A highlighted row, and rows that are done](#22-a-highlighted-row-and-rows-that-are-done) · lines 1424–1452
-- [23. A Group menu, and a record read beside the list](#23-a-group-menu-and-a-record-read-beside-the-list) · lines 1454–1528
+- [23. A Group menu, and a record read beside the list](#23-a-group-menu-and-a-record-read-beside-the-list) · lines 1454–1530
 
 <!-- /index -->
 
@@ -1523,6 +1523,8 @@ const { grouping, setGrouping, ...table } = useTableUrlState(FILTERS, MULTI, VIE
   short notes preview (a few lines of the record's notes, not the whole
   editor), and an "Open page" link (a `<Link>` in `text-link`, so it's
   announced as the link it is). Without `detailPanel` rows behave as they
-  always have: the title link opens the record's page.
+  always have: the title link opens the record's page, or, with
+  `onRowClick`, the row opens the record (a dialog over the list:
+  add-an-entity.md "Opening a record over its list").
 - **The table layout's alone:** a card layout's cards don't open the
   panel.

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

@@ -118,10 +118,13 @@ export type DataTableProps<TData extends Record<string, unknown>> = {
      */
     detailPanel?: (row: TData) => ReactNode;
     /**
-     * What a click on a row (or Enter on it) does instead of picking it for
-     * the `detailPanel`: open its page, say. A link or control inside the row
-     * keeps its own click, and the panel is then opened from the app's own
-     * control through `detailRow`. Left out, a row click picks the row.
+     * What a click on a row (or Enter on it) does: open its page, or open it
+     * in a dialog over the list (`useOpenRecord`, add-an-entity.md "Opening a
+     * record over its list"). The rows then take a pointer and the keyboard
+     * (↑/↓ between rows, Enter). A link or control inside the row keeps its
+     * own click. With a `detailPanel` it replaces picking the row, and the
+     * panel is then opened from the app's own control through `detailRow`.
+     * Left out, a row click picks the row for the panel, if there is one.
      */
     onRowClick?: (row: TData) => void;
     /**

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

@@ -395,6 +395,9 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     const places = runs
         ? runs.flatMap((run) => folded.has(run.key) ? [] : run.rows.map((row) => ({ key: placeKey(run.key, row.id), rowId: row.id })))
         : rows.map((row) => ({ key: row.id, rowId: row.id }));
+    // Rows that open on a click or Enter: picked for the panel, or the app's
+    // own `onRowClick` (a record's page, or a dialog over the list).
+    const rowsOpen = Boolean(detailPanel || onRowClickProp);
     const selectedRow = detailPanel && selection ? rows.find((row) => row.id === selection.rowId) : undefined;
     // The place marked picked: where it was picked, or (regrouped since) the
     // row's first place. None while its group is folded.
@@ -447,7 +450,9 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                 return;
             event.preventDefault();
             const down = event.key === 'ArrowDown';
-            const index = places.findIndex((place) => place.key === selectedKey);
+            // From the picked row, or (no panel: rows that only open) the focused one.
+            const fromKey = selectedKey ?? target.closest('tr[data-row-key]')?.dataset.rowKey;
+            const index = places.findIndex((place) => place.key === fromKey);
             const nextIndex = index === -1 ? (down ? 0 : places.length - 1) : Math.min(places.length - 1, Math.max(0, index + (down ? 1 : -1)));
             const next = places[nextIndex];
             if (!next)
@@ -475,16 +480,15 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     };
     // One body row, the same in a plain table and a grouped one.
     const renderRow = (row, key = row.id) => {
-        const isSelected = key === selectedKey;
-        return (_jsx(TableRow, { "data-highlighted": highlightRow?.(row.original) || undefined, ...(detailPanel
+        const isSelected = Boolean(detailPanel) && key === selectedKey;
+        return (_jsx(TableRow, { "data-highlighted": highlightRow?.(row.original) || undefined, ...(rowsOpen
                 ? {
                     'data-row-key': key,
-                    'data-selected': isSelected || undefined,
-                    'aria-selected': isSelected,
+                    ...(detailPanel ? { 'data-selected': isSelected || undefined, 'aria-selected': isSelected } : {}),
                     tabIndex: key === tabStopKey ? 0 : -1,
                     onClickCapture: (event) => onRowClick(event, { key, rowId: row.id }),
                 }
-                : {}), className: cn(pinFirstColumn && ROW_GROUP_CLASS, highlightRow?.(row.original) && HIGHLIGHTED_ROW_CLASS, detailPanel && SELECTABLE_ROW_CLASS, isSelected && SELECTED_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, alignClass(cell.column.columnDef.meta?.align)), 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))) }, key));
+                : {}), className: cn(pinFirstColumn && ROW_GROUP_CLASS, highlightRow?.(row.original) && HIGHLIGHTED_ROW_CLASS, rowsOpen && SELECTABLE_ROW_CLASS, isSelected && SELECTED_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, alignClass(cell.column.columnDef.meta?.align)), 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))) }, key));
     };
     const content = (_jsxs("div", { ref: root, className: cn('flex flex-col gap-4', width === 'content' && CONTENT_WIDTH_CLASS), "data-width": width, "data-layout": layouts?.length ? currentLayout : undefined, style: width === 'content' && !isSuccessView && lastWidth !== null
             ? { '--data-table-last-width': `${lastWidth}px` }
@@ -497,7 +501,7 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                             return;
                         event.preventDefault();
                         closeDetail();
-                    }, children: [_jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsx("h2", { className: "type-label text-muted-foreground", children: detailLabel }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Close", onClick: closeDetail, children: _jsx(XIcon, { "aria-hidden": "true" }) })] }), detailPanel(selectedRow.original)] })) : null, children: [cardLayout ? (_jsx(Cards, { layout: cardLayout, runs: runs, rows: rows, folded: folded, onToggleFold: toggleFold, groupSummary: groupSummary, groupIcons: groupIcons })) : (_jsxs(Table, { "data-state": "success", containerRef: containerRef, onKeyDown: detailPanel ? onListKeyDown : undefined, 
+                    }, children: [_jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsx("h2", { className: "type-label text-muted-foreground", children: detailLabel }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Close", onClick: closeDetail, children: _jsx(XIcon, { "aria-hidden": "true" }) })] }), detailPanel(selectedRow.original)] })) : null, children: [cardLayout ? (_jsx(Cards, { layout: cardLayout, runs: runs, rows: rows, folded: folded, onToggleFold: toggleFold, groupSummary: groupSummary, groupIcons: groupIcons })) : (_jsxs(Table, { "data-state": "success", containerRef: containerRef, onKeyDown: rowsOpen ? onListKeyDown : undefined, 
                         // With the sticky bar below as the visible scrollbar, hide the
                         // container's own. It stays overflow-x-auto and fully
                         // scrollable (wheel, trackpad, drag, and the sync effect); it

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

@@ -35,6 +35,11 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // <KeyStats>) under that, the record's key numbers; `footer`
 // (a <SourceCredit>) after them all, for crediting the data's source.
 //
+// Opened in a dialog over its list (RecordDialogRoute, record-dialog.tsx),
+// the view is the same: its <h1> names the dialog, the back link gives way
+// to the dialog's bar (Open full page, Close), and not found's way out
+// closes the dialog.
+//
 // Two layouts. `column` (the default): every section in one column capped
 // at max-w-4xl. `rail`, for a record with long content: the page takes the
 // content area's whole width, sections placed `rail` go in a narrow column
@@ -59,6 +64,7 @@ import { EditInPlaceContext } from './edit-in-place.js';
 import { EditInPlaceStore } from './edit-in-place-store.js';
 import { EditableList } from './editable-list.js';
 import { EditableValue, LeaveGuard } from './editable-value.js';
+import { useRecordDialog } from './record-dialog-context.js';
 const DEFAULT_EMPTY_LABEL = 'Not set';
 function isEmptyValue(value) {
     return (value === null ||
@@ -151,12 +157,15 @@ export function EntityView({ title, documentTitle, titleEdit, subtitle, badges,
     // Editing in place: one store per view, and the leave-page prompt only
     // while a field is open (or one is always editable).
     const [store] = useState(() => new EditInPlaceStore());
+    // Opened over its list (RecordDialogRoute): the heading names the dialog,
+    // and the dialog's own bar replaces the back link.
+    const dialog = useRecordDialog();
     const editing = useSyncExternalStore(store.subscribe, () => store.editing, () => store.editing);
     useDocumentTitle(isLoading || error || documentTitle === false ? undefined : (documentTitle ?? title));
     if (error?.kind === 'notfound') {
         // A record that doesn't exist and one that belongs to another user are
         // the same plain 404, so this never says which. Retrying can't help.
-        return (_jsxs(Empty, { "data-state": "notfound", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyMedia, { variant: "icon", children: _jsx(SearchXIcon, {}) }), _jsx(EmptyTitle, { children: "Not found" }), _jsx(EmptyDescription, { children: error.message })] }), _jsx(EmptyContent, { children: _jsxs(Button, { size: "sm", variant: "outline", nativeButton: false, render: _jsx(Link, { to: back.to }), children: ["Back to ", back.label] }) })] }));
+        return (_jsxs(Empty, { "data-state": "notfound", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyMedia, { variant: "icon", children: _jsx(SearchXIcon, {}) }), _jsx(EmptyTitle, { children: "Not found" }), _jsx(EmptyDescription, { children: error.message })] }), _jsx(EmptyContent, { children: dialog ? (_jsxs(Button, { size: "sm", variant: "outline", onClick: dialog.close, children: ["Back to ", back.label] })) : (_jsxs(Button, { size: "sm", variant: "outline", nativeButton: false, render: _jsx(Link, { to: back.to }), children: ["Back to ", back.label] })) })] }));
     }
     if (error)
         return _jsx(ErrorState, { error: error, onRetry: onRetry });
@@ -165,5 +174,5 @@ export function EntityView({ title, documentTitle, titleEdit, subtitle, badges,
     const railSections = sections.filter((section) => section.placement === 'rail');
     const mainSections = sections.filter((section) => section.placement !== 'rail');
     const main = (_jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) }));
-    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [editing && _jsx(LeaveGuard, { store: store }), _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), subtitle && (_jsx("div", { "data-slot": "entity-view-subtitle", className: "type-body break-words text-muted-foreground", children: subtitle })), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), _jsx("div", { role: "status", "data-slot": "entity-view-notice", className: "empty:hidden", children: notice }), strip && _jsx("div", { "data-slot": "entity-view-strip", children: strip }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [mobileOrder === 'main-first' && main, railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), mobileOrder === 'rail-first' && main] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title))), footer && (_jsx("footer", { "data-slot": "entity-view-footer", className: "type-caption text-muted-foreground", children: footer }))] }) }));
+    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [editing && _jsx(LeaveGuard, { store: store }), !dialog && _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { id: dialog?.titleId, className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), subtitle && (_jsx("div", { "data-slot": "entity-view-subtitle", className: "type-body break-words text-muted-foreground", children: subtitle })), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), _jsx("div", { role: "status", "data-slot": "entity-view-notice", className: "empty:hidden", children: notice }), strip && _jsx("div", { "data-slot": "entity-view-strip", children: strip }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [mobileOrder === 'main-first' && main, railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), mobileOrder === 'rail-first' && main] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title))), footer && (_jsx("footer", { "data-slot": "entity-view-footer", className: "type-caption text-muted-foreground", children: footer }))] }) }));
 }

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

@@ -26,6 +26,13 @@ export type MarkdownProps = {
      * text is never changed.
      */
     foldKey?: string;
+    /**
+     * Set `false` to keep headings plain, with no fold buttons, even when a
+     * `foldKey` is given: a page-level switch (a print view, a short note)
+     * that leaves the key in place. Nothing is folded while it's off, and
+     * what was folded is remembered for when it's on again. Default `true`.
+     */
+    foldable?: boolean;
     className?: string;
 } & Omit<ComponentProps<'div'>, 'children'>;
-export declare function Markdown({ children, headingLevel, headingFrom, foldKey, className, ...rest }: MarkdownProps): import("react").JSX.Element;
+export declare function Markdown({ children, headingLevel, headingFrom, foldKey: foldKeyProp, foldable, className, ...rest }: MarkdownProps): import("react").JSX.Element;

package/dist/components/app/markdown.js

@@ -184,7 +184,8 @@ function componentsFor(top, textTop) {
     }
     return components;
 }
-export function Markdown({ children, headingLevel = DEFAULT_HEADING_LEVEL, headingFrom = 'hash', foldKey, className, ...rest }) {
+export function Markdown({ children, headingLevel = DEFAULT_HEADING_LEVEL, headingFrom = 'hash', foldKey: foldKeyProp, foldable = true, className, ...rest }) {
+    const foldKey = foldable ? foldKeyProp : undefined;
     const textTop = useMemo(() => (headingFrom === 'text' ? textTopHeading(children) : 1), [headingFrom, children]);
     const components = useMemo(() => componentsFor(headingLevel, textTop), [headingLevel, textTop]);
     const [folded, setFolded] = useFolds(foldKey);

package/dist/components/app/record-dialog-context.d.ts

@@ -0,0 +1,39 @@
+import { type Location } from 'react-router';
+/**
+ * Where a record dialog was opened from: the list's address, and how many
+ * history entries the dialog has pushed since (1, or more after a linked
+ * record opened inside it), which Close goes back over.
+ */
+export type RecordDialogBackground = Pick<Location, 'pathname' | 'search' | 'hash'> & {
+    depth: number;
+};
+export type RecordDialogState = {
+    recordDialog: RecordDialogBackground;
+};
+export declare function backgroundOf(state: unknown): RecordDialogBackground | null;
+/**
+ * The history state that opens a record over the list it's on: pass it as
+ * a `<Link>`'s `state` (or use `<RecordLink>`, or `useOpenRecord`). Opened
+ * from inside a dialog (a linked record), the new one opens over the same
+ * list.
+ */
+export declare function recordDialogState(location: Pick<Location, 'pathname' | 'search' | 'hash' | 'state'>): RecordDialogState;
+/**
+ * Opens a record over the current list: `open('/widgets/3')` for a
+ * DataTable's `onRowClick`, say. The record's address goes in the address
+ * bar and history, so Back closes it.
+ */
+export declare function useOpenRecord(): (to: string) => void;
+export type RecordDialogContextValue = {
+    /** The dialog's title id: EntityView puts it on its heading. */
+    titleId: string;
+    /** Closes the dialog: back to the list, as Back does. */
+    close: () => void;
+};
+export declare const RecordDialogContext: import("react").Context<RecordDialogContextValue | null>;
+/**
+ * Inside a record dialog, its `close` (a Delete that has just removed the
+ * record closes the dialog rather than going to the list's page); `null`
+ * on the record's full page.
+ */
+export declare function useRecordDialog(): RecordDialogContextValue | null;

package/dist/components/app/record-dialog-context.js

@@ -0,0 +1,48 @@
+// The record dialog's state and hooks (record-dialog.tsx has the parts).
+// A record opened over its list is the record's own address with the list's
+// address in the history entry's state: `{ recordDialog: <the list's
+// location> }`. RecordDialogRoute reads it to draw the list under the
+// dialog, at the list's address (its filters, sort and page as they were),
+// and an address with no such state (a link pasted, a reload in a new tab,
+// "Open full page") is the record's full page.
+import { createContext, useCallback, useContext } from 'react';
+import { useLocation, useNavigate } from 'react-router';
+export function backgroundOf(state) {
+    if (typeof state !== 'object' || state === null || !('recordDialog' in state))
+        return null;
+    const background = state.recordDialog;
+    return typeof background?.pathname === 'string' && typeof background.depth === 'number' ? background : null;
+}
+/**
+ * The history state that opens a record over the list it's on: pass it as
+ * a `<Link>`'s `state` (or use `<RecordLink>`, or `useOpenRecord`). Opened
+ * from inside a dialog (a linked record), the new one opens over the same
+ * list.
+ */
+export function recordDialogState(location) {
+    const open = backgroundOf(location.state);
+    return {
+        recordDialog: open
+            ? { ...open, depth: open.depth + 1 }
+            : { pathname: location.pathname, search: location.search, hash: location.hash, depth: 1 },
+    };
+}
+/**
+ * Opens a record over the current list: `open('/widgets/3')` for a
+ * DataTable's `onRowClick`, say. The record's address goes in the address
+ * bar and history, so Back closes it.
+ */
+export function useOpenRecord() {
+    const navigate = useNavigate();
+    const location = useLocation();
+    return useCallback((to) => void navigate(to, { state: recordDialogState(location) }), [navigate, location]);
+}
+export const RecordDialogContext = createContext(null);
+/**
+ * Inside a record dialog, its `close` (a Delete that has just removed the
+ * record closes the dialog rather than going to the list's page); `null`
+ * on the record's full page.
+ */
+export function useRecordDialog() {
+    return useContext(RecordDialogContext);
+}

package/dist/components/app/record-dialog.d.ts

@@ -0,0 +1,21 @@
+import { type ComponentProps, type ReactNode } from 'react';
+import { Link } from 'react-router';
+export type RecordDialogRouteProps = {
+    /** The list's own element (the table route), drawn under an open record. */
+    list: ReactNode;
+    /**
+     * What one record is ("Widget"): the dialog's name while the record
+     * loads, fails or isn't found. Once it loads, its title names the dialog.
+     */
+    label: string;
+    /** Extra classes on the dialog's popup (its width, say: `sm:max-w-5xl`). */
+    className?: string;
+};
+export declare function RecordDialogRoute({ list, label, className }: RecordDialogRouteProps): import("react").JSX.Element;
+export type RecordLinkProps = Omit<ComponentProps<typeof Link>, 'state'>;
+/**
+ * A link to a record that opens it over the current list (a board's card,
+ * a name in a cell). Ctrl/Cmd+click and a new tab still get the full page:
+ * the state only travels with an in-app navigation.
+ */
+export declare function RecordLink(props: RecordLinkProps): import("react").JSX.Element;

package/dist/components/app/record-dialog.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// A record opened in a centered dialog over its list, instead of going to
+// the record's page (add-an-entity.md "Opening a record over its list").
+//
+// RecordDialogRoute is the list route's element, and the record's route is
+// its child:
+//
+//   { path: 'widgets', element: <RecordDialogRoute list={<WidgetsTableRoute />} label="Widget" />,
+//     children: [{ path: ':id', element: <WidgetViewRoute /> }] }
+//
+// The address is the record's own (`/widgets/3`) either way; what decides
+// dialog or page is the history entry's state, which `useOpenRecord`,
+// `<RecordLink>` and `recordDialogState` put there
+// (record-dialog-context.ts). So:
+//
+// - opened from the list, the record is a dialog over the list, and the
+//   list stays mounted underneath at its own address (filters, sort, page
+//   and scroll as they were);
+// - Back, Esc, the backdrop and Close all go back to the list's entry;
+// - "Open full page" swaps the entry for the same address with no state;
+// - a deep link (pasted, bookmarked, a new tab) has no state and is the
+//   full page, as is a record opened over a list other than its own
+//   (a link on the home page).
+//
+// Inside, the record's route renders as it always does. EntityView sees
+// the dialog (useRecordDialog): its heading names the dialog, its back link
+// gives way to the dialog's own bar, and not found's way out closes the
+// dialog. Its loading, error and not-found states are the dialog's.
+import { useCallback, useId, useMemo } from 'react';
+import { Link, UNSAFE_LocationContext as LocationContext, useLocation, useNavigate, useNavigationType, useOutlet, useResolvedPath, } from 'react-router';
+import { Maximize2Icon, XIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { Button, buttonVariants } from '../ui/button.js';
+import { Dialog, DialogClose, DialogContent } from '../ui/dialog.js';
+import { escapePassedThrough } from './escape-passthrough.js';
+import { backgroundOf, recordDialogState, RecordDialogContext } from './record-dialog-context.js';
+export function RecordDialogRoute({ list, label, className }) {
+    const location = useLocation();
+    const navigationType = useNavigationType();
+    const navigate = useNavigate();
+    const outlet = useOutlet();
+    const titleId = useId();
+    const listPath = useResolvedPath('.').pathname;
+    const opened = backgroundOf(location.state);
+    // Over its own list only: opened from anywhere else, the list under it
+    // would be a page the user wasn't on.
+    const background = opened && opened.pathname === listPath ? opened : null;
+    const open = outlet !== null && background !== null;
+    // The list sees the address it was opened from, not the record's, so
+    // its URL state (filters, sort, page) stays as it was under the dialog.
+    const { pathname, search, hash } = background ?? location;
+    const listLocation = useMemo(() => ({ pathname, search, hash, state: null, key: open ? 'record-dialog-list' : location.key }), [pathname, search, hash, open, location.key]);
+    const listContext = useMemo(() => ({ location: listLocation, navigationType }), [listLocation, navigationType]);
+    const depth = background?.depth ?? 0;
+    const close = useCallback(() => {
+        if (location.key === 'default' || depth === 0) {
+            // The first entry in this tab (a restored session): nothing to go
+            // back over, so the list's address replaces the record's.
+            void navigate({ pathname, search, hash }, { replace: true });
+        }
+        else
+            void navigate(-depth);
+    }, [navigate, location.key, depth, pathname, search, hash]);
+    const dialog = useMemo(() => ({ titleId, close }), [titleId, close]);
+    // The record's full page: a deep link, or "Open full page".
+    if (outlet !== null && !open)
+        return outlet;
+    return (_jsxs(_Fragment, { children: [_jsx(LocationContext.Provider, { value: listContext, children: list }), _jsx(Dialog, { open: open, onOpenChange: (next, details) => {
+                    if (next)
+                        return;
+                    // An Esc something inside already used (a field edited in place
+                    // giving up, a picker closing its list) isn't the dialog's. The
+                    // rich-text editor marks every Esc used, and passes on the ones
+                    // its menus didn't take.
+                    const native = details.event;
+                    if (details.reason === 'escape-key' && native.defaultPrevented && !escapePassedThrough(native)) {
+                        details.cancel();
+                        return;
+                    }
+                    close();
+                }, children: _jsxs(DialogContent, { showCloseButton: false, "aria-labelledby": titleId, "aria-label": label, "data-slot": "record-dialog", className: cn('flex max-h-[calc(100dvh-2rem)] flex-col gap-0 overflow-hidden p-0 sm:max-w-4xl data-closed:hidden', className), children: [_jsxs("div", { className: "flex items-center justify-between gap-2 border-b px-2 py-2", children: [_jsxs(Link, { to: { pathname: location.pathname, search: location.search, hash: location.hash }, replace: true, className: buttonVariants({ variant: 'ghost', size: 'sm' }), children: [_jsx(Maximize2Icon, { "aria-hidden": "true" }), "Open full page"] }), _jsxs(DialogClose, { render: _jsx(Button, { variant: "ghost", size: "icon-sm" }), children: [_jsx(XIcon, { "aria-hidden": "true" }), _jsx("span", { className: "sr-only", children: "Close" })] })] }), _jsx("div", { "data-slot": "record-dialog-body", className: "min-h-0 overflow-y-auto p-4 sm:p-6", children: _jsx(RecordDialogContext.Provider, { value: dialog, children: open && outlet }) })] }) })] }));
+}
+/**
+ * A link to a record that opens it over the current list (a board's card,
+ * a name in a cell). Ctrl/Cmd+click and a new tab still get the full page:
+ * the state only travels with an in-app navigation.
+ */
+export function RecordLink(props) {
+    const location = useLocation();
+    return _jsx(Link, { ...props, state: recordDialogState(location) });
+}

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

@@ -80,6 +80,12 @@ export type RichTextEditorProps = {
      * when it mounts.
      */
     foldKey?: string;
+    /**
+     * `false` keeps headings plain, with no fold buttons or shortcuts, even
+     * with a `foldKey`, as on `<Markdown>`. Read once, when it mounts.
+     * Default `true`.
+     */
+    foldable?: boolean;
     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

@@ -34,5 +34,5 @@ import { cn } from 'cn';
 import { Skeleton } from '../ui/skeleton.js';
 const MilkdownEditor = lazy(() => import('./milkdown-editor.js'));
 export function RichTextEditor(props) {
-    return (_jsx(Suspense, { fallback: _jsxs("div", { "data-slot": "rich-text-editor", "data-state": "loading", className: cn('flex w-full flex-col', !props.inline && 'rounded-lg border border-input', props.className), children: [(props.toolbar ?? true) === true && _jsx("div", { className: "h-9 border-b border-input" }), _jsxs("div", { className: cn('flex flex-col gap-2', props.inline ? 'py-0.5' : 'min-h-24 px-2.5 py-2'), children: [_jsx(Skeleton, { className: "h-4 w-3/4" }), _jsx(Skeleton, { className: "h-4 w-1/2" })] })] }), children: _jsx(MilkdownEditor, { ...props }) }));
+    return (_jsx(Suspense, { fallback: _jsxs("div", { "data-slot": "rich-text-editor", "data-state": "loading", className: cn('flex w-full flex-col', !props.inline && 'rounded-lg border border-input', props.className), children: [(props.toolbar ?? true) === true && _jsx("div", { className: "h-9 border-b border-input" }), _jsxs("div", { className: cn('flex flex-col gap-2', props.inline ? 'py-0.5' : 'min-h-24 px-2.5 py-2'), children: [_jsx(Skeleton, { className: "h-4 w-3/4" }), _jsx(Skeleton, { className: "h-4 w-1/2" })] })] }), children: _jsx(MilkdownEditor, { ...props, foldKey: props.foldable === false ? undefined : props.foldKey }) }));
 }

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export { byDay, type ByDayOptions } from './lib/group-by-day.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
 export { KeyStats, type KeyStat, type KeyStatsProps } from './components/app/key-stats.js';
 export { EntityView, type EntityViewField, type EntityViewLayout, type EntityViewMobileOrder, type EntityViewPlacement, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
+export { RecordDialogRoute, RecordLink, type RecordDialogRouteProps, type RecordLinkProps, } from './components/app/record-dialog.js';
+export { recordDialogState, useOpenRecord, useRecordDialog, type RecordDialogBackground, type RecordDialogContextValue, type RecordDialogState, } from './components/app/record-dialog-context.js';
 export { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceList, type EditInPlaceListOptions, type EditInPlaceOptions, type EditKind, type EditListAddProps, type EditListItemProps, } from './components/app/edit-in-place.js';
 export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
 export { EditableValue, type EditableValueProps } from './components/app/editable-value.js';

package/dist/index.js

@@ -17,6 +17,8 @@ export { byDay } from './lib/group-by-day.js';
 export { EntityForm } from './components/app/entity-form.js';
 export { KeyStats } from './components/app/key-stats.js';
 export { EntityView, } from './components/app/entity-view.js';
+export { RecordDialogRoute, RecordLink, } from './components/app/record-dialog.js';
+export { recordDialogState, useOpenRecord, useRecordDialog, } from './components/app/record-dialog-context.js';
 export { editInPlace, } from './components/app/edit-in-place.js';
 export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
 export { EditableValue } from './components/app/editable-value.js';

package/package.json

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