banhaten 0.3.0 → 0.5.0

package/docs/design-system/components/table.md

@@ -1,416 +1,420 @@
-# Table
-
-The table component family includes `Table` and `DataTable`.
-
-`Table` is the composable data surface. It owns layout, headers, row states, selection, sortable header affordances, and RTL mirroring. Cells are filled by table item variants, so new content can be added without creating one-off row layouts.
-
-`DataTable` is the dataset workflow wrapper. It composes the existing Banhaten `Table`, `Toolbar`, `Pagination`, and `Spinner` components to provide search, filters, sorting, selection summary, bulk actions, pagination, and empty/loading/error states.
-
-Figma references:
-
-- `Table Example`, node `449:2354`
-- `Table item 1.2`, node `438:41157`
-
-## Structure
-
-```tsx
-<Table
-  dir="ltr"
-  columns={columns}
-  rows={rows}
-  selectedRowIds={selectedRowIds}
-  onSelectedRowIdsChange={setSelectedRowIds}
-/>
-
-<DataTable
-  title="Component Operations"
-  description="Track component readiness across design-system work."
-  columns={columns}
-  rows={rows}
-  selectedRowIds={selectedRowIds}
-  onSelectedRowIdsChange={setSelectedRowIds}
-  search={{ label: "Search projects", placeholder: "Search projects..." }}
-  filters={filters}
-  pagination={{ pageSize: 10 }}
-/>
-
-<TableRoot aria-label="Compact audit data">
-  <TableHeader>
-    <TableRowElement>
-      <TableHead>Activity</TableHead>
-    </TableRowElement>
-  </TableHeader>
-  <TableBody>
-    <TableRowElement>
-      <TableCell>Member invited</TableCell>
-    </TableRowElement>
-  </TableBody>
-</TableRoot>
-```
-
-The table is composed from these parts:
-
-- `Table`: scroll container and semantic table/grid root.
-- `TableHeader`: one header row with sortable header cells.
-- `TableRow`: one data row with `default`, `selected`, and `disabled` states plus native hover styling.
-- `TableCell`: the layout shell for any table item.
-- `TableItem`: the content variant rendered inside a cell.
-- `DataTable`: composed workflow shell for search, filters, actions, pagination, and table states.
-- `DataTableSurface`: ARIA table surface for bespoke CSS-grid rows while keeping the table root owned by Banhaten.
-- `TableRoot`, `TableHeader`, `TableBody`, `TableRowElement`, `TableHead`, and `TableCell`: owned semantic elements for product-specific read-only tables that do not fit the data-column API.
-
-Use semantic `<table>` markup when the table is mostly read-only data. Use an ARIA grid only when the product needs cell-level keyboard navigation. Interactive content inside cells, such as checkboxes, toggles, and actions, must remain real controls.
-
-## Layout
-
-The Figma sample is `1024px` wide, but the implementation should be responsive. Fixed columns keep their design widths and the primary text column fills the remaining space.
-
-```ts
-const exampleColumns = [
-  { id: "select", width: 42, kind: "selection" },
-  { id: "project", header: "Project Name", width: "fill", sortable: true },
-  { id: "leader", header: "Project Leader", width: 203, sortable: true },
-  { id: "status", header: "Status", width: 147, sortable: true },
-  { id: "progress", header: "Progress", width: 160, sortable: true },
-  { id: "deadline", header: "Deadline", width: 155, sortable: true },
-  { id: "actions", width: 44, kind: "actions" },
-];
-```
-
-RTL tables reverse the visual column order and align cell content to the end. The selection cell moves to the far right, and the action cell moves to the far left. The row data order should not change.
-
-## Sizing
-
-| Area | Size | LTR height | RTL height |
-| --- | --- | ---: | ---: |
-| Header row | `sm` | `44px` | `44px` |
-| Body row | `sm` | `48px` | `44px` |
-| Body row | `lg` | `56px` | `56px` |
-
-Cell padding is `12px` on the inline axis. The fixed `44px` action column keeps `8px` inline padding around its `28px` action button. Inline content gap is `6px`; header label and sort icon gap is `4px`. The base checkbox and action columns use fixed dimensions so hover, selected, and icon states do not shift the table.
-
-## States
-
-| State | Treatment |
-| --- | --- |
-| `default` | Default background with a subtle bottom divider. |
-| Native hover | Ghost hover background across the full row. |
-| `selected` | Selected row background and checked selection control. |
-| `disabled` | Disabled content color and no row actions. |
-
-The selected checkbox uses the brand or checkbox fill and a white check icon. Header checkbox supports checked, unchecked, and indeterminate states.
-
-## Token Mapping
-
-The Figma nodes use names such as `interactive/table/header`, `interactive/ghost/hover`, and `bg/neutral/soft`. In this documentation set, map those to the semantic token contract:
-
-| Figma intent | Design-system token |
-| --- | --- |
-| Table header background | `background.muted` |
-| Row hover background | `background.hover` |
-| Row selected background | `background.selected` |
-| Row divider | `border.subtle` |
-| Body text | `content.default` |
-| Header text and secondary labels | `content.subtle` |
-| Checkbox active fill | `background.brand` |
-| Progress track | `background.muted` |
-| Progress fill | `background.success` or component success fill |
-| Row height | `density.tableRowHeight` |
-| Control radius | `shape.control` |
-| Avatar, badge, and progress radius | `shape.badge` |
-
-Do not hard-code preset-specific values in the table. Appearance presets may change density, radius, borders, and hover treatment while preserving the same component API.
-
-## Column API
-
-Use semantic names in code even if the Figma variant labels are title-cased.
-
-```ts
-type TableDirection = "ltr" | "rtl";
-type TableSize = "sm" | "lg";
-type TableRowState = "default" | "selected" | "disabled";
-
-type TableColumn<Row> = {
-  id: string;
-  header?: string;
-  width?: number | "fill";
-  minWidth?: number;
-  align?: "start" | "center" | "end";
-  sortable?: boolean;
-  sortValue?: (row: Row) => TableSortValue;
-  searchValue?: (row: Row) => string;
-  kind?: "data" | "selection" | "actions";
-  item?: TableItemFactory<Row>;
-  renderCell?: (row: Row) => React.ReactNode;
-};
-
-type TableItemFactory<Row> = (row: Row) => TableItem;
-type TableSortValue = string | number | boolean | Date | null | undefined;
-type TableSortState = { columnId: string; direction: "asc" | "desc" } | null;
-```
-
-Use `item` for standard content variants and `renderCell` only for custom product-specific cells. Custom cells still render inside `TableCell`, so spacing, alignment, row height, truncation, RTL behavior, and disabled state stay consistent.
-
-Use `sortValue` when the visible cell content should sort by an underlying value, such as dates, percentages, status rank, or formatted numbers. Use `searchValue` when the cell should contribute searchable text that is different from the visible content.
-
-## Table Items
-
-The item catalog in Figma supports these cell content variants. Code may normalize visual variants into semantic item types; for example, `baseLeading`, `baseRegular`, and `subtle` all map to the `text` item with different `weight` and `tone` values.
-
-| Figma item type | Use for | Notes |
-| --- | --- | --- |
-| `checkbox` | Row selection | Fixed selection column. |
-| `baseLeading` | Primary label | Medium body label. |
-| `baseRegular` | Standard body text | Regular body label. |
-| `subtle` | Secondary text | Uses subtle content color. |
-| `avatarText` | Person, owner, assignee | Avatar plus label; `lg` may include caption. |
-| `rating` | Star rating | Five 20px stars with full, half, and empty states. |
-| `progress` | Percent completion | 8px track, percent label, mirrored fill in RTL. |
-| `toggle` | Binary row setting | 32px switch in `sm`; preserve native button semantics. |
-| `badges` | Status and categorical chips | Supports multiple badges and overflow count. |
-| `onlyAvatar` | Compact person cell | Single avatar centered or aligned by column. |
-| `avatarStack` | Team or group membership | Overlapped 20px avatars, optional count and add button. |
-| `tags` | Neutral labels | Bordered tags with compact 24px height. |
-| `file` | Attachment indicator | Icon-only file cell. |
-| `brandLogoText` | Brand or account identity | Logo plus label. |
-| `payment` | Payment method | Payment icon plus optional label. |
-| `image` | Thumbnail item | Image thumbnail plus label. |
-| `action` | Single row menu | Icon button, usually overflow menu. |
-| `actionGroup` | Multiple row actions | View, edit, delete group; reverse order in RTL. |
-
-```ts
-type TableItem =
-  | { type: "checkbox"; checked: boolean; indeterminate?: boolean }
-  | { type: "text"; tone?: "default" | "subtle"; weight?: "regular" | "medium"; value: string }
-  | { type: "avatarText"; name: string; caption?: string; src?: string; status?: "top" | "bottom" }
-  | { type: "rating"; value: number; max?: 5 }
-  | { type: "progress"; value: number; label?: string; tone?: "success" | "brand" }
-  | { type: "toggle"; checked: boolean; disabled?: boolean }
-  | { type: "badges"; items: BadgeItem[]; maxVisible?: number }
-  | { type: "onlyAvatar"; src?: string; alt: string }
-  | { type: "avatarStack"; avatars: AvatarItem[]; count?: number; canAdd?: boolean }
-  | { type: "tags"; items: string[]; maxVisible?: number }
-  | { type: "file"; label?: string }
-  | { type: "brandLogoText"; label: string; logoSrc?: string }
-  | { type: "payment"; brand: "maestro" | "mastercard" | "visa" | string; label?: string }
-  | { type: "image"; label: string; src: string }
-  | { type: "action"; label: string; icon: "more"; onAction: () => void }
-  | { type: "actionGroup"; actions: TableAction[] };
-
-type BadgeItem = {
-  label: string;
-  tone?: "blue" | "fuchsia" | "amber" | "neutral" | "success" | "warning" | "danger";
-  dot?: boolean;
-};
-
-type AvatarItem = {
-  src?: string;
-  alt: string;
-};
-
-type TableAction = {
-  label: string;
-  icon: "view" | "edit" | "delete" | "more";
-  onAction: () => void;
-};
-```
-
-The item union intentionally describes content, not layout. `TableCell` decides padding, alignment, truncation, and RTL mirroring.
-
-## Adding Items
-
-Add a new table item by defining it on a column. The row supplies content values; the column controls presentation.
-
-```tsx
-const columns: TableColumn<Project>[] = [
-  {
-    id: "project",
-    header: "Project Name",
-    width: "fill",
-    sortable: true,
-    item: (project) => ({
-      type: "text",
-      value: project.name,
-      weight: "regular",
-    }),
-  },
-  {
-    id: "leader",
-    header: "Project Leader",
-    width: 203,
-    sortable: true,
-    item: (project) => ({
-      type: "avatarText",
-      name: project.leader.name,
-      src: project.leader.avatarUrl,
-    }),
-  },
-  {
-    id: "status",
-    header: "Status",
-    width: 147,
-    sortable: true,
-    item: (project) => ({
-      type: "badges",
-      items: [{ label: project.status, tone: "blue", dot: true }],
-    }),
-  },
-  {
-    id: "progress",
-    header: "Progress",
-    width: 160,
-    sortable: true,
-    item: (project) => ({
-      type: "progress",
-      value: project.progress,
-      label: `${project.progress}%`,
-      tone: "success",
-    }),
-  },
-  {
-    id: "deadline",
-    header: "Deadline",
-    width: 155,
-    sortable: true,
-    item: (project) => ({
-      type: "text",
-      value: project.deadlineLabel,
-    }),
-  },
-  {
-    id: "actions",
-    width: 44,
-    kind: "actions",
-    item: (project) => ({
-      type: "action",
-      label: `Open actions for ${project.name}`,
-      icon: "more",
-      onAction: () => openProjectActions(project.id),
-    }),
-  },
-];
-```
-
-For a custom item, first check whether the content can be represented by the existing union. Add a new item type only when the content appears in more than one table or needs shared behavior such as keyboard handling, truncation, or overflow.
-
-## Header Behavior
-
-Sortable headers render the label plus the expand-up-down icon. When sorted, the header cell sets `aria-sort` to `ascending` or `descending`; otherwise it uses `none`. Header controls must have a clear label such as `Sort by Project Name`.
-
-`Table` accepts `sort` and `onSortChange` when the host owns sorting. `DataTable` can own sorting internally with `defaultSort`, or operate as a controlled component with `sort` and `onSortChange`.
-
-The select-all checkbox announces:
-
-- unchecked when no visible rows are selected;
-- checked when all visible rows are selected;
-- indeterminate when some visible rows are selected.
-
-## Data Table
-
-Use `DataTable` when the product needs the complete dataset browsing workflow instead of only rows and columns.
-
-```tsx
-const filters = [
-  {
-    id: "review",
-    label: "Status",
-    value: "Review",
-    active: statusFilter === "Review",
-    onAction: () => setStatusFilter("Review"),
-    predicate: (row) => row.status === "Review",
-  },
-];
-
-<DataTable
-  actions={[{ label: "Export", variant: "soft" }]}
-  bulkActions={[{ label: "Archive", variant: "outline" }]}
-  columns={columns}
-  defaultSort={{ columnId: "project", direction: "asc" }}
-  emptyState={{
-    title: "No matching projects",
-    description: "Try another search or return to all statuses.",
-  }}
-  filters={filters}
-  pagination={{ pageSize: 10 }}
-  rows={rows}
-  search={{ label: "Search projects", placeholder: "Search projects..." }}
-/>
-```
-
-`DataTable` applies active filter predicates, searches row text from `getRowSearchText`, column `searchValue`, or table item text, sorts by column `sortValue` or table item value, and paginates the resulting rows. Set `pagination={false}` for unpaginated datasets.
-
-## Accessibility
-
-- Preserve native controls for checkbox, toggle, buttons, and menu triggers.
-- Use `aria-selected` on selected rows.
-- Provide labels for icon-only actions.
-- Keep focus outlines visible through `border.focus`.
-- Truncate long text visually, but keep the full value available through `title` or an accessible label when useful.
-- Do not put multiple unrelated buttons into one unlabeled cell; group row actions with a clear accessible name.
-
-## Usage
-
-```tsx
-<Table
-  dir="ltr"
-  columns={columns}
-  rows={projects}
-  selectedRowIds={selectedRowIds}
-  onSelectedRowIdsChange={setSelectedRowIds}
-/>
-
-<Table
-  dir="rtl"
-  columns={columns}
-  rows={projects}
-  selectedRowIds={selectedRowIds}
-  onSelectedRowIdsChange={setSelectedRowIds}
-/>
-```
-
-## Preset Impact
-
-- `default`: normal row density, quiet header background, modest control radius.
-- `rounded`: slightly taller rows, softer hover treatment, larger badges and control radius.
-- `sharp`: denser rows, stronger dividers, square or near-square controls.
-
-## Implementation Notes
-
-- Use Remix icons for Figma icon matches: `expand-up-down-line`, `more-fill`, `check-fill`, `eye-line`, `pencil-line`, and `delete-bin-line`.
-- Progress bars are `8px` high and pill-shaped. In RTL, the filled segment grows from the right.
-- Badges are `24px` tall, pill-shaped, and use `11px / 14px` medium text.
-- Tags are `24px` tall with a 1px border and `13px / 20px` medium text.
-- Avatar-with-text cells use the shared 24px avatar in `sm` rows. Avatar-only and avatar-stack cells use 20px avatars. All three use 32px avatars in `lg` rows.
-- Action buttons are fixed `28px` in `sm` rows and `32px` in `lg` rows.
-
-## Install
-
-```bash
-npx banhaten add table
-```
-
-## API
-
-Supported runtime exports: `DataTable`, `Table`, `DataTableSurface`, `TableBody`, `TableCell`, `TableHead`, `TableHeader`, `TableRoot`, `TableRowElement`.
-
-Use the live registry docs for the generated API table and source-backed examples.
-
-## Examples
-
-Primary registry example: `examples/expanded/table-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs table` to inspect source files, install command, and examples.
-
-## Token Contract
-
-Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
-Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
-Covered source files: `components/expanded/table.css`, `components/expanded/Table.tsx`.
-
-## RTL Rules
-
-This component has no special RTL contract beyond inherited document direction and logical spacing.
-
+# Table
+
+The table component family includes `Table` and `DataTable`.
+
+`Table` is the composable data surface. It owns layout, headers, row states, selection, sortable header affordances, and RTL mirroring. Cells are filled by table item variants, so new content can be added without creating one-off row layouts.
+
+`DataTable` is the dataset workflow wrapper. It composes the existing Banhaten `Table`, `Toolbar`, `Pagination`, and `Spinner` components to provide search, filters, sorting, selection summary, bulk actions, pagination, and empty/loading/error states.
+
+Figma references:
+
+- `Table Example`, node `449:2354`
+- `Table item 1.2`, node `438:41157`
+
+## Structure
+
+```tsx
+<Table
+  dir="ltr"
+  columns={columns}
+  rows={rows}
+  selectedRowIds={selectedRowIds}
+  onSelectedRowIdsChange={setSelectedRowIds}
+/>
+
+<DataTable
+  title="Component Operations"
+  description="Track component readiness across design-system work."
+  columns={columns}
+  rows={rows}
+  selectedRowIds={selectedRowIds}
+  onSelectedRowIdsChange={setSelectedRowIds}
+  search={{ label: "Search projects", placeholder: "Search projects..." }}
+  filters={filters}
+  pagination={{ pageSize: 10 }}
+/>
+
+<TableRoot aria-label="Compact audit data">
+  <TableHeader>
+    <TableRowElement>
+      <TableHead>Activity</TableHead>
+    </TableRowElement>
+  </TableHeader>
+  <TableBody>
+    <TableRowElement>
+      <TableCell>Member invited</TableCell>
+    </TableRowElement>
+  </TableBody>
+</TableRoot>
+```
+
+The table is composed from these parts:
+
+- `Table`: scroll container and semantic table/grid root.
+- `TableHeader`: one header row with sortable header cells.
+- `TableRow`: one data row with `default`, `selected`, and `disabled` states plus native hover styling.
+- `TableCell`: the layout shell for any table item.
+- `TableItem`: the content variant rendered inside a cell.
+- `DataTable`: composed workflow shell for search, filters, actions, pagination, and table states.
+- `DataTableSurface`: ARIA table surface for bespoke CSS-grid rows while keeping the table root owned by Banhaten.
+- `TableRoot`, `TableHeader`, `TableBody`, `TableRowElement`, `TableHead`, and `TableCell`: owned semantic elements for product-specific read-only tables that do not fit the data-column API.
+
+Use semantic `<table>` markup when the table is mostly read-only data. Use an ARIA grid only when the product needs cell-level keyboard navigation. Interactive content inside cells, such as checkboxes, toggles, and actions, must remain real controls.
+
+## Layout
+
+The Figma sample is `1024px` wide, but the implementation should be responsive. Fixed columns keep their design widths and the primary text column fills the remaining space.
+
+```ts
+const exampleColumns = [
+  { id: "select", width: 42, kind: "selection" },
+  { id: "project", header: "Project Name", width: "fill", sortable: true },
+  { id: "leader", header: "Project Leader", width: 203, sortable: true },
+  { id: "status", header: "Status", width: 147, sortable: true },
+  { id: "progress", header: "Progress", width: 160, sortable: true },
+  { id: "deadline", header: "Deadline", width: 155, sortable: true },
+  { id: "actions", width: 44, kind: "actions" },
+];
+```
+
+RTL tables reverse the visual column order and align cell content to the end. The selection cell moves to the far right, and the action cell moves to the far left. The row data order should not change. An `avatarText` name and caption each resolve their own content direction, so an opposing script truncates at its actual end without changing the avatar layout.
+
+## Sizing
+
+| Area | Size | LTR height | RTL height |
+| --- | --- | ---: | ---: |
+| Header row | `sm` | `44px` | `44px` |
+| Body row | `sm` | `48px` | `44px` |
+| Body row | `lg` | `56px` | `56px` |
+
+Cell padding is `12px` on the inline axis. The fixed `44px` action column keeps `8px` inline padding around its `28px` action button. Inline content gap is `6px`; header label and sort icon gap is `4px`. The base checkbox and action columns use fixed dimensions so hover, selected, and icon states do not shift the table.
+
+## States
+
+| State | Treatment |
+| --- | --- |
+| `default` | Default background with a subtle bottom divider. |
+| Native hover | Ghost hover background across the full row. |
+| `selected` | Selected row background and checked selection control. |
+| `disabled` | Disabled content color and no row actions. |
+
+The selected checkbox uses the brand or checkbox fill and a mode-aware contrasting check icon. Header checkbox supports checked, unchecked, and indeterminate states.
+
+## Token Mapping
+
+The Figma nodes use names such as `interactive/table/header`, `interactive/ghost/hover`, and `bg/neutral/soft`. In this documentation set, map those to the semantic token contract:
+
+| Figma intent | Design-system token |
+| --- | --- |
+| Table header background | `background.muted` |
+| Row hover background | `background.hover` |
+| Row selected background | `background.selected` |
+| Row divider | `border.subtle` |
+| Body text | `content.default` |
+| Header text and secondary labels | `content.subtle` |
+| Checkbox active fill | `background.brand` |
+| Progress track | `background.muted` |
+| Progress fill | `background.success` or component success fill |
+| Row height | `density.tableRowHeight` |
+| Control radius | `shape.control` |
+| Avatar, badge, and progress radius | `shape.badge` |
+
+Do not hard-code preset-specific values in the table. Appearance presets may change density, radius, borders, and hover treatment while preserving the same component API.
+
+## Column API
+
+Use semantic names in code even if the Figma variant labels are title-cased.
+
+```ts
+type TableDirection = "ltr" | "rtl";
+type TableSize = "sm" | "lg";
+type TableRowState = "default" | "selected" | "disabled";
+
+type TableColumn<Row> = {
+  id: string;
+  header?: string;
+  width?: number | "fill";
+  minWidth?: number;
+  align?: "start" | "center" | "end";
+  sortable?: boolean;
+  sortValue?: (row: Row) => TableSortValue;
+  searchValue?: (row: Row) => string;
+  kind?: "data" | "selection" | "actions";
+  item?: TableItemFactory<Row>;
+  renderCell?: (row: Row) => React.ReactNode;
+};
+
+type TableItemFactory<Row> = (row: Row) => TableItem;
+type TableSortValue = string | number | boolean | Date | null | undefined;
+type TableSortState = { columnId: string; direction: "asc" | "desc" } | null;
+```
+
+Use `item` for standard content variants and `renderCell` only for custom product-specific cells. Custom cells still render inside `TableCell`, so spacing, alignment, row height, truncation, RTL behavior, and disabled state stay consistent.
+
+Cell content resolves in this order: `renderCell`, `item`, then an own row field whose key matches the column `id`. The implicit row-field fallback applies only to ordinary data columns and renders string or number values—including `0`—through the standard text item. Use `item` or `renderCell` for formatted values, booleans, dates, objects, and custom nodes. Selection and action columns never read an implicit row value; return `null` from `renderCell` when a deliberately blank data cell is required.
+
+Use `sortValue` when the visible cell content should sort by an underlying value, such as dates, percentages, status rank, or formatted numbers. Use `searchValue` when the cell should contribute searchable text that is different from the visible content.
+
+## Table Items
+
+The item catalog in Figma supports these cell content variants. Code may normalize visual variants into semantic item types; for example, `baseLeading`, `baseRegular`, and `subtle` all map to the `text` item with different `weight` and `tone` values.
+
+| Figma item type | Use for | Notes |
+| --- | --- | --- |
+| `checkbox` | Row selection | Fixed selection column. |
+| `baseLeading` | Primary label | Medium body label. |
+| `baseRegular` | Standard body text | Regular body label. |
+| `subtle` | Secondary text | Uses subtle content color. |
+| `avatarText` | Person, owner, assignee | Avatar plus label; `lg` may include caption. Name and caption resolve direction independently. |
+| `rating` | Star rating | Five 20px stars with full, half, and empty states. |
+| `progress` | Percent completion | 8px track, percent label, mirrored fill in RTL. |
+| `toggle` | Binary row setting | 32px switch in `sm`; preserve native button semantics. |
+| `badges` | Status and categorical chips | Supports multiple badges and overflow count. |
+| `onlyAvatar` | Compact person cell | Single avatar centered or aligned by column. |
+| `avatarStack` | Team or group membership | Overlapped 20px avatars, optional count and add button. |
+| `tags` | Neutral labels | Bordered tags with compact 24px height. |
+| `file` | Attachment indicator | Icon-only file cell. |
+| `brandLogoText` | Brand or account identity | Logo plus label. |
+| `payment` | Payment method | Payment icon plus optional label. |
+| `image` | Thumbnail item | Image thumbnail plus label. |
+| `action` | Single row menu | Icon button, usually overflow menu. |
+| `actionGroup` | Multiple row actions | View, edit, delete group; reverse order in RTL. |
+
+```ts
+type TableItem =
+  | { type: "checkbox"; checked: boolean; indeterminate?: boolean }
+  | { type: "text"; tone?: "default" | "subtle"; weight?: "regular" | "medium"; value: string }
+  | { type: "avatarText"; name: string; caption?: string; src?: string; status?: "top" | "bottom" }
+  | { type: "rating"; value: number; max?: 5 }
+  | { type: "progress"; value: number; label?: string; tone?: "success" | "brand" }
+  | { type: "toggle"; checked: boolean; disabled?: boolean }
+  | { type: "badges"; items: BadgeItem[]; maxVisible?: number }
+  | { type: "onlyAvatar"; src?: string; alt: string }
+  | { type: "avatarStack"; avatars: AvatarItem[]; count?: number; canAdd?: boolean }
+  | { type: "tags"; items: string[]; maxVisible?: number }
+  | { type: "file"; label?: string }
+  | { type: "brandLogoText"; label: string; logoSrc?: string }
+  | { type: "payment"; brand: "maestro" | "mastercard" | "visa" | string; label?: string }
+  | { type: "image"; label: string; src: string }
+  | { type: "action"; label: string; icon: "more"; onAction: () => void }
+  | { type: "actionGroup"; actions: TableAction[] };
+
+type BadgeItem = {
+  label: string;
+  tone?: "blue" | "fuchsia" | "amber" | "neutral" | "success" | "warning" | "danger";
+  dot?: boolean;
+};
+
+type AvatarItem = {
+  src?: string;
+  alt: string;
+};
+
+type TableAction = {
+  label: string;
+  icon: "view" | "edit" | "delete" | "more";
+  onAction: () => void;
+};
+```
+
+The item union intentionally describes content, not layout. `TableCell` decides padding, alignment, truncation, and RTL mirroring.
+
+## Adding Items
+
+Add a new table item by defining it on a column. The row supplies content values; the column controls presentation.
+
+```tsx
+const columns: TableColumn<Project>[] = [
+  {
+    id: "project",
+    header: "Project Name",
+    width: "fill",
+    sortable: true,
+    item: (project) => ({
+      type: "text",
+      value: project.name,
+      weight: "regular",
+    }),
+  },
+  {
+    id: "leader",
+    header: "Project Leader",
+    width: 203,
+    sortable: true,
+    item: (project) => ({
+      type: "avatarText",
+      name: project.leader.name,
+      src: project.leader.avatarUrl,
+    }),
+  },
+  {
+    id: "status",
+    header: "Status",
+    width: 147,
+    sortable: true,
+    item: (project) => ({
+      type: "badges",
+      items: [{ label: project.status, tone: "blue", dot: true }],
+    }),
+  },
+  {
+    id: "progress",
+    header: "Progress",
+    width: 160,
+    sortable: true,
+    item: (project) => ({
+      type: "progress",
+      value: project.progress,
+      label: `${project.progress}%`,
+      tone: "success",
+    }),
+  },
+  {
+    id: "deadline",
+    header: "Deadline",
+    width: 155,
+    sortable: true,
+    item: (project) => ({
+      type: "text",
+      value: project.deadlineLabel,
+    }),
+  },
+  {
+    id: "actions",
+    width: 44,
+    kind: "actions",
+    item: (project) => ({
+      type: "action",
+      label: `Open actions for ${project.name}`,
+      icon: "more",
+      onAction: () => openProjectActions(project.id),
+    }),
+  },
+];
+```
+
+For a custom item, first check whether the content can be represented by the existing union. Add a new item type only when the content appears in more than one table or needs shared behavior such as keyboard handling, truncation, or overflow.
+
+## Header Behavior
+
+Sortable headers render the label plus the expand-up-down icon. When sorted, the header cell sets `aria-sort` to `ascending` or `descending`; otherwise it uses `none`. Header controls must have a clear label such as `Sort by Project Name`.
+
+`Table` accepts `sort` and `onSortChange` when the host owns sorting. `DataTable` can own sorting internally with `defaultSort`, or operate as a controlled component with `sort` and `onSortChange`.
+
+The select-all checkbox announces:
+
+- unchecked when no visible rows are selected;
+- checked when all visible rows are selected;
+- indeterminate when some visible rows are selected.
+
+## Data Table
+
+Use `DataTable` when the product needs the complete dataset browsing workflow instead of only rows and columns.
+
+```tsx
+const filters = [
+  {
+    id: "review",
+    label: "Status",
+    value: "Review",
+    active: statusFilter === "Review",
+    onAction: () => setStatusFilter("Review"),
+    predicate: (row) => row.status === "Review",
+  },
+];
+
+<DataTable
+  actions={[{ label: "Export", variant: "soft" }]}
+  bulkActions={[{ label: "Archive", variant: "outline" }]}
+  columns={columns}
+  defaultSort={{ columnId: "project", direction: "asc" }}
+  emptyState={{
+    title: "No matching projects",
+    description: "Try another search or return to all statuses.",
+  }}
+  filters={filters}
+  pagination={{ pageSize: 10 }}
+  rows={rows}
+  search={{ label: "Search projects", placeholder: "Search projects..." }}
+/>
+```
+
+`DataTable` applies active filter predicates, searches row text from `getRowSearchText`, column `searchValue`, or table item text, sorts by column `sortValue` or table item value, and paginates the resulting rows. Set `pagination={false}` for unpaginated datasets. When `pagination.showCaption` is enabled, the Pagination caption receives the same measured visible range and total as the DataTable footer summary; the standalone Pagination demo default is never used for table data.
+
+Direction does not choose language. Pass `pagination.messages` to localize Pagination controls and accessible names, and pass `labels.resultsSummary` to format the measured DataTable range and total. An explicit `pagination.ariaLabel` overrides the message catalog's navigation label.
+
+## Accessibility
+
+- Preserve native controls for checkbox, toggle, buttons, and menu triggers.
+- Use `aria-selected` on selected rows.
+- Provide labels for icon-only actions.
+- Keep focus outlines visible through `border.focus`.
+- Truncate long text visually, but keep the full value available through `title` or an accessible label when useful.
+- Do not put multiple unrelated buttons into one unlabeled cell; group row actions with a clear accessible name.
+
+## Usage
+
+```tsx
+<Table
+  dir="ltr"
+  columns={columns}
+  rows={projects}
+  selectedRowIds={selectedRowIds}
+  onSelectedRowIdsChange={setSelectedRowIds}
+/>
+
+<Table
+  dir="rtl"
+  columns={columns}
+  rows={projects}
+  selectedRowIds={selectedRowIds}
+  onSelectedRowIdsChange={setSelectedRowIds}
+/>
+```
+
+## Preset Impact
+
+- `default`: normal row density, quiet header background, modest control radius.
+- `rounded`: slightly taller rows, softer hover treatment, larger badges and control radius.
+- `sharp`: denser rows, stronger dividers, square or near-square controls.
+
+## Implementation Notes
+
+- Use Remix icons for Figma icon matches: `expand-up-down-line`, `more-fill`, `check-fill`, `eye-line`, `pencil-line`, and `delete-bin-line`.
+- Progress bars are `8px` high and pill-shaped. In RTL, the filled segment grows from the right.
+- Badges are `24px` tall, pill-shaped, and use `11px / 14px` medium text.
+- Tags are `24px` tall with a 1px border and `13px / 20px` medium text.
+- Avatar-with-text cells use the shared 24px avatar in `sm` rows. Avatar-only and avatar-stack cells use 20px avatars. All three use 32px avatars in `lg` rows.
+- Action buttons are fixed `28px` in `sm` rows and `32px` in `lg` rows.
+
+## Install
+
+```bash
+npx banhaten add table
+```
+
+## API
+
+Supported runtime exports: `DataTable`, `Table`, `DataTableSurface`, `TableBody`, `TableCell`, `TableHead`, `TableHeader`, `TableRoot`, `TableRowElement`.
+
+Use the live registry docs for the generated API table and source-backed examples.
+
+## Examples
+
+Primary registry example: `examples/expanded/table-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs table` to inspect source files, install command, and examples.
+
+## Token Contract
+
+Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
+Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
+Covered source files: `components/expanded/table.css`, `components/expanded/Table.tsx`.
+
+## RTL Rules
+
+The table layout inherits document direction and uses logical spacing. Within `avatarText`, the independently truncated name and caption use `dir="auto"`; this preserves the identifying start of Latin content in an RTL table (and Arabic content in an LTR table) while the avatar and columns continue to mirror with the table.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -422,8 +426,9 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/expanded/Table.tsx: DataTable, Table`, `components/table-elements.tsx: DataTableSurface, TableBody, TableCell, TableHead, TableHeader, TableRoot, TableRowElement` |
 | `parts` | `Table`, `DataTable`, `DataTableSurface`, `TableRoot`, `TableHeader`, `TableBody`, `TableRowElement`, `TableHead`, `TableCell` |
 | `registryDependencies` | `avatar`, `badge`, `button`, `checkbox`, `pagination`, `progress`, `spinner`, `tag`, `toggle`, `toolbar` |
+| `features` | `measured DataTable pagination captions`, `explicit DataTable pagination message catalogs`, `safe row-key cell fallback` |
 | `modes` | `table`, `data-table` |
 | `sizes` | `sm`, `lg` |
 | `states` | `default`, `selected`, `disabled`, `loading`, `empty`, `error` |
-| `tokens` | `--bh-avatar-fallback-font-size-md`, `--bh-avatar-fallback-font-size-xs`, `--bh-avatar-size-md`, `--bh-avatar-size-xs`, `--bh-bg-accent-amber-subtle`, `--bh-bg-accent-fuchsia-subtle`, `--bh-bg-accent-golden-default`, `--bh-bg-brand-default`, `--bh-bg-brand-soft`, `--bh-bg-danger-subtle`, `--bh-bg-default`, `--bh-bg-muted`, `--bh-bg-neutral-medium`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-success-default`, `--bh-bg-success-subtle`, `--bh-bg-warning-default`, `--bh-bg-warning-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-accent-amber-strong`, `--bh-content-accent-fuchsia-strong`, `--bh-content-brand-default`, `--bh-content-danger-strong`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-content-warning-strong`, `--bh-control-default`, `--bh-duration-fast`, `--bh-easing-standard`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-semibold`, `--bh-icon-stroke-190`, `--bh-icon-stroke-225`, `--bh-input-width`, `--bh-interactive-ghost-hover`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-opacity-muted`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-sm-4`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-table-min-width`, `--bh-table-selection-column-min-width`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-3xs-regular-font-size`, `--bh-text-body-3xs-regular-line-height`, `--bh-text-body-lg-semibold-font-size`, `--bh-text-body-lg-semibold-font-weight`, `--bh-text-body-lg-semibold-line-height`, `--bh-text-body-md-semibold-font-size`, `--bh-text-body-md-semibold-font-weight`, `--bh-text-body-md-semibold-line-height`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--shadow-component-focus-ring` |
+| `tokens` | `--bh-avatar-fallback-font-size-md`, `--bh-avatar-fallback-font-size-xs`, `--bh-avatar-size-md`, `--bh-avatar-size-xs`, `--bh-bg-accent-amber-subtle`, `--bh-bg-accent-fuchsia-subtle`, `--bh-bg-accent-golden-default`, `--bh-bg-brand-default`, `--bh-bg-brand-soft`, `--bh-bg-danger-subtle`, `--bh-bg-default`, `--bh-bg-muted`, `--bh-bg-neutral-medium`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-success-default`, `--bh-bg-success-subtle`, `--bh-bg-warning-default`, `--bh-bg-warning-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-accent-amber-strong`, `--bh-content-accent-fuchsia-strong`, `--bh-content-brand-default`, `--bh-content-danger-strong`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-content-warning-strong`, `--bh-control-default`, `--bh-duration-fast`, `--bh-easing-standard`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-semibold`, `--bh-icon-size-default`, `--bh-icon-slot-size-default`, `--bh-icon-stroke-190`, `--bh-icon-stroke-225`, `--bh-input-width`, `--bh-interactive-ghost-hover`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-opacity-muted`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-sm-4`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-table-min-width`, `--bh-table-selection-column-min-width`, `--bh-text-base-letter-spacing`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-3xs-regular-font-size`, `--bh-text-body-3xs-regular-line-height`, `--bh-text-body-lg-semibold-font-size`, `--bh-text-body-lg-semibold-font-weight`, `--bh-text-body-lg-semibold-line-height`, `--bh-text-body-md-semibold-font-size`, `--bh-text-body-md-semibold-font-weight`, `--bh-text-body-md-semibold-line-height`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--elevation-component-focus-ring` |
 <!-- registry-contract:end -->