@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/quote-reply.json

@@ -0,0 +1,105 @@
+{
+  "name": "QuoteReply",
+  "slug": "quote-reply",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Select a phrase in an answer and a toolbar offers to quote, explain, or rewrite it.",
+  "props": [
+    {
+      "name": "before",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Text preceding the selection."
+    },
+    {
+      "name": "selection",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The highlighted run the actions apply to."
+    },
+    {
+      "name": "after",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Text following the selection."
+    },
+    {
+      "name": "actions",
+      "type": "readonly QuoteAction[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the toolbar offers. Each action names one of the three built-in icons."
+    },
+    {
+      "name": "toolbarVisible",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the floating toolbar is showing. Drive it from your own selection handler."
+    },
+    {
+      "name": "quoted",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Once quoted, the text carried into the composer, shown under a rule."
+    },
+    {
+      "name": "onAction",
+      "type": "((key: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the key of the action that was chosen."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"before\"\n  | \"selection\"\n  | \"after\"\n  | \"actions\"\n  | \"toolbarVisible\"\n  | \"quoted\"\n  | \"onAction\"\n> & {\n  /** Text preceding the selection. */\n  before: string;\n  /** The highlighted run the actions apply to. */\n  selection: string;\n  /** Text following the selection. */\n  after: string;\n  /** What the toolbar offers. Each action names one of the three built-in icons. */\n  actions: readonly QuoteAction[];\n  /** Whether the floating toolbar is showing. Drive it from your own selection handler. */\n  toolbarVisible: boolean;\n  /** Once quoted, the text carried into the composer, shown under a rule. */\n  quoted?: string;\n  /** Called with the key of the action that was chosen. */\n  onAction?: (key: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Select a phrase in an answer and a toolbar offers to quote, explain, or rewrite it.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { QuoteReply } from \"@cueplusplus/ui/elements\";\n\n<QuoteReply\n  before=\"The regression happens because \"\n  selection=\"the converter drops parts with no text\"\n  after=\", so the turn never lands.\"\n  actions={actions}\n  toolbarVisible\n  onAction={handle}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/quote-reply",
+  "mdUrl": "/docs/components/quote-reply.md",
+  "jsonUrl": "/r/components/quote-reply.json",
+  "specimens": [
+    {
+      "title": "QuoteReply",
+      "group": "elements-thread",
+      "components": [
+        "QuoteReply"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"toolbar up\" wide>\n    <QuoteReply\n      before=\"Patched 6 fixtures on \"\n      selection=\"universe 3, channels 1 to 48\"\n      after=\". Cue 1 is untouched.\"\n      actions={QUOTE_ACTIONS}\n      toolbarVisible\n    />\n  </Specimen>\n  <Specimen label=\"quoted\" wide>\n    <QuoteReply\n      before=\"Patched 6 fixtures on \"\n      selection=\"universe 3, channels 1 to 48\"\n      after=\". Cue 1 is untouched.\"\n      actions={QUOTE_ACTIONS}\n      toolbarVisible={false}\n      quoted=\"universe 3, channels 1 to 48\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Select a phrase in an answer and act on that phrase rather than the whole turn. The selection stays lit in the streaming hue while the toolbar is up, and what you quoted is repeated under the composer so the next turn's subject is never in doubt.",
+      "interaction": "the toolbar's row is reserved whether or not it is showing, so nothing below it jumps when a selection appears. Each action is a labelled button."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/radio-group.json

@@ -0,0 +1,73 @@
+{
+  "name": "RadioGroup",
+  "slug": "radio-group",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "One-of-many selection: a roving-tabindex group of {@link Radio}s sharing a\nsingle value.\n\nArrow keys move *and* select, per the WAI-ARIA radio group pattern that Base\nUI implements — so the whole group is one tab stop, which is what keeps a\ndense settings panel navigable.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the stack defaults."
+    },
+    {
+      "name": "orientation",
+      "type": "\"horizontal\" | \"vertical\"",
+      "required": false,
+      "defaultValue": "vertical",
+      "description": "Lay the options out in a column (default) or a row."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseRadioGroup.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-ui"
+  ],
+  "summary": "One-of-many selection: a roving-tabindex group of {@link Radio}s sharing a single value.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<RadioGroup aria-label=\"Blend mode\" value={mode} onValueChange={setMode}>\n  <Radio value=\"htp\" label=\"HTP\" />\n  <Radio value=\"ltp\" label=\"LTP\" />\n</RadioGroup>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/radio-group",
+  "mdUrl": "/docs/components/radio-group.md",
+  "jsonUrl": "/r/components/radio-group.json",
+  "specimens": [
+    {
+      "title": "RadioGroup",
+      "group": "forms",
+      "components": [
+        "RadioGroup",
+        "Radio"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <RadioGroup aria-label=\"Blend mode\" defaultValue=\"htp\">\n    {BLEND_MODES.map((option) => (\n      <Radio key={option.value} value={option.value} label={option.label} />\n    ))}\n  </RadioGroup>\n  <RadioGroup aria-label=\"Blend mode, horizontal\" defaultValue=\"ltp\" orientation=\"horizontal\">\n    {BLEND_MODES.map((option) => (\n      <Radio key={option.value} value={option.value} label={option.label} />\n    ))}\n    <Radio value=\"off\" label=\"Off\" disabled />\n  </RadioGroup>\n</div>",
+      "note": "One choice out of a short set, in either orientation.",
+      "interaction": "arrow keys move the selection, and the group is one tab stop."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/radio.json

@@ -0,0 +1,80 @@
+{
+  "name": "Radio",
+  "slug": "radio",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "One option inside a {@link RadioGroup}.\n\nRound, to say \"exactly one\" the way a square {@link Checkbox } says \"any\nnumber\". Checked draws an accent rim with an accent core rather than a solid\nfill, so the selected option stays legible against the sunken field colour on\nevery theme.",
+  "props": [
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Inline label rendered beside the dot and wrapped with it in a `<label>`, so\nthe text is both the accessible name and part of the hit target."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the dot defaults."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the density icon ladder for the dot. Defaults to `\"md\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseRadio.Root.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-ui"
+  ],
+  "summary": "One option inside a {@link RadioGroup}.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Radio value=\"htp\" label=\"Highest takes precedence\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/radio",
+  "mdUrl": "/docs/components/radio.md",
+  "jsonUrl": "/r/components/radio.json",
+  "specimens": [
+    {
+      "title": "RadioGroup",
+      "group": "forms",
+      "components": [
+        "RadioGroup",
+        "Radio"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <RadioGroup aria-label=\"Blend mode\" defaultValue=\"htp\">\n    {BLEND_MODES.map((option) => (\n      <Radio key={option.value} value={option.value} label={option.label} />\n    ))}\n  </RadioGroup>\n  <RadioGroup aria-label=\"Blend mode, horizontal\" defaultValue=\"ltp\" orientation=\"horizontal\">\n    {BLEND_MODES.map((option) => (\n      <Radio key={option.value} value={option.value} label={option.label} />\n    ))}\n    <Radio value=\"off\" label=\"Off\" disabled />\n  </RadioGroup>\n</div>",
+      "note": "One choice out of a short set, in either orientation.",
+      "interaction": "arrow keys move the selection, and the group is one tab stop."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/rating.json

@@ -0,0 +1,141 @@
+{
+  "name": "Rating",
+  "slug": "rating",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A 0–N rating, drawn as marks.\n\nBuilt as a **radio group**, not a row of buttons: exactly one value is in\neffect, arrow keys move between the options, and one Tab stop covers the whole\nwidget. A row of toggle buttons would put five stops in the tab order and\nannounce five unrelated controls.\n\nRead-only renders as a single `img` with the value in its name — an\nun-interactive control that still takes focus is a trap, and five disabled\nradios announce five things where one sentence will do.",
+  "props": [
+    {
+      "name": "value",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "The rating, `0`–`count`. Use with `onValueChange` for a controlled widget."
+    },
+    {
+      "name": "defaultValue",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0",
+      "description": "Initial rating for an uncontrolled widget. Defaults to `0`."
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: number) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the new rating; `0` means \"cleared\"."
+    },
+    {
+      "name": "count",
+      "type": "number",
+      "required": false,
+      "defaultValue": "5",
+      "description": "How many marks. Defaults to `5`."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the icon ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "allowClear",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Picking the current value clears it back to `0`. Defaults to `true` — a\nrating you cannot take back is a trap, and there is no other affordance for\n\"actually, no opinion\"."
+    },
+    {
+      "name": "readOnly",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Render a static readout with no controls."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Grey the marks out and refuse interaction."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the group. Also the prefix of the read-only readout —\n`\"Signal quality: 4 of 5\"`. Synonym of `aria-label`, which wins if both are\ngiven."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the group, for callers who prefer the ARIA spelling."
+    },
+    {
+      "name": "icon",
+      "type": "ElementType<any, keyof IntrinsicElements>",
+      "required": false,
+      "defaultValue": "StarGlyph",
+      "description": "The mark component. Defaults to a filled star."
+    },
+    {
+      "name": "markLabel",
+      "type": "((index: number, count: number) => string)",
+      "required": false,
+      "defaultValue": "(index, total) => `${index} of ${total}`",
+      "description": "Accessible name for mark `index` (1-based) of `count`. Defaults to\n``(index, count) => `${index} of ${count}` ``."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the group."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onChange\" | \"defaultValue\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-space-1"
+  ],
+  "summary": "A 0–N rating, drawn as marks.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Rating label=\"Signal quality\" value={score} onValueChange={setScore} />\n<Rating aria-label=\"Signal quality\" value={4} readOnly size=\"sm\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/rating",
+  "mdUrl": "/docs/components/rating.md",
+  "jsonUrl": "/r/components/rating.json",
+  "specimens": [
+    {
+      "title": "Rating",
+      "group": "forms",
+      "components": [
+        "Rating"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <Rating label=\"Rig condition\" defaultValue={4} />\n  </Specimen>\n  <Specimen label=\"clearable\">\n    <Rating label=\"Rig condition, clearable\" defaultValue={3} allowClear />\n  </Specimen>\n  <Specimen label=\"read-only\">\n    <Rating label=\"Rig condition, read-only\" value={5} readOnly />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <Rating label=\"Rig condition, disabled\" defaultValue={2} disabled />\n  </Specimen>\n</Specimens>",
+      "note": "A radio group of marks, with the value spoken rather than implied by how many glyphs are filled.",
+      "interaction": "arrow keys move; clicking the current mark clears it when `allowClear` is on."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/read-aloud.json

@@ -0,0 +1,111 @@
+{
+  "name": "ReadAloud",
+  "slug": "read-aloud",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "An answer played back, the spoken word lit as it goes, speed under your thumb.",
+  "props": [
+    {
+      "name": "words",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The answer split into words, so the spoken one can be lit without re-parsing the\ntext."
+    },
+    {
+      "name": "spokenIndex",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Index of the word being spoken. Everything before it dims, everything after stays\nwaiting, and an index outside the text speaks none of it."
+    },
+    {
+      "name": "playing",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Swaps the transport button between play and pause."
+    },
+    {
+      "name": "rate",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Playback speed, printed on the rate control."
+    },
+    {
+      "name": "elapsed",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Pre-formatted elapsed time."
+    },
+    {
+      "name": "duration",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Pre-formatted total duration."
+    },
+    {
+      "name": "onToggle",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when playback is started or paused."
+    },
+    {
+      "name": "onRateChange",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the rate control is tapped; cycle the rate yourself."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"words\"\n  | \"spokenIndex\"\n  | \"playing\"\n  | \"rate\"\n  | \"elapsed\"\n  | \"duration\"\n  | \"onToggle\"\n  | \"onRateChange\"\n> & {\n  /**\n   * The answer split into words, so the spoken one can be lit without re-parsing the\n   * text.\n   */\n  words: readonly string[];\n  /**\n   * Index of the word being spoken. Everything before it dims, everything after stays\n   * waiting, and an index outside the text speaks none of it.\n   */\n  spokenIndex: number;\n  /** Swaps the transport button between play and pause. */\n  playing: boolean;\n  /** Playback speed, printed on the rate control. */\n  rate: number;\n  /** Pre-formatted elapsed time. */\n  elapsed: string;\n  /** Pre-formatted total duration. */\n  duration: string;\n  /** Called when playback is started or paused. */\n  onToggle?: () => void;\n  /** Called when the rate control is tapped; cycle the rate yourself. */\n  onRateChange?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "An answer played back, the spoken word lit as it goes, speed under your thumb.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ReadAloud } from \"@cueplusplus/ui/elements\";\n\n<ReadAloud\n  words={words}\n  spokenIndex={12}\n  playing\n  rate={1}\n  elapsed=\"0:04\"\n  duration=\"0:11\"\n  onToggle={toggle}\n  onRateChange={cycleRate}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/read-aloud",
+  "mdUrl": "/docs/components/read-aloud.md",
+  "jsonUrl": "/r/components/read-aloud.json",
+  "specimens": [
+    {
+      "title": "ReadAloud",
+      "group": "elements-thread",
+      "components": [
+        "ReadAloud"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"playing\" wide>\n    <ReadAloud\n      words={SPOKEN}\n      spokenIndex={4}\n      playing={playing}\n      rate={rate}\n      elapsed=\"0:06\"\n      duration=\"0:14\"\n      onToggle={() => setPlaying((current) => !current)}\n      onRateChange={() => setRate((current) => (current === 2 ? 1 : current + 0.5))}\n    />\n  </Specimen>\n  <Specimen label=\"paused at the start\" wide>\n    <ReadAloud\n      words={SPOKEN}\n      spokenIndex={0}\n      playing={false}\n      rate={1}\n      elapsed=\"0:00\"\n      duration=\"0:14\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "An answer played back with the spoken word lit as it goes. Position is a word index the caller advances, not an audio element, so the same component drives a real voice, a replay, or this bench. Speed is one tap away because that is the control people actually reach for.",
+      "interaction": "play/pause and the speed chip are both named buttons, and the label says the current rate rather than just the glyph. The progress bar animates linearly, and not at all under reduced motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/reasoning-effort.json

@@ -0,0 +1,81 @@
+{
+  "name": "ReasoningEffort",
+  "slug": "reasoning-effort",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "How hard to think, and how much of that budget the run actually spent.",
+  "props": [
+    {
+      "name": "levels",
+      "type": "readonly EffortLevel[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Every tier on offer, each carrying its own token budget."
+    },
+    {
+      "name": "selectedKey",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which tier is active. Its budget becomes the denominator."
+    },
+    {
+      "name": "spent",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Thinking tokens used so far, filling the bar against the selected budget."
+    },
+    {
+      "name": "onSelect",
+      "type": "((key: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a tier is picked."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"levels\" | \"selectedKey\" | \"spent\" | \"onSelect\"\n> & {\n  /** Every tier on offer, each carrying its own token budget. */\n  levels: readonly EffortLevel[];\n  /** Which tier is active. Its budget becomes the denominator. */\n  selectedKey: string;\n  /** Thinking tokens used so far, filling the bar against the selected budget. */\n  spent: number;\n  /** Called when a tier is picked. */\n  onSelect?: (key: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "How hard to think, and how much of that budget the run actually spent.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ReasoningEffort } from \"@cueplusplus/ui/elements\";\n\n<ReasoningEffort\n  levels={levels}\n  selectedKey=\"high\"\n  spent={5200}\n  onSelect={setLevel}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/reasoning-effort",
+  "mdUrl": "/docs/components/reasoning-effort.md",
+  "jsonUrl": "/r/components/reasoning-effort.json",
+  "specimens": [
+    {
+      "title": "ReasoningEffort",
+      "group": "elements-thread",
+      "components": [
+        "ReasoningEffort"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"medium, a third spent\" wide>\n    <ReasoningEffort\n      levels={EFFORT}\n      selectedKey={effort}\n      spent={2841}\n      onSelect={setEffort}\n    />\n  </Specimen>\n  <Specimen label=\"low, over its rung\" wide>\n    <ReasoningEffort levels={EFFORT} selectedKey=\"low\" spent={2048} />\n  </Specimen>\n</Specimens>",
+      "note": "How hard to think, and how much of that budget the run actually spent. The segmented control is the choice; the hairline under it is the consequence, and it moves when you change rungs because a bigger budget makes the same spend a smaller fraction.",
+      "interaction": "each segment is a button carrying aria-pressed. The meter animates its width rather than jumping, and holds still for a reader who asked for less motion."
+    }
+  ],
+  "todo": true
+}