@cueplusplus/ui 0.13.0

package/manifest/components/agent-plan.json

@@ -0,0 +1,74 @@
+{
+  "name": "AgentPlan",
+  "slug": "agent-plan",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A checklist the agent works through, with progress you can glance.",
+  "props": [
+    {
+      "name": "steps",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Checklist items the agent works through in order.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "activeIndex",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Index of the step currently running. Values past the end mark every step done, and\nvalues before the start mark none.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"steps\" | \"activeIndex\"> & {\n  /** Checklist items the agent works through in order. */\n  steps: readonly string[];\n  /**\n   * Index of the step currently running. Values past the end mark every step done, and\n   * values before the start mark none.\n   */\n  activeIndex: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body"
+  ],
+  "summary": "A checklist the agent works through, with progress you can glance.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { AgentPlan } from \"@cueplusplus/ui/elements\";\n\n<AgentPlan\n  steps={[\"Read the file\", \"Draft the fix\", \"Run tests\"]}\n  activeIndex={1}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-plan",
+  "mdUrl": "/docs/components/agent-plan.md",
+  "jsonUrl": "/r/components/agent-plan.json",
+  "specimens": [
+    {
+      "title": "AgentPlan",
+      "group": "elements",
+      "components": [
+        "AgentPlan"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"step 1\" wide>\n    <AgentPlan steps={PLAN} activeIndex={0} />\n  </Specimen>\n  <Specimen label=\"step 3\" wide>\n    <AgentPlan steps={PLAN} activeIndex={2} />\n  </Specimen>\n  <Specimen label=\"finished\" wide>\n    <AgentPlan steps={PLAN} activeIndex={PLAN.length} />\n  </Specimen>\n</Specimens>",
+      "note": "The checklist the agent published before it started, with one index driving the whole thing: steps before it are done, the step at it is running, steps after it are waiting. An index past the end marks every step done.",
+      "interaction": "none. A plan is a readout; the agent moves it, not the reader."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/agent-status.json

@@ -0,0 +1,87 @@
+{
+  "name": "AgentStatus",
+  "slug": "agent-status",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "One pill that always answers: what is it doing, and for how long.",
+  "props": [
+    {
+      "name": "state",
+      "type": "\"done\" | \"working\" | \"waiting\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Visual mode of the pill: working, waiting, or done with a check.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "done",
+          "working",
+          "waiting"
+        ]
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Short status line describing what the agent is doing.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "elapsed",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Elapsed time shown in mono when provided.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"state\" | \"label\" | \"elapsed\"> & {\n  /** Visual mode of the pill: working, waiting, or done with a check. */\n  state: AgentState;\n  /** Short status line describing what the agent is doing. */\n  label: string;\n  /** Elapsed time shown in mono when provided. */\n  elapsed?: string;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-stream",
+    "--cue-surface-3",
+    "--cue-text-ui"
+  ],
+  "summary": "One pill that always answers: what is it doing, and for how long.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { AgentStatus } from \"@cueplusplus/ui/elements\";\n\n<AgentStatus state=\"working\" label=\"Editing composer.tsx\" elapsed=\"8s\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-status",
+  "mdUrl": "/docs/components/agent-status.md",
+  "jsonUrl": "/r/components/agent-status.json",
+  "specimens": [
+    {
+      "title": "AgentStatus",
+      "group": "elements",
+      "components": [
+        "AgentStatus"
+      ],
+      "code": "<Specimens>\n  {PILLS.map((pill) => (\n    <Specimen key={pill.state} label={pill.state}>\n      <AgentStatus state={pill.state} label={pill.label} elapsed={pill.elapsed} />\n    </Specimen>\n  ))}\n</Specimens>",
+      "note": "One pill that always answers the two questions a run raises: what is it doing, and for how long. Working shimmers, waiting is still and marked, done carries a check and the elapsed total.",
+      "interaction": "the trailing control is a labelled icon button that pauses a run and offers to run it again once it is done."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/agent-surface.json

@@ -0,0 +1,93 @@
+{
+  "name": "AgentSurface",
+  "slug": "agent-surface",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The supersede island: one subtree, painted by a different set of values.\n\nRenders a plain `<div data-slot=\"agent-surface\" data-cue-skin=\"…\"\ndata-cue-fidelity=\"…\">` and publishes the same pair on React context. The attributes do the work —\n`@cueplusplus/ui/elements.css` re-declares, under them, the `--cue-*` tokens\nthe whole elements family reads, and custom properties inherit, so every\nelement inside repaints with no prop threading and no branch in any\ncomponent. The context exists for the one place that cannot see the DOM: an\noverlay portaled to `<body>` from inside the island, which\n{@link useCuePortalProps } stamps from the same values.\n\nTwo things this is not. It is not a theme — `data-theme`, `data-mode` and\n`data-density` are untouched, and a light app keeps a light island. And it is\nnot needed for cue mode: the elements were rewritten onto cue's tokens by the\nvendoring codemod, so `skin=\"cue\"` is what they already do. Reach for this to\nshow an element the way assistant-ui drew it, or to hand a chat panel back to\nupstream's design language inside a console that is otherwise cue's.\n\nWhat an `aui` island re-points is this family's own vocabulary rather than the\nwhole token contract: `--cue-busy`, `--cue-info`, `--cue-selection`,\n`--cue-focus`, `--cue-scrim` and every derived `*-soft` / `*-border` stay on\nthe console's theme. Nothing in the elements group reads them, so the island\nis complete for what it is for — but a *cue* component placed inside one (a\n`Chip tone=\"busy\"`, a `Toast`) paints half in each palette, and the\nderivations cannot be made to follow at all: they are `color-mix()` values\nresolved on the theme block and inherited as answers. `elements.css` carries\nthe full accounting beside the values themselves.\n\n`elements.css` is a consumer import: `@import \"@cueplusplus/ui/elements.css\";`\nafter the main stylesheet. Without it a `skin=\"aui\"` island simply stays in\ncue's palette.",
+  "props": [
+    {
+      "name": "skin",
+      "type": "\"cue\" | \"aui\"",
+      "required": false,
+      "defaultValue": "cue",
+      "description": "Which value-set paints the subtree: `cue` (the default) or `aui`, which\ninstalls assistant-ui's own inks, grounds and hues.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "cue",
+          "aui"
+        ]
+      }
+    },
+    {
+      "name": "fidelity",
+      "type": "\"upstream\" | \"cue-metrics\"",
+      "required": false,
+      "defaultValue": "cue-metrics",
+      "description": "How much a supersede island re-points: `cue-metrics` (the default, colour\nonly) or `upstream`, which also pins assistant-ui's radii, literal type\nsizes and spacing so the density ladder stops at the island edge.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "upstream",
+          "cue-metrics"
+        ]
+      }
+    },
+    {
+      "name": "render",
+      "type": "RenderProp<Record<string, unknown>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace the rendered element (Base UI render prop). Accepts an element —\n`render={<section />}` — or a function returning one.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The subtree that paints with this island's values.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "The supersede island: one subtree, painted by a different set of values.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<AgentSurface skin=\"aui\" fidelity=\"upstream\">\n  <ToolCall label=\"Searched\" activeLabel=\"Searching\" query=\"composer\" … />\n</AgentSurface>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/agent-surface",
+  "mdUrl": "/docs/components/agent-surface.md",
+  "jsonUrl": "/r/components/agent-surface.json",
+  "specimens": [
+    {
+      "title": "AgentSurface",
+      "group": "elements",
+      "components": [
+        "AgentSurface"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"skin=cue (the default)\" wide>\n    <AgentSurface className=\"flex w-full flex-col gap-(--cue-space-3) rounded-(--radius-surface) border border-border bg-bg p-(--cue-space-4)\">\n      <IslandCalls scope=\"cue\" open={open} onOpenChange={opener} />\n    </AgentSurface>\n  </Specimen>\n  <Specimen label=\"aui · cue-metrics\" wide>\n    <AgentSurface\n      skin=\"aui\"\n      fidelity=\"cue-metrics\"\n      className=\"flex w-full flex-col gap-(--cue-space-3) rounded-(--radius-surface) border border-border bg-bg p-(--cue-space-4)\"\n    >\n      <IslandCalls scope=\"aui-metrics\" open={open} onOpenChange={opener} />\n    </AgentSurface>\n  </Specimen>\n  <Specimen label=\"aui · upstream\" wide>\n    <AgentSurface\n      skin=\"aui\"\n      fidelity=\"upstream\"\n      className=\"flex w-full flex-col gap-(--cue-space-3) rounded-(--radius-surface) border border-border bg-bg p-(--cue-space-4)\"\n    >\n      <IslandCalls scope=\"aui-upstream\" open={open} onOpenChange={opener} />\n    </AgentSurface>\n  </Specimen>\n</Specimens>",
+      "note": "One DOM, three paint jobs. The same three tool calls sit in all three specimens; the only difference is the pair of attributes on the box around them. skin='aui' re-points the colour set to assistant-ui's own inks and grounds, and fidelity='upstream' re-points the metrics too, which is what stops cue's density ladder at the island edge. Without @cueplusplus/ui/elements.css imported, all three would look alike.",
+      "interaction": "none of its own. The island is a values-set, not a control: everything inside keeps the behaviour it has outside."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/alert-dialog.json

@@ -0,0 +1,215 @@
+{
+  "name": "AlertDialog",
+  "slug": "alert-dialog",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A modal that asks one question with two answers, for anything irreversible.\n\nWraps Base UI's `AlertDialog`: the popup takes `role=\"alertdialog\"`, focus is\ntrapped and restored, and — unlike {@link Dialog } — an outside press does not\ndismiss it. Everything else (scrim, surface, portal theme stamping) is shared\nwith the rest of the overlay family.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Trigger",
+    "Content",
+    "Title",
+    "Description",
+    "Footer",
+    "Cancel",
+    "Action"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "AlertDialog.Root",
+      "description": "Groups the parts of an alert dialog and owns its open state. Renders no\nelement.",
+      "props": [],
+      "typeReferences": [
+        "BaseAlertDialog.Root.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "AlertDialog.Trigger",
+      "description": "The control that raises the alert. Unstyled — pass\n`render={<Button variant=\"danger-outline\" />}`.",
+      "props": [],
+      "typeReferences": [
+        "BaseAlertDialog.Trigger.Props"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "AlertDialog.Content",
+      "description": "The alert's portal, scrim and popup.\n\nThere is no corner close affordance, and Base UI does not dismiss an alert on\nan outside press: the whole point of the component is that the user answers\nthe question. Provide exactly one {@link AlertDialogCancel} and one\n{@link AlertDialogAction}.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the popup surface.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "width",
+          "type": "\"sm\" | \"md\" | \"lg\"",
+          "required": false,
+          "defaultValue": "sm",
+          "description": "",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "sm",
+              "md",
+              "lg"
+            ]
+          }
+        },
+        {
+          "name": "keepMounted",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Keep the popup mounted while closed.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "backdropClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the scrim behind it.",
+          "control": {
+            "kind": "string"
+          }
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseAlertDialog.Popup.Props, \"className\">",
+        "VariantProps<typeof alertDialogPopupVariants>"
+      ]
+    },
+    {
+      "name": "Title",
+      "usage": "AlertDialog.Title",
+      "description": "The question being asked. Wired to the popup's `aria-labelledby`.",
+      "props": [],
+      "typeReferences": [
+        "BaseAlertDialog.Title.Props"
+      ]
+    },
+    {
+      "name": "Description",
+      "usage": "AlertDialog.Description",
+      "description": "What the consequences are. Wired to the popup's `aria-describedby`.",
+      "props": [],
+      "typeReferences": [
+        "BaseAlertDialog.Description.Props"
+      ]
+    },
+    {
+      "name": "Footer",
+      "usage": "AlertDialog.Footer",
+      "description": "The two-answer action strip.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Cancel",
+      "usage": "AlertDialog.Cancel",
+      "description": "The safe answer. Styled as a secondary button, because backing out must never\nbe the loudest thing on the surface.",
+      "props": [],
+      "typeReferences": [
+        "BaseAlertDialog.Close.Props"
+      ]
+    },
+    {
+      "name": "Action",
+      "usage": "AlertDialog.Action",
+      "description": "The answer that does the thing. Closes the alert on press, so hang the work\noff `onClick`.",
+      "props": [
+        {
+          "name": "tone",
+          "type": "\"danger\" | \"accent\"",
+          "required": false,
+          "defaultValue": "accent",
+          "description": "Which answer this is. `\"danger\"` for anything destructive, `\"accent\"` for a\nconfirmation that merely proceeds. Defaults to `\"accent\"`.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "danger",
+              "accent"
+            ]
+          }
+        }
+      ],
+      "typeReferences": [
+        "BaseAlertDialog.Close.Props"
+      ]
+    }
+  ],
+  "variants": {
+    "width": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "defaultVariants": {
+    "width": "sm"
+  },
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-leading-ui",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-6",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A modal that asks one question with two answers, for anything irreversible.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<AlertDialog.Root>\n  <AlertDialog.Trigger render={<Button variant=\"danger-outline\">Delete</Button>} />\n  <AlertDialog.Content>\n    <AlertDialog.Title>Delete universe 3?</AlertDialog.Title>\n    <AlertDialog.Description>Every patched fixture goes with it.</AlertDialog.Description>\n    <AlertDialog.Footer>\n      <AlertDialog.Cancel>Keep</AlertDialog.Cancel>\n      <AlertDialog.Action tone=\"danger\" onClick={remove}>Delete</AlertDialog.Action>\n    </AlertDialog.Footer>\n  </AlertDialog.Content>\n</AlertDialog.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/alert-dialog",
+  "mdUrl": "/docs/components/alert-dialog.md",
+  "jsonUrl": "/r/components/alert-dialog.json",
+  "specimens": [
+    {
+      "title": "AlertDialog",
+      "group": "overlays",
+      "components": [
+        "AlertDialog"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"danger\">\n    <AlertDialog.Root>\n      <AlertDialog.Trigger render={<Button variant=\"danger\">{COPY.destructive.action}</Button>} />\n      <AlertDialog.Content>\n        <AlertDialog.Title>{COPY.destructive.title}</AlertDialog.Title>\n        <AlertDialog.Description>{COPY.destructive.hint}</AlertDialog.Description>\n        <AlertDialog.Footer>\n          <AlertDialog.Cancel render={<Button>Keep it</Button>} />\n          <AlertDialog.Action tone=\"danger\">{COPY.destructive.action}</AlertDialog.Action>\n        </AlertDialog.Footer>\n      </AlertDialog.Content>\n    </AlertDialog.Root>\n  </Specimen>\n  <Specimen label=\"accent\">\n    <AlertDialog.Root>\n      <AlertDialog.Trigger render={<Button>Reload show</Button>} />\n      <AlertDialog.Content width=\"sm\">\n        <AlertDialog.Title>Reload the show file</AlertDialog.Title>\n        <AlertDialog.Description>\n          Unsaved edits to 3 cues are discarded.\n        </AlertDialog.Description>\n        <AlertDialog.Footer>\n          <AlertDialog.Cancel render={<Button>Cancel</Button>} />\n          <AlertDialog.Action>Reload</AlertDialog.Action>\n        </AlertDialog.Footer>\n      </AlertDialog.Content>\n    </AlertDialog.Root>\n  </Specimen>\n</Specimens>",
+      "note": "The destructive twin: no scrim dismissal, no close button, and an explicit pair of Cancel and Action.",
+      "interaction": "Escape is deliberately not enough on its own; the action has to be chosen."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/animated-number.json

@@ -0,0 +1,75 @@
+{
+  "name": "AnimatedNumber",
+  "slug": "animated-number",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A number that counts to its new value instead of jumping to it.\n\nThe smallest element in the canon and the one that touches the most rows: a\ntoken count, a cost, a duration, a file tally. Two rules, both from the same\nteardown. Tween, because a value that steps reads as a new fact while a value\nthat counts reads as the same fact moving — and a transcript's numbers are\nalmost always the second thing. And `tabular-nums`, because a proportional\n`1` is narrower than a `0`, so a stepping counter nudges everything to its\nright on every update.\n\nIt holds the only state in the canon, and it is a tween rather than a fact:\n`value` is still a prop, every tween ends exactly on it, and a replay that\nsets the prop paints the same number at every frame it rests on.\n\n**Reduced motion is answered by arriving, not by stopping.** A reader who has\nasked for stillness gets the value immediately and no frames are ever\nscheduled — the number is information, and the animation was only ever how it\ngot there.\n\nWhile a tween is in flight the digits on screen are `aria-hidden` and the\nsettled value is carried beside them for a screen reader, so an assistive\ntechnology reads the number the run actually reported rather than whichever\nframe it happened to land on. Once the tween ends there is one node again and\nnothing is duplicated.",
+  "props": [
+    {
+      "name": "value",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "The number to show. Every change eases from whatever is on screen to this,\nincluding a change that arrives mid-tween — which is the case a live\ncounter is actually made of.\n\nA non-finite value paints `0` rather than the word `NaN`: these arrive from\na caller's arithmetic over a stream that may not have started.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "duration",
+      "type": "number",
+      "required": false,
+      "defaultValue": "400",
+      "description": "How long one tween lasts, in milliseconds. Defaults to `400` — long enough\nto read as counting, short enough that a counter updated every second is\nnever behind the run it is describing. `0` steps.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "format",
+      "type": "((value: number) => string)",
+      "required": false,
+      "defaultValue": "(value: number): string => value.toLocaleString(\"en-US\")",
+      "description": "How to write the number. Defaults to grouped digits in `en-US`\n(`1,240`), which is deterministic across a server render and a client one;\n{@link formatCompactNumber} is the other one this family uses (`1.2k`).\n\nCalled on every frame, so keep it cheap.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"span\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "A number that counts to its new value instead of jumping to it.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { AnimatedNumber } from \"@cueplusplus/ui/elements\";\n\n<AnimatedNumber value={tokens} />\n// The reference's own readout: compact, inline, in the status line.\n<span className=\"text-fg-muted\">\n  · <AnimatedNumber value={tokens} format={formatCompactNumber} /> tokens\n</span>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/animated-number",
+  "mdUrl": "/docs/components/animated-number.md",
+  "jsonUrl": "/r/components/animated-number.json",
+  "specimens": [
+    {
+      "title": "AnimatedNumber",
+      "group": "elements",
+      "components": [
+        "AnimatedNumber"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"compact, in a status line\" wide>\n    <span className=\"flex items-center gap-(--cue-space-3)\">\n      <span className=\"text-fg-muted text-(length:--cue-text-ui)\">\n        Thinking · <AnimatedNumber value={tokens} format={formatCompactNumber} /> tokens\n      </span>\n      <Button size=\"sm\" onClick={() => setTokens((was) => was + 3400)}>\n        Read more\n      </Button>\n    </span>\n  </Specimen>\n  <Specimen label=\"grouped, as a stat\">\n    <span className=\"text-(length:--cue-text-emphasis) font-medium\">\n      <AnimatedNumber value={tokens} />\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "A number that counts to its new value instead of jumping to it, in tabular numerals so the digits do not jitter on the way. Both halves are one teardown's: the reference eases its live token estimate from the previous value to the new one and paints it in font-variant-numeric tabular-nums, because a proportional 1 is narrower than a 0 and a stepping counter nudges everything to its right on every update. A value that steps reads as a new fact; a value that counts reads as the same fact moving, which is what a token, a cost and a duration actually are.",
+      "interaction": "press the button and watch the digits rather than the box — nothing to the right of the number moves. Under prefers-reduced-motion the new value simply arrives: stillness for a counter has to mean landing on the number, because a readout that stopped where it was would be wrong rather than still. Mid-tween the digits are aria-hidden and the settled value is carried beside them, so a screen reader reads what the run reported and never a frame of the animation."
+    }
+  ],
+  "todo": true
+}