@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/table.md

@@ -0,0 +1,436 @@
+# Table
+
+> Displays rows and columns of data. A set of composable parts (header, body, footer, row, column header, cell, caption) with sortable column headers, a selected row state, and wrappable cells, plus two TanStack-independent companions — a pagination bar (TablePagination) and a show/hide-columns menu (TableViewOptions) — and two headless hooks (useSortState, useTableUrlState). Ported from the legacy shadcn-uikit `Table` and informed by the pre-release Table design; themed by the `--ui-table-*` token tier. The TanStack-backed data grid (`DataTable`) composes these primitives.
+
+**Status:** draft · **Category:** data-display · **Since:** v0.10.0
+
+## Import
+
+```tsx
+import { Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableSelectCell, TableActionsCell, TableSettingsCell, TableCaption, TablePagination, TableViewOptions, useSortState, useTableUrlState } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead sortable sortDirection={dir} onSort={toggleSort}>
+        Name
+      </TableHead>
+      <TableHead>Status</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow selected={isSelected}>
+      <TableCell>web-server-01</TableCell>
+      <TableCell wrap>{longDescription}</TableCell>
+      <TableCell><Tag>Protected</Tag></TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+<TablePagination
+  pageIndex={pageIndex}
+  pageCount={pageCount}
+  pageSize={pageSize}
+  onPageIndexChange={setPageIndex}
+  onPageSizeChange={setPageSize}
+/>
+```
+
+Displays rows and columns of data. Composable from native table parts, with
+sortable column headers, a selected row state, wrappable cells, fixed-width
+leading selection and trailing actions/settings cells, and — as
+TanStack-independent companions — a pagination bar and a show/hide-columns
+menu. Two headless hooks (`useSortState`, `useTableUrlState`) supply optional
+sort and URL-synced state.
+
+> **Status: draft (design-pending v1).** Ported from the legacy
+> `@acronis-platform/shadcn-uikit` `Table` and informed by the pre-release Table
+> design (shadcn-uikit Figma, node 2948-2416). Themed by the existing
+> `--ui-table-*` token tier. The TanStack-backed **`DataTable`** (sorting,
+> selection, pagination over these primitives) now ships alongside — also draft
+> — and composes these parts. Reconcile with
+> `/figma-component Table <url> --update` once the design is ready for dev.
+
+## When to use
+
+- Showing structured, comparable data in rows and columns (lists of workloads,
+  invoices, devices, …).
+- When you need sortable columns and/or row selection on top of native table
+  semantics.
+- When you want the pagination bar or the show/hide-columns menu without pulling
+  in `@tanstack/react-table` — pair the parts with your own or the
+  `useSortState` / `useTableUrlState` hooks.
+
+## When not to use
+
+- For a full data grid whose state (sorting/filtering/pagination/selection/
+  column resizing/sticky columns) is managed for you — use the `DataTable`,
+  which composes these primitives.
+- For non-tabular layout — use CSS grid/flex, not a table.
+
+## Parts
+
+| Part                | Element   | Purpose                                                                                                                     |
+| ------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `Table`             | `table`   | The table, in a horizontally scrollable container.                                                                          |
+| `TableHeader`       | `thead`   | Column-header section.                                                                                                      |
+| `TableBody`         | `tbody`   | Data rows section.                                                                                                          |
+| `TableFooter`       | `tfoot`   | Summary section with a top divider.                                                                                         |
+| `TableRow`          | `tr`      | A row; `selected` applies the active state.                                                                                 |
+| `TableHead`         | `th`      | Column header; `sortable` + `sortDirection` + `onSort`; `wrap`.                                                             |
+| `TableCell`         | `td`      | A data cell; `wrap` lets it grow to fit multi-line content.                                                                 |
+| `TableSelectCell`   | `td`/`th` | 32px leading selection cell for a `Checkbox`; `header` renders the select-all `th`.                                         |
+| `TableActionsCell`  | `td`      | 48px trailing cell for a row's overflow trigger; owns the hover/press tint and focus ring.                                  |
+| `TableSettingsCell` | `th`      | 48px trailing header cell for the column-settings trigger.                                                                  |
+| `TableCaption`      | `caption` | Optional caption below the table.                                                                                           |
+| `TablePagination`   | `div`     | Plain-prop pagination bar (no TanStack dependency).                                                                         |
+| `TableViewOptions`  | `div`     | Show/hide-columns dropdown driven by a plain columns array. `iconOnly` gives the cog trigger that fits `TableSettingsCell`. |
+
+## Hooks
+
+Headless helpers for the `Table` primitives — no TanStack dependency, no visual
+output. They drive the parts' props and own the state.
+
+| Hook               | Purpose                                                                                                                                                             |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useSortState`     | Client-side single-column sort. Returns `sortedData` + `getSortDirection` / `toggleSort` shaped for `TableHead`.                                                    |
+| `useTableUrlState` | Syncs pagination / sorting / column-filter state to and from the URL query string (namespaced `tbl_*` keys) via `history.pushState` + `popstate` — router-agnostic. |
+
+## Examples
+
+```tsx
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableHead,
+  TableCell,
+  TableSelectCell,
+  TableActionsCell,
+  TableSettingsCell,
+  TablePagination,
+  TableViewOptions,
+  ButtonIcon,
+  Checkbox,
+  Tag,
+} from '@acronis-platform/ui-react';
+import { useSortState } from '@acronis-platform/ui-react'; // headless hook
+import { EllipsisIcon } from '@acronis-platform/icons-react/stroke-mono';
+
+// Sortable header driven by the headless sort hook
+const { sortedData, getSortDirection, toggleSort } = useSortState({ data });
+
+<TableHead
+  sortable
+  sortDirection={getSortDirection('name')}
+  onSort={() => toggleSort('name')}
+>
+  Name
+</TableHead>
+
+// Wrappable cell — grows to fit multi-line content instead of truncating
+<TableCell wrap>{longDescription}</TableCell>
+
+// Header row — select-all cell leading, column-settings cell trailing
+<TableRow>
+  <TableSelectCell header>
+    <Checkbox checked={allChecked} onCheckedChange={toggleAll} aria-label="Select all" />
+  </TableSelectCell>
+  <TableHead>Name</TableHead>
+  <TableSettingsCell>
+    <TableViewOptions iconOnly columns={columns} onToggle={toggleColumn} />
+  </TableSettingsCell>
+</TableRow>
+
+// Selectable row, with the trailing overflow-actions cell
+<TableRow selected={checked}>
+  <TableSelectCell>
+    <Checkbox checked={checked} onCheckedChange={setChecked} aria-label="Select row" />
+  </TableSelectCell>
+  <TableCell>web-server-01</TableCell>
+  <TableCell><Tag>Protected</Tag></TableCell>
+  <TableActionsCell bulkSelectionActive={bulkSelectionActive}>
+    <ButtonIcon aria-label="Row actions"><EllipsisIcon /></ButtonIcon>
+  </TableActionsCell>
+</TableRow>
+
+// Pagination bar — plain props, no TanStack
+<TablePagination
+  pageIndex={pageIndex}
+  pageCount={pageCount}
+  pageSize={pageSize}
+  totalRows={rows.length}
+  onPageIndexChange={setPageIndex}
+  onPageSizeChange={setPageSize}
+/>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `selected` | `boolean` | `false` | no | On a row — marks it selected (active row token + `data-state="selected"`). |
+| `sortable` | `boolean` | `false` | no | On a column header — renders a focusable sort affordance and exposes `aria-sort`. |
+| `sort-direction` | `'asc' | 'desc' | false` | `false` | no | On a sortable column header — the current sort direction (`false` = sortable but unsorted). Drives the sort icon and `aria-sort`. |
+| `wrap` | `boolean` | `false` | no | On a cell or column header — allow the content to wrap onto multiple lines (`whitespace-normal`) and drop the fixed row height so the cell grows to fit multi-line content instead of truncating. |
+| `header` | `boolean` | `false` | no | On the select-cell — render the header's select-all cell (`<th>`) instead of a row's selection cell (`<td>`). |
+| `bulk-selection-active` | `boolean` | `false` | no | On the actions-cell — suppress this row's actions because a *bulk* selection is in play: the cell keeps its 48px column (so the grid doesn't reflow) but renders no children and no hover/press tint. The threshold is one or more rows being selected — a single selected row is already a bulk selection and loses its row actions. With a TanStack table, pass `isBulkSelectionActive(table)` (from the data-table part) instead of re-deriving it. |
+| `page-index` | `number` | — | yes | On the pagination part — the zero-based index of the current page. |
+| `page-count` | `number` | — | yes | On the pagination part — the total number of pages. |
+| `page-size` | `number` | — | yes | On the pagination part — the number of rows shown per page. |
+| `page-size-options` | `number[]` | `[10, 20, 30, 40, 50]` | no | On the pagination part — the page-size options offered in the rows-per-page select. |
+| `total-rows` | `number` | — | no | On the pagination part — total rows across all pages (drives the summary text). |
+| `selected-rows` | `number` | — | no | On the pagination part — number of currently selected rows (drives the selection summary text). |
+| `columns` | `{ id: string; label: string; hidden: boolean }[]` | — | yes | On the view-options part — the toggleable columns and their current visibility. |
+| `rows-per-page-label` | `string` | `'Rows per page'` | no | On the pagination part — label of the rows-per-page select (also its accessible name). Override to localize. |
+| `first-page-label` | `string` | `'Go to first page'` | no | On the pagination part — accessible name of the first-page control. |
+| `previous-page-label` | `string` | `'Go to previous page'` | no | On the pagination part — accessible name of the previous-page control. |
+| `next-page-label` | `string` | `'Go to next page'` | no | On the pagination part — accessible name of the next-page control. |
+| `last-page-label` | `string` | `'Go to last page'` | no | On the pagination part — accessible name of the last-page control. |
+| `page-label` | `(page: number, pageCount: number) => string` | `(page, count) => count === 0 ? 'No pages' : `Page ${page} of ${count}`` | no | On the pagination part — builds the page indicator from the 1-based page number and the total page count. |
+| `summary-label` | `(selectedRows: number | undefined, totalRows: number) => string | null` | `(selected, total) => selected != null ? `${selected} of ${total} row(s) selected.` : `${total} row(s).`` | no | On the pagination part — builds the leading row summary. Return `null` for no summary. |
+| `trigger-label` | `ReactNode` | `'View'` | no | On the view-options part — the trigger button label. Ignored when `icon-only` is set. |
+| `icon-only` | `boolean` | `false` | no | On the view-options part — render the trigger as a cog-only icon button instead of a labelled button: the shape that fits the 48px `TableSettingsCell` column. |
+| `trigger-aria-label` | `string` | `'Column settings'` | no | On the view-options part — accessible name of the `icon-only` trigger. Override to localize. |
+| `menu-label` | `ReactNode` | `'Toggle columns'` | no | On the view-options part — the dropdown heading. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `sort` | `void` | Fired when a sortable header is activated by click / Enter / Space (React: `onSort`). The consumer owns the sorting logic and updates `sort-direction`. |
+| `page-index-change` | `number` | On the pagination part — fired with the next zero-based page index (React: `onPageIndexChange`). |
+| `page-size-change` | `number` | On the pagination part — fired with the next page size (React: `onPageSizeChange`). |
+| `toggle` | `string` | On the view-options part — fired with the column id whose visibility was toggled (React: `onToggle`). |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The composed table. Author it from the parts: a header (rows of column headers), a body (rows of cells), an optional footer, and an optional caption. Cell content (text, tags, links, checkboxes, …) is arbitrary. |
+
+## Behavior
+
+Table is a composable, presentational data grid. It holds no sorting or
+selection _logic_ — the consumer owns that and drives the relevant props. The
+scenarios below describe the affordances the parts provide.
+
+### Sorting
+
+```gherkin
+Scenario: A sortable header exposes its state
+  Given a TableHead with sortable = true and sort-direction = false
+  Then it renders an inactive sort icon and aria-sort = "none"
+```
+
+```gherkin
+Scenario: Activating a sortable header
+  Given a sortable TableHead with an onSort handler
+  When the user clicks it (or focuses it and presses Enter / Space)
+  Then the sort event fires
+  And the consumer updates sort-direction, which swaps the icon (↑ asc / ↓ desc)
+  and sets aria-sort to "ascending" / "descending"
+```
+
+### Selection
+
+```gherkin
+Scenario: A selected row
+  Given a TableRow with selected = true
+  Then it carries data-state="selected" and the active row background token
+```
+
+```gherkin
+Scenario: Row selection is consumer-driven
+  Given a checkbox rendered inside a leading TableSelectCell
+  When the user toggles it
+  Then the consumer updates the row's selected prop (Table does not manage it)
+```
+
+```gherkin
+Scenario: The select cell renders for a header or a row
+  Given a TableSelectCell
+  When header = true
+  Then it renders a <th> (the select-all cell) with the header cell background
+  When header is omitted
+  Then it renders a <td> with the data cell background
+  And either way it keeps its fixed 32px width and inline-start-only padding, so
+  the checkbox sits flush against the first data cell
+```
+
+### Row actions and column settings
+
+```gherkin
+Scenario: The row-actions cell owns the interaction feedback
+  Given a TableActionsCell holding an overflow trigger
+  When the pointer is over it
+  Then the cell itself takes the hover tint (and the press tint on :active)
+  And a focus-visible trigger inside it draws the cell's inset focus ring
+```
+
+```gherkin
+Scenario: Row actions step aside for bulk actions
+  Given a TableActionsCell with bulk-selection-active = true
+  Then it renders no children and no hover/press tint
+  And it still reserves its 48px column, so the grid does not reflow
+  # The threshold itself is the consumer's call — with a TanStack table, pass
+  # isBulkSelectionActive(table) rather than re-deriving it (see api.yaml).
+```
+
+```gherkin
+Scenario: The settings cell holds the column-settings trigger
+  Given a TableSettingsCell in the header row
+  Then it renders a 48px end-aligned <th> that tints on hover/press and draws
+  the inset focus ring for a focus-visible trigger inside it
+  And what the trigger opens is the consumer's choice — TableViewOptions with
+  iconOnly is the ready-made cog + column-visibility menu
+```
+
+### Layout
+
+```gherkin
+Scenario: Overflow scrolls horizontally
+  Given a table wider than its container
+  When it renders
+  Then the wrapping container scrolls horizontally, keeping the page intact
+```
+
+```gherkin
+Scenario: Hover feedback
+  Given a row in the body
+  When the pointer is over it
+  Then it takes the hover background token (unless selected, which wins)
+```
+
+```gherkin
+Scenario: A wrapping cell grows the row
+  Given a TableCell (or TableHead) with wrap = true holding multi-line content
+  When it renders
+  Then it uses whitespace-normal and drops the fixed row height
+  And the row grows to fit the content instead of truncating it
+```
+
+### Pagination (TablePagination)
+
+TablePagination is a controlled, TanStack-independent bar. It renders from plain
+props and never holds page state itself.
+
+```gherkin
+Scenario: Page controls report the range
+  Given a TablePagination with page-index, page-count, page-size
+  Then it shows "Page {page-index + 1} of {page-count}"
+  And first/prev are disabled on the first page, next/last on the last page
+```
+
+```gherkin
+Scenario: Changing the page
+  Given a TablePagination
+  When the user clicks first / prev / next / last
+  Then the page-index-change event fires with the target zero-based index
+  When the user picks a rows-per-page option
+  Then the page-size-change event fires with that size
+```
+
+```gherkin
+Scenario: Selection summary
+  Given a TablePagination with total-rows and selected-rows
+  Then it shows "{selected-rows} of {total-rows} row(s) selected."
+```
+
+### View options (TableViewOptions)
+
+```gherkin
+Scenario: Toggling column visibility
+  Given a TableViewOptions with a { id, label, hidden }[] of columns
+  When the user toggles a column's checkbox in the dropdown
+  Then the toggle event fires with that column's id
+  And the consumer updates the column's hidden flag
+```
+
+```gherkin
+Scenario: The icon-only trigger fits the settings cell
+  Given a TableViewOptions with icon-only = true
+  Then its trigger is a cog-only icon button named by trigger-aria-label
+  ("Column settings" by default), the shape that fits the 48px settings cell
+  And the trigger-label is ignored in that form
+```
+
+### Headless state hooks
+
+```gherkin
+Scenario: useSortState drives a sortable header
+  Given useSortState({ data })
+  When a header calls toggleSort(columnId)
+  Then the sort cycles none → asc → desc → none
+  And sortedData reflects the current column + direction (alphanumeric by default)
+  And getSortDirection(columnId) returns the value for TableHead's sort-direction
+```
+
+```gherkin
+Scenario: useTableUrlState writes to the URL
+  Given useTableUrlState()
+  When the consumer advances the page via setPagination
+  Then the namespaced tbl_page param is pushed onto the URL (history.pushState)
+```
+
+```gherkin
+Scenario: useTableUrlState restores from the URL
+  Given a URL that already carries tbl_page / tbl_sort params
+  When the hook mounts
+  Then it seeds its initial state from those params
+  And a browser back/forward (popstate) re-syncs the state to the URL
+```
+
+## Accessibility
+
+Table renders native table semantics (`<table>`/`<thead>`/`<tbody>`/`<tr>`/
+`<th>`/`<td>`/`<caption>`), so assistive tech announces rows, columns, and
+headers natively. Use the parts as their elements intend.
+
+## Roles & semantics
+
+- The root is a native `<table>` (role `table`); `<th>` are column headers
+  (role `columnheader`), `<td>` are cells (role `cell`).
+- Provide a `TableCaption` (or an `aria-label`/`aria-labelledby` on the table)
+  so the table has an accessible name.
+- For row/column header association in complex tables, set `scope="col"` /
+  `scope="row"` on the relevant `<th>` (passes through as a native attribute).
+
+## Sorting
+
+- A `sortable` `TableHead` sets **`aria-sort`** on the `<th>`: `none` when
+  unsorted, `ascending` / `descending` when sorted — so screen readers announce
+  the current sort.
+- The sort affordance is a real **`<button>`**, so it is reachable by Tab and
+  activates with **Enter / Space**; it shows a `--ui-focus-primary` focus ring.
+
+## Selection
+
+- Selection is expressed by rendering a `Checkbox` in a leading cell; label it
+  (`aria-label`) and use an `aria-label="Select all"` checkbox in the header.
+- A selected `TableRow` sets `data-state="selected"` for styling — pair it with
+  the checkbox's checked state so the visual and programmatic states agree.
+
+## Pagination & view options
+
+- `TablePagination`'s page controls are icon buttons with explicit labels ("Go
+  to first page" / "…previous page" / "…next page" / "…last page"); the
+  rows-per-page control is a labelled `Select` ("Rows per page"). Disabled
+  buttons at the range ends carry the native `disabled` state.
+- `TableViewOptions` is a Base UI dropdown menu (keyboard-navigable) of checkbox
+  items; each row shows a presentational checkbox box beside the column name and
+  the row itself carries `role="menuitemcheckbox"` + `aria-checked`. The trigger
+  has a visible "View" label, or — with `iconOnly` — is a cog-only icon button
+  named by `triggerAriaLabel` (default "Column settings").
+
+## Contrast
+
+- Cell text uses `--ui-table-data-value-color-idle`, headers
+  `--ui-table-header-label-color`, dividers `--ui-table-global-row-border-color`;
+  row hover/active use `--ui-table-data-row-color-{hover,active}`. These meet
+  WCAG AA against the page surface in light and dark themes. Re-verify against
+  the final palette once the design is confirmed ready for dev.

package/dist/llms/tabs.md

@@ -0,0 +1,197 @@
+# Tabs
+
+> Switches between related panels of content within the same context. A bordered segmented-control tab group (list, trigger, content) built on the Base UI Tabs primitive. Ported from the legacy shadcn-uikit `Tabs`; themed by the shared semantic tokens (no `--ui-tabs-*` tier yet).
+
+**Status:** draft · **Category:** navigation · **Since:** v0.11.0
+
+## Import
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Tabs defaultValue="account">
+  <TabsList>
+    <TabsTrigger value="account">Account</TabsTrigger>
+    <TabsTrigger value="password">Password</TabsTrigger>
+  </TabsList>
+  <TabsContent value="account">Account settings</TabsContent>
+  <TabsContent value="password">Password settings</TabsContent>
+</Tabs>
+```
+
+Switches between related panels of content within the same context. A bordered
+segmented-control tab group built on the Base UI Tabs primitive.
+
+> **Status: draft (design-pending v1).** Ported from the legacy
+> `@acronis-platform/shadcn-uikit` `Tabs`. No `--ui-tabs-*` token tier yet, so
+> the segments use the shared brand tokens — the **`secondary`** bridge (the same
+> action blue Button uses), not `primary` (which is the dark navy brand). The
+> active segment is rendered **filled** (`bg-secondary` + a pure-white
+> `text-primary-foreground` label, like the default Button); the legacy
+> `bg-primary/10` tint was dropped to avoid an opacity hack — the final treatment
+> (filled vs tinted vs underline) is to be confirmed. Reconcile with
+> `/figma-component Tabs <url> --update` once a mockup lands.
+
+## When to use
+
+- Letting the user switch between a few peer views of the same area (Account /
+  Password; Overview / Analytics / Reports) without navigating away.
+
+## When not to use
+
+- For navigation between pages/routes — use links or a nav, not tabs.
+- For more tabs than fit comfortably in a segmented strip — consider a
+  different navigation pattern.
+- For sequential steps — use a wizard/stepper.
+
+## Parts
+
+| Part          | Element              | Purpose                                    |
+| ------------- | -------------------- | ------------------------------------------ |
+| `Tabs`        | `div` (Root)         | Owns the selected value and orientation.   |
+| `TabsList`    | `div[role=tablist]`  | The segmented strip of triggers.           |
+| `TabsTrigger` | `button[role=tab]`   | A tab; identified by `value`.              |
+| `TabsContent` | `div[role=tabpanel]` | A panel; shown when its `value` is active. |
+
+## Example
+
+```tsx
+import {
+  Tabs,
+  TabsList,
+  TabsTrigger,
+  TabsContent,
+} from '@acronis-platform/ui-react';
+
+<Tabs defaultValue="account" className="w-[400px]">
+  <TabsList className="grid w-full grid-cols-2">
+    <TabsTrigger value="account">Account</TabsTrigger>
+    <TabsTrigger value="password">Password</TabsTrigger>
+  </TabsList>
+  <TabsContent value="account">Make changes to your account here.</TabsContent>
+  <TabsContent value="password">Change your password here.</TabsContent>
+</Tabs>;
+```
+
+Controlled:
+
+```tsx
+const [tab, setTab] = useState('account');
+
+<Tabs value={tab} onValueChange={setTab}>
+  {/* … */}
+</Tabs>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `string` | — | no | Controlled selected-tab value. Pair with the change event. |
+| `default-value` | `string` | — | no | Initially selected tab value when uncontrolled. |
+| `orientation` | `'horizontal' | 'vertical'` | `'horizontal'` | no | Layout and arrow-key navigation orientation. |
+| `tab-value` | `string` | — | yes | On a trigger and its content — the identifier that links them and is emitted on selection. A trigger also accepts a `disabled` flag (pass-through to the underlying tab) to prevent selecting it. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `value-change` | `string` | Fired when the selected tab changes (React: `onValueChange`). Payload is the newly selected tab value. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | A `list` of `trigger`s followed by one `content` panel per tab. Each trigger and its panel share a `tab-value`. |
+
+## Behavior
+
+Tabs shows one panel at a time and lets the user switch between them. It owns
+the selected-tab state (or the consumer controls it via `value`).
+
+### Selecting
+
+```gherkin
+Scenario: Activating a tab by pointer
+  Given a tab group with the first tab selected
+  When the user clicks another trigger
+  Then that trigger becomes active (data-active, aria-selected="true")
+  And its content panel replaces the previous one
+  And value-change fires with the new value
+```
+
+```gherkin
+Scenario: Keyboard navigation (manual activation)
+  Given focus is on the active trigger
+  When the user presses Arrow keys (per orientation)
+  Then focus moves between triggers without changing the selection
+  And pressing Enter or Space activates the focused trigger
+```
+
+### Controlled vs uncontrolled
+
+```gherkin
+Scenario: Uncontrolled with default-value
+  Given a Tabs with default-value = "account" and no value prop
+  When it mounts
+  Then the "account" tab is selected and the user can switch freely
+```
+
+```gherkin
+Scenario: Controlled
+  Given a Tabs with a fixed value prop
+  When the user activates another tab
+  Then the selection does NOT change on its own
+  And value-change fires so the consumer can update value
+```
+
+### Orientation
+
+```gherkin
+Scenario: Vertical orientation
+  Given a Tabs with orientation = "vertical"
+  Then Up/Down arrows move between triggers (instead of Left/Right)
+```
+
+## Accessibility
+
+Tabs leans on the Base UI Tabs primitive for the WAI-ARIA tabs pattern: roles,
+selection state, roving focus, and keyboard navigation.
+
+## Roles & semantics
+
+- `TabsList` is `role="tablist"`; `TabsTrigger` is `role="tab"`; `TabsContent`
+  is `role="tabpanel"`.
+- The active trigger exposes `aria-selected="true"` (and `data-active` for
+  styling); its panel is associated via `aria-controls` / `aria-labelledby`.
+- Set `orientation="vertical"` so `aria-orientation` and arrow-key handling match
+  a vertical strip.
+
+## Keyboard
+
+- **Tab** moves into the tablist (one stop — roving tabindex), then into the
+  active panel.
+- **Arrow keys** (Left/Right when horizontal, Up/Down when vertical) move focus
+  between triggers **without** activating them (manual activation).
+- **Enter / Space** activates the focused trigger.
+- **Home / End** move to the first / last trigger.
+
+## Screen reader
+
+- Entering the tablist announces the tab role, the selected state, and the
+  position ("tab 1 of 2"). Activating a tab announces the newly selected tab and
+  its panel.
+
+## Contrast
+
+- Idle triggers use the brand action blue for border + label
+  (`--ui-background-brand-secondary`, the same blue Button uses); the active
+  trigger fills with that blue and uses a pure-white label
+  (`--ui-glyph-on-brand-primary`, like the default Button), and shows a
+  `--ui-focus-primary` ring on keyboard focus — all meeting WCAG AA in light and
+  dark. Re-verify against the final palette once a `--ui-tabs-*` tier and Figma
+  reference exist (the filled-vs-tinted active treatment is provisional).