{ "id": "data-table", "name": "DataTable", "level": "organism", "status": "stable", "purpose": "Shows records in rows and columns that people can sort, select and page through.", "description": "**Purpose.** The tabular surface organism. `DataTable` composes the molecule layer (`TableHeader`, `TableRow`, `TablePagination`, `EmptyState`, `LoadingState`) into a single coordinated component that owns row rendering, selection ergonomics, sort affordance and density propagation — but never the data itself.\n\n**When to use.**\n- A list of structured records that benefits from columns, sorting, and per-row actions.\n- A surface where the user needs to *select* one or many rows for a follow-up operation (`selection=\"multiple\"`).\n- A list whose layout must stay stable across loading, empty and error states (the chrome remains; the row area swaps).\n\n**When NOT to use.**\n- A scrolling feed of heterogeneous items → use `Card` or `ListItem` compositions inside a list shell.\n- A dashboard of metrics → use `MetricCard` / `Card` instead.\n- A small fixed list (≤ 5 rows) where columns add ceremony without value → use a `dl` / property list.\n- A tree, kanban or timeline view — these need their own organism, not a `DataTable` with hidden columns.\n\n**Composes with.**\n- `DataTableToolbar` (consumer-passed `toolbar` slot) — search, filter, bulk actions.\n- `DataTablePagination` (consumer-passed `pagination` slot) or `TablePagination` molecule directly.\n- `DataTableEmpty`, `DataTableLoading` — exposed for swap-in customisation.\n- `Badge`, `Avatar`, `IconButton`, `DropdownMenu` inside cells via column `render`.\n- `PageShell mainPadding=\"flush\"` to host the table edge-to-edge inside a Card.\n\n**Accessibility.**\n- Renders `
` so the table is an announced region.\n- Header cells expose `aria-sort` when `sortable`; the sort glyph is decorative.\n- Selection checkboxes carry explicit `aria-label`. The header tri-state checkbox announces `mixed` via `aria-checked`.\n- Loading renders skeleton rows inside `role=\"status\"` + `aria-live=\"polite\"` (shape-preserving, per Patterns/System States); empty exposes `role=\"status\"`. Neither state ever overlays stale rows.\n\n**Related patterns.**\n- `Patterns/System States · StateChoice` — Empty / Loading / Error are first-class states the organism honours.\n- `Patterns/Density & Growth · DensityLevels` — when to pick `compact` vs `comfortable`.\n- `Patterns/Navigation · PaginationForDatasets` — pagination over infinite scroll.\n- `Patterns/Decision Matrix · ComponentChoice` — DataTable vs ListItem vs Card.", "role": "content", "import": "@rrios-forge/ui/organisms/data-table", "exports": [ "DataTable", "DataTableEmpty", "DataTableHeader", "DataTableLoading", "DataTablePagination", "DataTableRow", "DataTableToolbar", "getVisibleColumns", "DATA_TABLE_DENSITIES", "DATA_TABLE_DENSITY_GAP", "DATA_TABLE_SELECTIONS", "dataTableVariants" ], "source": "packages/ui/src/organisms/data-table", "axes": [ { "axis": "density", "part": null, "values": [ "compact", "comfortable" ], "default": null, "meaning": null }, { "axis": "selection", "part": null, "values": [ "none", "multiple" ], "default": null, "meaning": null } ], "needs": [ { "need": "Table", "answer": "`DataTable`, or `TableHeader` + `TableRow` + `TablePagination`" }, { "need": "A chart (trend, comparison, part to whole)", "answer": "`Chart` with the `form` the data's job names (`dataviz.yaml`); a single number is a `MetricCard`, many classes a `DataTable`" } ], "patterns": [ "Patterns/Density & Growth · DensityLevels", "Patterns/Density & Growth · ContentGrowth", "Patterns/Navigation · PaginationForDatasets", "Patterns/Feedback · LoadingFeedback", "Patterns/Information Architecture · MetadataAndActions", "Patterns/Visual Priority · QuietSecondaryActions", "Patterns/Decision Matrix · ComponentChoice", "Patterns/System States · StateChoice" ], "a11yExceptions": [], "decisions": [ { "id": "ADR-003", "title": "Storybook editorial convention and pattern↔component bidirectionality" }, { "id": "ADR-004", "title": "Migrate boolean configuration props to semantic axes" }, { "id": "ADR-005", "title": "Visual operational rules: surfaces, interaction, motion" }, { "id": "ADR-006", "title": "Geometry and typography signature" }, { "id": "ADR-013", "title": "PageShell: mobile-nav polymorphism" }, { "id": "ADR-034", "title": "Accessible names come from a labels provider" }, { "id": "ADR-035", "title": "Motion grammar: the gate before motion, slop by repetition, and what reduced motion keeps" } ], "stories": [ { "name": "Playground", "id": "components-organisms-datatable--playground", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-organisms-datatable--playground", "frame": "/iframe.html?id=components-organisms-datatable--playground&viewMode=story" }, { "name": "Loading", "id": "components-organisms-datatable--loading", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-organisms-datatable--loading", "frame": "/iframe.html?id=components-organisms-datatable--loading&viewMode=story" }, { "name": "Empty", "id": "components-organisms-datatable--empty", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-organisms-datatable--empty", "frame": "/iframe.html?id=components-organisms-datatable--empty&viewMode=story" }, { "name": "With filters", "id": "components-organisms-datatable--with-filters", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-organisms-datatable--with-filters", "frame": "/iframe.html?id=components-organisms-datatable--with-filters&viewMode=story" }, { "name": "With pagination", "id": "components-organisms-datatable--with-pagination", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-organisms-datatable--with-pagination", "frame": "/iframe.html?id=components-organisms-datatable--with-pagination&viewMode=story" }, { "name": "Selectable rows", "id": "components-organisms-datatable--selectable-rows", "interaction": false, "snapshots": [ "dark", "high-contrast", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-organisms-datatable--selectable-rows", "frame": "/iframe.html?id=components-organisms-datatable--selectable-rows&viewMode=story" }, { "name": "Dense", "id": "components-organisms-datatable--dense", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-organisms-datatable--dense", "frame": "/iframe.html?id=components-organisms-datatable--dense&viewMode=story" }, { "name": "Row actions", "id": "components-organisms-datatable--row-actions", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-organisms-datatable--row-actions", "frame": "/iframe.html?id=components-organisms-datatable--row-actions&viewMode=story" }, { "name": "Status column", "id": "components-organisms-datatable--status-column", "interaction": false, "snapshots": [ "dark", "high-contrast", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-organisms-datatable--status-column", "frame": "/iframe.html?id=components-organisms-datatable--status-column&viewMode=story" }, { "name": "Full example", "id": "components-organisms-datatable--full-example", "interaction": false, "snapshots": [ "dark", "light" ], "skipsSnapshot": false, "docs": "/?path=/story/components-organisms-datatable--full-example", "frame": "/iframe.html?id=components-organisms-datatable--full-example&viewMode=story" } ], "storyFile": "tooling/storybook/stories/components/organisms/data-table.stories.tsx" }