@cueplusplus/ui 0.13.0

package/manifest/components/job-progress.json

@@ -0,0 +1,116 @@
+{
+  "name": "JobProgress",
+  "slug": "job-progress",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Work measured in minutes: weighted stages, an ETA, and a way out.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the job is doing.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "stages",
+      "type": "readonly JobStage[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Stages with relative weights, so a long install does not read the same as a fast\nclone.",
+      "control": {
+        "kind": "array",
+        "fixture": "agents.stages"
+      }
+    },
+    {
+      "name": "stageIndex",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which stage is running. Passing stages.length marks the job finished, and the bar\nnever runs past its track.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "stageProgress",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Progress inside the current stage, 0 to 1.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "eta",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Pre-formatted estimate. Replaced by done once finished.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onCancel",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to stop the job. Hidden once it finishes.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"title\"\n  | \"stages\"\n  | \"stageIndex\"\n  | \"stageProgress\"\n  | \"eta\"\n  | \"onCancel\"\n> & {\n  /** What the job is doing. */\n  title: string;\n  /**\n   * Stages with relative weights, so a long install does not read the same as a fast\n   * clone.\n   */\n  stages: readonly JobStage[];\n  /**\n   * Which stage is running. Passing stages.length marks the job finished, and the bar\n   * never runs past its track.\n   */\n  stageIndex: number;\n  /** Progress inside the current stage, 0 to 1. */\n  stageProgress: number;\n  /** Pre-formatted estimate. Replaced by done once finished. */\n  eta: string;\n  /** Called to stop the job. Hidden once it finishes. */\n  onCancel?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "Work measured in minutes: weighted stages, an ETA, and a way out.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { JobProgress } from \"@cueplusplus/ui/elements\";\n\n<JobProgress\n  title=\"Verify the fix on CI\"\n  stages={stages}\n  stageIndex={1}\n  stageProgress={0.6}\n  eta=\"about 3 min\"\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/job-progress",
+  "mdUrl": "/docs/components/job-progress.md",
+  "jsonUrl": "/r/components/job-progress.json",
+  "specimens": [
+    {
+      "title": "JobProgress",
+      "group": "elements-agents",
+      "components": [
+        "JobProgress"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"rendering\" wide>\n    <JobProgress\n      title=\"Overnight patch and pre-vis\"\n      stages={STAGES}\n      stageIndex={2}\n      stageProgress={0.42}\n      eta=\"4m left\"\n      onCancel={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"done\" wide>\n    <JobProgress\n      title=\"Overnight patch and pre-vis\"\n      stages={STAGES}\n      stageIndex={STAGES.length}\n      stageProgress={1}\n      eta=\"4m left\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Work measured in minutes rather than steps. The stages are weighted, so a six-minute render does not read the same length as a one-second export, and the bar is filled from those weights plus the fraction of the current stage — which is why it never jumps backwards when a short stage ends.",
+      "interaction": "cancel is a labelled icon button and disappears once the job finishes: there is nothing left to stop, and a dead X beside a green tick reads as an error."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/kbd.json

@@ -0,0 +1,52 @@
+{
+  "name": "Kbd",
+  "slug": "kbd",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A key cap for documenting shortcuts inline: `⌘K`, `Esc`, `Shift`.\n\nStatic markup — no `\"use client\"`, so it renders on the server. Sized off the\nchip height so a `Kbd` and a `Chip` line up on the same row, and set in the\nmicro type step because shortcut hints are reference material, not content.",
+  "props": [],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"kbd\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-chip-h",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-surface-2",
+    "--cue-text-micro"
+  ],
+  "summary": "A key cap for documenting shortcuts inline: `⌘K`, `Esc`, `Shift`.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<span>Press <Kbd>⌘</Kbd><Kbd>K</Kbd> to search</span>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/kbd",
+  "mdUrl": "/docs/components/kbd.md",
+  "jsonUrl": "/r/components/kbd.json",
+  "specimens": [
+    {
+      "title": "Kbd",
+      "group": "primitives",
+      "components": [
+        "Kbd"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"single\">\n    <Kbd>G</Kbd>\n  </Specimen>\n  <Specimen label=\"chord\">\n    <Kbd>⌘K</Kbd>\n  </Specimen>\n  <Specimen label=\"in a line\">\n    <span className=\"font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      Press <Kbd>⌘</Kbd> <Kbd>⇧</Kbd> <Kbd>P</Kbd> to open the palette.\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "A key cap, in the mono face. Static markup, so it renders on the server.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/launcher-bubble.json

@@ -0,0 +1,130 @@
+{
+  "name": "LauncherBubble",
+  "slug": "launcher-bubble",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The floating entry point, and the panel it opens into.",
+  "props": [
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the panel is showing. The trigger icon crossfades either way.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "unread",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Badge count on the closed bubble. Hidden at zero and while open.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "greeting",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Opening line in the panel.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "prompts",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Ways in, so the first message does not have to be invented.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "onToggle",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the bubble is pressed.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onPick",
+      "type": "((prompt: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a starter prompt is chosen.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onStart",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the Start a conversation action, for opening an empty thread.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"open\"\n  | \"unread\"\n  | \"greeting\"\n  | \"prompts\"\n  | \"onToggle\"\n  | \"onPick\"\n  | \"onStart\"\n> & {\n  /** Whether the panel is showing. The trigger icon crossfades either way. */\n  open: boolean;\n  /** Badge count on the closed bubble. Hidden at zero and while open. */\n  unread: number;\n  /** Opening line in the panel. */\n  greeting: string;\n  /** Ways in, so the first message does not have to be invented. */\n  prompts: readonly string[];\n  /** Called when the bubble is pressed. */\n  onToggle?: () => void;\n  /** Called when a starter prompt is chosen. */\n  onPick?: (prompt: string) => void;\n  /** Called from the Start a conversation action, for opening an empty thread. */\n  onStart?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "The floating entry point, and the panel it opens into.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { LauncherBubble } from \"@cueplusplus/ui/elements\";\n\n<LauncherBubble\n  open={open}\n  unread={2}\n  greeting=\"Need a hand?\"\n  prompts={prompts}\n  onToggle={toggle}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/launcher-bubble",
+  "mdUrl": "/docs/components/launcher-bubble.md",
+  "jsonUrl": "/r/components/launcher-bubble.json",
+  "specimens": [
+    {
+      "title": "LauncherBubble",
+      "group": "elements-composer",
+      "components": [
+        "LauncherBubble"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"open\" wide>\n    <LauncherBubble\n      open={launcher}\n      unread={2}\n      greeting=\"Ask us about the venue\"\n      prompts={[\"What is the rig?\", \"Can I bring my own desk?\", \"Who is the LX contact?\"]}\n      onToggle={() => setLauncher((open) => !open)}\n      onPick={() => setLauncher(false)}\n      onStart={() => setLauncher(false)}\n    />\n  </Specimen>\n  <Specimen label=\"closed, two waiting\" wide>\n    <LauncherBubble\n      open={false}\n      unread={2}\n      greeting=\"Ask us about the venue\"\n      prompts={[\"What is the rig?\"]}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The floating entry point and the panel it opens into — the shape an assistant takes on somebody else's site. The badge counts unread and disappears the moment the panel is open, because a count of things you are currently looking at is noise. The starter prompts exist so the first message does not have to be invented by a visitor who has no idea what this thing knows.",
+      "interaction": "the bubble carries `aria-expanded` and its label changes with it (`Open the assistant` / `Close the assistant`); the two icons cross-fade in one grid cell so nothing reflows."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/ledger.json

@@ -0,0 +1,330 @@
+{
+  "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:\nheadings, slugs, rows. What it owns above all is the document outline. Tiers\nand groups are real `<h2>` / `<h3>` elements at caller-chosen levels, because\nin a list of two hundred rows the heading list *is* how a screen-reader user\nnavigates.\n\n## Folding: the accordion pattern, opt-in, and why it lives here\n\nThis component used to refuse disclosure outright, on the grounds that *a\nledger which folds is a tree with worse semantics*. That ruling was right\nabout rows and wrong about places, and the distinction is the whole of\n{@link LedgerTierProps.collapsible}:\n\n- **`DataTree` folds a row.** Its `role=\"treeitem\"` rows carry their own\n  `aria-expanded`, its chevron is `role=\"presentation\"` because in tree\n  semantics the row owns its expansion, and a tier and a subgroup drawn\n  through it stop being places and become rows. A consumer who measured this\n  exact shape through `DataTree` counted **zero** `h2`/`h3` elements and zero\n  `button[aria-expanded]`, which is `DataTree` working correctly and still\n  not being what a grouped document needs.\n- **`Ledger` folds a place.** A tier is already an `<h2>`, which is already\n  the right element for it, so the disclosure goes *inside* the heading as a\n  real `<button aria-expanded aria-controls>` — the accordion pattern, and\n  the same one `Table.GroupRow`'s note has always pointed at for a table that\n  genuinely needs to fold. The outline is untouched: the heading list of a\n  folding ledger and a plain one are identical, which is what lets a page\n  offer both idioms over one dataset without the outline moving under a\n  reader who switches.\n\nSo it is one component with two forms rather than a `DisclosureLedger` beside\nit: everything a folding ledger needs — the gutter track, the sticky offsets,\nthe label recipe, the type contract — is this component, and a sibling would\nhave been a copy of all of it wrapped around one `<button>`.\n\nExpansion is controllable and stores nothing. *Which* places a reader has\nfolded is a fact about the reader; consumers keep that set themselves and\npass it back in. A folded run of rows is hidden rather than unmounted, so a\ngroup that keeps its own fold inside a tier still keeps it after the tier has\nbeen shut and opened over it.\n\nStatic markup — no `\"use client\"` — **until a heading is asked to fold**, at\nwhich point that heading and its rows become a small client island and the\nrest of the ledger keeps rendering on the server.",
+  "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.",
+          "control": {
+            "kind": "boolean"
+          }
+        }
+      ],
+      "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.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "count",
+          "type": "number",
+          "required": false,
+          "defaultValue": null,
+          "description": "How many rows the tier holds, printed beside its name.",
+          "control": {
+            "kind": "number"
+          }
+        },
+        {
+          "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`.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "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.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              4,
+              2,
+              3
+            ],
+            "min": 2,
+            "max": 4
+          }
+        },
+        {
+          "name": "note",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "A qualifier printed after the name — a date, a source, a state.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "collapsible",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Put a disclosure in the tier's heading that folds its rows away. Defaults\nto `false`, and a tier with no `heading` has nothing to fold from, so it\nignores this and renders as it always has.\n\n**This is the accordion pattern, not the tree pattern.** What folds is the\nheading — a *place* — and the `<h2>` stays exactly where it was with a real\n`<button aria-expanded aria-controls>` inside it. The rows below are hidden\nwhile it is shut, which takes them out of the accessibility tree and out of\nthe layout but keeps whatever state they hold. If what you are folding is a\n*row*, and the thing under it is that row's children rather than that\nplace's contents, you want `DataTree` and its `treeitem` semantics instead.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "expanded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Whether the tier is open, when the caller owns the state.\n\n**Persistence is the caller's.** Which places a reader has folded is a fact\nabout the reader, not about the list, and it belongs wherever that consumer\nkeeps the rest of them — `localStorage`, a URL, a profile. This library\nstores nothing. Pass this with {@link LedgerTierProps.onExpandedChange};\nomit both and the tier keeps its own state from\n{@link LedgerTierProps.defaultExpanded}. Ignored unless `collapsible`.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "defaultExpanded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Whether an uncontrolled tier starts open. Defaults to `true`.\n\nOpen, because a ledger whose content is folded away on first paint has\nhidden the thing the reader came for; the reader folds what they are done\nwith. Ignored unless `collapsible`, and ignored entirely once\n{@link LedgerTierProps.expanded} is passed.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "onExpandedChange",
+          "type": "((expanded: boolean) => void)",
+          "required": false,
+          "defaultValue": null,
+          "description": "Called with the tier's next state each time the reader presses the\ndisclosure — `true` when it is being opened, `false` when it is being shut.\n\nFires in both the controlled and the uncontrolled form, so a consumer can\nrecord what was folded without also having to own the state.",
+          "control": {
+            "kind": "callback",
+            "fixture": "callback.log"
+          }
+        }
+      ],
+      "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.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "headingLevel",
+          "type": "4 | 3",
+          "required": false,
+          "defaultValue": "3",
+          "description": "Which heading element the slug is. Defaults to `3`.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              4,
+              3
+            ],
+            "min": 3,
+            "max": 4
+          }
+        },
+        {
+          "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.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "collapsible",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Put a disclosure in the group's slug that folds its rows away. Defaults to\n`false`, and an unlabelled group has no slug to fold from, so it ignores\nthis. The same accordion pattern the tier takes — see\n{@link LedgerTierProps.collapsible} for why it is not the tree pattern.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "expanded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Whether the group is open, when the caller owns the state. Persistence is\nthe caller's; see {@link LedgerTierProps.expanded}.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "defaultExpanded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Whether an uncontrolled group starts open. Defaults to `true`.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "onExpandedChange",
+          "type": "((expanded: boolean) => void)",
+          "required": false,
+          "defaultValue": null,
+          "description": "Called with the group's next state each time the reader presses the slug.",
+          "control": {
+            "kind": "callback",
+            "fixture": "callback.log"
+          }
+        }
+      ],
+      "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-accent",
+    "--cue-bg",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--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 an opt-in disclosure that folds a heading without leaving the outline.",
+  "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": "Folded places, persisted by the caller",
+      "code": "<Ledger.Tier\n  heading=\"Ours\"\n  count={13}\n  collapsible\n  expanded={!folded.includes(\"ours\")}\n  onExpandedChange={(open) => remember(\"ours\", open)}\n>\n  <Ledger.Group label=\"released\" collapsible defaultExpanded={false}>\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>\n// Folded places are the reader's, so the reader's storage holds them.\n<Ledger.Tier\n  heading=\"Ours\"\n  count={13}\n  collapsible\n  expanded={!folded.includes(\"ours\")}\n  onExpandedChange={(open) => remember(\"ours\", open)}\n>\n  <Ledger.Group label=\"released\">…</Ledger.Group>\n</Ledger.Tier>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/ledger",
+  "mdUrl": "/docs/components/ledger.md",
+  "jsonUrl": "/r/components/ledger.json",
+  "whenToUse": [
+    "A long grouped list: 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.",
+    "A grouped list the reader folds *by place* — `collapsible` puts a real `button[aria-expanded]` inside the heading and leaves the `h2`/`h3` outline exactly as it was."
+  ],
+  "whenNotToUse": [
+    "A hierarchy whose *rows* fold into their own children. Use `DataTree`, where the row is the treeitem and owns its expansion.",
+    "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": [
+    "Reaching for `DataTree` to fold a grouped list. A tree turns every tier and subgroup into a `treeitem` row and leaves zero headings behind — if the thing folding is a *place*, `collapsible` is the prop.",
+    "Storing the folded set inside the component. Which places a reader folded is a fact about the reader: pass `expanded` and `onExpandedChange` and keep it wherever the rest of that reader's preferences live.",
+    "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 until a heading is asked for one — this bench asks for none, so the whole surface stays static markup. The bench below it asks.",
+      "interaction": "the tier heading and the group slug dock as the rows scroll under them; scroll the pane to see it."
+    },
+    {
+      "title": "Ledger — collapsible",
+      "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\n        heading=\"Patch\"\n        count={PATCH_DEVICES.length}\n        collapsible\n        expanded={patchOpen}\n        onExpandedChange={setPatchOpen}\n      >\n        {PATCH_GROUPS.map((group, index) => (\n          <Ledger.Group\n            key={group.id}\n            label={group.label}\n            collapsible\n            defaultExpanded={index === 0}\n          >\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.Tier>\n    </Ledger.Root>\n  </div>\n</Panel>",
+      "note": "The same ledger with `collapsible` on the tier and on one group. The disclosure is a real `button[aria-expanded aria-controls]` *inside* the `h2`/`h3`, so the heading outline is identical to the bench above it. A folded run of rows is hidden rather than unmounted — out of the layout and out of the accessibility tree, but still holding its state, which is what lets a group keep its own fold while the tier above it is shut and reopened. Which places are folded is the caller's to keep; this bench keeps it in React state and nothing is stored by the library.",
+      "interaction": "press a tier heading or a group slug to fold it; the chevron turns, the sibling group stays open, and Tab reaches each disclosure as a real button with Enter and Space. Fold the first group, then fold and reopen the tier over it: the group is still folded."
+    }
+  ]
+}