@entifix/react-controls 0.19.0 → 0.20.0

package/dist/ui/organisms/entity-table/entity-table.js

@@ -1,48 +1,34 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { emptySelection, extractMetaEntity, hierarchyOf, isSelected, selectionSize, toggleSelected } from '@entifix/core';
-import { Fragment, useMemo, useRef, useState } from 'react';
-import { useErrorMessage, useT, useTranslateKey } from '../../../i18n/index.js';
-import { OVERFLOW_GLYPH, renderAnchor, useCasesForSurface } from '../../actions/index.js';
-import { Button } from '../../atoms/button/index.js';
+import { emptySelection, extractMetaEntity, hierarchyOf, isSelected, queryPropertyFor, selectionSize, toggleSelected } from '@entifix/core';
+import { Fragment, useId, useMemo, useRef, useState } from 'react';
+import { useEntityNoun, useLocale, useT, useTranslateKey } from '../../../i18n/index.js';
+import { renderAnchor, useCasesForSurface } from '../../actions/index.js';
+import { useVerbInvoker } from '../../actions/use-verb-invoker.js';
+import { Button, button } from '../../atoms/button/index.js';
 import { CellValue } from '../../atoms/cell-value/index.js';
 import { Checkbox } from '../../atoms/field/index.js';
 import { Skeleton } from '../../atoms/skeleton/index.js';
 import { Table, TableBody, TableCell, TableHead, TableHeaderCell, TableMessageRow, TableRow } from '../../atoms/table/index.js';
 import { linkClassName } from '../../atoms/text/index.js';
+import { ActionBar, itemsForUseCases } from '../../molecules/action-bar/index.js';
 import { BulkActionBar } from '../../molecules/bulk-action-bar/index.js';
 import { BulkResult } from '../../molecules/bulk-result/index.js';
 import { ColumnSettings } from '../../molecules/column-settings/index.js';
-import { ConfirmDialog } from '../../molecules/confirm-dialog/index.js';
 import { EntityRecordCard } from '../../molecules/entity-record-card/index.js';
 import { FilterBuilder } from '../../molecules/filter-builder/index.js';
+import { FilterChips } from '../../molecules/filter-chips/index.js';
 import { LoadingBoundary } from '../../molecules/loading-boundary/index.js';
-import { Menu } from '../../molecules/menu/index.js';
 import { Pagination } from '../../molecules/pagination/index.js';
+import { RegionState } from '../../molecules/region-state/index.js';
 import { SortBuilder } from '../../molecules/sort-builder/index.js';
 import { TableToolbar } from '../../molecules/table-toolbar/index.js';
 import { readEntityTableSlots } from './entity-table-slots.js';
 import { shownTreeRows, TreeCell, treeRows } from './entity-table-tree.js';
+import { nextHeaderSorting, sortKeys } from './header-sort.js';
+import { ACTIONS_WIDTH, pivotClasses, pivotWidth, SELECTION_WIDTH } from './pivot.js';
 import { useEntityTableColumns } from './use-entity-table-columns.js';
-/**
- * The grid and the card list are both rendered, and CSS picks one. A JS
- * breakpoint hook would have to guess during SSR and correct after mount —
- * a hydration mismatch on every page load. Classes are written out in full
- * because Tailwind cannot see a class name that is concatenated at runtime.
- */ const PIVOT_CLASS = {
-    sm: {
-        grid: 'hidden sm:block',
-        cards: 'sm:hidden'
-    },
-    md: {
-        grid: 'hidden md:block',
-        cards: 'md:hidden'
-    },
-    lg: {
-        grid: 'hidden lg:block',
-        cards: 'lg:hidden'
-    }
-};
+import { useResultAnnouncement } from './use-result-announcement.js';
 /**
  * How many placeholder rows the built-in skeleton draws.
  *
@@ -51,36 +37,18 @@ import { useEntityTableColumns } from './use-entity-table-columns.js';
  * a fifty-row page would otherwise paint fifty shimmer rows to stand in for
  * content that arrives below the fold anyway.
  */ const SKELETON_ROW_CAP = 5;
-export function EntityTable({ entityConstructor, isLoading, skeleton = true, error, items, totalItems, currentPage, pageSize, onPageChange, onPageSizeChange, hrefFor, newHref, renderLink = renderAnchor, onSelect, preferencesKey, showControls = true, pivotBreakpoint = 'md', filtering, sorting, onFilteringChange, onSortingChange, selection, onSelectionChange, metadata, isMetadataLoading = false, onBulkUseCase, onUseCase, bulkOutcomes, onBulkDismiss, onBulkRetry, isBulkRunning = false, children }) {
-    var _ref;
+/** How many members a card shows as meta when none declares a `card` role. */ const UNDECLARED_META_CAP = 3;
+export function EntityTable({ entityConstructor, isLoading, skeleton = true, error, items, totalItems, currentPage, pageSize, onPageChange, onPageSizeChange, hrefFor, newHref, renderLink = renderAnchor, onSelect, preferencesKey, showControls = true, pivotBreakpoint, filtering, sorting, onFilteringChange, onSortingChange, facets, selection, onSelectionChange, metadata, isMetadataLoading = false, onBulkUseCase, onUseCase, onRetry, bulkOutcomes, onBulkDismiss, onBulkRetry, isBulkRunning = false, children }) {
+    var _ref, _ref1;
     const t = useT();
     // A descriptor's label is a runtime catalog key — the typed gate cannot see
     // it, which is why a host's catalog check is what catches a typo.
     const translateKey = useTranslateKey();
-    const errorMessage = useErrorMessage();
+    const entityNoun = useEntityNoun();
     const metaEntity = extractMetaEntity(entityConstructor);
     const slots = readEntityTableSlots(children);
     const [panel, setPanel] = useState('none');
-    /**
-   * A verb waiting to be confirmed, and what it will act on.
-   *
-   * ⚠️ **The table had no confirmation flow at all** until a change moved a
-   * destructive verb onto it. It read `confirm.tone` — only to pick a tone for
-   * a button or a menu item — and then fired on the first click. `unpublish` is
-   * declared `destructive`, so a verb reachable from a row menu without this
-   * would have been a one-click unpublish with a red label explaining what had
-   * already happened.
-   *
-   * The state holds the confirmation itself rather than the descriptor, so the
-   * dialog cannot open for a verb that never asked for one — the same shape
-   * `EntityForm` uses, and for the same reason.
-   *
-   * It carries the **target** too, which the form's does not need: a form has
-   * one record and a table has a row or a selection, and those run through two
-   * different handlers with two different payloads.
-   */ const [pending, setPending] = useState(undefined);
     const { columns, visibleColumns, hidden, setPersonalization } = useEntityTableColumns(entityConstructor, slots.columns, items[0], `entity-table:${(_ref = preferencesKey != null ? preferencesKey : metaEntity.key) != null ? _ref : metaEntity.name}`);
-    const pivot = PIVOT_CLASS[pivotBreakpoint];
     // A picker's table is choosing *one* value; a multi-selection there would
     // offer a set to a form member that holds a single reference, and the two
     // controls would fight over the same row. This is a wiring mistake rather
@@ -116,30 +84,91 @@ export function EntityTable({ entityConstructor, isLoading, skeleton = true, err
         total: totalItems,
         excluded: new Set()
     };
-    const hasRowAction = onSelect !== undefined || hrefFor !== undefined || hasRowMenu;
+    // Opening a record is its title's link, so a row needs an actions column
+    // only to pick it or to run a verb on it.
+    const hasRowAction = onSelect !== undefined || hasRowMenu;
     const columnCount = visibleColumns.length + (hasRowAction ? 1 : 0) + (selectable ? 1 : 0);
     /**
+   * The grid and the cards are both rendered, and a container query on the
+   * table's own box picks one — at the width its visible columns need. A
+   * viewport breakpoint was wrong inside a split view, a drawer or a wizard
+   * step, and a JS measurement would guess during SSR and correct after mount.
+   */ const pivot = pivotClasses(pivotWidth(visibleColumns, (selectable ? SELECTION_WIDTH : 0) + (hasRowAction ? ACTIONS_WIDTH : 0), pivotBreakpoint));
+    /**
    * The first load has nothing to show and is held with a skeleton; a refetch
    * already has rows, so it keeps them and only marks the region busy. Splitting
    * the two is what stops every pagination click flashing grey.
    */ const isFirstLoad = isLoading && items.length === 0;
-    const isRefetching = isLoading && items.length > 0;
     /** `true`/omitted → the built-in default; a node → that node; `false` → none. */ const customSkeleton = typeof skeleton === 'boolean' ? undefined : skeleton;
     const showSkeleton = isFirstLoad && skeleton !== false;
     const skeletonRows = Array.from({
         length: Math.min(pageSize, SKELETON_ROW_CAP)
     }, (_, index)=>index);
     /**
-   * The refetch hint, and it is deliberately the only one: rows stay readable
-   * and simply dim, because a second skeleton over live data would be two
-   * loading signals in one region.
-   */ const busyClass = isRefetching ? 'opacity-60 transition-opacity duration-200 ease-smooth' : '';
-    const renderCell = (column, item)=>column.render ? column.render(item) : /*#__PURE__*/ _jsx(CellValue, {
+   * A refetch keeps its rows at full contrast and marks them `aria-busy`:
+   * dimming them through opacity took the text under the contrast a reader
+   * needs, on every page change.
+   */ const busy = isLoading || undefined;
+    /** The column a row reads *as*: the first non-identifier one it filled in. */ const titleColumn = (item)=>visibleColumns.find((column)=>{
+            if (column.type === 'id') return false;
+            const value = item[column.name];
+            return value != null && String(value) !== '';
+        });
+    /** The column that links to the record: one declared `card: 'title'`, else the row's title. */ const declaredTitle = visibleColumns.find((column)=>column.card === 'title');
+    const linkColumn = (item)=>declaredTitle != null ? declaredTitle : titleColumn(item);
+    /**
+   * What a record's card shows, by each member's declared `card` role or the
+   * default: an id is hidden, the first enum is the badge, and up to
+   * {@link UNDECLARED_META_CAP} more members are meta — a card is a summary,
+   * and the grid holds the rest.
+   */ const firstEnum = visibleColumns.find((column)=>column.card === undefined && column.type === 'enum');
+    const roleOf = (column)=>{
+        var _column_card;
+        return (_column_card = column.card) != null ? _column_card : column.type === 'id' ? 'hidden' : column === firstEnum ? 'badge' : 'meta';
+    };
+    const cardParts = (item)=>{
+        const title = linkColumn(item);
+        const rest = visibleColumns.filter((column)=>column !== title);
+        let undeclared = 0;
+        return {
+            title,
+            subtitle: rest.find((column)=>roleOf(column) === 'subtitle'),
+            badges: rest.filter((column)=>roleOf(column) === 'badge'),
+            meta: rest.filter((column)=>{
+                if (roleOf(column) !== 'meta') return false;
+                if (column.card !== undefined) return true;
+                undeclared += 1;
+                return undeclared <= UNDECLARED_META_CAP;
+            })
+        };
+    };
+    const renderValue = (column, item)=>column.render ? column.render(item) : /*#__PURE__*/ _jsx(CellValue, {
             value: item[column.name],
             descriptor: column,
             record: item
         });
     /**
+   * A cell, and the row's title cell is the record's link
+   * ([ADR 0026](../../../../../../../docs/adr/0026-actions-hierarchy-overflow-and-destructive-verbs.md)).
+   * A column of identical "Open" links named nothing, and a reader tabbing
+   * down it heard "Open" once per row; the title says which record it opens.
+   * A picker's rows are chosen, not opened, so they stay plain.
+   */ const renderCell = (column, item)=>{
+        var _linkColumn;
+        const value = renderValue(column, item);
+        if (hrefFor === undefined || onSelect !== undefined) return value;
+        if (((_linkColumn = linkColumn(item)) == null ? void 0 : _linkColumn.name) !== column.name) return value;
+        return renderLink({
+            href: hrefFor(item.id),
+            className: linkClassName,
+            children: value,
+            intent: {
+                kind: 'open',
+                id: item.id
+            }
+        });
+    };
+    /**
    * The row a shift-click ranges *from* — the last box the user actually
    * toggled. Held in a ref rather than state because it changes nothing on
    * screen, and re-rendering the whole table on every click to remember an
@@ -220,11 +249,7 @@ export function EntityTable({ entityConstructor, isLoading, skeleton = true, err
         //
         // The id remains the last resort, because a row with nothing rendered
         // still has to announce itself.
-        const named = visibleColumns.find((column)=>{
-            if (column.type === 'id') return false;
-            const value = item[column.name];
-            return value != null && String(value) !== '';
-        });
+        const named = titleColumn(item);
         return named ? String(item[named.name]) : String(item.id);
     };
     const selectionCell = (item, index, // Passed in rather than closed over: this is only ever called under
@@ -245,113 +270,196 @@ export function EntityTable({ entityConstructor, isLoading, skeleton = true, err
         if (target.kind === 'row') onUseCase == null ? void 0 : onUseCase(key, target.item);
         else onBulkUseCase == null ? void 0 : onBulkUseCase(key, target.selection);
     };
+    /**
+   * Every verb on the table goes through here — the row menu, the bulk bar and
+   * the toolbar — so none reaches a destructive verb around its confirmation,
+   * its typed check or its Undo.
+   */ const verbs = useVerbInvoker({
+        run: runTarget,
+        busy: isBulkRunning,
+        served: metadata == null ? void 0 : metadata.useCases
+    });
     const invoke = (useCase, target)=>{
-        const confirm = useCase.confirm;
-        if (confirm) {
-            setPending({
-                key: useCase.key,
-                labelKey: useCase.labelKey,
-                confirm,
-                target
+        if (target.kind === 'row') {
+            verbs.invoke({
+                descriptor: useCase,
+                target,
+                object: rowLabel(target.item),
+                count: 1
             });
             return;
         }
-        runTarget(useCase.key, target);
+        const count = selectionSize(target.selection);
+        verbs.invoke({
+            descriptor: useCase,
+            target,
+            object: t('confirm.selection', {
+                count,
+                label: entityNoun(metaEntity),
+                plural: entityNoun(metaEntity, 'plural')
+            }),
+            count,
+            matching: target.selection.mode === 'matching'
+        });
     };
-    const rowMenu = (item)=>hasRowMenu ? /*#__PURE__*/ _jsxs(Menu, {
-            children: [
-                /*#__PURE__*/ _jsx(Menu.Trigger, {
-                    "aria-label": t('table.actions'),
-                    children: OVERFLOW_GLYPH
-                }),
-                /*#__PURE__*/ _jsx(Menu.Items, {
-                    children: rowUseCases.map((useCase)=>{
-                        var _useCase_confirm;
-                        return /*#__PURE__*/ _jsx(Menu.Item, {
-                            tone: ((_useCase_confirm = useCase.confirm) == null ? void 0 : _useCase_confirm.tone) === 'destructive' ? 'destructive' : 'neutral',
-                            onClick: ()=>invoke(useCase, {
-                                    kind: 'row',
-                                    item
-                                }),
-                            children: translateKey(useCase.labelKey)
-                        }, useCase.key);
-                    })
-                })
-            ]
+    const rowMenu = (item)=>hasRowMenu ? /*#__PURE__*/ _jsx(ActionBar, {
+            surface: "row-menu",
+            menuLabel: t('actions.forRecord', {
+                record: rowLabel(item)
+            }),
+            items: itemsForUseCases(rowUseCases, translateKey, (useCase)=>invoke(useCase, {
+                    kind: 'row',
+                    item
+                }))
         }) : undefined;
     /**
-   * Selection wins over navigation: a picker's row must set the value, not send
-   * the user away from the form they came from.
-   *
-   * The row menu sits *beside* whichever of the two applies rather than
-   * replacing it — "open this record" and "run a verb on it" are both true at
-   * once, and folding the first into the menu would bury the action every row
-   * of a list exists for.
+   * A picker's Select, then the row's verbs. Opening the record is not here:
+   * it is the title's link.
    */ const recordAction = (item)=>{
-        const primary = onSelect ? /*#__PURE__*/ _jsx(Button, {
+        const pick = onSelect ? /*#__PURE__*/ _jsx(Button, {
             type: "button",
             variant: "secondary",
             size: "sm",
             onClick: ()=>onSelect(item),
             children: t('table.select')
-        }) : hrefFor ? renderLink({
-            href: hrefFor(item.id),
-            className: linkClassName,
-            children: t('table.open'),
-            intent: {
-                kind: 'open',
-                id: item.id
-            }
         }) : undefined;
         const menu = rowMenu(item);
-        if (!menu) return primary;
+        if (!menu) return pick;
         return /*#__PURE__*/ _jsxs("span", {
             className: "flex items-center gap-2xs",
             children: [
-                primary,
+                pick,
                 menu
             ]
         });
     };
     /**
-   * "No records" is a statement about the data; after a failed load it would be
-   * a lie about it. The distinction matters most to the user who is deciding
-   * whether their catalog is empty or their backend is down.
-   */ const emptyMessage = error ? t('table.error') : t('table.empty');
+   * "New" is the list's primary, and only where something can be created
+   * here: the entity is not one only a flow writes (`creatable: false`), and
+   * the caller may write it. A list that offered "New" to a reader who could
+   * never save opened a form with no Save on it.
+   */ const mayCreate = newHref !== undefined && metaEntity.creatable && (metadata === undefined || metadata.actions.includes('write'));
+    const toolbarItems = itemsForUseCases(toolbarUseCases, translateKey, (useCase)=>invoke(useCase, {
+            kind: 'selection',
+            selection: everythingMatching
+        }), isBulkRunning);
+    const declaresToolbarPrimary = toolbarItems.some((item)=>item.emphasis === 'primary');
+    const toolbarActions = [
+        ...mayCreate ? [
+            {
+                key: 'new',
+                label: t('table.new'),
+                emphasis: declaresToolbarPrimary ? 'default' : 'primary',
+                href: newHref,
+                intent: {
+                    kind: 'new'
+                }
+            }
+        ] : [],
+        ...toolbarItems
+    ];
+    const locale = useLocale();
+    const panelId = useId();
+    const keys = sortKeys(sorting, columns);
+    const activeFilters = (_ref1 = filtering == null ? void 0 : filtering.values.length) != null ? _ref1 : 0;
+    const results = t('table.results', {
+        count: totalItems
+    });
+    /**
+   * What the status region says once a filter, a sort or a page has settled —
+   * debounced, and silent on the first load.
+   */ const announcement = useResultAnnouncement(!isLoading, totalItems === 0 && activeFilters > 0 ? t('table.noResultsFiltered') : results, JSON.stringify([
+        filtering,
+        sorting,
+        currentPage,
+        pageSize
+    ]));
+    /** The caption: what the table holds, how many, and in what order. */ const primaryKey = keys[0];
+    const primaryColumn = primaryKey === undefined ? undefined : columns.find((column)=>column.name === primaryKey.member);
+    const caption = primaryKey === undefined || primaryColumn === undefined ? t('table.caption', {
+        entity: entityNoun(metaEntity, 'plural'),
+        results
+    }) : t('table.captionSorted', {
+        entity: entityNoun(metaEntity, 'plural'),
+        results,
+        column: primaryColumn.label,
+        direction: t(primaryKey.type === 'asc' ? 'sort.ascending' : 'sort.descending')
+    });
+    /**
+   * A column's header: its name, and — for a sortable one — a button that
+   * cycles it ascending → descending → unsorted, with Shift adding it as the
+   * next key. Only the primary key carries `aria-sort`.
+   */ const headerCell = (column)=>{
+        var _column_header;
+        var _keys_position;
+        const label = (_column_header = column.header) != null ? _column_header : column.label;
+        if (!column.sortable || onSortingChange === undefined) return /*#__PURE__*/ _jsx(TableHeaderCell, {
+            children: label
+        }, column.name);
+        const position = keys.findIndex((key)=>key.member === column.name);
+        const type = (_keys_position = keys[position]) == null ? void 0 : _keys_position.type;
+        return /*#__PURE__*/ _jsx(TableHeaderCell, {
+            "aria-sort": position === 0 ? type === 'asc' ? 'ascending' : 'descending' : undefined,
+            children: /*#__PURE__*/ _jsxs("button", {
+                type: "button",
+                className: "inline-flex min-h-(--target-min) items-center gap-3xs rounded-sm focus-ring hover:text-content",
+                onClick: (event)=>onSortingChange(nextHeaderSorting(keys, {
+                        member: column.name,
+                        property: queryPropertyFor(column, locale)
+                    }, event.shiftKey)),
+                children: [
+                    label,
+                    /*#__PURE__*/ _jsx("span", {
+                        "aria-hidden": "true",
+                        children: type === 'asc' ? '▲' : type === 'desc' ? '▼' : '↕'
+                    }),
+                    keys.length > 1 && position >= 0 && /*#__PURE__*/ _jsx("span", {
+                        "aria-hidden": "true",
+                        className: "text-step-sm",
+                        children: position + 1
+                    })
+                ]
+            })
+        }, column.name);
+    };
+    /** A panel toggle: its state said by `aria-expanded`, and its count shown. */ const panelToggle = (which, count)=>/*#__PURE__*/ _jsxs(Button, {
+            type: "button",
+            variant: panel === which ? 'primary' : 'secondary',
+            size: "sm",
+            "aria-expanded": panel === which,
+            "aria-controls": panelId,
+            onClick: ()=>setPanel((current)=>current === which ? 'none' : which),
+            children: [
+                t(which === 'filters' ? 'table.filters' : 'table.sorting'),
+                count > 0 && // Its name stays "Filters": the chips say which filters, and a count
+                // in the name would change it under the reader with every filter.
+                /*#__PURE__*/ _jsx("span", {
+                    "aria-hidden": "true",
+                    className: "ms-3xs rounded-full bg-surface px-3xs text-step-sm text-content",
+                    children: count
+                })
+            ]
+        });
     return /*#__PURE__*/ _jsxs("div", {
-        className: "flex flex-col gap-s",
+        className: "@container/entity-table flex flex-col gap-s",
         children: [
             /*#__PURE__*/ _jsx("span", {
                 role: "status",
                 "aria-live": "polite",
                 className: "sr-only",
-                children: isFirstLoad ? t('table.loading') : ''
+                children: isFirstLoad ? t('table.loading') : announcement
             }),
             showControls && /*#__PURE__*/ _jsx(TableToolbar, {
                 start: /*#__PURE__*/ _jsxs(_Fragment, {
                     children: [
-                        newHref && renderLink({
-                            href: newHref,
-                            className: linkClassName,
-                            children: t('table.new'),
-                            intent: {
-                                kind: 'new'
-                            }
-                        }),
                         /*#__PURE__*/ _jsx(LoadingBoundary, {
                             isLoading: isMetadataLoading,
                             lines: 0,
                             children: /*#__PURE__*/ _jsx(_Fragment, {
-                                children: toolbarUseCases.map((useCase)=>{
-                                    var _useCase_confirm;
-                                    return /*#__PURE__*/ _jsx(Button, {
-                                        type: "button",
-                                        variant: ((_useCase_confirm = useCase.confirm) == null ? void 0 : _useCase_confirm.tone) === 'destructive' ? 'destructive' : 'secondary',
-                                        size: "sm",
-                                        disabled: isBulkRunning,
-                                        onClick: ()=>onBulkUseCase == null ? void 0 : onBulkUseCase(useCase.key, everythingMatching),
-                                        children: translateKey(useCase.labelKey)
-                                    }, useCase.key);
+                                children: toolbarActions.length > 0 && /*#__PURE__*/ _jsx(ActionBar, {
+                                    surface: "table-toolbar",
+                                    items: toolbarActions,
+                                    renderLink: renderLink
                                 })
                             })
                         }),
@@ -360,20 +468,8 @@ export function EntityTable({ entityConstructor, isLoading, skeleton = true, err
                 }),
                 end: /*#__PURE__*/ _jsxs(_Fragment, {
                     children: [
-                        /*#__PURE__*/ _jsx(Button, {
-                            type: "button",
-                            variant: panel === 'filters' ? 'primary' : 'secondary',
-                            size: "sm",
-                            onClick: ()=>setPanel((current)=>current === 'filters' ? 'none' : 'filters'),
-                            children: t('table.filters')
-                        }),
-                        /*#__PURE__*/ _jsx(Button, {
-                            type: "button",
-                            variant: panel === 'sorting' ? 'primary' : 'secondary',
-                            size: "sm",
-                            onClick: ()=>setPanel((current)=>current === 'sorting' ? 'none' : 'sorting'),
-                            children: t('table.sorting')
-                        }),
+                        panelToggle('filters', activeFilters),
+                        panelToggle('sorting', keys.length),
                         /*#__PURE__*/ _jsx(ColumnSettings, {
                             columns: columns,
                             hidden: hidden,
@@ -381,16 +477,23 @@ export function EntityTable({ entityConstructor, isLoading, skeleton = true, err
                         })
                     ]
                 }),
+                panelId: panelId,
                 panel: panel === 'filters' ? /*#__PURE__*/ _jsx(FilterBuilder, {
                     descriptors: columns.filter((column)=>column.filterable),
+                    facets: facets,
                     value: filtering,
                     onChange: (applied)=>onFilteringChange == null ? void 0 : onFilteringChange(applied)
-                }) : panel === 'sorting' ? /*#__PURE__*/ _jsx(SortBuilder, {
+                }, JSON.stringify(filtering != null ? filtering : null)) : panel === 'sorting' ? /*#__PURE__*/ _jsx(SortBuilder, {
                     descriptors: columns.filter((column)=>column.sortable),
                     value: sorting,
                     onChange: (applied)=>onSortingChange == null ? void 0 : onSortingChange(applied)
                 }) : undefined
             }),
+            showControls && onFilteringChange !== undefined && /*#__PURE__*/ _jsx(FilterChips, {
+                descriptors: columns.filter((column)=>column.filterable),
+                value: filtering,
+                onChange: onFilteringChange
+            }),
             selectionState && selectionSize(selectionState) > 0 && /*#__PURE__*/ _jsx(BulkActionBar, {
                 count: selectionSize(selectionState),
                 useCases: bulkUseCases,
@@ -405,19 +508,7 @@ export function EntityTable({ entityConstructor, isLoading, skeleton = true, err
                         selection: selectionState
                     })
             }),
-            pending && /*#__PURE__*/ _jsx(ConfirmDialog, {
-                open: true,
-                tone: pending.confirm.tone,
-                title: translateKey(pending.labelKey),
-                message: translateKey(pending.confirm.messageKey),
-                busy: isBulkRunning,
-                onCancel: ()=>setPending(undefined),
-                onConfirm: ()=>{
-                    const { key, target } = pending;
-                    setPending(undefined);
-                    runTarget(key, target);
-                }
-            }),
+            verbs.dialog,
             bulkOutcomes && bulkOutcomes.length > 0 && onBulkDismiss && /*#__PURE__*/ _jsx(BulkResult, {
                 outcomes: bulkOutcomes,
                 busy: isBulkRunning,
@@ -428,15 +519,37 @@ export function EntityTable({ entityConstructor, isLoading, skeleton = true, err
                 onRetryFailed: onBulkRetry,
                 onDismiss: onBulkDismiss
             }),
-            error && /*#__PURE__*/ _jsx("p", {
-                role: "alert",
-                "data-testid": "entity-table-error",
-                className: "rounded-sm border border-danger bg-danger-subtle px-s py-2xs text-step-sm text-danger",
-                children: errorMessage(error)
+            /*#__PURE__*/ _jsx(RegionState, {
+                plural: entityNoun(metaEntity, 'plural'),
+                isLoading: isLoading,
+                error: error,
+                onRetry: onRetry,
+                hasStaleData: items.length > 0,
+                isEmpty: items.length === 0,
+                isFiltered: activeFilters > 0,
+                onClearFilters: onFilteringChange === undefined ? undefined : ()=>onFilteringChange({
+                        // Only offered under a filter, so there is one to keep the
+                        // logic of.
+                        operator: filtering.operator,
+                        values: []
+                    }),
+                emptyAction: mayCreate ? renderLink({
+                    href: newHref,
+                    className: button({
+                        variant: 'primary'
+                    }),
+                    children: t('table.new'),
+                    intent: {
+                        kind: 'new'
+                    }
+                }) : undefined
             }),
             /*#__PURE__*/ _jsx("div", {
-                className: `${pivot.grid} ${busyClass}`,
+                className: pivot.grid,
+                "aria-busy": busy,
                 children: /*#__PURE__*/ _jsxs(Table, {
+                    caption: caption,
+                    containerClassName: "max-h-(--table-max-block) scroll-pt-12",
                     children: [
                         /*#__PURE__*/ _jsx(TableHead, {
                             children: slots.header ? slots.header.render(visibleColumns) : /*#__PURE__*/ _jsxs("tr", {
@@ -450,12 +563,7 @@ export function EntityTable({ entityConstructor, isLoading, skeleton = true, err
                                             onChange: (event)=>toggleAllOnPage(event.currentTarget.checked, selectionState)
                                         })
                                     }),
-                                    visibleColumns.map((column)=>{
-                                        var _column_header;
-                                        return /*#__PURE__*/ _jsx(TableHeaderCell, {
-                                            children: (_column_header = column.header) != null ? _column_header : column.label
-                                        }, column.name);
-                                    }),
+                                    visibleColumns.map(headerCell),
                                     hasRowAction && /*#__PURE__*/ _jsx(TableHeaderCell, {
                                         children: t('table.actions')
                                     })
@@ -463,7 +571,6 @@ export function EntityTable({ entityConstructor, isLoading, skeleton = true, err
                             })
                         }),
                         /*#__PURE__*/ _jsxs(TableBody, {
-                            "aria-busy": isLoading || undefined,
                             children: [
                                 showSkeleton && (customSkeleton ? /*#__PURE__*/ _jsx(TableMessageRow, {
                                     colSpan: columnCount,
@@ -490,10 +597,6 @@ export function EntityTable({ entityConstructor, isLoading, skeleton = true, err
                                             })
                                         ]
                                     }, row))),
-                                !isLoading && items.length === 0 && /*#__PURE__*/ _jsx(TableMessageRow, {
-                                    colSpan: columnCount,
-                                    children: emptyMessage
-                                }),
                                 shown.map(({ item, depth, hasChildren }, index)=>{
                                     var _item_id, _item_id1;
                                     return slots.row ? // A Fragment carries the key without wrapping the custom row in
@@ -529,30 +632,62 @@ export function EntityTable({ entityConstructor, isLoading, skeleton = true, err
                 })
             }),
             /*#__PURE__*/ _jsxs("div", {
-                className: `${pivot.cards} flex flex-col gap-2xs ${busyClass}`,
-                "aria-busy": isLoading || undefined,
+                className: pivot.cards,
+                "aria-busy": busy,
                 children: [
-                    showSkeleton && (customSkeleton != null ? customSkeleton : skeletonRows.map((row)=>/*#__PURE__*/ _jsx(EntityRecordCard, {
-                            columns: visibleColumns,
-                            renderCell: ()=>/*#__PURE__*/ _jsx(Skeleton, {
-                                    shape: "line",
-                                    className: "w-24"
+                    showSkeleton && (customSkeleton != null ? customSkeleton : /*#__PURE__*/ _jsx("ul", {
+                        role: "list",
+                        className: "m-0 p-0 flex list-none flex-col gap-2xs",
+                        children: skeletonRows.map((row)=>/*#__PURE__*/ _jsx("li", {
+                                children: /*#__PURE__*/ _jsx(EntityRecordCard, {
+                                    title: /*#__PURE__*/ _jsx(Skeleton, {
+                                        shape: "line",
+                                        className: "w-32"
+                                    }),
+                                    meta: visibleColumns.slice(1).map((column)=>({
+                                            key: column.name,
+                                            label: column.label,
+                                            value: /*#__PURE__*/ _jsx(Skeleton, {
+                                                shape: "line",
+                                                className: "w-24"
+                                            })
+                                        }))
                                 })
-                        }, row))),
-                    !isLoading && items.length === 0 && /*#__PURE__*/ _jsx("p", {
-                        className: "text-step-sm text-content-muted",
-                        children: emptyMessage
-                    }),
-                    shown.map(({ item }, index)=>{
-                        var _item_id;
-                        return /*#__PURE__*/ _jsx(EntityRecordCard, {
-                            columns: visibleColumns,
-                            // The card is handed the resolved columns themselves, so the
-                            // narrow layout goes through the exact same renderers as the grid.
-                            renderCell: (column)=>renderCell(column, item),
-                            leading: selectionState ? selectionCell(item, index, selectionState) : undefined,
-                            actions: recordAction(item)
-                        }, String((_item_id = item.id) != null ? _item_id : index));
+                            }, row))
+                    })),
+                    shown.length > 0 && /*#__PURE__*/ _jsx("ul", {
+                        role: "list",
+                        className: "m-0 p-0 flex list-none flex-col gap-2xs",
+                        children: shown.map(({ item, depth }, index)=>{
+                            var _item_id;
+                            const parts = cardParts(item);
+                            return /*#__PURE__*/ _jsx("li", {
+                                // A tree's card says how deep it sits, as its row does.
+                                "aria-level": treeKeys === undefined ? undefined : depth + 1,
+                                style: treeKeys === undefined ? undefined : {
+                                    marginInlineStart: `${depth * 1.5}rem`
+                                },
+                                children: /*#__PURE__*/ _jsx(EntityRecordCard, {
+                                    // The same renderers as the grid, so the two layouts agree.
+                                    title: parts.title === undefined ? rowLabel(item) : renderCell(parts.title, item),
+                                    subtitle: parts.subtitle === undefined ? undefined : renderCell(parts.subtitle, item),
+                                    badges: parts.badges.map((column)=>({
+                                            key: column.name,
+                                            value: renderCell(column, item)
+                                        })),
+                                    meta: parts.meta.map((column)=>{
+                                        var _column_header;
+                                        return {
+                                            key: column.name,
+                                            label: (_column_header = column.header) != null ? _column_header : column.label,
+                                            value: renderCell(column, item)
+                                        };
+                                    }),
+                                    leading: selectionState ? selectionCell(item, index, selectionState) : undefined,
+                                    actions: recordAction(item)
+                                })
+                            }, String((_item_id = item.id) != null ? _item_id : index));
+                        })
                     })
                 ]
             }),