@cueplusplus/ui 0.5.0 → 0.6.0

package/manifest/components/data-tree.json

@@ -0,0 +1,151 @@
+{
+  "name": "DataTree",
+  "slug": "data-tree",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A hierarchy of multi-column rows: the tree idiom over the `DataRow` anatomy.\n\n## The ARIA pattern, chosen before the component was written\n\n`role=\"treegrid\"` is **rejected** for this foundation. It is the semantically\nexact answer — tabular *and* hierarchical — and it is the one with the worst\nreal-world assistive-technology record: Adrian Roselli's survey of expando\ntables calls its support poor and notes that the APG's own worked example\ncarries unresolved issues; fancytree's maintainer describes treegrid support\nas unproven ground; MUI X shipped hierarchical rows with no `aria-level` /\n`aria-expanded` / `aria-setsize` at all and retrofitted them later. Treegrid\nearns its cost when cells are individually interactive or editable, because\nthen a reader genuinely needs two-dimensional cell navigation. This surface is\nread-and-navigate: you move down rows, fold a branch, and open the thing a row\nnames.\n\nSo the pattern is `role=\"tree\"` with `role=\"treeitem\"` rows — VS Code's\nchoice and Carbon's, and the best-supported composite pattern in ARIA:\n\n- A **flat DOM** with `aria-level` / `aria-posinset` / `aria-setsize` per row\n  rather than nested `role=\"group\"` wrappers.\n- **Roving tabindex**: the tree is one Tab stop and the arrows move inside it.\n- The **APG tree keyboard map**: Up/Down between visible rows, Home/End to the\n  ends, Right to unfold then to descend, Left to fold then to ascend,\n  Enter/Space to select.\n- Expansion lives on the **row**, as `aria-expanded` on the `treeitem` — that\n  is what tree semantics mean by a parent, and it is why the chevron here is\n  `role=\"presentation\"` rather than a button. (The other half of this trade\n  is `Table.GroupRow`, where the table's semantics own the grouping and a real\n  `<button aria-expanded>` owns the disclosure. Two patterns, each internally\n  consistent; what would be wrong is half of each.)\n\n**The documented trade**: columns are not independently navigable. A row's\nmulti-column content lives *inside* the treeitem, so a screen-reader user\nhears the row as one string rather than moving cell to cell through it. For a\ndense browse-and-open surface that is the better bargain — `tree` works today\non every screen reader, `treegrid` does not — but a surface whose cells are\ngenuinely editable has outgrown this component and wants a real treegrid from\na library that maintains one.\n\n## Everything else\n\nRows are the `DataRow` chassis: same padding, same hairline, same hover wash,\nsame inset focus ring, same `group/data-row`, so `DataRow.Actions` reveals in\na tree exactly as it does in a ledger. The row element itself is the\ntreeitem — one element owns focus, expansion, selection and the click reading\n— and the caller's `DataRow.*` slots are its content.\n\nA tree whose items declare no children anywhere is a flat list: no chevrons,\nno spacer column where a chevron would be, no guides, and `aria-expanded` on\nnothing. A leaf row that carried `aria-expanded=\"false\"` would tell a screen\nreader it has children it does not have.",
+  "props": [
+    {
+      "name": "items",
+      "type": "readonly DataTreeItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The roots, in display order."
+    },
+    {
+      "name": "expanded",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Expanded ids when controlled. Pass with `onExpandedChange`."
+    },
+    {
+      "name": "defaultExpanded",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initially expanded ids when uncontrolled."
+    },
+    {
+      "name": "onExpandedChange",
+      "type": "((expanded: string[]) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the whole next expanded set whenever a row is folded or unfolded."
+    },
+    {
+      "name": "selected",
+      "type": "string | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "Selected id when controlled. Pass with `onSelect`."
+    },
+    {
+      "name": "defaultSelected",
+      "type": "string | null",
+      "required": false,
+      "defaultValue": "null",
+      "description": "Initially selected id when uncontrolled."
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the id of the row the user selected."
+    },
+    {
+      "name": "guides",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Draw the depth guides. Defaults to `true`.\n\nRoots never draw one — there is no ancestor to draw — so a flat tree draws\nnone at all whatever this is set to."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the tree. Required in practice — name what it lists."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onSelect\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-data-row-cols",
+    "--cue-data-tree-indent",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-hair",
+    "--cue-icon-sm",
+    "--cue-pad-row-x",
+    "--cue-pad-row-y",
+    "--cue-row-hover",
+    "--cue-space-3",
+    "--cue-text-ui"
+  ],
+  "summary": "A hierarchy of multi-column rows under real `role=\"tree\"` semantics, with CSS depth guides.",
+  "examples": [
+    {
+      "title": "Items carry rows, not labels",
+      "code": "const items: DataTreeItem[] = groups.map((group) => ({\n  id: group.id,\n  row: <DataRow.Label>{group.label}</DataRow.Label>,\n  children: group.rows.map((device) => ({\n    id: device.id,\n    row: (\n      <>\n        <DataRow.Label>{device.name}</DataRow.Label>\n        <DataRow.Meta>{device.latency}</DataRow.Meta>\n      </>\n    ),\n  })),\n}));\n\n<DataTree\n  aria-label=\"Patch\"\n  className=\"[--cue-data-row-cols:1fr_6rem]\"\n  items={items}\n  defaultExpanded={[\"inputs\"]}\n  selected={selected}\n  onSelect={setSelected}\n/>;",
+      "language": "tsx"
+    },
+    {
+      "title": "The container, named",
+      "code": "<div className=\"patch [container-type:inline-size] [container-name:patch]\">\n  <DataTree … />\n</div>",
+      "language": "tsx"
+    },
+    {
+      "title": "Narrow the step before you drop the guides",
+      "code": "@container patch (max-width: 32rem) {\n  .patch [data-slot=\"data-tree\"] {\n    --cue-data-tree-indent: 0.75rem;\n  }\n}",
+      "language": "css"
+    },
+    {
+      "title": "Usage",
+      "code": "<DataTree\n  aria-label=\"Patch\"\n  items={nodes}\n  defaultExpanded={[\"inputs\"]}\n  selected={selected}\n  onSelect={setSelected}\n  className=\"[--cue-data-row-cols:1fr_8rem_auto]\"\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/data-tree",
+  "mdUrl": "/docs/components/data-tree.md",
+  "jsonUrl": "/r/components/data-tree.json",
+  "whenToUse": [
+    "A grouped list the reader folds and unfolds, where each row still carries columns — a patch by bus, a corpus by stack, a plan by phase.",
+    "A hierarchy that has to keep working for a screen-reader user today: this is the `tree` pattern, which is the best-supported composite pattern in ARIA."
+  ],
+  "whenNotToUse": [
+    "A single-column outline of labels with a glyph gutter. Use `Tree`, which is that component.",
+    "A grouped list nobody folds. Use `Ledger` or a grouped `Table`; disclosure semantics you never use are a promise you never keep.",
+    "A grid whose cells are individually editable. That needs a real `treegrid` from a library that maintains one — this component trades cell navigation away on purpose."
+  ],
+  "commonMistakes": [
+    "Expecting cell-by-cell arrow navigation. Columns live inside the treeitem, so a row is announced as one string; that is the documented trade for the support `tree` has and `treegrid` does not.",
+    "Giving a leaf `children: []` to make it look like the others. An empty array *is* a parent — an empty folder — and it will carry `aria-expanded`.",
+    "Passing `expanded` without `onExpandedChange`, which freezes the tree: controlled means the caller owns the next state.",
+    "Fighting the guides with a row background. They are a `background-image` and survive hover and selection fills by design; switch them off with `guides={false}` instead."
+  ],
+  "specimens": [
+    {
+      "title": "DataTree",
+      "group": "instruments",
+      "components": [
+        "DataTree"
+      ],
+      "code": "<Panel className={`w-full ${PATCH_TRACKS}`}>\n  <DataTree\n    aria-label=\"Patch\"\n    items={PATCH_TREE}\n    defaultExpanded={[\"inputs\"]}\n    defaultSelected=\"scarlett\"\n  />\n</Panel>",
+      "note": "The same rows as a hierarchy: `role='tree'` with `treeitem` rows, chosen over `treegrid` for the support it actually has. Guides are a background gradient keyed off the row's depth, so a hover or selection fill cannot cover them.",
+      "interaction": "one tab stop: arrows move between rows, Right unfolds then descends, Left folds then climbs, Enter selects."
+    }
+  ]
+}

package/manifest/components/date-field.json

@@ -35,12 +35,14 @@
     "--cue-accent",
     "--cue-accent-fg",
     "--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/date-picker.json

@@ -145,12 +145,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-sm",
     "--cue-radius-control",

package/manifest/components/date-range-picker.json

@@ -145,12 +145,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-sm",
     "--cue-radius-control",

package/manifest/components/env-var-input.json

@@ -102,12 +102,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/input-group.json

@@ -5,7 +5,7 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": true,
-  "description": "A control and its adornments, drawn as a single field.\n\nThe group — not the input — owns the chassis, so there is exactly one rim and\none fill however many affordances are bolted on. It publishes that fact\nthrough context: an {@link Input } rendered inside strips its own border,\nbackground, height and padding and inherits the group's font size. Focus\nfeedback moves to `focus-within`, since a `<div>` never matches\n`:focus-visible`.",
+  "description": "A control and its adornments, drawn as a single field.\n\nThe group — not the input — owns the chassis, so there is exactly one rim and\none fill however many affordances are bolted on. It publishes that fact\nthrough context: an {@link Input } rendered inside strips its own border,\nbackground, height and padding and inherits the group's font size.\n\nFocus feedback splits in two, because a `<div>` matches neither `:focus` nor\n`:focus-visible` itself. The rim strengthens on `:focus-within` — anything\nfocused inside, however it got there — while the ring waits for\n`:has(:focus-visible)`, so a mouse click into the field does not light the\nwhole cluster up. Both halves live on the wrapper; the inner control paints\nno ring of its own.",
   "props": [
     {
       "name": "leading",
@@ -46,12 +46,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",
@@ -84,7 +86,7 @@
       ],
       "code": "<Specimens>\n  <Specimen label=\"leading\">\n    <InputGroup leading={<Plug aria-hidden=\"true\" className=\"size-icon-md\" />}>\n      <Input aria-label=\"Node address\" defaultValue=\"10.0.0.42\" />\n    </InputGroup>\n  </Specimen>\n  <Specimen label=\"trailing\">\n    <InputGroup trailing={<span className=\"font-mono text-fg-subtle\">%</span>}>\n      <Input aria-label=\"Level\" defaultValue=\"80\" />\n    </InputGroup>\n  </Specimen>\n  <Specimen label=\"both, sm\">\n    <InputGroup\n      size=\"sm\"\n      leading={<Ruler aria-hidden=\"true\" className=\"size-icon-sm\" />}\n      trailing={<span className=\"font-mono text-fg-subtle\">m</span>}\n    >\n      <Input aria-label=\"Throw distance\" defaultValue=\"7.5\" />\n    </InputGroup>\n  </Specimen>\n</Specimens>",
       "note": "One rim around a control and its adornments, so the group focuses as a unit.",
-      "interaction": "focus inside the group lights the whole rim, not just the input."
+      "interaction": "any focus inside strengthens the whole rim; the ring waits for a keyboard-visible descendant, so a click on an adornment does not light the cluster up. The inner control never rings — the group owns the rim."
     }
   ],
   "todo": true

package/manifest/components/input.json

@@ -32,12 +32,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-3",
@@ -83,7 +85,7 @@
       ],
       "code": "<Specimens>\n  {SIZES.map((size) => (\n    <Specimen key={size} label={size}>\n      <Input aria-label={`Cue label, ${size}`} size={size} defaultValue=\"1/12 @ 80%\" />\n    </Specimen>\n  ))}\n  <Specimen label=\"placeholder\">\n    <Input aria-label=\"Empty cue label\" placeholder=\"e.g. Blackout\" />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <Input aria-label=\"Disabled cue label\" defaultValue=\"Read-only\" disabled />\n  </Specimen>\n  <Specimen label=\"readonly\">\n    <Input aria-label=\"Read-only cue label\" defaultValue=\"1/12 @ 80%\" readOnly />\n  </Specimen>\n</Specimens>",
       "note": "The recessed chassis: sunken fill, hairline rim, height from the density ladder.",
-      "interaction": "the rim goes accent on focus and the ring sits outside it; `invalid` turns the rim danger and outranks focus."
+      "interaction": "the rim strengthens one rung on focus and a single flush ring in the theme's focus colour sits just inside it — clicking in shows the same ring as tabbing in, because a typing surface is always focus-visible; `invalid` keeps the danger rim and the ring stays visible beside it."
     }
   ]
 }

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",