@gntik-ai/blocks 0.0.0-stage → 0.6.0

package/src/tables/DataTable/DataTable.tsx

@@ -0,0 +1,531 @@
+import {
+  Checkbox,
+  cn,
+  DensityProvider,
+  Table,
+  TableCaption,
+  TableHead,
+  TableHeader,
+  TableRow,
+  type TableDensity,
+  useDensity,
+  useI18n,
+} from '@gntik-ai/ui';
+import { useId, useRef, useState } from 'react';
+import { PaginationFooter } from '../PaginationFooter/PaginationFooter';
+import { ColumnVisibilityMenu } from './column-menu';
+import {
+  clampColumnWidth,
+  columnWidthOf,
+  orderColumns,
+  pinSideOf,
+  setColumnPin,
+  stickyTint,
+  tableLayout,
+  widthBounds,
+  type ColumnWidths,
+  type PinnedColumns,
+} from './column-sizing';
+import { DataTableBody, flattenBody, type DataTableBodyGroup } from './data-table-body';
+import type { DataTableProps } from './data-table-props';
+import {
+  groupKeyOf,
+  groupRows,
+  paginate,
+  selectionState,
+  sortRows,
+  toggleAll,
+  toggleOne,
+  type DataTableColumn,
+  type DataTableGroupBy,
+  type SortState,
+} from './data-table-utils';
+import { DensityToggle } from './density-toggle';
+import { DEPLOYMENT_COLUMNS, DEPLOYMENT_ROWS } from './fixtures';
+import { DataTableHeadCell } from './header-cell';
+import { SelectionGroup, useSingleSelection, useSingleSelectionWarnings } from './single-selection';
+import { useControllable, useTableViews } from './use-table-views';
+import { useVirtualRows } from './use-virtual-rows';
+import { ViewSwitcher, type DataTableViewState } from './views';
+
+export type { DataTableLabels } from './labels';
+export type { DataTableProps } from './data-table-props';
+
+const defaultRowId = (row: unknown): string => {
+  const id = (row as { id?: unknown }).id;
+  return typeof id === 'string' || typeof id === 'number' ? String(id) : '';
+};
+const EMPTY_PINNED: PinnedColumns = {};
+const EMPTY_WIDTHS: ColumnWidths = {};
+const ROW_HEIGHT: Record<TableDensity, number> = { comfortable: 44, compact: 36 };
+
+/**
+ * Generic data table on the kit Table: typed columns, sortable headers (aria-sort), row selection
+ * with select-all / indeterminate, column visibility menu, density toggle, row actions, loading
+ * and empty states, client-side sort + pagination, optional collapsible row groups (`groupBy`),
+ * column resize and pinning, row virtualization, inline cell editing and saved views.
+ */
+export function DataTable<T = (typeof DEPLOYMENT_ROWS)[number]>({
+  rows = DEPLOYMENT_ROWS as unknown as readonly T[],
+  columns = DEPLOYMENT_COLUMNS as unknown as ReadonlyArray<DataTableColumn<T>>,
+  getRowId = defaultRowId,
+  getRowLabel,
+  caption = 'Deployments',
+  showCaption = false,
+  selectable: selectableProp = true,
+  selectionMode,
+  selectionName,
+  legend,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  selectedId,
+  defaultSelectedId,
+  onSelectedIdChange,
+  isRowDisabled,
+  selectedIds,
+  defaultSelectedIds = [],
+  onSelectionChange,
+  bulkActions,
+  selectionSummary = true,
+  rowActions,
+  sort: sortProp,
+  defaultSort = null,
+  onSortChange,
+  manualSorting = false,
+  paginated: paginatedProp,
+  defaultPageSize = 10,
+  pageSizeOptions = [10, 25, 50],
+  density: densityProp,
+  defaultDensity,
+  onDensityChange,
+  showDensityToggle = true,
+  showColumnMenu = true,
+  loading = false,
+  loadingRows = 5,
+  emptyState,
+  groupBy,
+  groupLabel,
+  collapsibleGroups = true,
+  collapsedGroups: collapsedProp,
+  defaultCollapsedGroups = [],
+  onCollapsedGroupsChange,
+  onGroupByChange,
+  hiddenColumns: hiddenProp,
+  onHiddenColumnsChange,
+  resizable = false,
+  columnWidths: widthsProp,
+  defaultColumnWidths = EMPTY_WIDTHS,
+  onColumnWidthsChange,
+  pinnedColumns: pinnedProp,
+  defaultPinnedColumns = EMPTY_PINNED,
+  onPinnedColumnsChange,
+  showPinMenu,
+  virtualize = 'auto',
+  virtualizeThreshold = 100,
+  rowHeight: rowHeightProp,
+  virtualContainerClassName = 'max-h-[32rem]',
+  onCellEdit,
+  views: viewsProp,
+  defaultViews,
+  onViewsChange,
+  activeViewId,
+  defaultActiveViewId,
+  onActiveViewChange,
+  showViewSwitcher,
+  filters,
+  onFiltersChange,
+  toolbar,
+  className,
+  labels,
+}: DataTableProps<T>) {
+  const { t } = useI18n();
+  const singleMode = selectionMode === 'single';
+  const selectable = selectionMode === undefined ? selectableProp : selectionMode === 'multiple';
+  const selectionColumn = selectable || singleMode;
+  const paginated = !singleMode && (paginatedProp ?? true);
+  const editHintId = useId();
+  const tableRef = useRef<HTMLTableElement>(null);
+  // A view active at mount seeds the initial state.
+  const [initialView] = useState(() =>
+    (viewsProp ?? defaultViews ?? []).find((v) => v.id === (activeViewId ?? defaultActiveViewId)),
+  );
+  const [initialFilters] = useState(() => filters);
+  const seed = initialView?.state ?? {};
+  const defaultHidden = columns.filter((c) => c.defaultHidden).map((c) => c.id);
+
+  const [innerSort, setInnerSort] = useState<SortState | null>(seed.sort !== undefined ? seed.sort : defaultSort);
+  const [innerSelected, setInnerSelected] = useState<ReadonlySet<string>>(() => new Set(defaultSelectedIds));
+  const [innerDensity, setInnerDensity] = useState<TableDensity | null>(defaultDensity ?? null);
+  const contextDensity = useDensity();
+  const [hiddenList, setHiddenList] = useControllable<readonly string[]>(
+    hiddenProp,
+    () => seed.hiddenColumns ?? defaultHidden,
+    (ids) => onHiddenColumnsChange?.([...ids]),
+  );
+  const [widths, setWidths] = useControllable<ColumnWidths>(
+    widthsProp,
+    () => seed.columnWidths ?? defaultColumnWidths,
+    (w) => onColumnWidthsChange?.({ ...w }),
+  );
+  const [pinned, setPinned] = useControllable<PinnedColumns>(
+    pinnedProp,
+    () => seed.pinnedColumns ?? defaultPinnedColumns,
+    onPinnedColumnsChange,
+  );
+  // `undefined`: follow the groupBy prop; a string or null: set by a saved view.
+  const [groupOverride, setGroupOverride] = useState<string | null | undefined>(seed.groupBy);
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(defaultPageSize);
+
+  const hidden: ReadonlySet<string> = new Set(hiddenList);
+  const effectiveGroupBy: DataTableGroupBy<T> | undefined =
+    groupOverride === undefined ? groupBy : ((groupOverride ?? undefined) as DataTableGroupBy<T> | undefined);
+  const sort = sortProp === undefined ? innerSort : sortProp;
+  const selected: ReadonlySet<string> = selectedIds ? new Set(selectedIds) : innerSelected;
+  const density = densityProp ?? innerDensity ?? contextDensity;
+  const visibleColumns = orderColumns(
+    columns.filter((c) => !hidden.has(c.id)),
+    pinned,
+  );
+  const labelOf =
+    getRowLabel ??
+    ((row: T) => {
+      const first = columns[0];
+      const value = first?.accessor?.(row);
+      return value == null ? getRowId(row) : String(value);
+    });
+
+  const [innerCollapsed, setInnerCollapsed] = useState<ReadonlySet<string>>(() => new Set(defaultCollapsedGroups));
+  const collapsed: ReadonlySet<string> = collapsedProp ? new Set(collapsedProp) : innerCollapsed;
+
+  const sortedRows = manualSorting ? [...rows] : sortRows(rows, columns, sort);
+  const allGroups = effectiveGroupBy ? groupRows(sortedRows, effectiveGroupBy, rows) : null;
+  const sorted = allGroups ? allGroups.flatMap((g) => g.rows) : sortedRows;
+  const pageRows = paginated ? paginate(sorted, page, pageSize) : sorted;
+  // Rows in collapsed groups are hidden, so select-all leaves them alone.
+  const pageIds = (
+    effectiveGroupBy ? pageRows.filter((row) => !collapsed.has(groupKeyOf(row, effectiveGroupBy))) : pageRows
+  ).map(getRowId);
+  const header = selectionState(pageIds, selected);
+  const selectedList = rows.map(getRowId).filter((id) => selected.has(id));
+
+  const setSelected = (next: Set<string>) => {
+    setInnerSelected(next);
+    onSelectionChange?.(rows.map(getRowId).filter((id) => next.has(id)));
+  };
+  const changeSort = (columnId: string, direction: SortState['direction']) => {
+    const next: SortState = { columnId, direction: sort?.columnId === columnId ? direction : 'ascending' };
+    setInnerSort(next);
+    onSortChange?.(next);
+    setPage(1);
+  };
+  const toggleGroup = (key: string) => {
+    const next = new Set(collapsed);
+    if (next.has(key)) next.delete(key);
+    else next.add(key);
+    setInnerCollapsed(next);
+    onCollapsedGroupsChange?.([...next]);
+  };
+  const nameOf = (key: string) => key || (labels?.noGroup ?? 'No group');
+  const bodyGroups: Array<DataTableBodyGroup<T>> | undefined =
+    effectiveGroupBy && allGroups
+      ? allGroups
+          .map((g) => ({
+            key: g.key,
+            label: groupLabel ? groupLabel(g.key, g.rows) : nameOf(g.key),
+            name: nameOf(g.key),
+            rows: pageRows.filter((row) => groupKeyOf(row, effectiveGroupBy) === g.key),
+            ids: g.rows.map(getRowId),
+          }))
+          .filter((g) => g.rows.length > 0)
+      : undefined;
+  const groupsForBody = bodyGroups && bodyGroups.length > 0 ? bodyGroups : undefined;
+  const singleSelection = useSingleSelection({
+    selectionName,
+    selectedId,
+    defaultSelectedId,
+    onSelectedIdChange,
+    getRowId,
+    getRowLabel: labelOf,
+    isRowDisabled,
+    rows:
+      !singleMode || loading
+        ? []
+        : pageRows.filter((row) => !effectiveGroupBy || !collapsed.has(groupKeyOf(row, effectiveGroupBy))),
+  });
+  useSingleSelectionWarnings({
+    single: singleMode,
+    selectionName,
+    paginated: paginatedProp,
+    hasLabel:
+      Boolean(legend || ariaLabel?.trim() || ariaLabelledBy?.trim()) ||
+      typeof legend === 'number' ||
+      typeof legend === 'bigint',
+  });
+
+  const changeDensity = (next: TableDensity) => {
+    setInnerDensity(next);
+    onDensityChange?.(next);
+  };
+  const toggleColumn = (id: string, visible: boolean) =>
+    setHiddenList(visible ? hiddenList.filter((c) => c !== id) : [...hiddenList, id]);
+  const resizeColumn = (column: DataTableColumn<T>, width: number) =>
+    setWidths({ ...widths, [column.id]: clampColumnWidth(column, width) });
+
+  // Saved views.
+  const groupName = (g: DataTableGroupBy<T> | undefined): string | null => (typeof g === 'string' ? g : null);
+  const currentState: DataTableViewState = {
+    filters,
+    sort,
+    hiddenColumns: hiddenList,
+    columnWidths: widths,
+    pinnedColumns: pinned,
+    groupBy: groupOverride === undefined ? groupName(groupBy) : groupOverride,
+  };
+  const defaultState: DataTableViewState = {
+    filters: initialFilters,
+    sort: defaultSort,
+    hiddenColumns: defaultHidden,
+    columnWidths: defaultColumnWidths,
+    pinnedColumns: defaultPinnedColumns,
+    groupBy: groupName(groupBy),
+  };
+  const applyState = (state: DataTableViewState) => {
+    const nextSort = state.sort ?? null;
+    setInnerSort(nextSort);
+    if (nextSort) onSortChange?.(nextSort);
+    setHiddenList(state.hiddenColumns ?? defaultHidden);
+    setWidths(state.columnWidths ?? defaultColumnWidths);
+    setPinned(state.pinnedColumns ?? defaultPinnedColumns);
+    const nextGroup = state.groupBy ?? null;
+    setGroupOverride(nextGroup === groupName(groupBy) && typeof groupBy !== 'function' ? undefined : nextGroup);
+    if (nextGroup !== currentState.groupBy) onGroupByChange?.(nextGroup);
+    if (state.filters !== filters) onFiltersChange?.(state.filters);
+    setPage(1);
+  };
+  const viewsApi = useTableViews({
+    views: viewsProp,
+    defaultViews,
+    onViewsChange,
+    activeViewId,
+    defaultActiveViewId,
+    onActiveViewChange,
+    current: currentState,
+    defaults: defaultState,
+    apply: applyState,
+  });
+  const showViews = showViewSwitcher ?? (viewsProp != null || defaultViews != null || onViewsChange != null);
+
+  const pinning =
+    showPinMenu ?? (pinnedProp != null || defaultPinnedColumns !== EMPTY_PINNED || onPinnedColumnsChange != null);
+  const layout = tableLayout({
+    columns: visibleColumns,
+    widths,
+    pinned,
+    sized: resizable || widthsProp != null || defaultColumnWidths !== EMPTY_WIDTHS,
+    lead: selectionColumn,
+    trail: rowActions != null,
+  });
+
+  const items = loading || pageRows.length === 0 ? 0 : flattenBody(pageRows, groupsForBody, collapsed).length;
+  const virtualOn =
+    !singleMode && !loading && (virtualize === true || (virtualize === 'auto' && items > virtualizeThreshold));
+  const rowHeight = rowHeightProp ?? ROW_HEIGHT[density];
+  const virtual = useVirtualRows({ enabled: virtualOn, count: items, rowHeight, tableRef, viewportHeight: 512 });
+
+  const hasSelection = selectable && selectedList.length > 0 && (selectionSummary || bulkActions != null);
+  const showToolbar = toolbar != null || showDensityToggle || showColumnMenu || showViews || hasSelection;
+  const anyEditable = onCellEdit != null && columns.some((c) => c.editable);
+
+  return (
+    <div className={cn('overflow-hidden rounded-xl border border-border bg-card shadow-sm', className)}>
+      {showToolbar && (
+        <div
+          className={cn(
+            'flex min-h-12 flex-wrap items-center gap-2 border-b border-border px-3 py-2 transition-colors motion-reduce:transition-none',
+            hasSelection ? 'bg-primary/8' : 'bg-secondary/30',
+          )}
+        >
+          <div className="flex min-w-0 flex-1 flex-wrap items-center gap-2">
+            {hasSelection ? (
+              <>
+                {selectionSummary && (
+                  <span className="text-[12.5px] font-semibold text-foreground" aria-live="polite">
+                    {labels?.selectionCount ? (
+                      labels.selectionCount(selectedList.length)
+                    ) : (
+                      <>{selectedList.length} selected</>
+                    )}
+                  </span>
+                )}
+                {selectionSummary && bulkActions && <span aria-hidden className="h-4 w-px bg-border" />}
+                {bulkActions?.(selectedList)}
+              </>
+            ) : (
+              toolbar
+            )}
+          </div>
+          <div className="flex items-center gap-2">
+            {showViews && (
+              <ViewSwitcher
+                labels={labels}
+                views={viewsApi.views}
+                activeId={viewsApi.activeId}
+                dirty={viewsApi.dirty}
+                onSelect={viewsApi.select}
+                onSaveAs={viewsApi.saveAs}
+                onSave={viewsApi.save}
+                onRename={viewsApi.rename}
+                onDelete={viewsApi.remove}
+                onReset={viewsApi.reset}
+              />
+            )}
+            {showDensityToggle && <DensityToggle labels={labels} value={density} onChange={changeDensity} />}
+            {showColumnMenu && (
+              <ColumnVisibilityMenu
+                labels={labels}
+                columns={columns}
+                hidden={hidden}
+                onToggle={toggleColumn}
+                pinOf={pinning ? (id) => pinSideOf(id, pinned) : undefined}
+                onPin={pinning ? (id, side) => setPinned(setColumnPin(pinned, id, side)) : undefined}
+              />
+            )}
+          </div>
+        </div>
+      )}
+      {anyEditable && (
+        <span id={editHintId} className="sr-only">
+          {labels?.editHint ?? 'Press Enter or F2 to edit.'}
+        </span>
+      )}
+      {/* The toggle drives a density context for the table: its rows and the controls inside them. */}
+      <SelectionGroup single={singleMode} legend={legend} aria-label={ariaLabel} aria-labelledby={ariaLabelledBy}>
+        <DensityProvider density={density}>
+          <Table
+            ref={tableRef}
+            aria-busy={loading || undefined}
+            aria-rowcount={virtual ? items + 1 : undefined}
+            stickyHeader={virtualOn}
+            containerClassName={virtualOn ? virtualContainerClassName : undefined}
+            containerLabel={virtualOn ? caption : labels?.scrollRegion}
+            // Keep single-mode resize handles inside their cells. Overflow at the
+            // final column would add a scroll-container stop before the header.
+            className={cn(
+              layout.tableClassName,
+              singleMode && '[&_[data-column-resizer]]:end-0 [&_[data-column-resizer]]:justify-end',
+            )}
+            style={layout.tableStyle}
+            data-virtualized={virtualOn || undefined}
+          >
+            <TableCaption srOnly={!showCaption}>{caption}</TableCaption>
+            <TableHeader>
+              <TableRow className="hover:bg-transparent" aria-rowindex={virtual ? 1 : undefined}>
+                {selectionColumn && (
+                  <TableHead
+                    className={cn(
+                      'w-10 pe-0',
+                      layout.lead.className,
+                      layout.lead.pinned && 'z-[11] bg-card',
+                      stickyTint(layout.lead, { head: true }),
+                    )}
+                    style={layout.lead.style}
+                  >
+                    {singleMode && <span className="sr-only">{labels?.selection ?? t('table.selection')}</span>}
+                    {selectable && (
+                      <Checkbox
+                        aria-label={labels?.selectAll ?? t('table.selectAllPage')}
+                        checked={header.checked}
+                        indeterminate={header.indeterminate}
+                        disabled={loading || pageIds.length === 0}
+                        onCheckedChange={() => setSelected(toggleAll(pageIds, selected))}
+                      />
+                    )}
+                  </TableHead>
+                )}
+                {visibleColumns.map((c) => {
+                  const bounds = widthBounds(c);
+                  return (
+                    <DataTableHeadCell
+                      labels={labels}
+                      key={c.id}
+                      column={c}
+                      layout={layout.columns.get(c.id)}
+                      sortDirection={sort?.columnId === c.id ? sort.direction : 'none'}
+                      onSortChange={(dir) => changeSort(c.id, dir)}
+                      resize={
+                        resizable && c.resizable !== false
+                          ? {
+                              width: columnWidthOf(c, widths),
+                              min: bounds.min,
+                              max: bounds.max,
+                              onResize: (w) => resizeColumn(c, w),
+                            }
+                          : undefined
+                      }
+                    />
+                  );
+                })}
+                {rowActions && (
+                  <TableHead
+                    className={cn(
+                      'w-12',
+                      layout.trail.className,
+                      layout.trail.pinned && 'z-[11] bg-card',
+                      stickyTint(layout.trail, { head: true }),
+                    )}
+                    style={layout.trail.style}
+                  >
+                    <span className="sr-only">{labels?.actions ?? t('table.actions')}</span>
+                  </TableHead>
+                )}
+              </TableRow>
+            </TableHeader>
+            <DataTableBody
+              labels={labels}
+              rows={pageRows}
+              columns={visibleColumns}
+              getRowId={getRowId}
+              getRowLabel={labelOf}
+              selectable={selectable}
+              selected={selected}
+              singleSelection={singleMode ? singleSelection : undefined}
+              onToggleRow={(id) => setSelected(toggleOne(id, selected))}
+              rowActions={rowActions}
+              loading={loading}
+              loadingRows={loadingRows}
+              emptyState={emptyState}
+              groups={groupsForBody}
+              collapsedGroups={collapsed}
+              collapsibleGroups={collapsibleGroups}
+              onToggleGroup={toggleGroup}
+              onToggleGroupRows={(ids) => setSelected(toggleAll(ids, selected))}
+              layout={layout}
+              onCellEdit={onCellEdit}
+              editHintId={anyEditable ? editHintId : undefined}
+              virtual={virtual}
+            />
+          </Table>
+        </DensityProvider>
+      </SelectionGroup>
+      {loading && (
+        <p role="status" className="sr-only">
+          {labels?.loading ? labels.loading(caption) : <>Loading {caption.toLowerCase()}…</>}
+        </p>
+      )}
+      {paginated && !loading && rows.length > 0 && (
+        <PaginationFooter
+          labels={labels}
+          className="border-t border-border px-4 py-3"
+          total={rows.length}
+          page={page}
+          onPageChange={setPage}
+          pageSize={pageSize}
+          onPageSizeChange={setPageSize}
+          pageSizeOptions={pageSizeOptions}
+          noun={caption}
+        />
+      )}
+    </div>
+  );
+}

package/src/tables/DataTable/block.meta.ts

@@ -0,0 +1,129 @@
+import type { BlockMeta } from '../../meta';
+import type { DataTableLabels } from './labels';
+
+export const meta: BlockMeta = {
+  name: 'Data table',
+  family: 'tables',
+  status: 'beta',
+  description:
+    'Generic typed table: sortable headers with aria-sort, row selection with select-all and indeterminate by default (selectionMode="multiple"), selectionMode="none" to hide selection, column visibility menu, density toggle, row actions, loading and empty states, client-side sort and pagination, optional row groups (groupBy) with rowgroup header rows, counts, keyboard-accessible collapse buttons and group selection; column resize (pointer drag or a focusable role="separator" handle with arrow keys, min/max widths, controlled columnWidths), column pinning to either edge with sticky cells (column menu or pinnedColumns), row virtualization for large datasets (aria-rowcount/aria-rowindex, works with selection and grouping), inline cell editing (text, number and select editors; Enter/F2 to edit, Enter/Tab to commit, Escape to cancel, onCellEdit can reject with an inline error) and saved views (filters, sort, visible columns, widths, pinning and grouping) with a view switcher to save as, rename, delete and reset. ' +
+    'Opt-in selectionMode="single" uses native radios in a labelled fieldset (never paginated or virtualized; paginated defaults to false and paginated=true is a type error). Single mode uses selectedId/onSelectedIdChange or defaultSelectedId; isRowDisabled skips unavailable rows and preserves a checked disabled choice without callbacks. Supply legend, aria-label or aria-labelledby for the group and getRowLabel for each radio (otherwise the first column labels it). selectionName is used verbatim and must be unique per page; omitted names use an instance-unique useId name, and duplicate supplied names or missing group labels warn in development. Tab enters once on the checked enabled row or first enabled row; arrows wrap and skip disabled rows, Space selects, Shift+Tab exits, and all-disabled groups have no tab stop. No select-all, group checkboxes, bulk actions or selection summary appear in single mode. ' +
+    'Examples in examples/single-selection.tsx: an uncontrolled non-paginated list with legend="Available items" and a controlled versions table with legend="Available versions", selectedId="v2" and a checked disabled version.',
+
+  labels: [
+    {
+      key: 'scrollRegion',
+      type: 'string',
+      state: 'Non-virtual table overflow: focusable scroll region name; virtualized regions use the caller caption',
+    },
+    {
+      key: 'selectionCount',
+      type: '(count: number) => string',
+      state: 'Multiple selection: toolbar count and polite live region',
+    },
+    { key: 'columns', type: 'string', state: 'Column visibility trigger text and name' },
+    { key: 'visibleColumns', type: 'string', state: 'Open column menu: visibility heading' },
+    { key: 'pinColumns', type: 'string', state: 'Open column menu with pinning: pin heading' },
+    { key: 'pinnedLeft', type: 'string', state: 'Open pin submenu trigger: left side suffix' },
+    { key: 'pinnedRight', type: 'string', state: 'Open pin submenu trigger: right side suffix' },
+    { key: 'pinLeft', type: 'string', state: 'Open pin submenu: left option' },
+    { key: 'pinRight', type: 'string', state: 'Open pin submenu: right option' },
+    { key: 'unpinned', type: 'string', state: 'Open pin submenu: unpinned option' },
+    { key: 'density', type: 'string', state: 'Density group accessible name' },
+    { key: 'comfortable', type: 'string', state: 'Comfortable density button name' },
+    { key: 'compact', type: 'string', state: 'Compact density button name' },
+    {
+      key: 'resizeColumn',
+      type: '(label: string) => string',
+      state: 'Resizable header: separator name; label is caller column header',
+    },
+    {
+      key: 'columnWidth',
+      type: '(width: number) => string',
+      state: 'Resizable header: separator aria-valuetext in pixels',
+    },
+    { key: 'defaultView', type: 'string', state: 'View trigger when no active view' },
+    { key: 'defaultViewOption', type: 'string', state: 'Open views menu: default option' },
+    { key: 'modified', type: 'string', state: 'Dirty view trigger: screen reader suffix' },
+    { key: 'views', type: 'string', state: 'Open views menu: heading' },
+    { key: 'saveChanges', type: 'string', state: 'Open views menu: save current view action' },
+    { key: 'saveAs', type: 'string', state: 'Open views menu: save as action' },
+    { key: 'renameView', type: 'string', state: 'Open views menu: rename action' },
+    { key: 'deleteView', type: 'string', state: 'Open views menu: immediate delete action; no confirmation dialog' },
+    { key: 'resetChanges', type: 'string', state: 'Open views menu: reset action' },
+    { key: 'saveViewTitle', type: 'string', state: 'Save as dialog: title and accessible name' },
+    { key: 'renameViewTitle', type: 'string', state: 'Rename dialog: title and accessible name' },
+    { key: 'viewName', type: 'string', state: 'Save as and Rename dialogs: input label' },
+    { key: 'cancel', type: 'string', state: 'Save as and Rename dialogs: cancel button' },
+    { key: 'saveView', type: 'string', state: 'Save as dialog: submit button' },
+    { key: 'rename', type: 'string', state: 'Rename dialog: submit button' },
+    { key: 'closeDialog', type: 'string', state: 'Save as and Rename dialogs: close button name' },
+    { key: 'selection', type: 'string', state: 'Single selection: screen reader column heading' },
+    { key: 'selectAll', type: 'string', state: 'Multiple selection: header checkbox name' },
+    {
+      key: 'selectRow',
+      type: '(label: string) => string',
+      state: 'Multiple selection: row checkbox name; label is caller row name',
+    },
+    { key: 'selectGroup', type: '(group: string) => string', state: 'Grouped multiple selection: group checkbox name' },
+    {
+      key: 'groupRows',
+      type: '(count: number) => string',
+      state: 'Grouped header: screen reader row-count unit; numeric count stays unchanged',
+    },
+    { key: 'noGroup', type: 'string', state: 'Grouped header: fallback when group key is empty' },
+    { key: 'actions', type: 'string', state: 'Row actions present: screen reader column heading' },
+    {
+      key: 'rowActions',
+      type: '(label: string) => string',
+      state: 'Row action menu trigger name; label is caller row name',
+    },
+    { key: 'emptyTitle', type: 'string', state: 'Empty rows: default empty-state title' },
+    { key: 'emptyDescription', type: 'string', state: 'Empty rows: default empty-state description' },
+    {
+      key: 'loading',
+      type: '(caption: string) => string',
+      state: 'Loading: status announcement; receives original caller caption',
+    },
+    { key: 'editHint', type: 'string', state: 'Editable table: shared keyboard instruction description' },
+    { key: 'editLabel', type: '(column: string, row: string) => string', state: 'Editing cell: input accessible name' },
+    { key: 'editError', type: 'string', state: 'Rejected cell edit without caller error message: alert' },
+    { key: 'enterNumber', type: 'string', state: 'Editing number: invalid numeric value alert' },
+    { key: 'minimumValue', type: '(min: number) => string', state: 'Editing number below minimum: alert' },
+    { key: 'maximumValue', type: '(max: number) => string', state: 'Editing number above maximum: alert' },
+    { key: 'rowsPerPage', type: 'string', state: 'Always: visible page-size text' },
+    { key: 'rowsPerPageLabel', type: 'string', state: 'Always: page-size Select accessible name' },
+    {
+      key: 'rangeSummary',
+      type: '(from: number, to: number, total: number) => string',
+      state: 'Every page and page-size change: visible summary and polite live region',
+    },
+    {
+      key: 'paginationNav',
+      type: '(noun: string) => string',
+      state: 'Always: navigation accessible name; noun is the caller caption',
+    },
+    { key: 'previous', type: 'string', state: 'Always: previous-page button name' },
+    { key: 'next', type: 'string', state: 'Always: next-page button name' },
+    {
+      key: 'page',
+      type: '(page: number) => string',
+      state: 'Always: numbered-page button name; number stays caller content',
+    },
+  ] satisfies Array<{ key: keyof DataTableLabels; type: string; state: string }>,
+  uses: [
+    'Table',
+    'Checkbox',
+    'Menu',
+    'MoreMenu',
+    'ToggleGroup',
+    'Button',
+    'Skeleton',
+    'EmptyState',
+    'Pagination',
+    'SimpleSelect',
+    'StatusTag',
+    'Input',
+    'Dialog',
+  ],
+};