--- name: table-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit Table for semantic tabular data with caption, header, body, footer, rows, column headers, numeric cells, selected rows, variants, interactive rows, sticky header/first column, column borders, and size props. metadata: component_version: "2.0.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "" contributor_sources: "libs/ui/src/organisms/table.tsx libs/ui/src/tokens/components/organisms/_table.css libs/ui/stories/organisms/table.stories.tsx" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit Table Usage Use Table for semantic tabular data. Do not use div grids for data tables when table semantics are needed. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `Table`. **Use it when** - Static or lightly interactive tabular data: invoice lines, order items, spec sheets, comparison tables. **Use something else when** | Need | Use instead | | --- | --- | | Sorting, filtering, selection, paging, inline edit | DataTable | | Layout of non-tabular content | grid/flex layout | | Trends | Chart | **Do** - Use `numeric` on number/money cells and their headers so they end-align; add `tabular-nums` (ux-guidelines/formatting#alignment-in-tables). - Keep precision equal within a column; totals row repeats alignment with a top border. - Render missing values as `—`; format dates/numbers with `Intl`. - Add a caption or heading that names the data. **Don't** - Use `$` + `toFixed(2)` or raw ISO dates in cells. - Center numeric columns or mix alignments between header and cells. **Copy and states** - Column headers short nouns with units (`Qty`, `Unit price (€)`). **Behaviour (from the UX spec)** - Links or buttons in cells don't make a Table a grid; keep normal tab order and no `role="grid"`. - If the data isn't comparable by column, use cards or a list, not Table. - One click never both selects a row and opens its detail; no data, no matches and a failed load get different messages. **Figma → code** | Figma | Code | | --- | --- | | `appearance=line\|outline\|striped`, `size=sm…lg` | `appearance` (same values), `size` | | — | `interactive`, `stickyHeader`, `stickyFirstColumn`, `showColumnBorder`, `captionPlacement`, `Row selected` (code only) | | Toolbar, FilterRow, PaginationBar in the Table doc | `DataTable`, not Table | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Organisms/Table → UX guidelines*. ## Setup ```tsx Orders OrderTotal #1001{money.format(129)}
``` Supported props: ```text appearance: line | outline | striped size: sm | md | lg interactive, stickyHeader, stickyFirstColumn, showColumnBorder captionPlacement: top | bottom Row selected ColumnHeader/Cell numeric, data-align: start | center | end parts: Caption, Header, Body, Footer, Row, ColumnHeader, Cell ``` ## Core Patterns ### Use semantic table parts Use Table.Header/Body/Footer and ColumnHeader/Cell rather than div grids. ### Mark numeric columns Use `numeric` on headers and cells for right alignment. It asserts that the value *is* a number, so keep it for money, counts and measures. ### Align a column deliberately `data-align="start | center | end"` on a ColumnHeader/Cell is a pure presentation choice — reach for it when the column is not numeric, e.g. a centred icon, status or boolean column. ```tsx In stock {inStock ? 'Yes' : 'No'} ``` Set `numeric` or `data-align`, not both — combining them with conflicting directions leaves the winner up to stylesheet order. ### Use selected/interactive props Use `selected` on rows and `interactive` on the root; do not add hover/selected classes to rows. ## Common Mistakes ### HIGH Div-based data table Wrong: ```tsx
Order
Total
``` Correct: ```tsx Order
``` Source: libs/ui/src/organisms/table.tsx ### HIGH Inline row/cell styling Wrong: ```tsx ``` Correct: ```tsx
``` Source: libs/ui/src/tokens/components/organisms/_table.css ### MEDIUM Numeric alignment via class Wrong: ```tsx {total} ``` Correct: ```tsx {total} ``` Source: libs/ui/src/organisms/table.tsx ## Validation Commands ```sh rg -n "grid-cols.*(Order|Total|Price)|]*className=.*(hover:|border-|text-right|p-)" apps rg -n "]*className=\"[^\"]*text-right|]*className=\"[^\"]*text-right" apps rg -n "]*(variant=|appearance=\"(default|bordered)\")|captionPlacement=\"(left|right)\"" apps ``` ## Wave 2 contracts All Table ref props accept React Ref, including createRef() objects and callback refs. With interactive=true, rows that supply onClick join the tab order and activate with Enter or Space; keyboard events from nested controls do not activate the row. Provide a visible destination/action label and do not rely on row hover alone. A caller may override tabIndex/onKeyDown; preventDefault cancels built-in activation. Canonical sizes are sm/md/lg (default md). Wrap wide tables in a labelled, keyboard-focusable `overflow-x-auto` region. Keep native table semantics; do not force block layout on rows or allow the entire page to overflow on mobile. Table.Row selected exposes aria-selected as well as the visual data-selected state. Keep selection in application state and supply selected on each selectable row, including false for rows that are not selected. Frozen first cells composite the row stripe/hover/selection tint over an opaque table surface; other body cells remain transparent so row-level styling is preserved.