@nanisoft/prism-ui 0.16.0 → 1.0.0

package/dist/blocks/data-table-01/data-table.js

@@ -1,15 +1,30 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { ChevronDown, ListFilter, MoreHorizontal, Search } from 'lucide-react';
-import { useId, useState } from 'react';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ChevronDown, ListFilter, Search, XIcon } from 'lucide-react';
+import { Fragment, useEffect, useId, useRef, useState } from 'react';
+import { Avatar } from '../../components/ui/avatar.js';
+import { Badge } from '../../components/ui/badge.js';
 import { Button } from '../../components/ui/button.js';
 import { Checkbox } from '../../components/ui/checkbox.js';
-import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, } from '../../components/ui/dropdown-menu.js';
+import { Checklist } from '../../components/ui/checklist.js';
+import { CodeBlock } from '../../components/ui/code-block.js';
+import { Diff } from '../../components/ui/diff.js';
+import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, } from '../../components/ui/dropdown-menu.js';
 import { Input } from '../../components/ui/input.js';
+import { Kbd } from '../../components/ui/kbd.js';
+import { LiveRegion } from '../../components/ui/live-region.js';
+import { Mark } from '../../components/ui/mark.js';
 import { Pagination, PaginationContent, PaginationItem } from '../../components/ui/pagination.js';
 import { Popover, PopoverContent, PopoverTrigger } from '../../components/ui/popover.js';
+import { Price } from '../../components/ui/price.js';
+import { RelativeTime } from '../../components/ui/relative-time.js';
 import { headingSizeClass } from '../../components/ui/section.js';
+import { Status } from '../../components/ui/status.js';
 import { Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow, } from '../../components/ui/table.js';
+import { TableSort } from '../../components/ui/table-sort.js';
+import { TagGroup } from '../../components/ui/tag-group.js';
+import { Text } from '../../components/ui/typography.js';
+import { cn } from '../../lib/utils.js';
 /** The page numbers to show, with `ellipsis` where a run is held back. */
 function pageWindow(page, pageCount) {
     if (pageCount <= 7) {
@@ -27,47 +42,193 @@ function pageWindow(page, pageCount) {
     pages.push(pageCount);
     return pages;
 }
-function RowMenu({ actions, label }) {
-    if (!actions.length)
-        return null;
-    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { "aria-label": label, className: "size-8 p-0 pointer-coarse:size-11", children: _jsx(MoreHorizontal, { className: "size-4" }) }), _jsx(DropdownMenuContent, { align: "end", children: actions.map((action, index) => (
-                // Positional: an action label is display content and two may repeat.
-                _jsx(DropdownMenuItem, { variant: action.variant, onClick: action.onSelect, children: action.label }, index))) })] }));
+/** Where a value belongs in a cell, defaulting to the start. */
+function alignClass(column) {
+    if (column.align === 'center')
+        return 'text-center';
+    if (column.align === 'end')
+        return 'text-end';
+    return 'text-start';
 }
 /**
- * A table section with a toolbar, filters, row selection and pagination.
+ * One cell, drawn from the column's kind and the row's value at its key.
  *
- * The block renders exactly the rows it is given for the current page and
- * reports every interaction through a callback. It performs no filtering,
- * sorting or fetching of its own: the page, the search text, the filter values
- * and the selection are the consumer's state, so a server-rendered page and a
- * client data layer can each drive it. Every label is a prop.
+ * The value at `column.key` is the cell's own content. A kind that names a
+ * single-node cell (`Typography`, `Badge`, `Avatar`, `Kbd`) draws the value as that
+ * Component's child; a kind that names a structured cell (`Price`, `RelativeTime`,
+ * `Status`, `TagGroup`, `Checklist`, `Diff`, `Mark`, `CodeBlock`) takes the value as
+ * that Component's props; and `slot` draws the value as the caller's own node.
+ *
+ * The map is keyed by the kind's lowercase name and every member of `ColumnKind`
+ * has one entry, so a kind added to the union fails the compiler here until it is
+ * drawn. The lowercase keys are machine values rather than copy, which is the same
+ * reason a variant name is written in lowercase everywhere else in this package.
+ */
+const CELL = {
+    typography: (value) => _jsx(Text, { as: "span", children: value }),
+    price: (value) => _jsx(Price, { ...value }),
+    relativetime: (value) => _jsx(RelativeTime, { ...value }),
+    status: (value) => _jsx(Status, { ...value }),
+    badge: (value) => _jsx(Badge, { children: value }),
+    avatar: (value) => _jsx(Avatar, { children: value }),
+    taggroup: (value) => _jsx(TagGroup, { ...value }),
+    checklist: (value) => _jsx(Checklist, { ...value }),
+    diff: (value) => _jsx(Diff, { ...value }),
+    mark: (value) => _jsx(Mark, { ...value }),
+    kbd: (value) => _jsx(Kbd, { children: value }),
+    codeblock: (value) => _jsx(CodeBlock, { ...value }),
+    slot: (value) => value,
+};
+/** The cell for one column and one row. */
+function renderCell(column, row) {
+    return CELL[column.kind.toLowerCase()](row[column.key]);
+}
+/**
+ * The record index: a table of rows a reader scans and acts on.
+ *
+ * It draws the page of rows it was handed for the page it was told about, and it
+ * fetches nothing, sorts nothing, filters nothing and slices nothing. `columns` is
+ * the shared `ColumnSpec` typed data rather than a render function per column, so
+ * alignment, width, the header and the sort affordance are drawn once for every
+ * consumer. `getRowId` is required, because a row's position moves under sorting,
+ * filtering and paging and an index-keyed selection would act on the wrong records.
+ *
+ * **It is also the log and the event stream, drawing event rows from the shared event
+ * specification.** A consumer composing a delivery log or a console events screen
+ * passes the same `EventSpec` values an activity trail takes, and draws columns from
+ * them: the sending process in `actor`, the event type in `action`, the endpoint in
+ * `target`, the payload in a `CodeBlock` cell the caller composes, and the response
+ * status in a `Status` cell the caller composes rather than declared as a member,
+ * because the event specification has no kind and no severity. A log is a different
+ * job from the trail on the arrangement signal: it gains a filter region the trail
+ * does not draw, a second axis on which entries are compared, and a page boundary in
+ * place of a silent limit, and every one of those belongs to this Block rather than
+ * to a rail. So a screen that wants the events of one record composes
+ * `ActivityFeed01`, a screen that wants to find one entry among many composes this
+ * Block, and there is no second log Item beside it.
+ *
+ * **The Block composes no disclosure.** Seeing one entry in full is a destination the
+ * caller names with its required words, expanding a payload in place is the caller's
+ * own `Collapsible` placed in a `slot` cell, and taking an identifier away is the
+ * caller's own control composed beside a code block. A control whose handler arrives
+ * through a spread of unknown shape reads as carrying no handler, so the escape for a
+ * per-entry action is the `renderRowActions` node rather than a spread.
+ *
+ * **It draws no retention window, no archive, no purge, no legal hold and no export**,
+ * and no immutability mark, no time axis, no live tail, no aggregate over the
+ * population and no command of its own. A filter is a narrowing the caller passed and
+ * the Block states nothing about what is behind it. Row selection exists so the caller
+ * can drive a command against its own store.
+ *
+ * **It holds the selection set it was given, and reports every change.** This is the
+ * one piece of state a block in this repository keeps, and it is scoped by what the
+ * state is: a set of keys the caller passed for the page about to be drawn. Nothing
+ * in the block fetches, derives from application state or decides. A consumer that
+ * wants the set mirrored passes `selectedIds` and writes one line in
+ * `onSelectedIdsChange`; a consumer that wants nothing passes neither and the block
+ * still draws the tick, the header's three-state control, the count, the batch bar
+ * and the announcement.
+ *
+ * **The count is announced once, politely.** One `LiveRegion` at `polite` carries the
+ * count and is never assertive, and it is mounted while there is an announcement
+ * rather than always, so its appearance is the first thing spoken rather than a
+ * silent mutation of a node that was always there. It announces the count and never
+ * a list of labels, because each row's own checkbox already names its record. When
+ * the set empties, the region speaks its own sentence rather than a count of zero.
+ * The visible summary in the footer and the announced count are the same string.
+ *
+ * **The batch bar is the block's region and the caller's controls.** It mounts only
+ * while the set is non-empty, displaces the filter controls rather than sitting
+ * beside them, and holds one required `batchActions` node the caller wrote plus the
+ * block's own dismiss. The dismiss is the only control the block draws, and its whole
+ * body is the same report every tick makes with an empty set.
+ *
+ * **Per-row actions are a node per row.** The block draws the trailing cell and
+ * places `renderRowActions(row)` inside it, so a row that navigates and a row that is
+ * ticked are two separately reachable targets and the block owns no command.
+ *
+ * **Grouping is a key on a row, not a second arrangement.** `groupBy` returns the key
+ * a row belongs to and the block draws `groupLabel(key)` in a full-width row above
+ * each run of rows that shares one, in the caller's own order. A heading is a row in
+ * the same body as any other and it is not a record: it is never in the selection
+ * set, never in the count and never what the header's page scope counts.
+ *
+ * **The two selection scopes are announced differently.** A page-wide selection is
+ * one the block can count, so it speaks `labels.selectedCount`. A filter-wide
+ * selection is a population the block never fetched, so the caller reports it
+ * through `selectionScope` and the block speaks `labels.selectedAllMatching` with the
+ * caller's own number rather than printing the page as if it were the total.
  */
-export function DataTable01({ title, description, columns, rows, getRowId, caption, selectable = false, selectedIds, defaultSelectedIds, onSelectedIdsChange, searchValue, onSearchChange, filters, filterValues, onFilterChange, page: pageProp, defaultPage = 1, pageCount, onPageChange, rowActions, toolbarActions, emptyMessage, labels, headingLevel = 'h2', }) {
+export function DataTable01(props) {
+    const { title, description, columns, rows, getRowId, caption, headingLevel = 'h2', sort: sortProp, onSortChange, searchValue, onSearchChange, filters, filterValues, onFilterChange, page: pageProp, defaultPage = 1, pageCount, onPageChange, renderRowActions, toolbarActions, emptyMessage, labels, groupBy, groupLabel, } = props;
     const Heading = headingLevel;
     // The handle the table names itself from; see the note on the table.
     const headingId = useId();
-    const [internalSelected, setInternalSelected] = useState(defaultSelectedIds ?? []);
+    // The prefix the per-cell help ids are built from.
+    const helpPrefix = useId();
+    const isSelectable = props.selectable === true;
+    const [internalSelected, setInternalSelected] = useState(() => [
+        ...(props.defaultSelectedIds ?? []),
+    ]);
     const [internalPage, setInternalPage] = useState(defaultPage);
     const [internalSearch, setInternalSearch] = useState('');
     const [internalFilters, setInternalFilters] = useState({});
+    const [internalSort, setInternalSort] = useState(null);
     const [hiddenColumns, setHiddenColumns] = useState([]);
-    const selected = selectedIds ?? internalSelected;
+    const selected = isSelectable
+        ? props.selectedIds === undefined
+            ? internalSelected
+            : [...props.selectedIds]
+        : [];
     const page = pageProp ?? internalPage;
     const search = searchValue ?? internalSearch;
     const activeFilters = filterValues ?? internalFilters;
+    const sortState = sortProp !== undefined ? sortProp : internalSort;
     const clampPage = (value) => Math.min(Math.max(1, value), Math.max(1, pageCount));
     const currentPage = clampPage(page);
-    const visibleColumns = columns.filter((column) => !hiddenColumns.includes(column.id));
-    const hasRowActions = Boolean(rowActions);
-    const columnCount = (selectable ? 1 : 0) + visibleColumns.length + (hasRowActions ? 1 : 0);
+    const visibleColumns = columns.filter((column) => !hiddenColumns.includes(column.key));
+    const hasRowActions = renderRowActions !== undefined;
+    const columnCount = (isSelectable ? 1 : 0) + visibleColumns.length + (hasRowActions ? 1 : 0);
+    // The scope the caller reports. Absent means the page, which is the one
+    // population the block can count for itself.
+    const scope = isSelectable ? props.selectionScope : undefined;
+    const filterScope = scope?.scope === 'filter' ? scope : undefined;
+    // A filter-wide selection is a selection even though its keys are not on screen,
+    // so the bar mounts and the region speaks from the scope rather than from the
+    // page's keys. The number is the caller's and is never the rows on screen.
+    const selectionActive = isSelectable && (filterScope !== undefined || selected.length > 0);
+    const selectionSummary = filterScope !== undefined
+        ? labels.selectedAllMatching(filterScope.count)
+        : labels.selectedCount(selected.length);
     const rowIds = rows.map(getRowId);
-    const allSelected = rowIds.length > 0 && rowIds.every((id) => selected.includes(id));
-    const someSelected = rowIds.some((id) => selected.includes(id));
+    // A filter-wide selection covers the page whether or not the page's keys were
+    // passed, so the header reads as fully selected on that arm. A heading is not in
+    // `rowIds`, so grouping never changes what these two say.
+    const allSelected = filterScope !== undefined || (rowIds.length > 0 && rowIds.every((id) => selected.includes(id)));
+    const someSelected = filterScope !== undefined || rowIds.some((id) => selected.includes(id));
+    // The emptying sentence. A live region speaks when its text changes, and the
+    // sequence where the selection falls to nothing is the one the reader has to be told
+    // about because the batch bar they were about to use disappears with it. The
+    // previous presence is ref-held, so the render that reaches nothing still knows
+    // there was a selection and can speak the sentence rather than the absence of one.
+    const previousActive = useRef(selectionActive);
+    useEffect(() => {
+        previousActive.current = selectionActive;
+    }, [selectionActive]);
+    const announcement = selectionActive
+        ? selectionSummary
+        : previousActive.current
+            ? labels.clearedSelection
+            : null;
     function changeSelection(ids) {
-        if (selectedIds === undefined)
+        if (isSelectable === false)
+            return;
+        if (props.selectedIds === undefined)
             setInternalSelected(ids);
-        onSelectedIdsChange?.(ids);
+        props.onSelectedIdsChange?.(ids);
+    }
+    function clearSelection() {
+        changeSelection([]);
     }
     function toggleAll(checked) {
         if (checked) {
@@ -103,18 +264,39 @@ export function DataTable01({ title, description, columns, rows, getRowId, capti
             setInternalPage(clamped);
         onPageChange?.(clamped);
     }
-    function toggleColumn(id, visible) {
-        setHiddenColumns((previous) => visible ? previous.filter((item) => item !== id) : [...previous, id]);
+    function changeSort(column, direction) {
+        const next = direction === 'none' ? null : { column, direction };
+        if (sortProp === undefined)
+            setInternalSort(next);
+        onSortChange?.(next);
+    }
+    function toggleColumn(key, visible) {
+        setHiddenColumns((previous) => visible ? previous.filter((item) => item !== key) : [...previous, key]);
     }
     const activeFilterCount = Object.values(activeFilters).filter(Boolean).length;
-    return (_jsxs("div", { className: "flex flex-col gap-4", children: [title || description ? (_jsxs("div", { className: "flex flex-col gap-1", children: [title ? (_jsx(Heading, { id: headingId, className: `font-semibold tracking-tight text-balance ${headingSizeClass(headingLevel)}`, children: title })) : null, description ? (_jsx("p", { className: "text-muted-foreground text-sm", children: description })) : null] })) : null, _jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3", children: [_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsxs("div", { className: "relative", children: [_jsx(Search, { className: "text-muted-foreground pointer-events-none absolute top-1/2 left-2.5 size-4 -translate-y-1/2" }), _jsx(Input, { value: search, onChange: (event) => changeSearch(event.target.value), placeholder: labels.search, "aria-label": labels.search, className: "h-9 w-56 pl-8" })] }), filters?.length ? (_jsxs(Popover, { children: [_jsxs(PopoverTrigger, { children: [_jsx(ListFilter, { className: "size-4" }), labels.filters, activeFilterCount > 0 ? (_jsx("span", { className: "bg-primary text-primary-foreground rounded-full px-1.5 text-xs", children: activeFilterCount })) : null] }), _jsxs(PopoverContent, { align: "start", className: "flex w-64 flex-col gap-4", children: [filters.map((filter) => (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx("span", { className: "text-sm font-medium", children: filter.label }), _jsx("div", { className: "flex flex-wrap gap-1.5", children: filter.options.map((option) => {
-                                                            const active = activeFilters[filter.id] === option.value;
-                                                            return (_jsx(Button, { type: "button", size: "sm", variant: active ? 'default' : 'outline', onClick: () => changeFilter(filter.id, active ? undefined : option.value), children: option.label }, option.value));
-                                                        }) })] }, filter.id))), _jsx(Button, { type: "button", variant: "ghost", size: "sm", disabled: activeFilterCount === 0, onClick: resetFilters, children: labels.reset })] })] })) : null] }), _jsxs("div", { className: "flex items-center gap-2", children: [toolbarActions, _jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { children: [labels.viewColumns, _jsx(ChevronDown, { className: "size-4" })] }), _jsxs(DropdownMenuContent, { align: "end", children: [_jsx(DropdownMenuLabel, { children: labels.columns }), _jsx(DropdownMenuSeparator, {}), columns.map((column) => (_jsx(DropdownMenuCheckboxItem, { checked: !hiddenColumns.includes(column.id), closeOnClick: false, onCheckedChange: (checked) => toggleColumn(column.id, checked), children: column.label ?? column.id }, column.id)))] })] })] })] }), _jsx("div", { className: "border-border overflow-hidden rounded-xl border", children: _jsxs(Table, { "aria-labelledby": caption === undefined && title ? headingId : undefined, children: [caption ? _jsx(TableCaption, { children: caption }) : null, _jsx(TableHeader, { children: _jsxs(TableRow, { children: [selectable ? (_jsx(TableHead, { className: "w-10", children: _jsx(Checkbox, { checked: allSelected, indeterminate: !allSelected && someSelected, onCheckedChange: toggleAll, "aria-label": labels.selectAll }) })) : null, visibleColumns.map((column) => (_jsx(TableHead, { className: column.className, children: column.header }, column.id))), hasRowActions ? (_jsx(TableHead, { className: "w-10", children: _jsx("span", { className: "sr-only", children: labels.rowActions }) })) : null] }) }), _jsx(TableBody, { children: rows.length ? (rows.map((row) => {
+    // The key of the row before this one, so a heading belongs to a run of rows and
+    // not to a row. It resets every render and is read by the body below.
+    let previousGroupKey;
+    return (_jsxs("div", { className: "flex flex-col gap-4", children: [title || description ? (_jsxs("div", { className: "flex flex-col gap-1", children: [title ? (_jsx(Heading, { id: headingId, className: `font-semibold tracking-tight text-balance ${headingSizeClass(headingLevel)}`, children: title })) : null, description ? (_jsx("p", { className: "text-muted-foreground text-sm", children: description })) : null] })) : null, _jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3", children: [_jsx("div", { className: "flex min-w-0 flex-1 flex-wrap items-center gap-2", children: selectionActive ? (_jsxs("div", { "data-slot": "data-table-01-batch-bar", role: "toolbar", "aria-label": selectionSummary, className: "bg-card flex w-full items-center gap-1 rounded-md border p-1", children: [_jsx("span", { className: "text-muted-foreground px-2 text-sm font-medium", children: selectionSummary }), _jsx("div", { className: "flex flex-1 flex-wrap items-center gap-2", children: props.selectable === true ? props.batchActions : null }), _jsx(Button, { "data-slot": "data-table-01-dismiss", type: "button", variant: "ghost", size: "sm", "aria-label": labels.dismissSelection, onClick: clearSelection, children: _jsx(XIcon, { "aria-hidden": "true" }) })] })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "relative", children: [_jsx(Search, { className: "text-muted-foreground pointer-events-none absolute top-1/2 left-2.5 size-4 -translate-y-1/2" }), _jsx(Input, { value: search, onChange: (event) => changeSearch(event.target.value), placeholder: labels.search, "aria-label": labels.search, className: "h-9 w-56 pl-8" })] }), filters?.length ? (_jsxs(Popover, { children: [_jsxs(PopoverTrigger, { children: [_jsx(ListFilter, { className: "size-4" }), labels.filters, activeFilterCount > 0 ? (_jsx("span", { className: "bg-primary text-primary-foreground rounded-full px-1.5 text-xs", children: activeFilterCount })) : null] }), _jsxs(PopoverContent, { align: "start", className: "flex w-64 flex-col gap-4", children: [filters.map((filter) => (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx("span", { className: "text-sm font-medium", children: filter.label }), _jsx("div", { className: "flex flex-wrap gap-1.5", children: filter.options.map((option) => {
+                                                                const active = activeFilters[filter.id] === option.value;
+                                                                return (_jsx(Button, { type: "button", size: "sm", variant: active ? 'default' : 'outline', onClick: () => changeFilter(filter.id, active ? undefined : option.value), children: option.label }, option.value));
+                                                            }) })] }, filter.id))), _jsx(Button, { type: "button", variant: "ghost", size: "sm", disabled: activeFilterCount === 0, onClick: resetFilters, children: labels.reset })] })] })) : null] })) }), _jsxs("div", { className: "flex items-center gap-2", children: [toolbarActions, _jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { children: [labels.viewColumns, _jsx(ChevronDown, { className: "size-4" })] }), _jsxs(DropdownMenuContent, { align: "end", children: [_jsx(DropdownMenuLabel, { children: labels.columns }), _jsx(DropdownMenuSeparator, {}), columns.map((column) => (_jsx(DropdownMenuCheckboxItem, { checked: !hiddenColumns.includes(column.key), closeOnClick: false, onCheckedChange: (checked) => toggleColumn(column.key, checked), children: typeof column.header === 'string' ? column.header : column.key }, column.key)))] })] })] })] }), _jsx(LiveRegion, { "data-slot": "data-table-01-announcement", politeness: "polite", className: "sr-only", children: announcement }), _jsx("div", { className: "border-border overflow-hidden rounded-xl border", children: _jsxs(Table, { "aria-labelledby": caption === undefined && title ? headingId : undefined, children: [caption ? _jsx(TableCaption, { children: caption }) : null, _jsx(TableHeader, { children: _jsxs(TableRow, { children: [isSelectable ? (_jsx(TableHead, { className: "w-10", children: _jsx(Checkbox, { checked: allSelected, indeterminate: !allSelected && someSelected, onCheckedChange: toggleAll, "aria-label": labels.selectAll }) })) : null, visibleColumns.map((column) => column.sortable ? (_jsx(TableSort, { column: column.key, direction: sortState?.column === column.key ? sortState.direction : 'none', onDirectionChange: (direction) => changeSort(column.key, direction), announce: (direction) => labels.sort(column.key, direction), className: cn(column.width), children: column.header }, column.key)) : (_jsx(TableHead, { className: cn(column.width, alignClass(column)), children: column.header }, column.key))), hasRowActions ? (_jsx(TableHead, { className: "w-10", children: _jsx("span", { className: "sr-only", children: labels.rowActions }) })) : null] }) }), _jsx(TableBody, { children: rows.length ? (rows.map((row, rowIndex) => {
                                 const id = getRowId(row);
                                 const isSelected = selected.includes(id);
-                                const actions = rowActions?.(row) ?? [];
-                                return (_jsxs(TableRow, { "data-state": isSelected ? 'selected' : undefined, children: [selectable ? (_jsx(TableCell, { children: _jsx(Checkbox, { checked: isSelected, onCheckedChange: (checked) => toggleRow(id, checked), "aria-label": labels.selectRow }) })) : null, visibleColumns.map((column) => (_jsx(TableCell, { className: column.className, children: column.cell(row) }, column.id))), hasRowActions ? (_jsx(TableCell, { className: "text-right", children: _jsx(RowMenu, { actions: actions, label: labels.rowActions }) })) : null] }, id));
-                            })) : (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: columnCount, className: "text-muted-foreground h-24 text-center", children: emptyMessage ?? labels.empty }) })) })] }) }), _jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3", children: [selectable ? (_jsx("span", { className: "text-muted-foreground text-sm", children: labels.selectedCount(selected.length) })) : (_jsx("span", {})), _jsx(Pagination, { className: "mx-0 w-auto justify-end", children: _jsxs(PaginationContent, { children: [_jsx(PaginationItem, { children: _jsx(Button, { type: "button", variant: "ghost", size: "sm", disabled: currentPage <= 1, "aria-label": labels.previous, onClick: () => changePage(currentPage - 1), children: labels.previous }) }), pageWindow(currentPage, Math.max(1, pageCount)).map((item, index) => item === 'ellipsis' ? (_jsx(PaginationItem, { children: _jsx("span", { "aria-hidden": "true", className: "text-muted-foreground px-2", children: "..." }) }, `ellipsis-${index}`)) : (_jsx(PaginationItem, { children: _jsx(Button, { type: "button", variant: item === currentPage ? 'outline' : 'ghost', size: "icon", "aria-label": labels.page(item), "aria-current": item === currentPage ? 'page' : undefined, onClick: () => changePage(item), children: item }) }, item))), _jsx(PaginationItem, { children: _jsx(Button, { type: "button", variant: "ghost", size: "sm", disabled: currentPage >= Math.max(1, pageCount), "aria-label": labels.next, onClick: () => changePage(currentPage + 1), children: labels.next }) })] }) })] })] }));
+                                // A heading is drawn once per run of rows with one key, in the
+                                // caller's own order. A row with no key starts no heading and is not
+                                // a record that a group owns; it is simply ungrouped.
+                                const rowGroupKey = groupBy?.(row);
+                                const startsGroup = groupBy !== undefined &&
+                                    rowGroupKey !== undefined &&
+                                    rowGroupKey !== previousGroupKey;
+                                previousGroupKey = rowGroupKey;
+                                return (_jsxs(Fragment, { children: [startsGroup ? (_jsx(TableRow, { "data-slot": "data-table-01-group", children: _jsx(TableCell, { colSpan: columnCount, className: "text-muted-foreground bg-muted text-sm font-medium", children: groupLabel?.(rowGroupKey) }) })) : null, _jsxs(TableRow, { "data-state": isSelected ? 'selected' : undefined, children: [isSelectable ? (_jsx(TableCell, { className: "w-10", children: _jsx(Checkbox, { checked: isSelected, onCheckedChange: (checked) => toggleRow(id, checked), "aria-label": labels.selectRow(row) }) })) : null, visibleColumns.map((column, columnIndex) => {
+                                                    const helpId = column.help === undefined
+                                                        ? undefined
+                                                        : `${helpPrefix}-help-${columnIndex}-${rowIndex}`;
+                                                    return (_jsxs(TableCell, { className: cn(column.width, alignClass(column)), "aria-describedby": helpId, children: [renderCell(column, row), helpId === undefined ? null : (_jsx("span", { id: helpId, className: "sr-only", children: column.help }))] }, column.key));
+                                                }), hasRowActions ? (_jsx(TableCell, { className: "text-right", children: renderRowActions?.(row) })) : null] })] }, id));
+                            })) : (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: columnCount, className: "text-muted-foreground h-24 text-center", children: emptyMessage ?? labels.empty }) })) })] }) }), _jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3", children: [selectionActive ? (_jsx("span", { className: "text-muted-foreground text-sm", children: selectionSummary })) : (_jsx("span", {})), _jsx(Pagination, { className: "mx-0 w-auto justify-end", children: _jsxs(PaginationContent, { children: [_jsx(PaginationItem, { children: _jsx(Button, { type: "button", variant: "ghost", size: "sm", disabled: currentPage <= 1, "aria-label": labels.previous, onClick: () => changePage(currentPage - 1), children: labels.previous }) }), pageWindow(currentPage, Math.max(1, pageCount)).map((item, index) => item === 'ellipsis' ? (_jsx(PaginationItem, { children: _jsx("span", { "aria-hidden": "true", className: "text-muted-foreground px-2", children: "..." }) }, `ellipsis-${index}`)) : (_jsx(PaginationItem, { children: _jsx(Button, { type: "button", variant: item === currentPage ? 'outline' : 'ghost', size: "icon", "aria-label": labels.page(item), "aria-current": item === currentPage ? 'page' : undefined, onClick: () => changePage(item), children: item }) }, item))), _jsx(PaginationItem, { children: _jsx(Button, { type: "button", variant: "ghost", size: "sm", disabled: currentPage >= Math.max(1, pageCount), "aria-label": labels.next, onClick: () => changePage(currentPage + 1), children: labels.next }) })] }) })] })] }));
 }
 export default DataTable01;

package/dist/blocks/data-table-01/index.d.ts

@@ -1,3 +1,3 @@
 export { DataTable01, default } from './data-table.js';
-export type { DataTable01Props, DataTable01Labels, DataTableColumn, DataTableFilter, DataTableFilterOption, DataTableRow, DataTableRowAction, } from './data-table.js';
+export type { DataTable01Props, DataTable01Labels, DataTable01SelectionScope, DataTableFilter, DataTableFilterOption, DataTableRow, DataTableSort, } from './data-table.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/blocks/data-table-01/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/data-table-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACnD,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,YAAY,EACZ,kBAAkB,GACnB,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/data-table-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACnD,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,EACzB,eAAe,EACf,qBAAqB,EACrB,YAAY,EACZ,aAAa,GACd,MAAM,cAAc,CAAA"}

package/dist/blocks/directory-01/directory-01.d.ts

@@ -182,7 +182,7 @@ export type Directory01Props = {
      */
     empty: ReactNode;
     /**
-     * The caller's own line about what the query found.
+     * The result line, written the way four products write it.
      *
      * A function and not a node, because the count a reader reads is a sentence whose
      * word order and noun inflection belong to their language, and a Block that composed
@@ -192,6 +192,27 @@ export type Directory01Props = {
      * paint.
      */
     summary?: (matches: number) => ReactNode;
+    /**
+     * The caller's own control for one member, placed without styling at the member's
+     * trailing edge.
+     *
+     * A node per member rather than one node for the directory, because what a caller
+     * puts here acts on the member it sits beside: a plugin's enable is a `Switch`
+     * whose `onCheckedChange` names that plugin, and one node reused across fifty
+     * members could not. It is a function in the shape `DataTable01`'s
+     * `renderRowActions` already takes, so the two per-row action shapes in this
+     * package are one shape and not two.
+     *
+     * **The Block draws no control of its own here, and that is the whole reason the
+     * prop is a node.** `scripts/check-block-controls.mjs` classifies `Switch` and
+     * fails a Block that renders one without its handler, and a Block ships no
+     * behaviour and so cannot supply one. So a member's action arrives as the caller's
+     * own node, holding the caller's own control and its own handler, and the Block
+     * places it in the member's trailing edge in both arrangements and draws nothing
+     * where it is not passed. Until a directory wants one of these, this is absent and
+     * a member is a name, a role, the tags and a destination.
+     */
+    renderMemberAction?: (member: Directory01Member) => ReactNode;
     /**
      * How the set is drawn.
      *
@@ -311,6 +332,6 @@ export type Directory01Props = {
  * itself is a substring test per member and holds no index of its own, so the client
  * cost is the derivation and not a running loop.
  */
-export declare function Directory01({ eyebrow, title, description, value, onValueChange, label, clearLabel, categories, empty, summary, variant, headingLevel, className, }: Directory01Props): import("react").JSX.Element;
+export declare function Directory01({ eyebrow, title, description, value, onValueChange, label, clearLabel, categories, empty, summary, renderMemberAction, variant, headingLevel, className, }: Directory01Props): import("react").JSX.Element;
 export default Directory01;
 //# sourceMappingURL=directory-01.d.ts.map

package/dist/blocks/directory-01/directory-01.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"directory-01.d.ts","sourceRoot":"","sources":["../../../src/blocks/directory-01/directory-01.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAQtC,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAA;AA4EpC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAA;IACV,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ,+FAA+F;IAC/F,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE;QACP,2EAA2E;QAC3E,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,wDAAwD;QACxD,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;IACD;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAChD,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,0FAA0F;IAC1F,EAAE,EAAE,MAAM,CAAA;IACV,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,sEAAsE;IACtE,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,mFAAmF;IACnF,KAAK,EAAE,SAAS,CAAA;IAChB,kFAAkF;IAClF,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,UAAU,EAAE,mBAAmB,EAAE,CAAA;IACjC;;;;;;;;;;OAUG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAA;IACxC;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,iEAAiE;IACjE,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,aAAa,EACb,KAAK,EACL,UAAU,EACV,UAAU,EACV,KAAK,EACL,OAAO,EACP,OAAiB,EACjB,YAAmB,EACnB,SAAS,GACV,EAAE,gBAAgB,+BAgSlB;AAED,eAAe,WAAW,CAAA"}
+{"version":3,"file":"directory-01.d.ts","sourceRoot":"","sources":["../../../src/blocks/directory-01/directory-01.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAQtC,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAA;AA4EpC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAA;IACV,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ,+FAA+F;IAC/F,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE;QACP,2EAA2E;QAC3E,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,wDAAwD;QACxD,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;IACD;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAChD,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,0FAA0F;IAC1F,EAAE,EAAE,MAAM,CAAA;IACV,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,sEAAsE;IACtE,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,mFAAmF;IACnF,KAAK,EAAE,SAAS,CAAA;IAChB,kFAAkF;IAClF,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,UAAU,EAAE,mBAAmB,EAAE,CAAA;IACjC;;;;;;;;;;OAUG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAA;IACxC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,SAAS,CAAA;IAC7D;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,iEAAiE;IACjE,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,aAAa,EACb,KAAK,EACL,UAAU,EACV,UAAU,EACV,KAAK,EACL,OAAO,EACP,kBAAkB,EAClB,OAAiB,EACjB,YAAmB,EACnB,SAAS,GACV,EAAE,gBAAgB,+BAyTlB;AAED,eAAe,WAAW,CAAA"}

package/dist/blocks/directory-01/directory-01.js

@@ -196,7 +196,7 @@ function assertMembers(members) {
  * itself is a substring test per member and holds no index of its own, so the client
  * cost is the derivation and not a running loop.
  */
-export function Directory01({ eyebrow, title, description, value, onValueChange, label, clearLabel, categories, empty, summary, variant = 'cards', headingLevel = 'h2', className, }) {
+export function Directory01({ eyebrow, title, description, value, onValueChange, label, clearLabel, categories, empty, summary, renderMemberAction, variant = 'cards', headingLevel = 'h2', className, }) {
     // A category's title is a heading one step below the section that introduces the
     // set, and a member's name is a step below that, so a reader who searches a
     // directory and then navigates by heading lands on the team and then on the person
@@ -239,7 +239,7 @@ export function Directory01({ eyebrow, title, description, value, onValueChange,
                     // is one set of elements whichever arrangement is drawn and a consumer
                     // who switches `variant` at render time gets one list in the
                     // accessibility tree rather than two.
-                    asCards ? 'grid items-start gap-6 md:grid-cols-2 lg:grid-cols-3' : null), children: visible.map((category) => (_jsxs("section", { "data-slot": "directory-01-category", "data-category": category.id, "aria-labelledby": `${category.id}-heading`, className: "flex min-w-0 flex-col gap-4", children: [_jsxs("div", { "data-slot": "directory-01-category-head", className: "flex flex-col gap-1.5", children: [_jsx(Title, { id: `${category.id}-heading`, "data-slot": "directory-01-category-title", className: "text-lg font-semibold tracking-tight", children: category.title }), category.description === undefined ? null : (_jsx("p", { "data-slot": "directory-01-category-description", className: "text-muted-foreground text-pretty text-sm", children: category.description }))] }), asCards ? (_jsx("ul", { "data-slot": "directory-01-members", className: "grid gap-4 sm:grid-cols-2", children: category.members.map((member) => (_jsx("li", { "data-slot": "directory-01-card", "data-member": member.id, className: "flex", children: _jsxs(Card, { "data-slot": "directory-01-card-surface", className: "w-full gap-4 py-5", children: [_jsxs(CardHeader, { className: "gap-3", children: [_jsxs("div", { "data-slot": "directory-01-identity", className: "flex min-w-0 gap-3", children: [member.avatar === undefined ? null : (_jsxs(Avatar, { className: "size-10 shrink-0", children: [member.avatar.src === undefined ? null : (_jsx(AvatarImage, { src: member.avatar.src, alt: "" })), _jsx(AvatarFallback, { className: "text-mono", children: initialsOf(member.avatar.name) })] })), _jsxs("div", { className: "flex min-w-0 flex-col gap-0.5", children: [_jsx(CardTitle, { as: Member, "data-slot": "directory-01-name", className: "truncate text-sm leading-snug", children: member.name }), member.role === undefined ? null : (_jsx("span", { "data-slot": "directory-01-role", className: "text-muted-foreground text-xs", children: member.role }))] })] }), member.tags === undefined || member.tags.length === 0 ? null : (_jsx("div", { "data-slot": "directory-01-tags", className: "flex flex-wrap items-center gap-1.5", children: member.tags.map((tag) => (_jsx(Badge, { variant: "secondary", children: tag.label }, tag.id))) }))] }), _jsx(CardFooter, { children: _jsx(CtaLink, { href: member.href, variant: "outline", size: "sm", children: member.hrefLabel }) })] }) }, member.id))) })) : (
+                    asCards ? 'grid items-start gap-6 md:grid-cols-2 lg:grid-cols-3' : null), children: visible.map((category) => (_jsxs("section", { "data-slot": "directory-01-category", "data-category": category.id, "aria-labelledby": `${category.id}-heading`, className: "flex min-w-0 flex-col gap-4", children: [_jsxs("div", { "data-slot": "directory-01-category-head", className: "flex flex-col gap-1.5", children: [_jsx(Title, { id: `${category.id}-heading`, "data-slot": "directory-01-category-title", className: "text-lg font-semibold tracking-tight", children: category.title }), category.description === undefined ? null : (_jsx("p", { "data-slot": "directory-01-category-description", className: "text-muted-foreground text-pretty text-sm", children: category.description }))] }), asCards ? (_jsx("ul", { "data-slot": "directory-01-members", className: "grid gap-4 sm:grid-cols-2", children: category.members.map((member) => (_jsx("li", { "data-slot": "directory-01-card", "data-member": member.id, className: "flex", children: _jsxs(Card, { "data-slot": "directory-01-card-surface", className: "w-full gap-4 py-5", children: [_jsxs(CardHeader, { className: "gap-3", children: [_jsxs("div", { "data-slot": "directory-01-identity", className: "flex min-w-0 gap-3", children: [member.avatar === undefined ? null : (_jsxs(Avatar, { className: "size-10 shrink-0", children: [member.avatar.src === undefined ? null : (_jsx(AvatarImage, { src: member.avatar.src, alt: "" })), _jsx(AvatarFallback, { className: "text-mono", children: initialsOf(member.avatar.name) })] })), _jsxs("div", { className: "flex min-w-0 flex-col gap-0.5", children: [_jsx(CardTitle, { as: Member, "data-slot": "directory-01-name", className: "truncate text-sm leading-snug", children: member.name }), member.role === undefined ? null : (_jsx("span", { "data-slot": "directory-01-role", className: "text-muted-foreground text-xs", children: member.role }))] })] }), member.tags === undefined || member.tags.length === 0 ? null : (_jsx("div", { "data-slot": "directory-01-tags", className: "flex flex-wrap items-center gap-1.5", children: member.tags.map((tag) => (_jsx(Badge, { variant: "secondary", children: tag.label }, tag.id))) }))] }), _jsxs(CardFooter, { className: "gap-2", children: [_jsx(CtaLink, { href: member.href, variant: "outline", size: "sm", children: member.hrefLabel }), renderMemberAction === undefined ? null : (_jsx("span", { "data-slot": "directory-01-member-action", className: "flex items-center", children: renderMemberAction(member) }))] })] }) }, member.id))) })) : (
                             /*
                               * A list rather than a grid of cards, because in this arrangement
                               * the portrait belongs at the leading edge of a line and the badges
@@ -247,6 +247,6 @@ export function Directory01({ eyebrow, title, description, value, onValueChange,
                               * border rather than a gap alone, so the boundary survives at any
                               * zoom level where the gap stops being visible.
                               */
-                            _jsx("ul", { "data-slot": "directory-01-members", className: "border-border flex flex-col border-t", children: category.members.map((member) => (_jsxs("li", { "data-slot": "directory-01-row", "data-member": member.id, className: "border-border flex flex-wrap items-center gap-x-4 gap-y-2 border-b py-4 last:border-b-0", children: [member.avatar === undefined ? null : (_jsxs(Avatar, { className: "size-8 shrink-0", children: [member.avatar.src === undefined ? null : (_jsx(AvatarImage, { src: member.avatar.src, alt: "" })), _jsx(AvatarFallback, { className: "text-mono", children: initialsOf(member.avatar.name) })] })), _jsx(Member, { "data-slot": "directory-01-name", className: "min-w-0 truncate text-sm font-medium", children: member.name }), member.role === undefined ? null : (_jsx("span", { "data-slot": "directory-01-role", className: "text-muted-foreground min-w-0 flex-1 truncate text-sm", children: member.role })), member.tags === undefined || member.tags.length === 0 ? null : (_jsx("span", { "data-slot": "directory-01-tags", className: "flex flex-wrap items-center gap-1.5", children: member.tags.map((tag) => (_jsx(Badge, { variant: "secondary", children: tag.label }, tag.id))) })), _jsx(CtaLink, { href: member.href, variant: "outline", size: "sm", className: "ms-auto shrink-0", children: member.hrefLabel })] }, member.id))) }))] }, category.id))) }))] }) }));
+                            _jsx("ul", { "data-slot": "directory-01-members", className: "border-border flex flex-col border-t", children: category.members.map((member) => (_jsxs("li", { "data-slot": "directory-01-row", "data-member": member.id, className: "border-border flex flex-wrap items-center gap-x-4 gap-y-2 border-b py-4 last:border-b-0", children: [member.avatar === undefined ? null : (_jsxs(Avatar, { className: "size-8 shrink-0", children: [member.avatar.src === undefined ? null : (_jsx(AvatarImage, { src: member.avatar.src, alt: "" })), _jsx(AvatarFallback, { className: "text-mono", children: initialsOf(member.avatar.name) })] })), _jsx(Member, { "data-slot": "directory-01-name", className: "min-w-0 truncate text-sm font-medium", children: member.name }), member.role === undefined ? null : (_jsx("span", { "data-slot": "directory-01-role", className: "text-muted-foreground min-w-0 flex-1 truncate text-sm", children: member.role })), member.tags === undefined || member.tags.length === 0 ? null : (_jsx("span", { "data-slot": "directory-01-tags", className: "flex flex-wrap items-center gap-1.5", children: member.tags.map((tag) => (_jsx(Badge, { variant: "secondary", children: tag.label }, tag.id))) })), _jsx(CtaLink, { href: member.href, variant: "outline", size: "sm", className: "ms-auto shrink-0", children: member.hrefLabel }), renderMemberAction === undefined ? null : (_jsx("span", { "data-slot": "directory-01-member-action", className: "flex shrink-0 items-center", children: renderMemberAction(member) }))] }, member.id))) }))] }, category.id))) }))] }) }));
 }
 export default Directory01;

package/dist/blocks/empty-state-01/empty-state.d.ts

@@ -1,34 +1,55 @@
 import type { ReactNode } from 'react';
 /**
- * The three reasons a region has nothing in it.
+ * The four reasons a region has nothing in it.
  *
- * **Three, and the set is closed because the three want different words and
+ * **Four, and the set is closed at four because the four want different words and
  * different actions, so a consumer who cannot say which one they have writes
  * "No data".** That is the whole failure this Block exists to prevent, and it is
- * a failure rather than a style preference because the three are answers to three
- * different questions and the reader acts on each one differently:
+ * a failure rather than a style preference because all four answer one question
+ * and the reader acts on each answer differently. The question is what happened
+ * to the collection this region would have drawn:
  *
  * - `first-run` - nothing has ever existed here. The reader is not blocked, they
  *   are at the beginning, and the action is to *make the first one*. A sentence
  *   that says nothing is available and an action that creates is the whole state.
- * - `no-match` - things exist and the reader's own filter removed all of them.
+ * - `no-match` - things exist and the reader's own narrowing removed all of them.
  *   The reader is not at the beginning and nothing is missing; the action is to
- *   *widen or clear the filter*, and offering to create something here invents
+ *   *widen or clear the narrowing*, and offering to create something here invents
  *   work the reader does not need.
+ * - `emptied-by-reader` - things existed here and this reader's own earlier action
+ *   moved every one of them out of it. The reader is not at the beginning either,
+ *   and nothing is missing or hidden: this is a bin the reader has just cleared.
+ *   There is no action *in this region*, because a reader who has deleted nothing
+ *   has nothing to restore, and restoring is a per row command and a batch action
+ *   in the surrounding surface, on the caller's own nodes.
  * - `not-permitted` - things exist and this reader may not see them. The action
  *   is to *ask for access or change context*, and a create action here is a lie
  *   about what the reader can do, which is worse than no action at all.
  *
- * A fourth such as `error` or `loading` is deliberately absent: those are states
+ * **Two of the four are the reader's own doing, and a narrowing and a deletion are
+ * not the same doing, so they are two members rather than one.** `no-match` hides
+ * rows out of a set that is still there, so clearing it brings them back;
+ * `emptied-by-reader` is a record that is gone from the live set rather than hidden
+ * in it, and the reader put it there. Every saved view a caller builds out of the
+ * filter values it holds is already `no-match` and wants no member of its own,
+ * because a view that matches nothing is a narrowing that came back empty. A trash
+ * view is the one that differs in kind rather than in content: it is a different
+ * collection the caller chose to fetch rather than a narrowing of this one. So the
+ * two differ in exactly the fact a reader must be told honestly, which is whether
+ * the records are still there behind the narrowing or gone and only the caller can
+ * bring them back. One sentence for both would tell a reader who has deleted
+ * everything that their own search found nothing.
+ *
+ * **A fifth such as `error` or `loading` is deliberately absent:** those are states
  * the surrounding surface already owns, and a region that is erroring has an
  * `Alert` and a region that is loading has a `Spinner`. A Block that drew them
  * would give a consumer two places to put the same fact.
  *
  * @see EMPTY_REASONS
  */
-export declare const EMPTY_REASONS: readonly ["first-run", "no-match", "not-permitted"];
+export declare const EMPTY_REASONS: readonly ["first-run", "no-match", "emptied-by-reader", "not-permitted"];
 /**
- * One of the three reasons a region has nothing in it.
+ * One of the four reasons a region has nothing in it.
  *
  * The reason is a machine value and never reader-facing text. The words are the
  * consumer's: two products call the same state "Nothing here yet" and "Your
@@ -45,12 +66,15 @@ export type EmptyReason = (typeof EMPTY_REASONS)[number];
  */
 export type EmptyState01Props = {
     /**
-     * Which of the three situations this is. Required rather than defaulted,
+     * Which of the four situations this is. Required rather than defaulted,
      * because the default would be the one that hides the bug: a Block that
      * defaulted to `first-run` would render a create action beside a permission
      * boundary, and a Block that defaulted to `no-match` would tell every reader
      * their own filter removed something on their first visit. Making the caller
-     * name the reason is what stops either from happening quietly.
+     * name the reason is what stops either from happening quietly, and it is what
+     * separates the two the reader emptied themselves: passing `no-match` beside a
+     * bin the reader just cleared says their search found nothing in it, which is
+     * false, because nothing there was there to be filtered.
      */
     reason: EmptyReason;
     /**
@@ -69,11 +93,15 @@ export type EmptyState01Props = {
      * The label of the one action, in the product's own words.
      *
      * Optional, and its absence is a legitimate state rather than a gap: a region
-     * a reader cannot act on - a permission boundary, an archived-only view, a
-     * feature that is switched off for their plan - has no next step, and inventing
-     * one is how an empty state ends up offering a reader a button that cannot
-     * help them. `reason` does not require it either, because the same rule applies
-     * across the three: the action exists when the reader has something to do.
+     * a reader cannot act on - a permission boundary, a bin the reader has just
+     * emptied, an archived-only view, a feature that is switched off for their plan
+     * - has no next step *in this region*, and inventing one is how an empty state
+     * ends up offering a reader a button that cannot help them. `reason` does not
+     * require it either, because the same rule applies across the four: the action
+     * exists when the reader has something to do here. For `emptied-by-reader` the
+     * next step is elsewhere by construction, since the records to restore are the
+     * caller's own nodes and their restore command belongs to the index around this
+     * region.
      */
     actionLabel?: string;
     /**
@@ -88,7 +116,7 @@ export type EmptyState01Props = {
      * A slot and not an icon the Block picks, because the mark that means "nothing
      * here yet" and the mark that means "you cannot see this" are different marks,
      * and a Block that chose one would give four products an icon that is wrong for
-     * one of the three reasons. It is `aria-hidden` wherever a consumer puts it: the
+     * one of the four reasons. It is `aria-hidden` wherever a consumer puts it: the
      * reason is carried by the words, and an icon a screen reader reads is a second
      * announcement of the same sentence.
      */
@@ -105,12 +133,13 @@ export type EmptyState01Props = {
  *
  * **The design decision is the `reason` prop, and it is the reason this is a Block
  * rather than a Component.** An empty state looks like one thing, which is why it
- * has been written by hand in every product that has one, and it is actually three
+ * has been written by hand in every product that has one, and it is actually four
  * things that need different words and different actions. A component with a
  * `title` and a `body` and an `action` cannot express the difference, so every
  * consumer re-decides it in their own words and at least one of them gets it
- * wrong: a permission boundary that offers "Create your first project", or a
- * first-run state that says "No results found". Naming the reason forces the
+ * wrong: a permission boundary that offers "Create your first project", a
+ * first-run state that says "No results found", or a bin the reader has just
+ * emptied that says their filter matched nothing. Naming the reason forces the
  * decision into the open and gives the Block something to enforce.
  *
  * **A Block and not a Component because it is a composition of five decisions
@@ -132,7 +161,17 @@ export type EmptyState01Props = {
  * actions is a form, and a form in a region that has nothing in it is a form with
  * nothing to submit. One action is the next step; the rest belong in the
  * surrounding surface, where the reader can see them without this region
- * competing.
+ * competing. `emptied-by-reader` is the case where there is provably no next step
+ * in the region at all, because the records a reader could restore are not in it.
+ *
+ * **All four are statements about a collection, and that is what keeps the fourth
+ * one here rather than beside `NothingChosen01`.** Each answers what happened to
+ * the set this region would have drawn, so the frame the four share stays true of
+ * all four: there is nothing here to read. A bin the reader emptied has no
+ * readable neighbour to make that frame a lie beside it, because everything it
+ * would have drawn is gone. `NothingChosen01` is the opposite claim in a region
+ * whose records are all still there, which is why it is a Block of its own and
+ * not a fifth reason here; `DESIGN.md` holds that argument in full.
  *
  * It is a server Component. It holds no state and imports no client code, so a
  * consumer that passes a client action inside it pays for the action and not for

package/dist/blocks/empty-state-01/empty-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"empty-state.d.ts","sourceRoot":"","sources":["../../../src/blocks/empty-state-01/empty-state.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,aAAa,qDAAsD,CAAA;AAEhF;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAuBxD;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;OAOG;IACH,MAAM,EAAE,WAAW,CAAA;IACnB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,KAAK,EACL,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,IAAI,EACJ,SAAS,GACV,EAAE,iBAAiB,+BAoEnB;AAED,eAAe,YAAY,CAAA"}
+{"version":3,"file":"empty-state.d.ts","sourceRoot":"","sources":["../../../src/blocks/empty-state-01/empty-state.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,aAAa,0EAA2E,CAAA;AAErG;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AA0BxD;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;;;;OAUG;IACH,MAAM,EAAE,WAAW,CAAA;IACnB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,KAAK,EACL,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,IAAI,EACJ,SAAS,GACV,EAAE,iBAAiB,+BAoEnB;AAED,eAAe,YAAY,CAAA"}