@cueplusplus/ui 0.5.0 → 0.7.0

package/manifest/components/ledger.json

@@ -0,0 +1,187 @@
+{
+  "name": "Ledger",
+  "slug": "ledger",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A grouped run of dense rows under sticky headings: the ledger idiom.\n\nThe flattest of the three surfaces this package ships over one row model, and\nthe one that does the least: headings, slugs, rows. **Nothing here collapses.**\nA ledger with a disclosure on it would be a tree with worse semantics, so the\ncomponent emits no `aria-expanded` anywhere, and a test holds it to that —\ncollapse belongs to `DataTree`, and grouping-with-columns belongs to a\ngrouped `Table`.\n\nWhat it does own is the document outline. Tiers and groups are real `<h2>` /\n`<h3>` elements at caller-chosen levels, because in a list of two hundred\nrows the heading list *is* how a screen-reader user navigates.\n\nStatic markup — no `\"use client\"`. The rows inside it may be anything;\n`DataRow` is the intended tenant.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Tier",
+    "Group",
+    "Empty"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Ledger.Root",
+      "description": "The ledger surface: the type contract, and the container the columns shed\nagainst.\n\nDeliberately unframed. A ledger is a continuous document of rows, so the\nhairlines belong to the rows and there is no border, radius or card around\nany part of it — a per-group card would turn one list into a stack of little\ntables and break the top-to-bottom scan the whole idiom exists for.",
+      "props": [
+        {
+          "name": "containment",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Make the ledger a size container, so a caller's `@container` rules shed\ncolumns against the *pane* rather than the viewport. Defaults to `true`.\n\nThis is the difference between a list that sheds a column when the window\nnarrows and one that also sheds it when a detail drawer opens beside it and\ntakes half the pane — which is the same visual problem and, without a\ncontainer, an entirely separate piece of code. Switch it off only when an\nancestor is already the container the rules name; nesting containers moves\nwhich one a bare `@container` query resolves against."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Tier",
+      "usage": "Ledger.Tier",
+      "description": "One named run of the ledger, with its own sticky heading.\n\nThe heading paints its own ground (`bg-bg`) because a sticky element with a\ntransparent background is a sticky element you can read rows straight through.",
+      "props": [
+        {
+          "name": "heading",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The tier's name. Omitted, the tier draws no heading and reserves no space\nfor one — which is how a single unnamed run of rows uses the same component\nas a grouped one."
+        },
+        {
+          "name": "count",
+          "type": "number",
+          "required": false,
+          "defaultValue": null,
+          "description": "How many rows the tier holds, printed beside its name."
+        },
+        {
+          "name": "sticky",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Dock the heading to the top of the scroll container while the tier's rows\nscroll past. Defaults to `true`."
+        },
+        {
+          "name": "headingLevel",
+          "type": "4 | 2 | 3",
+          "required": false,
+          "defaultValue": "2",
+          "description": "Which heading element the tier's name is. Defaults to `2`.\n\nThe outline is the navigation: a screen-reader user moves through a long\nledger by heading, so the levels have to describe the real nesting of the\npage the ledger sits in, not the ledger's own idea of itself."
+        },
+        {
+          "name": "note",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "A qualifier printed after the name — a date, a source, a state."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"section\">"
+      ]
+    },
+    {
+      "name": "Group",
+      "usage": "Ledger.Group",
+      "description": "A run of rows under a slug in the left gutter.\n\nThe gutter is a grid track whose width is the custom property\n`--cue-ledger-gutter` (default `7rem`), so a `@container` rule can narrow it\nat the same breakpoint it sheds a column, without this component knowing\nanything about the caller's breakpoints.\n\nThe slug is `self-start`, which is the load-bearing half of making it stick:\na stretched grid item is exactly as tall as the group, and an element as tall\nas its own scroll range has nowhere to slide to.",
+      "props": [
+        {
+          "name": "label",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The group's slug, printed in the left gutter.\n\nOmitted, the group is a plain block: no gutter, no heading, no indent. A\ngrouped list that has one unnamed run in it should not pay a 7rem empty\ncolumn for it, and an empty gutter reads as a missing label rather than as\nan absent one."
+        },
+        {
+          "name": "headingLevel",
+          "type": "4 | 3",
+          "required": false,
+          "defaultValue": "3",
+          "description": "Which heading element the slug is. Defaults to `3`."
+        },
+        {
+          "name": "sticky",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Dock the slug under the tier heading while the group's rows scroll past.\nDefaults to `true`.\n\nThe offset is a custom property, `--cue-ledger-slug-top` (default `2.5rem`):\nhow far down the slug docks depends on how tall the tier heading above it\nrenders, which is a function of the density and the type the *caller*\nconfigured. Set it on the ledger — `className=\"[--cue-ledger-slug-top:2rem]\"` —\nrather than measuring at runtime."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Empty",
+      "usage": "Ledger.Empty",
+      "description": "The line that stands where a group's rows would be.\n\nA slot rather than an `empty` prop on the group, because there are two\ndifferent emptinesses and only the caller knows which one this is: a place\nsomebody made that has nothing in it yet (\"Nothing yet.\") and a filter that\nemptied a place that does have things in it (\"Nothing matches …\"). A prop\nwould have to guess, and guessing conflates them — which is precisely the bug\nthis slot exists to make impossible. For a whole surface with nothing in it\nand no heading left to keep, use `EmptyState` instead.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"p\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-data-row-cols",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-ledger-gutter",
+    "--cue-ledger-slug-top",
+    "--cue-pad-row-x",
+    "--cue-pad-row-y",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "Grouped dense rows under sticky tier headings and gutter slugs, with no disclosure anywhere.",
+  "examples": [
+    {
+      "title": "Tiers, groups, rows",
+      "code": "<Ledger.Root className=\"[--cue-data-row-cols:1fr_8rem_auto] [--cue-ledger-slug-top:1.75rem]\">\n  <Ledger.Tier heading=\"Patch\" count={5} note=\"polled 18:04\">\n    <Ledger.Group label=\"inputs\">\n      {inputs.map((device) => (\n        <DataRow.Root key={device.id} interactive onActivate={() => open(device)}>\n          …\n        </DataRow.Root>\n      ))}\n    </Ledger.Group>\n    <Ledger.Group label=\"spare\">\n      <Ledger.Empty>Nothing yet.</Ledger.Empty>\n    </Ledger.Group>\n  </Ledger.Tier>\n</Ledger.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "One unnamed group",
+      "code": "<Ledger.Tier>\n  <Ledger.Group>\n    <DataRow.Root>…</DataRow.Root>\n  </Ledger.Group>\n</Ledger.Tier>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Ledger.Root className=\"[--cue-data-row-cols:1fr_8rem_auto]\">\n  <Ledger.Tier heading=\"Ours\" count={12}>\n    <Ledger.Group label=\"released\">\n      <DataRow.Root interactive onActivate={open}>…</DataRow.Root>\n    </Ledger.Group>\n    <Ledger.Group label=\"lab\">\n      <Ledger.Empty>Nothing yet.</Ledger.Empty>\n    </Ledger.Group>\n  </Ledger.Tier>\n</Ledger.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/ledger",
+  "mdUrl": "/docs/components/ledger.md",
+  "jsonUrl": "/r/components/ledger.json",
+  "whenToUse": [
+    "A long list that is grouped but never folded: a corpus by source, a patch by direction, a run log by day.",
+    "A surface whose groups should be reachable by heading, since the tiers and slugs are real `h2`/`h3` elements."
+  ],
+  "whenNotToUse": [
+    "A hierarchy the reader folds. Use `DataTree`, which owns collapse and the tree semantics that go with it.",
+    "Rows meant to be compared down a named column. Use a grouped `Table`, where the columns are named once in a `thead`.",
+    "A handful of rows in a panel. Use `Row` inside `Panel`; a tier heading over three rows is furniture with nothing to organise."
+  ],
+  "commonMistakes": [
+    "Adding a toggle to a tier. A ledger that folds is a tree with worse semantics — the component emits no `aria-expanded`, and a test holds it to that.",
+    "Framing each group in a `Panel`. A card per group turns one list into a stack of little tables and breaks the top-to-bottom scan.",
+    "Leaving `--cue-ledger-slug-top` at its default after changing the density or the heading type, which docks the slug over the tier heading instead of under it.",
+    "Passing an `empty` string as a prop. `Ledger.Empty` takes the words because \"this place is empty\" and \"your filter emptied it\" are different sentences."
+  ],
+  "specimens": [
+    {
+      "title": "Ledger",
+      "group": "instruments",
+      "components": [
+        "Ledger"
+      ],
+      "code": "<Panel className=\"w-full\">\n  <div className=\"max-h-[18rem] overflow-y-auto\">\n    <Ledger.Root className={PATCH_TRACKS}>\n      <Ledger.Tier heading=\"Patch\" count={PATCH_DEVICES.length} note=\"polled 18:04\">\n        {PATCH_GROUPS.map((group) => (\n          <Ledger.Group key={group.id} label={group.label}>\n            {group.rows.map((device) => (\n              <DataRow.Root key={device.id} interactive>\n                <PatchRowSlots device={device} />\n              </DataRow.Root>\n            ))}\n          </Ledger.Group>\n        ))}\n        <Ledger.Group label=\"spare\">\n          <Ledger.Empty>Nothing yet.</Ledger.Empty>\n        </Ledger.Group>\n      </Ledger.Tier>\n    </Ledger.Root>\n  </div>\n</Panel>",
+      "note": "The same rows as tiers and slugs: sticky headings, a gutter for the group name, and no disclosure anywhere — the ledger does not collapse.",
+      "interaction": "the tier heading and the group slug dock as the rows scroll under them; scroll the pane to see it."
+    }
+  ]
+}

package/manifest/components/multi-select.json

@@ -137,6 +137,7 @@
     "--cue-accent-soft",
     "--cue-border",
     "--cue-border-overlay",
+    "--cue-border-strong",
     "--cue-chip-h",
     "--cue-control-lg",
     "--cue-control-md",
@@ -145,6 +146,7 @@
     "--cue-fg",
     "--cue-fg-muted",
     "--cue-fg-subtle",
+    "--cue-focus",
     "--cue-font-mono",
     "--cue-icon-sm",
     "--cue-radius-control",

package/manifest/components/musical-time-input.json

@@ -67,12 +67,14 @@
   "tokensUsed": [
     "--cue-accent",
     "--cue-border",
+    "--cue-border-strong",
     "--cue-control-lg",
     "--cue-control-md",
     "--cue-control-sm",
     "--cue-danger",
     "--cue-fg",
     "--cue-fg-subtle",
+    "--cue-focus",
     "--cue-font-mono",
     "--cue-radius-control",
     "--cue-space-2",

package/manifest/components/number-field.json

@@ -5,7 +5,7 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": true,
-  "description": "A numeric control with explicit − / + affordances and no native spinners.\n\nNative `<input type=\"number\">` spinners are unusable at console density — a\npair of 4px arrows that only appear on hover — so this is a text input with\n`inputMode=\"numeric\"` flanked by real buttons, which is also what makes it\ntouch-usable. Arrow keys step, Shift steps by `largeStep`, Alt by `smallStep`,\nand values typed out of range are clamped to `min`/`max` on blur.\n\nThe group owns the rim; the input and both buttons render bare inside it, so\nthe whole cluster reads as one field and focus feedback moves to\n`focus-within`.",
+  "description": "A numeric control with explicit − / + affordances and no native spinners.\n\nNative `<input type=\"number\">` spinners are unusable at console density — a\npair of 4px arrows that only appear on hover — so this is a text input with\n`inputMode=\"numeric\"` flanked by real buttons, which is also what makes it\ntouch-usable. Arrow keys step, Shift steps by `largeStep`, Alt by `smallStep`,\nand values typed out of range are clamped to `min`/`max` on blur.\n\nThe group owns the rim; the input and both buttons render bare inside it, so\nthe whole cluster reads as one field. Focus feedback follows the group's\nsplit: the rim strengthens on `:focus-within`, and the ring waits for\n`:has(:focus-visible)` so a click on a stepper does not paint one.",
   "props": [
     {
       "name": "className",
@@ -60,6 +60,7 @@
   "tokensUsed": [
     "--cue-accent",
     "--cue-border",
+    "--cue-border-strong",
     "--cue-control-lg",
     "--cue-control-md",
     "--cue-control-sm",
@@ -67,6 +68,7 @@
     "--cue-fg",
     "--cue-fg-muted",
     "--cue-fg-subtle",
+    "--cue-focus",
     "--cue-font-mono",
     "--cue-radius-control",
     "--cue-space-2",

package/manifest/components/otp-field.json

@@ -81,12 +81,14 @@
   "tokensUsed": [
     "--cue-accent",
     "--cue-border",
+    "--cue-border-strong",
     "--cue-control-lg",
     "--cue-control-md",
     "--cue-control-sm",
     "--cue-danger",
     "--cue-fg",
     "--cue-fg-subtle",
+    "--cue-focus",
     "--cue-font-mono",
     "--cue-radius-control",
     "--cue-space-1",

package/manifest/components/password-input.json

@@ -74,12 +74,14 @@
   "tokensUsed": [
     "--cue-accent",
     "--cue-border",
+    "--cue-border-strong",
     "--cue-control-lg",
     "--cue-control-md",
     "--cue-control-sm",
     "--cue-danger",
     "--cue-fg",
     "--cue-fg-subtle",
+    "--cue-focus",
     "--cue-font-mono",
     "--cue-icon-md",
     "--cue-radius-control",

package/manifest/components/scrub-input.json

@@ -144,12 +144,14 @@
   "tokensUsed": [
     "--cue-accent",
     "--cue-border",
+    "--cue-border-strong",
     "--cue-control-lg",
     "--cue-control-md",
     "--cue-control-sm",
     "--cue-danger",
     "--cue-fg",
     "--cue-fg-subtle",
+    "--cue-focus",
     "--cue-font-mono",
     "--cue-radius-control",
     "--cue-space-2",

package/manifest/components/search-input.json

@@ -88,12 +88,14 @@
   "tokensUsed": [
     "--cue-accent",
     "--cue-border",
+    "--cue-border-strong",
     "--cue-control-lg",
     "--cue-control-md",
     "--cue-control-sm",
     "--cue-danger",
     "--cue-fg",
     "--cue-fg-subtle",
+    "--cue-focus",
     "--cue-font-mono",
     "--cue-icon-md",
     "--cue-icon-sm",

package/manifest/components/select.json

@@ -138,6 +138,7 @@
     "--cue-fg",
     "--cue-fg-muted",
     "--cue-fg-subtle",
+    "--cue-focus",
     "--cue-font-mono",
     "--cue-icon-md",
     "--cue-icon-sm",

package/manifest/components/status-bar.json

@@ -5,11 +5,100 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": false,
-  "description": "The quiet strip along the bottom of a window.\n\nThe smallest type in the system in the subtlest ink: a status bar is read\nwhen you go looking for it and ignored otherwise, so it must never compete\nwith the work above it. Height comes from `--cue-chrome-statusbar`.\n\nNot a live region — a status bar changes constantly (frame counters, DMX\noutput), and announcing every change would make the app unusable with a\nscreen reader. Put anything that genuinely must be announced in a `Toast`.\n\nStatic markup — no `\"use client\"`.",
+  "description": "The quiet strip along the bottom of a window.\n\nThe smallest type in the system in the subtlest ink: a status bar is read\nwhen you go looking for it and ignored otherwise, so it must never compete\nwith the work above it. Height comes from `--cue-chrome-statusbar`, and the\nbar clips rather than wrapping — one rung of the frame, always, whatever it\nis asked to hold.\n\nItems come in two kinds and the difference is deliberate. A plain\n`StatusBar.Item` is a **reading**: a `<div>`, inert by construction, with no\nhover, no focus and nothing to click — which is what most of a status bar is.\n`interactive` (or a `render`) makes one a **control**, and only then does it\ngrow the button chassis, the full-height hover fill and the inset focus ring.\n`StatusBar.Group` fuses adjacent items into one segmented control.\n\nNot a live region — a status bar changes constantly (frame counters, DMX\noutput), and announcing every change would make the app unusable with a\nscreen reader. Put anything that genuinely must be announced in a `Toast`.\n\nStatic markup — no `\"use client\"`. A bar of readings renders on the server\nand ships no JavaScript at all; the interactive item is the one part that\ncrosses the boundary, and it crosses it alone (`./_status-bar-item.tsx`).",
   "props": [],
-  "typeReferences": [],
-  "subcomponents": [],
-  "parts": [],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [
+    "Item",
+    "Group"
+  ],
+  "parts": [
+    {
+      "name": "Item",
+      "usage": "StatusBar.Item",
+      "description": "One reading in the bar: a mode, a count, a connection state — or, given\n`interactive`, one control in it.",
+      "props": [
+        {
+          "name": "tone",
+          "type": "\"accent\" | \"danger\" | \"busy\" | \"neutral\" | \"ok\" | \"warn\" | \"info\"",
+          "required": false,
+          "defaultValue": "neutral",
+          "description": "Ink for this item. Defaults to the bar's own subtle grey."
+        },
+        {
+          "name": "push",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Start the trailing cluster here: pushes this item and everything after it\nto the far edge. Cheaper and more robust than a spacer element, which a\ncaller has to remember to keep in the right place."
+        },
+        {
+          "name": "icon",
+          "type": "ElementType<any, keyof IntrinsicElements>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Optional leading icon (e.g. a lucide icon), drawn `aria-hidden`."
+        },
+        {
+          "name": "interactive",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Make the item a real control: a `<button type=\"button\">` with hover, press\nand keyboard-focus feedback. Defaults to `false`.\n\nA native button, not a `<div>` with an `onClick` — keyboard order is DOM\norder, `Enter` and `Space` work because the platform makes them work, and\nassistive technology is told what the thing is by the element rather than\nby a role attribute that has to be kept honest by hand.\n\n**An icon-only interactive item needs an `aria-label`.** There is no text\nfor a screen reader to read and the icon is drawn `aria-hidden`, so without\none the control announces as \"button\" and nothing else."
+        },
+        {
+          "name": "prominence",
+          "type": "\"quiet\" | \"filled\"",
+          "required": false,
+          "defaultValue": "quiet",
+          "description": "How loudly the item states itself. Defaults to `\"quiet\"`.\n\n`quiet` is a reading: tone ink on the bar's own ground. `filled` is a chip\n— a full-height tone wash behind tone ink — for the small set of states\nthat earn a colour of their own: a warning, an error, the remote you are\nattached to. It is loud deliberately, and a bar of five filled items is a\nbar nobody reads."
+        },
+        {
+          "name": "render",
+          "type": "RenderProp<Record<string, unknown>>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Replace the rendered element (Base UI render prop) — `render={<a href=\"…\" />}`\nfor a status item that navigates.\n\nImplies {@link StatusBarItemProps.interactive}: whatever is rendered gets\nthe control chassis, because an element a reader can click has to look like\none whether it is a button or a link."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Grey the control out, take it out of the pointer's reach and announce it as\ndisabled. Defaults to `false`. Ignored by a static item, which is a reading\nand not a control.\n\nHonoured whatever {@link StatusBarItemProps.render} renders, but by two\nroutes: the `disabled` attribute where it means something — the default\n`<button>`, a form control, a component that takes a `disabled` prop of its\nown — and `aria-disabled` plus `data-disabled` everywhere, which is all an\nanchor gets. There is no such thing as a disabled link; a link that should\nnot be followed should not be a link, and this states the intent rather\nthan pretending to enforce it."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Group",
+      "usage": "StatusBar.Group",
+      "description": "Items that belong to each other, one pixel apart.\n\nThe bar spaces its readings at `--cue-space-4` because they are unrelated\nfacts. A branch name and its ahead/behind count are not unrelated facts; they\nare one control that happens to have two halves, and the gap between them is\nwhat says so. This is VS Code's `compact` mechanic — the seam collapses, and\nhovering either half grounds both while the half under the cursor goes one\nrung further — expressed as a wrapper rather than as an id-reference between\ntwo items, because a design system's items do not have ids to point at.\n\nA `role=\"group\"` rather than nothing: the members are announced as a set, and\nthe DOM order they are announced in is the order they are read in. Give it an\n`aria-label` when the members only make sense together.",
+      "props": [
+        {
+          "name": "push",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Start the trailing cluster at this group: pushes it and everything after it\nto the far edge, exactly as `push` does on a single item."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "What the cluster is called. Optional, and worth giving whenever the members\nonly make sense together — \"Repository\", \"Connection\" — because a `group`\nwith no name is a landmark a screen reader reads straight past."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    }
+  ],
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [
@@ -18,6 +107,7 @@
     "--cue-busy",
     "--cue-chrome-statusbar",
     "--cue-danger",
+    "--cue-fg",
     "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-icon-sm",
@@ -25,23 +115,68 @@
     "--cue-ok",
     "--cue-pad-row-x",
     "--cue-space-2",
+    "--cue-space-3",
     "--cue-space-4",
     "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
     "--cue-text-label",
     "--cue-warn"
   ],
-  "summary": "The quiet strip along the bottom of a window.",
+  "summary": "The quiet strip along the bottom of a window: readings by default, controls where the reading is worth clicking.",
   "examples": [
     {
-      "title": "Usage",
+      "title": "Readings and controls",
       "code": "<StatusBar>\n  <StatusBar.Item icon={Plug} tone=\"ok\">Art-Net connected</StatusBar.Item>\n  <StatusBar.Item push>512 channels</StatusBar.Item>\n</StatusBar>",
       "language": "tsx"
+    },
+    {
+      "title": "Readings and controls",
+      "code": "<StatusBar.Item interactive icon={GitBranch} onClick={openBranchPicker}>act-2</StatusBar.Item>\n<StatusBar.Item render={<a href=\"/runs/42\" />}>run 42</StatusBar.Item>",
+      "language": "tsx"
+    },
+    {
+      "title": "`push`, and the two clusters",
+      "code": "<StatusBar>\n  <StatusBar.Item>universe 1</StatusBar.Item>\n  <StatusBar.Item tone=\"ok\">44 Hz</StatusBar.Item>\n  <StatusBar.Item push>10.0.0.42</StatusBar.Item>\n  <StatusBar.Item tone=\"info\">art-net</StatusBar.Item>\n</StatusBar>",
+      "language": "tsx"
+    },
+    {
+      "title": "Groups: items that belong to each other",
+      "code": "<StatusBar.Group aria-label=\"Show file\">\n  <StatusBar.Item interactive icon={GitBranch}>act-2</StatusBar.Item>\n  <StatusBar.Item interactive icon={ArrowUp}>2</StatusBar.Item>\n</StatusBar.Group>",
+      "language": "tsx"
+    },
+    {
+      "title": "`prominence`, and how rarely to reach for it",
+      "code": "<StatusBar.Item prominence=\"filled\" tone=\"danger\" icon={TriangleAlert}>3 faults</StatusBar.Item>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<StatusBar>\n  <StatusBar.Item icon={Plug} tone=\"ok\">Art-Net connected</StatusBar.Item>\n  <StatusBar.Item push>512 channels</StatusBar.Item>\n</StatusBar>\n// The VS Code shape: a clickable cluster left, a loud state right.\n<StatusBar>\n  <StatusBar.Group aria-label=\"Repository\">\n    <StatusBar.Item interactive icon={GitBranch}>main</StatusBar.Item>\n    <StatusBar.Item interactive icon={ArrowUp}>2</StatusBar.Item>\n  </StatusBar.Group>\n  <StatusBar.Item push interactive prominence=\"filled\" tone=\"danger\">3 faults</StatusBar.Item>\n</StatusBar>",
+      "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/status-bar",
   "mdUrl": "/docs/components/status-bar.md",
   "jsonUrl": "/r/components/status-bar.json",
+  "whenToUse": [
+    "Ambient state a reader goes looking for rather than is interrupted by: a connection, a frame rate, a cursor position, a branch name.",
+    "A state that is also a destination. `interactive` makes an item a real button, `render={<a href=\"…\" />}` makes it a link, and `StatusBar.Group` fuses two of them into one control."
+  ],
+  "whenNotToUse": [
+    "Anything that must be noticed. A status bar is deliberately the quietest thing on screen and nothing in it is announced — urgent messages are `Toast`'s job.",
+    "A row of actions. That is `Toolbar`, which is sized for controls and has the keyboard model to match.",
+    "The end of a document — an address, fine print, a sitemap. That is `Footer`, which scrolls away with the content; the bar is part of the frame and never leaves the screen."
+  ],
+  "commonMistakes": [
+    "Making every item interactive. Most of a status bar is a reading, and a bar where everything lights up under the pointer is a bar where nothing means anything.",
+    "Filling more than one or two items. `prominence=\"filled\"` is the loudest thing the bar can do; a bar of five filled chips is a bar nobody reads.",
+    "An icon-only interactive item with no `aria-label`. The icon is drawn `aria-hidden`, so the control announces as \"button\" and nothing else.",
+    "Wrapping related items in a plain `<div>` to close the gap. `StatusBar.Group` closes the seam *and* neutralises the interactive item's negative margin, which a bare div does not.",
+    "Reaching for `aria-live` to make a reading announce itself. The bar changes constantly, and a live region here makes the app unusable with a screen reader.",
+    "Fixing the height with `h-6` instead of letting `--cue-chrome-statusbar` set it, which stops tracking density."
+  ],
   "specimens": [
     {
       "title": "StatusBar",
@@ -49,10 +184,9 @@
       "components": [
         "StatusBar"
       ],
-      "code": "<div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n  <StatusBar>\n    <StatusBar.Item>universe 1</StatusBar.Item>\n    <StatusBar.Item tone=\"ok\">44 Hz</StatusBar.Item>\n    <StatusBar.Item tone=\"warn\">2 conflicts</StatusBar.Item>\n    <StatusBar.Item push>10.0.0.42</StatusBar.Item>\n    <StatusBar.Item tone=\"info\">art-net</StatusBar.Item>\n  </StatusBar>\n</div>",
-      "note": "The bottom strip: tone-inked items, and a `push` item that takes the remaining space.",
-      "interaction": "none by default; items are plain readouts."
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  <div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n    <StatusBar>\n      <StatusBar.Item>universe 1</StatusBar.Item>\n      <StatusBar.Item tone=\"ok\">44 Hz</StatusBar.Item>\n      <StatusBar.Item tone=\"warn\">2 conflicts</StatusBar.Item>\n      <StatusBar.Item push>10.0.0.42</StatusBar.Item>\n      <StatusBar.Item tone=\"info\">art-net</StatusBar.Item>\n    </StatusBar>\n  </div>\n\n  <div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n    <StatusBar>\n      <StatusBar.Group aria-label=\"Show file\">\n        <StatusBar.Item interactive icon={GitBranch}>\n          act-2\n        </StatusBar.Item>\n        <StatusBar.Item interactive icon={ArrowUp}>\n          2\n        </StatusBar.Item>\n      </StatusBar.Group>\n      <StatusBar.Item interactive tone=\"ok\">\n        44 Hz\n      </StatusBar.Item>\n      <StatusBar.Item interactive icon={Radio} aria-label=\"Art-Net output\" />\n      <StatusBar.Item push interactive prominence=\"filled\" tone=\"warn\" icon={TriangleAlert}>\n        2 conflicts\n      </StatusBar.Item>\n    </StatusBar>\n  </div>\n</div>",
+      "note": "The bottom strip: tone-inked items, and a `push` item that takes the remaining space. Drawn twice — the readings-only bar it has always been, and the VS Code shape beneath it, where some of the items are controls: a compact Group whose two halves read as one, an icon-only control that carries its name in aria-label, and a filled item for the one state that has earned a colour.",
+      "interaction": "the plain items are inert by construction — no hover, no focus, nothing to click. The controls take a full-height fill on hover and a darker one while pressed, Tab reaches them in DOM order and Enter fires them, and the focus ring is drawn inside the item so it never paints across the bar. Hovering either half of the Group grounds both, and the half under the pointer goes one rung further."
     }
-  ],
-  "todo": true
+  ]
 }

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

@@ -24,14 +24,20 @@
   "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"
   ],