@cueplusplus/ui 0.13.0

package/manifest/components/switch.json

@@ -0,0 +1,102 @@
+{
+  "name": "Switch",
+  "slug": "switch",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A binary on/off control — `role=\"switch\"`, not a checkbox.\n\nThe distinction matters to assistive tech: a switch takes effect immediately,\na checkbox is a value you submit later. Use this for \"live\" state (blackout,\nmute, follow) and {@link Checkbox } for form values.\n\nShips in three sizes down to a 22×12 track, because a dense console cannot\nspare the height a stock switch demands. The thumb slides on a transform and\nstills entirely under `prefers-reduced-motion`.",
+  "props": [
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Inline label rendered beside the track and wrapped with it in a `<label>`,\nso the text is both the accessible name and part of the hit target.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the track defaults.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Track size. Defaults to `\"md\"` (28×14). `sm` exists because a console packs\nswitches into 20px rows where a stock 44px switch simply does not fit.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "sm",
+          "md",
+          "lg"
+        ]
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseSwitch.Root.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-space-3",
+    "--cue-surface-3",
+    "--cue-text-ui"
+  ],
+  "summary": "A binary control that takes effect the moment it moves.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Switch label=\"Blackout\" checked={blackout} onCheckedChange={setBlackout} />\n<Switch aria-label=\"Mute channel\" size=\"sm\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/switch",
+  "mdUrl": "/docs/components/switch.md",
+  "jsonUrl": "/r/components/switch.json",
+  "whenToUse": [
+    "Live state: blackout, mute, follow, a feature flag that applies at once.",
+    "Dense rows. The `sm` track is 22x12, which fits a status bar without crowding it."
+  ],
+  "whenNotToUse": [
+    "A value a form submits later. Use `Checkbox`, which is what assistive tech expects there.",
+    "One choice out of several. Use `RadioGroup` or `SegmentedControl`."
+  ],
+  "commonMistakes": [
+    "Putting a Save button next to it. A switch has already taken effect.",
+    "Shipping it with no label and no `aria-label`, which leaves an unnamed toggle."
+  ],
+  "specimens": [
+    {
+      "title": "Switch",
+      "group": "forms",
+      "components": [
+        "Switch"
+      ],
+      "code": "<Specimens>\n  {([\"sm\", \"md\", \"lg\"] as const).map((size) => (\n    <Specimen key={size} label={size}>\n      <Switch size={size} label=\"Blackout\" defaultChecked />\n    </Specimen>\n  ))}\n  <Specimen label=\"off\">\n    <Switch label=\"Follow\" />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <Switch label=\"Locked\" disabled defaultChecked />\n  </Specimen>\n  <Specimen label=\"no label\">\n    <Switch aria-label=\"Highlight\" />\n  </Specimen>\n</Specimens>",
+      "note": "Three sizes, because a console row cannot afford the marketing-page switch.",
+      "interaction": "the whole label is the hit target; Space toggles."
+    }
+  ]
+}

package/manifest/components/table-scroll-region.json

@@ -0,0 +1,78 @@
+{
+  "name": "TableScrollRegion",
+  "slug": "table-scroll-region",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A named horizontal viewport for a table wider than its container.\n\nThe region is independently keyboard-focusable so keyboard users can reach\nnative horizontal scrolling. It adds no table semantics of its own; place a\ncompound {@link Table} inside it and keep the table's caption.",
+  "props": [
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Accessible name announced for the keyboard-focusable scrolling region.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"aria-label\" | \"role\" | \"tabIndex\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-hair-strong",
+    "--cue-pad-row-x",
+    "--cue-pad-row-y",
+    "--cue-row-hover",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-1",
+    "--cue-table-group-top",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A named keyboard-focusable horizontal viewport for wide semantic tables.",
+  "examples": [],
+  "status": "stable",
+  "url": "/docs/components/table-scroll-region",
+  "mdUrl": "/docs/components/table-scroll-region.md",
+  "jsonUrl": "/r/components/table-scroll-region.json",
+  "whenToUse": [
+    "A semantic table can be wider than its panel or mobile viewport.",
+    "Keyboard users need a reachable region for native horizontal scrolling."
+  ],
+  "whenNotToUse": [
+    "The table already fits its container. Render `Table.Root` directly.",
+    "Non-tabular content. Use `ScrollArea` for a general scrolling viewport."
+  ],
+  "commonMistakes": [
+    "Omitting `aria-label`; the scrolling region requires its own accessible name.",
+    "Using the region instead of `Table.Caption`; the region and table each keep their own name."
+  ],
+  "specimens": [
+    {
+      "title": "Table",
+      "group": "instruments",
+      "components": [
+        "Table",
+        "TableScrollRegion"
+      ],
+      "code": "<Panel className=\"w-full\">\n  <TableScrollRegion aria-label=\"Cue list table\">\n    <Table.Root>\n      <Table.Caption>Cue list</Table.Caption>\n      <Table.Header>\n        <Table.Row>\n          <Table.Head numeric>#</Table.Head>\n          <Table.Head>Label</Table.Head>\n          <Table.Head numeric>Fade</Table.Head>\n          <Table.Head>Follow</Table.Head>\n          <Table.Head numeric>Level</Table.Head>\n        </Table.Row>\n      </Table.Header>\n      <Table.Body>\n        {CUES.map((cue) => (\n          <Table.Row key={cue.id}>\n            <Table.Cell numeric>{cue.id}</Table.Cell>\n            <Table.Cell>{cue.label}</Table.Cell>\n            <Table.Cell numeric>{cue.time}</Table.Cell>\n            <Table.Cell>{cue.follow}</Table.Cell>\n            <Table.Cell numeric>{cue.level}%</Table.Cell>\n          </Table.Row>\n        ))}\n      </Table.Body>\n    </Table.Root>\n  </TableScrollRegion>\n</Panel>",
+      "note": "The canonical console table inside its named horizontal scroll region: hairline rows, mono headers, and `numeric` cells that are right-aligned and tabular.",
+      "interaction": "the scroll region is keyboard-focusable. Sorting, filtering and paging come from the DataTable recipe below."
+    }
+  ]
+}

package/manifest/components/table.json

@@ -0,0 +1,306 @@
+{
+  "name": "Table",
+  "slug": "table",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The canonical console table: hairlines, mono figures, no zebra striping.\n\nSemantic `<table>` markup throughout — a grid of divs loses row/column\nannouncement, and a console table is exactly the place a screen reader user\nneeds it. Zebra rows are deliberately absent: at console density the stripes\nare thicker than the data.\n\nStatic markup — no `\"use client\"`. Compose it with `Panel` for the rim.\nUse {@link TableScrollRegion} only when the table can exceed its container.\n\nFor a grouped list, the table stays *one* table: `Table.Head sticky` docks the\ncolumn names, and one `Table.Body` per group opens with a `Table.GroupRow`\ndivider — so the columns are named once and scan straight through every group\nboundary. Rows may hold `DataRow` slots, and `DataRow.Actions` reveals inside\na cell on hover and on selection exactly as it does in a `Ledger` row — on\nfocus too, once the row holds something focusable outside the track, which a\n`<tr>` never is by itself. See {@link TableRowProps.interactive}.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Header",
+    "Body",
+    "Row",
+    "GroupRow",
+    "Head",
+    "Cell",
+    "Caption"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Table.Root",
+      "description": "The table frame. Owns the type, the collapse and the numeric alignment rule.\n\n`data-numeric` is the contract, not a prop: the alignment and\n`tabular-nums` live in one descendant selector here, so a hand-written\n`<td data-numeric>` inside a data-driven body lines up exactly like a\n`<Table.Cell numeric>`. Figures that do not share a column width are\nunreadable as a column, which is the whole point of a table.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"table\">"
+      ]
+    },
+    {
+      "name": "Header",
+      "usage": "Table.Header",
+      "description": "The header band. Sticky-able by the caller; sized by the row padding tokens.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"tbody\">"
+      ]
+    },
+    {
+      "name": "Body",
+      "usage": "Table.Body",
+      "description": "The data band.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"tbody\">"
+      ]
+    },
+    {
+      "name": "Row",
+      "usage": "Table.Row",
+      "description": "One row, separated by a hairline underneath — dropped on the last row so the\ntable never draws a rule against the panel rim it sits in. In a `<thead>` the\n\"last row\" is the header row itself, so the header's own bottom border (on\nthe cells) is the only rule there and the two can never stack into 2px.\n\nEvery row carries the `group/data-row` name unconditionally. It paints\nnothing by itself, and it is what lets a `DataRow.Actions` cluster inside a\n`Table.Cell` reveal on hover, on focus and on selection with no second\nimplementation of that idiom for the table — the whole point of the three\nidioms sharing one row anatomy.\n\n**The focus half of that reveal is the caller's to supply here.** A `<tr>` is\nnot focusable and this component does not make it one — a tab stop on every\nrow of a long table is a tab stop a keyboard user has to walk past hundreds\nof times, which is the reason `Ledger` rows opt in individually. So the\nreveal-on-focus only happens if the row *contains* something focusable\noutside the hidden track: a link on the row's name, a checkbox in the leading\ncell, any real control. Without one, `:focus-within` can never fire — content\ninside a `visibility: hidden` subtree cannot be focused, so the track cannot\nbootstrap its own reveal — and a hidden action cluster is then reachable by\npointer only, which is a WCAG 2.1.1 failure the screen gives no sign of. A\ntable whose only per-row controls live in a hidden track wants either a\nfocusable cell beside it or an always-visible cluster.\n\nA caller who instead makes the *row* focusable — a `tabIndex` plus\n{@link activateRowFromClick } and {@link activateRowFromKeyDown }, which is the\nshape a row that opens a drawer takes — gets the focus ring from\n{@link TableRowProps.interactive} and needs to draw nothing of its own.\n\nThe selected tint is the row's, not the cell's: a `background` on the `<tr>`\nshows through every cell in it, so the fill cannot end up ragged where one\ncell sets a ground of its own.",
+      "props": [
+        {
+          "name": "interactive",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "The row responds to a pointer and to focus: the row-hover wash, a pointer\ncursor across the whole row, and an inset focus ring. Defaults to `false`.\n\nOpt-in rather than automatic, because a table of figures nobody can click\nthat lit up under the pointer would be promising an interaction it does not\nhave. Wiring the row up to actually do something — a click handler, a\nkeyboard path to the same thing — stays the caller's job; this is the paint.\n\n**The focus ring ships with it, because the caller's half is what makes the\nrow focusable.** A `<tr>` cannot take focus on its own, so the moment a\ncaller gives one a `tabIndex` to run\n{@link activateRowFromKeyDown } against, a keyboard user can reach and\nactivate a row that shows nothing — a WCAG 2.4.7 failure the pointer user\nnever sees. The ring is *inset* (`-outline-offset-2`), the same ruling as\n`Row` and `DataRow.Root`: these tables live in clipped panes and scroll\nregions, where an outset ring on the first or last row is cut off by the\npane's own rim. `outline-solid` rides along with every `outline-<n>` here\nbecause Tailwind v4 leaves `--tw-outline-style` unset otherwise and the\nring never paints — `test/focus-ring.test.ts` is what keeps the pair\ntogether.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "selected",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Draw the row as picked out of the table. Defaults to `false`.\n\nSets `data-selected`, which is what the tint and the hover-revealed\n`DataRow.Actions` inside the row both key off — so a hand-written\n`<tr data-selected>` in a data-driven body gets exactly the same treatment.",
+          "control": {
+            "kind": "boolean"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"tr\">"
+      ]
+    },
+    {
+      "name": "GroupRow",
+      "usage": "Table.GroupRow",
+      "description": "A group divider inside one continuous table.\n\nThe whole point is that it is *inside*: a grouped list drawn as one table per\ngroup names its columns once per group, so a reader scanning a column\ntop-to-bottom crosses a fresh header band at every boundary and a screen\nreader announces four tables where there is one dataset. So the table stays\none `<table>` with one `<thead>`, and each group is its own `<tbody>` — which\nis valid HTML, keeps the group's rows together, and gives the divider a row\ngroup to be the header of.\n\nThat last part is why the cell is a `<th scope=\"rowgroup\">` rather than a\nstyled `<td>`: `rowgroup` scope is exactly the statement \"this heading names\nthe rows of this `<tbody>`\", and it leaves the column headers' associations\nuntouched. A `<td colSpan>` divider is invisible to assistive technology as a\nheading, and a `<th scope=\"col\">` one would quietly re-scope the columns.\n\nNo `aria-expanded` here, and no toggle: groups in a table divide, they do not\nfold. A hierarchy that folds is `DataTree`, whose treeitem rows own their own\nexpansion — and if a table genuinely needs to fold rows, the pattern is a real\n`<button aria-expanded aria-controls>` inside this cell, never the row itself.\n\nThe divider can also be a real heading — see {@link * TableGroupRowProps.headingLevel}, which is how a page whose heading outline\nhas to survive a switch between the ledger, table and tree idioms keeps the\nsame `h2`/`h3` structure in all three.",
+      "props": [
+        {
+          "name": "span",
+          "type": "number",
+          "required": true,
+          "defaultValue": null,
+          "description": "How many columns the divider spans. Required: it must equal the table's\ncolumn count, or the group's cell stops covering the row and the columns\nbelow it shift by one.",
+          "control": {
+            "kind": "number"
+          }
+        },
+        {
+          "name": "label",
+          "type": "ReactNode",
+          "required": true,
+          "defaultValue": null,
+          "description": "What the group is called.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "headingLevel",
+          "type": "4 | 2 | 3 | 5 | 6",
+          "required": false,
+          "defaultValue": null,
+          "description": "Make the label slot a real heading element. Defaults to `undefined` — no\nheading, and the label stays the `<span>` it has always been.\n\n**Set this rather than passing a heading as `label`.** The label slot wraps\nwhatever it is given, so an `<h2>` handed in as `label` lands *inside* a\n`<span>` — which renders, and exposes the heading, and does not validate: a\n`<span>` is phrasing content and may not contain a heading. With this prop\nthe wrapper *is* the heading (`<h2 data-slot=\"table-group-label\">`), so\nthere is nothing to nest.\n\nA heading inside a `<th>` is valid — `<th>` takes flow content — and it is\nuseful: a screen-reader user navigates a long grouped table by heading, and\nwithout one the group names are reachable only by walking the rows. The\n`scope=\"rowgroup\"` association is untouched either way; this adds the\ndivider to the document outline, it does not change what the cell heads.\n\nLevels run `2`–`6` because the outline has to describe the real nesting of\nthe page the table sits in, not the table's own idea of itself — the same\nruling as {@link LedgerTierProps.headingLevel }. There is no `1`: a group\ndivider is never the title of the document.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              4,
+              2,
+              3,
+              5,
+              6
+            ],
+            "min": 2,
+            "max": 6
+          }
+        },
+        {
+          "name": "count",
+          "type": "number",
+          "required": false,
+          "defaultValue": null,
+          "description": "How many rows the group holds, printed beside its name.",
+          "control": {
+            "kind": "number"
+          }
+        },
+        {
+          "name": "sticky",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Dock the divider under the header band while the group's rows scroll past.\nDefaults to `false`.\n\nThe offset is the custom property `--cue-table-group-top` (default `0`):\nhow far down the divider docks is the rendered height of the sticky header\nabove it, which depends on the density and type the caller configured. Set\nit on the table — `className=\"[--cue-table-group-top:2rem]\"` — rather than\nmeasuring at runtime.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Classes for the divider's *cell*, not its row.\n\nThe `<tr>` paints nothing — the ground, the type and the sticky offset all\nlive on the `<th>` that spans it, and a background on the row would sit\nbehind the cell's own. Every other prop, and the ref, go to the row.",
+          "control": {
+            "kind": "string"
+          }
+        }
+      ],
+      "typeReferences": [
+        "Omit<React.ComponentPropsWithoutRef<\"tr\">, \"children\">"
+      ]
+    },
+    {
+      "name": "Head",
+      "usage": "Table.Head",
+      "description": "A column heading: the same mono uppercase label as `SectionHeader` and\n`Eyebrow`, on the raised surface so the band reads as chrome rather than as\nthe first row of data.\n\n**Sticky swaps the bottom border for an inset shadow.** `Table.Root` collapses\nits borders, and a collapsed border belongs to the table's shared grid rather\nthan to the cell — so when a cell detaches to stay at the top of the scroll\ncontainer, its rule stays behind with the rows and the stuck band appears to\nlose its edge. An inset `box-shadow` is a paint effect on the cell itself, so\nit travels with it. The alternative — putting the whole table on\n`border-separate` — would change the geometry of every table in the library\nto fix one that scrolls.\n\nThe opaque `bg-surface-1` is not decoration either: a transparent sticky cell\nis a sticky cell you read the rows through. A caller who wants the header on\nthe page's own ground can pass `className=\"bg-bg\"` — what it must not pass is\nnothing.",
+      "props": [
+        {
+          "name": "numeric",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Right-align this column and set it in tabular figures.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "sticky",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Dock the header band to the top of the scroll container while the rows\nscroll under it. Defaults to `false`.\n\nSet it on the cells, not on the `<tr>`: sticky on a table row is honoured\ninconsistently across engines, and the cell is the reliable baseline\neverywhere.",
+          "control": {
+            "kind": "boolean"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"th\">"
+      ]
+    },
+    {
+      "name": "Cell",
+      "usage": "Table.Cell",
+      "description": "One data cell, padded on the density row tokens like every other list row.",
+      "props": [
+        {
+          "name": "numeric",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Right-align this cell and set it in tabular figures.",
+          "control": {
+            "kind": "boolean"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"td\">"
+      ]
+    },
+    {
+      "name": "Caption",
+      "usage": "Table.Caption",
+      "description": "The table's name. Sits under the data (`caption-bottom`) because in a console\nthe heading above a table is a `SectionHeader` or a `PanelHeader`; a caption\nhere is the footnote — the source, the window, the count.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"caption\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-hair-strong",
+    "--cue-pad-row-x",
+    "--cue-pad-row-y",
+    "--cue-row-hover",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-1",
+    "--cue-table-group-top",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The semantic table: mono uppercase headers, hairline rows, tabular numerals.",
+  "examples": [
+    {
+      "title": "A grouped table whose groups are h3s",
+      "code": "{groups.map((group) => (\n  <Table.Body key={group.id}>\n    <Table.GroupRow span={2} headingLevel={3} label={group.label} count={group.rows.length} />\n    {group.rows.map((device) => (\n      <Table.Row key={device.id}>\n        <Table.Cell>{device.name}</Table.Cell>\n        <Table.Cell numeric>{device.latency}</Table.Cell>\n      </Table.Row>\n    ))}\n  </Table.Body>\n))}",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Table.Root>\n  <Table.Header>\n    <Table.Row>\n      <Table.Head>Fixture</Table.Head>\n      <Table.Head numeric>Address</Table.Head>\n    </Table.Row>\n  </Table.Header>\n  <Table.Body>\n    <Table.Row>\n      <Table.Cell>Par 64</Table.Cell>\n      <Table.Cell numeric>001</Table.Cell>\n    </Table.Row>\n  </Table.Body>\n</Table.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/table",
+  "mdUrl": "/docs/components/table.md",
+  "jsonUrl": "/r/components/table.json",
+  "whenToUse": [
+    "Rows that share columns and are meant to be compared down a column.",
+    "Numeric cells. Mark them `data-numeric` so the figures line up.",
+    "Wrap a wide table in `TableScrollRegion`; render the table directly when it fits."
+  ],
+  "whenNotToUse": [
+    "One object's fields. Use `DescriptionList`.",
+    "Layout. A table is for data that has columns.",
+    "Sorting, filtering and paging over thousands of rows on its own. Compose it with `useCueTable` from `@cueplusplus/ui/instruments/data-table`."
+  ],
+  "commonMistakes": [
+    "Leaving out `Table.Caption`, which is what names the table for a screen reader.",
+    "Wrapping cells in a `Row`. The table has its own row part.",
+    "Giving a row a `tabIndex` to make it activatable and then drawing no focus indicator. `Table.Row interactive` ships the inset focus ring along with the hover wash, so mark the row `interactive` rather than hand-rolling `focus-visible` classes on it.",
+    "Passing an `<h2>` as `Table.GroupRow`'s `label` to get a heading. The label slot wraps what it is given, so the heading lands inside a `<span>` — which renders, and does not validate. Set `headingLevel` and the wrapper becomes the heading."
+  ],
+  "specimens": [
+    {
+      "title": "Table",
+      "group": "instruments",
+      "components": [
+        "Table",
+        "TableScrollRegion"
+      ],
+      "code": "<Panel className=\"w-full\">\n  <TableScrollRegion aria-label=\"Cue list table\">\n    <Table.Root>\n      <Table.Caption>Cue list</Table.Caption>\n      <Table.Header>\n        <Table.Row>\n          <Table.Head numeric>#</Table.Head>\n          <Table.Head>Label</Table.Head>\n          <Table.Head numeric>Fade</Table.Head>\n          <Table.Head>Follow</Table.Head>\n          <Table.Head numeric>Level</Table.Head>\n        </Table.Row>\n      </Table.Header>\n      <Table.Body>\n        {CUES.map((cue) => (\n          <Table.Row key={cue.id}>\n            <Table.Cell numeric>{cue.id}</Table.Cell>\n            <Table.Cell>{cue.label}</Table.Cell>\n            <Table.Cell numeric>{cue.time}</Table.Cell>\n            <Table.Cell>{cue.follow}</Table.Cell>\n            <Table.Cell numeric>{cue.level}%</Table.Cell>\n          </Table.Row>\n        ))}\n      </Table.Body>\n    </Table.Root>\n  </TableScrollRegion>\n</Panel>",
+      "note": "The canonical console table inside its named horizontal scroll region: hairline rows, mono headers, and `numeric` cells that are right-aligned and tabular.",
+      "interaction": "the scroll region is keyboard-focusable. Sorting, filtering and paging come from the DataTable recipe below."
+    },
+    {
+      "title": "Table — grouped",
+      "group": "instruments",
+      "components": [
+        "Table"
+      ],
+      "code": "<Panel className=\"w-full\">\n  <div className=\"max-h-[18rem] overflow-y-auto [--cue-table-group-top:1.75rem]\">\n    <Table.Root>\n      <Table.Caption>Patch, one table, two row groups.</Table.Caption>\n      <Table.Header>\n        <Table.Row>\n          <Table.Head sticky>Device</Table.Head>\n          <Table.Head sticky>Detail</Table.Head>\n          <Table.Head sticky numeric>\n            Latency\n          </Table.Head>\n          <Table.Head sticky className=\"sr-only\">\n            Actions\n          </Table.Head>\n        </Table.Row>\n      </Table.Header>\n      {PATCH_GROUPS.map((group) => (\n        <Table.Body key={group.id}>\n          <Table.GroupRow\n            span={4}\n            label={group.label}\n            count={group.rows.length}\n            sticky\n          />\n          {group.rows.map((device) => (\n            <Table.Row key={device.id} interactive>\n              {/* The name is a link, and that is load-bearing rather\n                  than decorative. A `<tr>` is not focusable, so\n                  without a real control somewhere outside the hidden\n                  action track nothing in the row can take focus,\n                  `:focus-within` never fires, and the Copy and\n                  Actions buttons are reachable by pointer only —\n                  visible to a mouse user, invisible to Tab. The\n                  ledger and the tree get this for free because their\n                  rows are focusable themselves; the table has to be\n                  given it. */}\n              <Table.Cell>\n                <Link href={`#patch-${device.id}`}>{device.name}</Link>\n              </Table.Cell>\n              <Table.Cell className=\"text-fg-muted\">{device.detail}</Table.Cell>\n              <Table.Cell numeric>{device.latency}</Table.Cell>\n              {/* The action column's width is a sum of the tokens it\n                  holds — two small controls, the gap between them and\n                  the cell's own padding on each side — so it stays\n                  right whatever the density does to any of them. */}\n              <Table.Cell className=\"w-[calc(2_*_var(--cue-control-sm)_+_var(--cue-space-1)_+_2_*_var(--cue-pad-row-x))]\">\n                <DataRow.Actions>\n                  <CopyButton\n                    value={device.id}\n                    size=\"sm\"\n                    className=\"w-control-sm px-0\"\n                  />\n                  <IconButton\n                    icon={MoreVertical}\n                    size=\"sm\"\n                    aria-label={`Actions for ${device.name}`}\n                  />\n                </DataRow.Actions>\n              </Table.Cell>\n            </Table.Row>\n          ))}\n        </Table.Body>\n      ))}\n    </Table.Root>\n  </div>\n</Panel>",
+      "note": "The same rows as one continuous table: `Table.Head sticky` docks the column names, and one `Table.Body` per group opens with a `Table.GroupRow` divider — a `th` with `scope='rowgroup'`, so the columns are named once and scan straight through every boundary.",
+      "interaction": "rows marked `interactive` take the row-hover wash across the whole row; `selected` tints it and reveals the action track. Tab reaches each row through its name link, which is what lets `:focus-within` reveal the track at all — a `tr` cannot take focus, so a table row whose only controls are in the hidden cluster would be pointer-only."
+    },
+    {
+      "title": "Table — group dividers as headings",
+      "group": "instruments",
+      "components": [
+        "Table"
+      ],
+      "code": "<Panel className=\"w-full\">\n  <Table.Root>\n    <Table.Caption>Patch, grouped into the page's outline.</Table.Caption>\n    <Table.Header>\n      <Table.Row>\n        <Table.Head>Device</Table.Head>\n        <Table.Head numeric>Latency</Table.Head>\n      </Table.Row>\n    </Table.Header>\n    {PATCH_GROUPS.map((group) => (\n      <Table.Body key={group.id}>\n        <Table.GroupRow\n          span={2}\n          headingLevel={3}\n          label={group.label}\n          count={group.rows.length}\n        />\n        {group.rows.map((device) => (\n          <Table.Row key={device.id}>\n            <Table.Cell>{device.name}</Table.Cell>\n            <Table.Cell numeric>{device.latency}</Table.Cell>\n          </Table.Row>\n        ))}\n      </Table.Body>\n    ))}\n  </Table.Root>\n</Panel>",
+      "note": "`headingLevel` makes the divider's label slot a real `h3` instead of a `span`, so a grouped table joins the page's heading outline and a screen-reader user can jump between groups by heading. It is the prop to reach for rather than passing an `<h3>` as `label`: the label slot wraps what it is given, so a heading handed in that way lands inside a `<span>`, which may not contain one. The heading sits in the same `<th scope='rowgroup'>` as before — valid, because a `<th>` takes flow content — and wears the same type as the span form, so the level is in the outline and never in the design.",
+      "interaction": "none. Navigate by heading in a screen reader to hear the group names as an outline."
+    }
+  ]
+}

package/manifest/components/tabs.json

@@ -0,0 +1,156 @@
+{
+  "name": "Tabs",
+  "slug": "tabs",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "One surface, several views.\n\nWraps Base UI's `Tabs`, so roving focus, `aria-controls` wiring and\nactivation semantics are the primitive's. This layer adds the console skin:\na hairline strip, mono labels and an accent underline for the active tab.\n\nReach for {@link ScrollableTabsList} instead of `Tabs.List` when the number of\ntabs is data-driven and can outgrow its container.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "List",
+    "Tab",
+    "Panel"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Tabs.Root",
+      "description": "Groups a tab list with its panels and owns the selected value.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the tabs frame.",
+          "control": {
+            "kind": "string"
+          }
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseTabs.Root.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "List",
+      "usage": "Tabs.List",
+      "description": "The strip of tabs, hung off a hairline.\n\nThe rule belongs to the list rather than to the active tab so it spans the\nfull width even when the tabs do not — which is what makes the selected tab's\naccent underline read as a mark *on* a rule rather than as a floating dash.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the strip.",
+          "control": {
+            "kind": "string"
+          }
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseTabs.List.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Tab",
+      "usage": "Tabs.Tab",
+      "description": "One tab. Selected state is an accent underline sitting on the list's rule —\nnever a filled pill, which at console density turns a row of four tabs into a\nrow of four buttons and loses the \"one surface, several views\" reading.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the tab button.",
+          "control": {
+            "kind": "string"
+          }
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseTabs.Tab.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Panel",
+      "usage": "Tabs.Panel",
+      "description": "The body shown for the matching tab. Focusable, so keyboard users land in it.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the panel.",
+          "control": {
+            "kind": "string"
+          }
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseTabs.Panel.Props, \"className\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-md",
+    "--cue-edge-fade",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-ui"
+  ],
+  "summary": "One surface, several views, with the roving focus wired for you.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Tabs.Root defaultValue=\"patch\">\n  <Tabs.List>\n    <Tabs.Tab value=\"patch\">Patch</Tabs.Tab>\n    <Tabs.Tab value=\"cues\">Cues</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"patch\">…</Tabs.Panel>\n  <Tabs.Panel value=\"cues\">…</Tabs.Panel>\n</Tabs.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/tabs",
+  "mdUrl": "/docs/components/tabs.md",
+  "jsonUrl": "/r/components/tabs.json",
+  "whenToUse": [
+    "Two to seven views of the same object, where only one is needed at a time.",
+    "A tab strip that may outgrow its container. Use `ScrollableTabsList`, which fades its edges and scrolls the active tab into view."
+  ],
+  "whenNotToUse": [
+    "Steps in a sequence the user works through. Use `Stepper`.",
+    "Sections a reader may want open at once. Use `Accordion`.",
+    "Navigation between pages. Use the app shell: `Sidebar` or `NavigationMenu`."
+  ],
+  "commonMistakes": [
+    "Hiding a panel with CSS instead of letting `Tabs.Panel` unmount it, which leaves the hidden content in the tab order.",
+    "Filling the selected tab with a solid block. The selected state here is the accent underline sitting on the list's rule."
+  ],
+  "specimens": [
+    {
+      "title": "Tabs",
+      "group": "chrome",
+      "components": [
+        "Tabs"
+      ],
+      "code": "<Tabs.Root value={tab} onValueChange={setTab} className=\"w-full max-w-[36rem]\">\n  <Tabs.List>\n    <Tabs.Tab value=\"patch\">Patch</Tabs.Tab>\n    <Tabs.Tab value=\"cues\">Cues</Tabs.Tab>\n    <Tabs.Tab value=\"setup\" disabled>\n      Setup\n    </Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"patch\">48 fixtures across 4 universes.</Tabs.Panel>\n  <Tabs.Panel value=\"cues\">12 cues, last edited 4 minutes ago.</Tabs.Panel>\n  <Tabs.Panel value=\"setup\">Setup.</Tabs.Panel>\n</Tabs.Root>",
+      "note": "Selection is an underline, never a filled block.",
+      "interaction": "hover lifts the inactive label; arrow keys move the active tab, and the panel follows."
+    }
+  ]
+}