@cueplusplus/ui 0.3.0 → 0.6.0

package/manifest/components/image-generation.json

@@ -0,0 +1,67 @@
+{
+  "name": "ImageGeneration",
+  "slug": "image-generation",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A dot grid holds the frame while the image resolves out of a blur.",
+  "props": [
+    {
+      "name": "prompt",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Prompt text shown under the image frame."
+    },
+    {
+      "name": "generating",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true the frame holds a pulsing dot grid; otherwise the image resolves."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"prompt\" | \"generating\"> & {\n  /** Prompt text shown under the image frame. */\n  prompt: string;\n  /** When true the frame holds a pulsing dot grid; otherwise the image resolves. */\n  generating: boolean;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-3",
+    "--cue-text-ui"
+  ],
+  "summary": "A dot grid holds the frame while the image resolves out of a blur.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ImageGeneration } from \"@cueplusplus/ui/elements\";\n\n<ImageGeneration prompt=\"A calm blue abstract\" generating={false} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/image-generation",
+  "mdUrl": "/docs/components/image-generation.md",
+  "jsonUrl": "/r/components/image-generation.json",
+  "specimens": [
+    {
+      "title": "ImageGeneration",
+      "group": "elements-agents",
+      "components": [
+        "ImageGeneration"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"generating\">\n    <ImageGeneration prompt=\"Pre-vis: front wash at 8.4 m trim\" generating />\n  </Specimen>\n  <Specimen label=\"resolved\">\n    <ImageGeneration prompt=\"Pre-vis: front wash at 8.4 m trim\" generating={false} />\n  </Specimen>\n</Specimens>",
+      "note": "A dot grid holds the square while the image resolves out of a blur — the frame is the right size from the first frame, so nothing below it moves when the picture lands. While generating, the prompt is replaced by a shimmering label; when it settles, the prompt is what is left under the image.",
+      "interaction": "regenerate is a labelled icon button. The grid and the image are both `aria-hidden`: the prompt underneath is the description, and a decorative placeholder should not be announced as a picture."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/info-tip.json

@@ -30,7 +30,7 @@
     },
     {
       "name": "side",
-      "type": "\"left\" | \"right\" | \"top\" | \"bottom\" | \"inline-end\" | \"inline-start\"",
+      "type": "\"left\" | \"right\" | \"bottom\" | \"top\" | \"inline-end\" | \"inline-start\"",
       "required": false,
       "defaultValue": "top",
       "description": "Preferred side of the badge. Defaults to `\"top\"`."

package/manifest/components/inline-citation.json

@@ -0,0 +1,77 @@
+{
+  "name": "InlineCitation",
+  "slug": "inline-citation",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Numbered references inside a sentence, each with a hover preview of its source.",
+  "props": [
+    {
+      "name": "sources",
+      "type": "CitationSource[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Sources attached to the numbered reference markers in the sentence."
+    },
+    {
+      "name": "openIndex",
+      "type": "number | null",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which citation preview is open, or null when none is open."
+    },
+    {
+      "name": "onOpenIndexChange",
+      "type": "(index: number | null) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when a citation marker opens or closes its preview."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"p\">,\n  \"children\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-micro"
+  ],
+  "summary": "Numbered references inside a sentence, each with a hover preview of its source.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { InlineCitation } from \"@cueplusplus/ui/elements\";\n\n<InlineCitation\n  sources={[\n    {\n      domain: \"docs.example.com\",\n      title: \"Optimistic updates\",\n      snippet: \"Confirm writes after paint.\",\n    },\n  ]}\n  openIndex={0}\n  onOpenIndexChange={setOpenIndex}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/inline-citation",
+  "mdUrl": "/docs/components/inline-citation.md",
+  "jsonUrl": "/r/components/inline-citation.json",
+  "specimens": [
+    {
+      "title": "InlineCitation",
+      "group": "elements-knowledge",
+      "components": [
+        "InlineCitation"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"the first marker open\" wide>\n    <InlineCitation\n      sources={CITED}\n      openIndex={citation}\n      onOpenIndexChange={setCitation}\n    />\n  </Specimen>\n  <Specimen label=\"both closed\" wide>\n    <InlineCitation\n      sources={CITED}\n      openIndex={null}\n      onOpenIndexChange={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The marker inside the sentence, rather than the list under it: a numbered chip the paragraph flows around, and behind each one the page it stands on. `Sources` is the bibliography; this is the footnote, and the two are meant to be read together — the chip says a claim is attributable without spending a clause saying so.",
+      "interaction": "each marker is a button, so the preview is reachable from a keyboard as well as a pointer; the open one inverts to the accent fill. The card is the family's one portal, and it carries the island stamp — opened inside an `AgentSurface`, it paints in that island's values rather than the document's."
+    }
+  ],
+  "todo": true
+}

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/job-progress.json

@@ -0,0 +1,96 @@
+{
+  "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "name": "stageProgress",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Progress inside the current stage, 0 to 1."
+    },
+    {
+      "name": "eta",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Pre-formatted estimate. Replaced by done once finished."
+    },
+    {
+      "name": "onCancel",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to stop the job. Hidden once it finishes."
+    }
+  ],
+  "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/launcher-bubble.json

@@ -0,0 +1,105 @@
+{
+  "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."
+    },
+    {
+      "name": "unread",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Badge count on the closed bubble. Hidden at zero and while open."
+    },
+    {
+      "name": "greeting",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Opening line in the panel."
+    },
+    {
+      "name": "prompts",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Ways in, so the first message does not have to be invented."
+    },
+    {
+      "name": "onToggle",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the bubble is pressed."
+    },
+    {
+      "name": "onPick",
+      "type": "((prompt: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a starter prompt is chosen."
+    },
+    {
+      "name": "onStart",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the Start a conversation action, for opening an empty thread."
+    }
+  ],
+  "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,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."
+    }
+  ]
+}