@tristan2828/ui-foundation 4.44.0 → 4.46.0

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

@@ -14,16 +14,18 @@ import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } fr
 import { flexRender } from '@tanstack/react-table';
 import { cn } from 'cn';
 import { getCoreRowModel, useLegacyTable } from '@tanstack/react-table/legacy';
-import { ArrowDownIcon, ArrowUpIcon, ArrowUpDownIcon, ChevronLeftIcon, ChevronRightIcon, TableIcon } from 'lucide-react';
+import { ArrowDownIcon, ArrowUpIcon, ArrowUpDownIcon, ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon, ListTreeIcon, TableIcon, XIcon, } from 'lucide-react';
 import { ErrorState } from './error-state.js';
 import { Button } from '../ui/button.js';
+import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuTrigger, } from '../ui/dropdown-menu.js';
 import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from '../ui/empty.js';
+import { Sheet, SheetContent, SheetHeader, SheetTitle } from '../ui/sheet.js';
 import { Skeleton } from '../ui/skeleton.js';
 import { ToggleGroup, ToggleGroupItem } from '../ui/toggle-group.js';
 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 { groupByValues, groupRuns } from './table-groups.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
@@ -74,6 +76,35 @@ function LayoutSwitch({ options, value, onValueChange, }) {
                 onValueChange(chosen);
         }, children: options.map(({ id, label, icon: Icon }) => (_jsxs(ToggleGroupItem, { value: id, className: LAYOUT_ITEM_CLASS, title: label, children: [_jsx(Icon, { "aria-hidden": "true", className: "size-4" }), _jsx("span", { className: "max-sm:sr-only", children: label })] }, id))) }));
 }
+// The Group menu (`groupings`): a radio list, None first, that closes on
+// a pick. Base UI's radio group needs a value for None, so it's this
+// stand-in, never '' (the grouping's own word for None).
+const NO_GROUPING = '__none__';
+function GroupMenu({ groupings, value, onValueChange, }) {
+    const current = groupings.find((grouping) => grouping.id === value);
+    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { render: _jsx(Button, { variant: "outline", size: "sm", "data-slot": "data-table-group-menu" }), children: [_jsx(ListTreeIcon, { "aria-hidden": "true" }), current ? `Group: ${current.label}` : 'Group'] }), _jsx(DropdownMenuContent, { align: "end", className: "w-48", children: _jsxs(DropdownMenuGroup, { children: [_jsx(DropdownMenuLabel, { children: "Group by" }), _jsxs(DropdownMenuRadioGroup, { value: current?.id ?? NO_GROUPING, onValueChange: (next) => onValueChange(next === NO_GROUPING ? '' : String(next)), children: [_jsx(DropdownMenuRadioItem, { value: NO_GROUPING, closeOnClick: true, children: "None" }), groupings.map((grouping) => (_jsx(DropdownMenuRadioItem, { value: grouping.id, closeOnClick: true, children: grouping.label }, grouping.id)))] })] }) })] }));
+}
+// Whether the detail panel (`detailPanel`) fits beside the table, or opens
+// as a bottom sheet. Wide on the server and wherever matchMedia is missing
+// (a test's DOM), so markup never depends on it.
+const WIDE_QUERY = '(min-width: 64rem)';
+const canMatchMedia = () => typeof window !== 'undefined' && typeof window.matchMedia === 'function';
+function subscribeWide(listener) {
+    if (!canMatchMedia())
+        return () => { };
+    const query = window.matchMedia(WIDE_QUERY);
+    query.addEventListener('change', listener);
+    return () => query.removeEventListener('change', listener);
+}
+const useIsWide = () => useSyncExternalStore(subscribeWide, () => !canMatchMedia() || window.matchMedia(WIDE_QUERY).matches, () => true);
+// A click on one of these inside a row is the control's own, not a pick of
+// the row. A link is the exception: a plain click picks the row instead of
+// following it (a modified one still opens it, in a new tab).
+const ROW_CONTROL_SELECTOR = 'a[href],button,input,select,textarea,label,summary,[contenteditable="true"],' +
+    '[role="button"],[role="checkbox"],[role="switch"],[role="combobox"],[role="link"],[role="slider"]';
+// Keys typed into one of these are its own: ↑/↓ and Escape stay with it.
+const TYPING_SELECTOR = 'input,select,textarea,[contenteditable="true"],[role="combobox"],[role="listbox"],[role="menu"],' +
+    '[role="slider"],[role="spinbutton"]';
 function TableSkeleton({ columnCount }) {
     return (_jsx("div", { className: "flex flex-col gap-2 p-2", "data-state": "loading", children: Array.from({ length: 5 }, (_, row) => (_jsx("div", { className: "flex gap-4", children: Array.from({ length: columnCount }, (_, col) => (_jsx(Skeleton, { className: "h-8 flex-1" }, col))) }, row))) }));
 }
@@ -140,6 +171,25 @@ const HIDDEN_HEAD_CLASS = 'h-0 p-0';
 const ALIGN_CLASS = { center: 'text-center', right: 'text-right' };
 const alignClass = (align) => align && ALIGN_CLASS[align];
 const GROUP_HEADING_CLASS = 'h-auto bg-background pt-4 pb-1.5 align-bottom';
+// A grouping's heading (`groupings`) is a button that folds its rows: the
+// label, then the count, a chevron that turns when folded.
+const GROUP_TOGGLE_CLASS = '-mx-1 inline-flex items-baseline gap-2 rounded-sm px-1 outline-none hover:underline ' +
+    'focus-visible:ring-3 focus-visible:ring-ring/50';
+// `detailPanel`: a row that can be picked shows a pointer and its focus
+// ring inside it (a row has no outline of its own room); the picked one
+// takes the muted fill on every cell, over the zebra stripe and the pinned
+// cells' opaque backgrounds as highlightRow's wash does, with a bar in
+// --primary at its start, so it reads without colour too.
+const SELECTABLE_ROW_CLASS = 'cursor-pointer outline-none focus-visible:[&>td]:shadow-[inset_0_2px_0_0_var(--ring),inset_0_-2px_0_0_var(--ring)]';
+const SELECTED_ROW_CLASS = '[&>td]:bg-muted [&>td:first-child]:shadow-[inset_3px_0_0_0_var(--primary)] ' +
+    'focus-visible:[&>td:first-child]:shadow-[inset_3px_0_0_0_var(--primary),inset_0_2px_0_0_var(--ring),inset_0_-2px_0_0_var(--ring)]';
+// The table and the panel side by side once one is picked on a wide
+// screen. The grid is there from the start, so opening the panel never
+// remounts the table (and the focused row with it).
+const WITH_DETAIL_OPEN_CLASS = 'grid-cols-[minmax(0,1fr)_minmax(18rem,26rem)]';
+const DETAIL_ASIDE_CLASS = 'sticky top-4 flex max-h-[calc(100dvh-2rem)] min-w-0 flex-col gap-3 overflow-y-auto rounded-lg border ' +
+    'border-border bg-card p-4 text-card-foreground';
+const EMPTY_KEYS = new Set();
 // `width="content"`: from a table area 80rem wide, as wide as the columns
 // need (`w-fit` over the table's own `w-full`), at least 36rem, or the
 // width it last had loaded while it shows another state
@@ -208,7 +258,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, totals, layouts, layout: layoutProp, onLayoutChange, tableLayout, }) {
+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, layouts, layout: layoutProp, onLayoutChange, tableLayout, groupings, grouping: groupingProp, onGroupingChange, detailPanel, detailLabel = 'Details', }) {
     // The switch's own state, for a table that doesn't pass `layout`.
     const [ownLayout, setOwnLayout] = useState('table');
     const requestedLayout = layoutProp ?? ownLayout;
@@ -219,6 +269,22 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
             setOwnLayout(next);
         onLayoutChange?.(next);
     };
+    // The grouping on (`groupings`), the menu's own state for a table that
+    // doesn't pass `grouping`.
+    const [ownGrouping, setOwnGrouping] = useState('');
+    const activeGrouping = groupings?.find((candidate) => candidate.id === (groupingProp ?? ownGrouping));
+    const setGrouping = (next) => {
+        if (groupingProp === undefined)
+            setOwnGrouping(next);
+        onGroupingChange?.(next);
+    };
+    // The folded headings, for the grouping they were folded in: picking
+    // another starts with every group open.
+    const [folds, setFolds] = useState({ grouping: '', keys: EMPTY_KEYS });
+    const folded = activeGrouping && folds.grouping === activeGrouping.id ? folds.keys : EMPTY_KEYS;
+    // The picked row (`detailPanel`) and the place it was picked in.
+    const [selection, setSelection] = useState(null);
+    const isWide = useIsWide();
     // 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
@@ -228,9 +294,13 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     const pageCount = Math.max(1, Math.ceil(total / pageSize));
     // TanStack treats a column missing from this map as visible, so every
     // column gets an entry once a list is given.
-    const columnVisibility = visibleColumns
-        ? Object.fromEntries(leafColumnIds(columns).map((id) => [id, visibleColumns.includes(id)]))
-        : {};
+    // While grouped, the grouped column is hidden: its value is the heading.
+    const columnVisibility = {
+        ...(visibleColumns
+            ? Object.fromEntries(leafColumnIds(columns).map((id) => [id, visibleColumns.includes(id)]))
+            : {}),
+        ...(activeGrouping ? { [activeGrouping.id]: false } : {}),
+    };
     const table = useLegacyTable({
         data,
         columns,
@@ -279,14 +349,124 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     const rows = table.getRowModel().rows;
     const visibleLeafColumns = table.getVisibleLeafColumns();
     const visibleColumnCount = visibleLeafColumns.length;
+    // The groups, if any: a grouping's (folding, with counts), else groupBy's.
+    const runs = activeGrouping
+        ? groupByValues(rows, (row) => activeGrouping.value(row.original), activeGrouping.options, activeGrouping.emptyLabel ?? 'Not set').map((run) => ({ ...run, foldable: true }))
+        : groupBy
+            ? groupRuns(rows, (row) => groupBy(row.original)).map((run) => ({ ...run, foldable: false }))
+            : null;
+    const allFolded = runs !== null && runs.length > 0 && runs.every((run) => folded.has(run.key));
+    const toggleFold = (key) => {
+        if (!activeGrouping)
+            return;
+        const keys = new Set(folded);
+        if (!keys.delete(key))
+            keys.add(key);
+        setFolds({ grouping: activeGrouping.id, keys });
+    };
+    const foldAll = () => {
+        if (!activeGrouping || !runs)
+            return;
+        setFolds({ grouping: activeGrouping.id, keys: allFolded ? EMPTY_KEYS : new Set(runs.map((run) => run.key)) });
+    };
+    // Every row's place in the list as shown (folded groups left out), in
+    // order, for ↑/↓. Under a grouping a place is the group and the row,
+    // since a multi-value field shows a row in more than one.
+    const placeKey = (runKey, rowId) => activeGrouping ? `${encodeURIComponent(runKey)}:${rowId}` : rowId;
+    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 }));
+    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.
+    const selectedKey = selectedRow
+        ? places.some((place) => place.key === selection?.key)
+            ? selection?.key
+            : places.find((place) => place.rowId === selectedRow.id)?.key
+        : undefined;
+    // The list's one tab stop: the picked row, else the first.
+    const tabStopKey = selectedKey ?? places[0]?.key;
+    const focusRow = (key) => {
+        if (key === undefined)
+            return;
+        containerRef.current?.querySelector(`tr[data-row-key="${CSS.escape(key)}"]`)?.focus();
+    };
+    const closeDetail = () => {
+        setSelection(null);
+        focusRow(selectedKey);
+    };
+    const onRowClick = (event, place) => {
+        const target = event.target;
+        // A click from a portal (a picker's popup opened from a cell) reaches
+        // the row through React, not the DOM: it's that control's.
+        if (!event.currentTarget.contains(target))
+            return;
+        if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+            return;
+        const control = target.closest(ROW_CONTROL_SELECTOR);
+        if (control && event.currentTarget.contains(control)) {
+            if (!control.matches('a[href]'))
+                return;
+            // In the capture phase, so react-router's Link sees it prevented and
+            // doesn't navigate.
+            event.preventDefault();
+        }
+        setSelection(place);
+    };
+    const onListKeyDown = (event) => {
+        const target = event.target;
+        if (event.defaultPrevented || !event.currentTarget.contains(target) || target.closest(TYPING_SELECTOR))
+            return;
+        if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+            if (places.length === 0)
+                return;
+            event.preventDefault();
+            const down = event.key === 'ArrowDown';
+            const index = places.findIndex((place) => place.key === selectedKey);
+            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)
+                return;
+            setSelection(next);
+            focusRow(next.key);
+        }
+        else if (event.key === 'Enter' && target.dataset.rowKey !== undefined) {
+            const place = places.find((candidate) => candidate.key === target.dataset.rowKey);
+            if (!place)
+                return;
+            event.preventDefault();
+            setSelection(place);
+        }
+        else if (event.key === 'Escape' && selectedRow) {
+            event.preventDefault();
+            closeDetail();
+        }
+    };
     // 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, 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))) }, row.id));
+    const renderRow = (row, key = row.id) => {
+        const isSelected = key === selectedKey;
+        return (_jsx(TableRow, { "data-highlighted": highlightRow?.(row.original) || undefined, ...(detailPanel
+                ? {
+                    'data-row-key': key,
+                    '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));
+    };
     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` }
-            : undefined, children: [layouts?.length ? (_jsxs("div", { className: "flex flex-wrap items-end gap-x-4 gap-y-2", children: [_jsx("div", { className: "min-w-0 flex-1", children: toolbar }), _jsx(LayoutSwitch, { options: [
+            : undefined, children: [layouts?.length || groupings?.length ? (_jsxs("div", { className: "flex flex-wrap items-end gap-x-4 gap-y-2", children: [_jsx("div", { className: "min-w-0 flex-1", children: toolbar }), groupings?.length ? (_jsxs("div", { className: "flex items-center gap-2", children: [activeGrouping && (_jsx(Button, { variant: "ghost", size: "sm", "data-slot": "data-table-fold-all", disabled: !runs?.length, onClick: foldAll, children: allFolded ? 'Unfold all' : 'Fold all' })), _jsx(GroupMenu, { groupings: groupings, value: activeGrouping?.id ?? '', onValueChange: setGrouping })] })) : null, layouts?.length ? (_jsx(LayoutSwitch, { options: [
                             { id: 'table', label: tableLayout?.label ?? 'Table', icon: tableLayout?.icon ?? TableIcon },
                             ...layouts,
-                        ], value: currentLayout, onValueChange: setLayout })] })) : (toolbar), error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (cardLayout ? (_jsx(CardsSkeleton, { layout: cardLayout })) : (_jsx(TableSkeleton, { columnCount: table.getVisibleLeafColumns().length }))) : isEmpty ? (_jsxs(Empty, { "data-state": "empty", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: emptyTitle }), emptyDescription && _jsx(EmptyDescription, { children: emptyDescription })] }), emptyAction] })) : (_jsxs(_Fragment, { children: [cardLayout ? (_jsx(Cards, { layout: cardLayout, rows: rows, groupBy: groupBy, groupSummary: groupSummary })) : (_jsxs(Table, { "data-state": "success", containerRef: containerRef, 
+                        ], value: currentLayout, onValueChange: setLayout })) : null] })) : (toolbar), error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (cardLayout ? (_jsx(CardsSkeleton, { layout: cardLayout })) : (_jsx(TableSkeleton, { columnCount: table.getVisibleLeafColumns().length }))) : isEmpty ? (_jsxs(Empty, { "data-state": "empty", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: emptyTitle }), emptyDescription && _jsx(EmptyDescription, { children: emptyDescription })] }), emptyAction] })) : (_jsxs(DetailFrame, { enabled: Boolean(detailPanel) && !cardLayout, aside: selectedRow && detailPanel && isWide ? (_jsxs("aside", { "aria-label": detailLabel, "data-slot": "data-table-detail", className: DETAIL_ASIDE_CLASS, onKeyDown: (event) => {
+                        const target = event.target;
+                        if (event.key !== 'Escape' || event.defaultPrevented || target.closest(TYPING_SELECTOR))
+                            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 })) : (_jsxs(Table, { "data-state": "success", containerRef: containerRef, onKeyDown: detailPanel ? 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
@@ -315,18 +495,38 @@ 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) })), totals && (_jsx(TableFooter, { className: TOTALS_FOOTER_CLASS, children: _jsx(TableRow, { "data-slot": "table-totals", className: "hover:bg-transparent", children: visibleLeafColumns.map((column, index) => {
+                                    }) }, headerGroup.id))) }), runs ? (runs.map((run, runIndex) => {
+                                const isFolded = folded.has(run.key);
+                                return (_jsxs(TableBody, { "data-slot": "table-group", "data-folded": isFolded || undefined, children: [_jsx(TableRow, { "data-slot": "table-group-heading", className: "hover:bg-transparent has-aria-expanded: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(GroupLabel, { run: run, isFolded: isFolded, onToggle: () => toggleFold(run.key) }), groupSummary && (_jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: groupSummary(run.rows.map((row) => row.original), { key: run.key, label: run.label }) }))] }) }) }), _jsx("tr", { hidden: true, "aria-hidden": "true", "data-slot": "table-group-stripe-offset" }), !isFolded && run.rows.map((row) => renderRow(row, placeKey(run.key, row.id)))] }, `${runIndex}:${run.key}`));
+                            })) : (_jsx(TableBody, { children: rows.map((row) => renderRow(row)) })), 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, alignClass(column.columnDef.meta?.align));
                                         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 && !cardLayout && (_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] }));
+    return (_jsxs(EditInPlaceContext.Provider, { value: store, children: [editing && _jsx(LeaveGuard, { store: store }), width === 'content' ? _jsx("div", { className: "@container/data-table", children: content }) : content, detailPanel && (_jsx(Sheet, { open: Boolean(selectedRow) && !isWide && isSuccessView && !cardLayout, onOpenChange: (open) => {
+                    if (!open)
+                        setSelection(null);
+                }, children: _jsxs(SheetContent, { side: "bottom", className: "max-h-[85dvh] overflow-y-auto", "data-slot": "data-table-detail-sheet", children: [_jsx(SheetHeader, { className: "pb-0", children: _jsx(SheetTitle, { children: detailLabel }) }), _jsx("div", { className: "px-4 pb-4", children: selectedRow && detailPanel(selectedRow.original) })] }) }))] }));
+}
+// The list and, once a row is picked on a wide screen, the detail panel
+// beside it (`detailPanel`). Without a panel it adds nothing.
+function DetailFrame({ enabled, aside, children }) {
+    if (!enabled)
+        return _jsx(_Fragment, { children: children });
+    return (_jsxs("div", { "data-slot": "data-table-with-detail", className: cn('grid items-start gap-4', aside && WITH_DETAIL_OPEN_CLASS), children: [_jsx("div", { className: "flex min-w-0 flex-col gap-4", children: children }), aside] }));
+}
+// A group's heading text: under a grouping, a button that folds the group,
+// with its row count; under `groupBy`, the label alone.
+function GroupLabel({ run, isFolded, onToggle, }) {
+    if (!run.foldable)
+        return _jsx("span", { className: "type-label text-foreground", children: run.label });
+    return (_jsxs("button", { type: "button", "aria-expanded": !isFolded, onClick: onToggle, className: GROUP_TOGGLE_CLASS, children: [_jsx(ChevronDownIcon, { "aria-hidden": "true", className: cn('size-4 self-center text-muted-foreground transition-transform', isFolded && '-rotate-90') }), _jsx("span", { className: "type-label text-foreground", children: run.label }), _jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: run.rows.length })] }));
 }
-// A card layout's success view: the rows as cards in a grid or a list,
-// each run of one group (`groupBy`) under its own heading, as the table's
-// heading rows are, with the same label and summary.
-function Cards({ layout, rows, groupBy, groupSummary, }) {
+function Cards({ layout, runs, rows, folded, onToggleFold, groupSummary, }) {
     const list = (items) => (_jsx("ul", { role: "list", className: cn(layout.arrange === 'list' ? CARD_LIST_CLASS : ['grid', CARD_GRID_CLASS[layout.size ?? 'md'], CARD_GRID_GAP_CLASS]), children: items.map((row) => (_jsx("li", { "data-slot": "data-table-card", className: "min-w-0", children: layout.renderCard(row.original) }, row.id))) }));
-    return (_jsx("div", { className: "@container/data-table-cards flex flex-col gap-6", "data-state": "success", "data-slot": "data-table-cards", children: groupBy
-            ? groupRuns(rows, (row) => groupBy(row.original)).map((run, runIndex) => (_jsxs("section", { "data-slot": "table-group", className: "flex flex-col gap-3", children: [_jsxs("h2", { "data-slot": "table-group-heading", className: "flex items-baseline gap-2 border-b border-border pb-1.5", 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)) }))] }), list(run.rows)] }, `${runIndex}:${run.key}`)))
+    return (_jsx("div", { className: "@container/data-table-cards flex flex-col gap-6", "data-state": "success", "data-slot": "data-table-cards", children: runs
+            ? runs.map((run, runIndex) => {
+                const isFolded = folded.has(run.key);
+                return (_jsxs("section", { "data-slot": "table-group", "data-folded": isFolded || undefined, className: "flex flex-col gap-3", children: [_jsxs("h2", { "data-slot": "table-group-heading", className: "flex items-baseline gap-2 border-b border-border pb-1.5", children: [_jsx(GroupLabel, { run: run, isFolded: isFolded, onToggle: () => onToggleFold(run.key) }), groupSummary && (_jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: groupSummary(run.rows.map((row) => row.original), { key: run.key, label: run.label }) }))] }), !isFolded && list(run.rows)] }, `${runIndex}:${run.key}`));
+            })
             : list(rows) }));
 }

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

@@ -66,6 +66,12 @@ export type EntityViewProps = {
     titleEdit?: EditInPlace & {
         label: string;
     };
+    /**
+     * A line under the title, in muted body type: what the record is for (a
+     * goal, a one-line summary). Any markup, an `<EditableValue>` included,
+     * so it can be edited in place where it's shown.
+     */
+    subtitle?: ReactNode;
     /**
      * A few status-like values beside the title, as `<Badge>`s, or as the
      * control that changes one when the plan makes it a quick action (a
@@ -80,6 +86,13 @@ export type EntityViewProps = {
      * every width. Announced when it appears or changes after the page loads.
      */
     notice?: ReactNode;
+    /**
+     * A row of the record's key numbers (`<KeyStats>`) under the header and
+     * its notice, across the page at every width: in the rail layout above
+     * both columns, so on a phone it comes before the rail and the main
+     * column.
+     */
+    strip?: ReactNode;
     sections: EntityViewSection[];
     /**
      * Below every section (both columns in the rail layout), in small muted
@@ -101,4 +114,4 @@ export type EntityViewProps = {
         label: string;
     };
 };
-export declare function EntityView({ title, documentTitle, titleEdit, badges, actions, notice, sections, footer, layout, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;
+export declare function EntityView({ title, documentTitle, titleEdit, subtitle, badges, actions, notice, strip, sections, footer, layout, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;

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

@@ -29,8 +29,10 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // autosave as it's typed (`autosave`), and be the editor itself, with no
 // click to open (`alwaysEditable`).
 //
+// In the header, `subtitle` under the title (a goal, a one-line summary).
 // Around the sections: `notice` (a <Notice>) under the header, across the
-// page, for a state that decides what you do with the record; `footer`
+// page, for a state that decides what you do with the record; `strip` (a
+// <KeyStats>) under that, the record's key numbers; `footer`
 // (a <SourceCredit>) after them all, for crediting the data's source.
 //
 // Two layouts. `column` (the default): every section in one column capped
@@ -141,7 +143,7 @@ function Rail({ label, sections }) {
     const [ref, fits] = useFitsWindow();
     return (_jsx("aside", { ref: ref, "aria-label": label, "data-fits": fits ? '' : undefined, className: cn(RAIL_LAYOUT.rail, RAIL_LAYOUT.sticky, 'flex min-w-0 flex-col gap-6'), children: sections.map((section) => (_jsx(ViewSection, { section: section, inRail: true }, section.title))) }));
 }
-export function EntityView({ title, documentTitle, titleEdit, badges, actions, notice, sections, footer, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
+export function EntityView({ title, documentTitle, titleEdit, subtitle, badges, actions, notice, strip, sections, footer, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
     // Editing in place: one store per view, and the leave-page prompt only
     // while a field is open (or one is always editable).
     const [store] = useState(() => new EditInPlaceStore());
@@ -158,5 +160,5 @@ export function EntityView({ title, documentTitle, titleEdit, badges, actions, n
         return _jsx(EntityViewSkeleton, { layout: layout });
     const railSections = sections.filter((section) => section.placement === 'rail');
     const mainSections = sections.filter((section) => section.placement !== 'rail');
-    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [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) }), 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 }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), _jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) })] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title))), 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 }), _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: [railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), _jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) })] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title))), footer && (_jsx("footer", { "data-slot": "entity-view-footer", className: "type-caption text-muted-foreground", children: footer }))] }) }));
 }

package/dist/components/app/key-stats.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+export type KeyStat = {
+    label: string;
+    value: ReactNode;
+    /** A few words under the value ("of 12", "since May"), in caption type. */
+    hint?: ReactNode;
+};
+export type KeyStatsProps = {
+    stats: readonly KeyStat[];
+    /** What an empty value reads as. Defaults to "Not set". */
+    emptyLabel?: string;
+    className?: string;
+};
+export declare function KeyStats({ stats, emptyLabel, className }: KeyStatsProps): import("react").JSX.Element;

package/dist/components/app/key-stats.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from 'cn';
+const isEmpty = (value) => value === null || value === undefined || value === false || value === '';
+export function KeyStats({ stats, emptyLabel = 'Not set', className }) {
+    return (_jsx("dl", { "data-slot": "key-stats", className: cn('flex flex-wrap gap-x-8 gap-y-3 rounded-lg border border-border bg-card px-4 py-3 text-card-foreground', className), children: stats.map((stat) => (_jsxs("div", { className: "flex min-w-0 flex-col gap-0.5", children: [_jsx("dt", { className: "type-caption text-muted-foreground", children: stat.label }), _jsx("dd", { className: "type-section-title tabular-nums break-words text-foreground", children: isEmpty(stat.value) ? _jsx("span", { className: "type-body text-muted-foreground", children: emptyLabel }) : stat.value }), stat.hint && _jsx("dd", { className: "type-caption text-muted-foreground", children: stat.hint })] }, stat.label))) }));
+}

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

@@ -7,3 +7,15 @@ export type GroupRun<T> = RowGroup & {
     rows: T[];
 };
 export declare function groupRuns<T>(rows: readonly T[], groupOf: (row: T) => RowGroup): GroupRun<T>[];
+/**
+ * Rows grouped by a choice field's value (DataTable's `groupings`): one
+ * group per option, in the options' order, then any value the options
+ * don't name (in the order first met), then the rows with none under
+ * `emptyLabel`. A multi-value field (an array) puts the row under each of
+ * its values. Rows keep the server's order inside a group, and a group
+ * with no rows on this page never exists.
+ */
+export declare function groupByValues<T>(rows: readonly T[], valueOf: (row: T) => string | readonly string[] | null | undefined, options: readonly {
+    value: string;
+    label: string;
+}[], emptyLabel: string): GroupRun<T>[];

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

@@ -16,3 +16,40 @@ export function groupRuns(rows, groupOf) {
     }
     return runs;
 }
+/**
+ * Rows grouped by a choice field's value (DataTable's `groupings`): one
+ * group per option, in the options' order, then any value the options
+ * don't name (in the order first met), then the rows with none under
+ * `emptyLabel`. A multi-value field (an array) puts the row under each of
+ * its values. Rows keep the server's order inside a group, and a group
+ * with no rows on this page never exists.
+ */
+export function groupByValues(rows, valueOf, options, emptyLabel) {
+    const byKey = new Map();
+    const unknown = [];
+    const known = new Set(options.map((option) => option.value));
+    // The empty group's key can't collide with a value: values are non-empty.
+    const EMPTY = '';
+    for (const row of rows) {
+        const raw = valueOf(row);
+        const values = [...new Set((typeof raw === 'string' ? [raw] : (raw ?? [])).filter((value) => value !== ''))];
+        for (const value of values.length > 0 ? values : [EMPTY]) {
+            if (value !== EMPTY && !known.has(value) && !byKey.has(value))
+                unknown.push(value);
+            const group = byKey.get(value);
+            if (group)
+                group.push(row);
+            else
+                byKey.set(value, [row]);
+        }
+    }
+    const run = (key, label) => {
+        const groupRows = byKey.get(key);
+        return groupRows ? [{ key, label, rows: groupRows }] : [];
+    };
+    return [
+        ...options.flatMap((option) => run(option.value, option.label)),
+        ...unknown.flatMap((value) => run(value, value)),
+        ...run(EMPTY, emptyLabel),
+    ];
+}

package/dist/components/app/widget-card.d.ts

@@ -4,6 +4,11 @@ import type { AppError } from '../../api/contracts.js';
 import type { IconComponent } from './icon-component.js';
 export interface WidgetCardProps {
     title: string;
+    /**
+     * The card's id, on its region: the one WidgetCardGroup's `defaultOpen`
+     * names and useWidgetLayout orders (`"ready"`). Unique on the page.
+     */
+    id?: string;
     /**
      * An icon shown before the title: a Lucide icon, or an app's own mark (an
      * outside service's logo on a card about that service). Decorative: the
@@ -39,6 +44,14 @@ export interface WidgetCardProps {
      * Left out, it starts at `defaultCollapsed` on every visit.
      */
     storageKey?: string;
+    /**
+     * One short value shown in the header while the card is folded: a count
+     * (`3`), or a word or two (`"Due today"`). A skeleton while loading, a
+     * muted dash on an error. Ignored while open.
+     */
+    summary?: ReactNode;
+    /** What a folded card's summary says when it's empty (`"None"`); nothing when left out. */
+    emptySummary?: ReactNode;
     children?: ReactNode;
     className?: string;
 }
@@ -51,7 +64,22 @@ export type WidgetCardLink = {
     label: string;
     to?: never;
 };
-export declare function WidgetCard({ title, icon: Icon, headingLevel, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows, collapsible, defaultCollapsed, storageKey, children, className, }: WidgetCardProps): import("react").JSX.Element;
+export declare function WidgetCard({ id, title, icon: Icon, headingLevel, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows, collapsible, defaultCollapsed, storageKey, summary, emptySummary, children, className, }: WidgetCardProps): import("react").JSX.Element;
+export interface WidgetCardGroupProps {
+    /**
+     * One card open at a time: `true` always, `"mobile"` only below the
+     * sidebar's breakpoint (a desktop hub keeps each card's own
+     * `collapsible`), `false` never (the group is a plain wrapper).
+     */
+    accordion?: boolean | 'mobile';
+    /** The `id` of the card open at first; all folded (showing their summaries) when left out. */
+    defaultOpen?: string | null;
+    children: ReactNode;
+    /** The wrapper's classes: the hub's grid of cards, usually. */
+    className?: string;
+}
+/** Wraps a hub's WidgetCards so that opening one folds the others (on a phone only, with `accordion="mobile"`). */
+export declare function WidgetCardGroup({ accordion, defaultOpen, children, className }: WidgetCardGroupProps): import("react").JSX.Element;
 /** The rows of a WidgetCard: a list with a divider between rows. */
 export declare function WidgetList({ children, className }: {
     children: ReactNode;