@tristan2828/ui-foundation 4.54.0 → 4.55.0

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

@@ -117,6 +117,21 @@ export type DataTableProps<TData extends Record<string, unknown>> = {
      * layout's alone: a card layout's cards are as they are.
      */
     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.
+     */
+    onRowClick?: (row: TData) => void;
+    /**
+     * The row the `detailPanel` shows, controlled: its row id (`getRowId`), or
+     * null for none. With `onDetailRowChange` it lets a control of the app's
+     * own (a button in a row) open the panel. Left out, the table keeps the
+     * pick itself.
+     */
+    detailRow?: string | null;
+    onDetailRowChange?: (rowId: string | null) => void;
     /** The panel's heading and landmark name: "Details" unless set. */
     detailLabel?: string;
     /**
@@ -178,6 +193,7 @@ export type DataTableGrouping<TData> = {
     options: readonly {
         value: string;
         label: string;
+        icon?: ReactNode;
     }[];
     /**
      * The row's value: one option's value, or a list of them for a
@@ -224,4 +240,4 @@ export type DataTableTotals = {
      */
     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, layouts, layout: layoutProp, onLayoutChange, tableLayout, groupings, grouping: groupingProp, onGroupingChange, detailPanel, detailLabel, }: DataTableProps<TData>): import("react").JSX.Element;
+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, layouts, layout: layoutProp, onLayoutChange, tableLayout, groupings, grouping: groupingProp, onGroupingChange, detailPanel, onRowClick: onRowClickProp, detailRow, onDetailRowChange, detailLabel, }: DataTableProps<TData>): import("react").JSX.Element;

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

@@ -260,7 +260,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, groupings, grouping: groupingProp, onGroupingChange, detailPanel, detailLabel = 'Details', }) {
+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, onRowClick: onRowClickProp, detailRow, onDetailRowChange, detailLabel = 'Details', }) {
     // The switch's own state, for a table that doesn't pass `layout`.
     const [ownLayout, setOwnLayout] = useState('table');
     const requestedLayout = layoutProp ?? ownLayout;
@@ -275,6 +275,10 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     // doesn't pass `grouping`.
     const [ownGrouping, setOwnGrouping] = useState('');
     const activeGrouping = groupings?.find((candidate) => candidate.id === (groupingProp ?? ownGrouping));
+    // Each group's icon (an option's `icon`), by the group's key.
+    const groupIcons = activeGrouping
+        ? new Map(activeGrouping.options.flatMap((option) => (option.icon ? [[option.value, option.icon]] : [])))
+        : undefined;
     const setGrouping = (next) => {
         if (groupingProp === undefined)
             setOwnGrouping(next);
@@ -285,7 +289,20 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     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 [ownSelection, setOwnSelection] = useState(null);
+    // Controlled (`detailRow`): the app's row id, at the place picked in when
+    // that's the same row, else the row's first place.
+    const selection = detailRow === undefined
+        ? ownSelection
+        : detailRow === null
+            ? null
+            : ownSelection?.rowId === detailRow
+                ? ownSelection
+                : { key: detailRow, rowId: detailRow };
+    const setSelection = (next) => {
+        setOwnSelection(next);
+        onDetailRowChange?.(next?.rowId ?? 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
@@ -407,12 +424,18 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
             return;
         const control = target.closest(ROW_CONTROL_SELECTOR);
         if (control && event.currentTarget.contains(control)) {
-            if (!control.matches('a[href]'))
+            if (!control.matches('a[href]') || onRowClickProp)
                 return;
             // In the capture phase, so react-router's Link sees it prevented and
             // doesn't navigate.
             event.preventDefault();
         }
+        if (onRowClickProp) {
+            const row = rows.find((candidate) => candidate.id === place.rowId);
+            if (row)
+                onRowClickProp(row.original);
+            return;
+        }
         setSelection(place);
     };
     const onListKeyDown = (event) => {
@@ -437,6 +460,12 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
             if (!place)
                 return;
             event.preventDefault();
+            if (onRowClickProp) {
+                const row = rows.find((candidate) => candidate.id === place.rowId);
+                if (row)
+                    onRowClickProp(row.original);
+                return;
+            }
             setSelection(place);
         }
         else if (event.key === 'Escape' && selectedRow) {
@@ -468,7 +497,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 })) : (_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: 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
@@ -499,7 +528,7 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                                                         : '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))) }), 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}`));
+                                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, icon: groupIcons?.get(run.key), 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));
@@ -518,17 +547,19 @@ function DetailFrame({ enabled, aside, children }) {
 }
 // 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 })] }));
+function GroupLabel({ run, icon, isFolded, onToggle, }) {
+    const label = (_jsxs(_Fragment, { children: [icon ? (_jsx("span", { "aria-hidden": "true", className: "inline-flex shrink-0 items-center self-center", children: icon })) : null, _jsx("span", { className: "type-label text-foreground", children: run.label })] }));
+    if (!run.foldable) {
+        return icon ? (_jsx("span", { className: "inline-flex items-baseline gap-1.5", children: label })) : (_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') }), label, _jsx("span", { className: "type-caption text-muted-foreground tabular-nums", children: run.rows.length })] }));
 }
-function Cards({ layout, runs, rows, folded, onToggleFold, groupSummary, }) {
+function Cards({ layout, runs, rows, folded, onToggleFold, groupSummary, groupIcons, }) {
     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: 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}`));
+                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, icon: groupIcons?.get(run.key), 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/package.json

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