@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/navigation-menu.json

@@ -0,0 +1,226 @@
+{
+  "name": "NavigationMenu",
+  "slug": "navigation-menu",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The marketing-shaped navigation header: a strip of words, each opening a panel\nof destinations.\n\nWraps Base UI's `NavigationMenu`, which is the right primitive because a\nnavigation menu is *not* a menu: its rows are links, not commands, so it must\nnot take `role=\"menu\"` (which tells a screen reader to expect commands and\nswallows the browser's own link affordances). Hover intent, the shared\nresizing popup, focus handling and the landmark are all the primitive's.\n\nReach for {@link Menubar } when the entries run commands, `Tabs` when they\nswitch a panel in place, and `Sidebar` when the console has more than about\nsix destinations.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "List",
+    "Item",
+    "Trigger",
+    "Content",
+    "Link",
+    "Viewport"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "NavigationMenu.Root",
+      "description": "The navigation landmark. Renders a `<nav>` at the top level.\n\nGive it an `aria-label`: a page with more than one navigation landmark and no\nnames on them is a page a screen-reader user cannot navigate by landmark,\nwhich is the only reason the landmark exists.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the `<nav>`."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseNavigationMenu.Root.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "List",
+      "usage": "NavigationMenu.List",
+      "description": "The horizontal strip of top-level items. Renders a `<ul>`.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the strip of items."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseNavigationMenu.List.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Item",
+      "usage": "NavigationMenu.Item",
+      "description": "One top-level entry: a trigger with a panel, or a bare\n{@link NavigationMenuLink}. Renders an `<li>`.",
+      "props": [],
+      "typeReferences": [
+        "BaseNavigationMenu.Item.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "NavigationMenu.Trigger",
+      "description": "A top-level word that opens a panel.\n\nOpen is `accent-soft` plus full-strength ink — the same tint the active tab\nand the highlighted menu row use, never a solid accent block. The caret is a\nchild of the trigger rather than a sibling so it inherits the ink and rotates\nwith the open state for free.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the trigger."
+        },
+        {
+          "name": "caret",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Draw the caret that says a panel opens below. Defaults to `true`."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseNavigationMenu.Trigger.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "NavigationMenu.Content",
+      "description": "One item's panel. Only the open item's content is mounted into the shared\n{@link NavigationMenuViewport}, which is what lets the popup resize smoothly\nbetween items instead of one panel per popup.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the panel body."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseNavigationMenu.Content.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Link",
+      "usage": "NavigationMenu.Link",
+      "description": "One destination inside a panel.\n\nNever underlined at rest — the same rule as `Link` — because a panel of eight\nunderlined rows is a wall of rules. Hover moves the ink and the ground, which\nis louder and quieter at the same time.\n\nPass `render={<NextLink href=\"…\" />}` for client-side routing.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the link row."
+        },
+        {
+          "name": "active",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Mark this link as the current destination."
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "Supporting line under the label."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseNavigationMenu.Link.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Viewport",
+      "usage": "NavigationMenu.Viewport",
+      "description": "The single floating panel every item shares: portal, positioner, popup and\nviewport in one part.\n\nPut exactly one of these inside a {@link NavigationMenuRoot}, after the list.\nIt is one popup rather than one-per-item on purpose — that is what makes\nmoving between two open items a resize instead of a close-and-reopen — and it\nis portalled through {@link useCuePortalProps} so it carries the caller's\ntheme, density and mode.\n\nThe popup animates its own `width`/`height` from the `--popup-width` /\n`--popup-height` custom properties Base UI publishes as the active panel\nchanges.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the popup surface."
+        },
+        {
+          "name": "align",
+          "type": "\"center\" | \"end\" | \"start\"",
+          "required": false,
+          "defaultValue": "start",
+          "description": "Alignment along the bottom of the active trigger. Defaults to `\"start\"`."
+        },
+        {
+          "name": "positionerClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the positioner that places the popup."
+        },
+        {
+          "name": "sideOffset",
+          "type": "number | OffsetFunction",
+          "required": false,
+          "defaultValue": "4",
+          "description": "Gap in px between the strip and the popup. Defaults to `4`."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseNavigationMenu.Popup.Props, \"className\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The marketing-shaped navigation header: a strip of words, each opening a panel of destinations.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<NavigationMenu.Root aria-label=\"Console\">\n  <NavigationMenu.List>\n    <NavigationMenu.Item>\n      <NavigationMenu.Trigger>Patch</NavigationMenu.Trigger>\n      <NavigationMenu.Content>\n        <NavigationMenu.Link href=\"/patch/fixtures\" description=\"Everything addressed\">\n          Fixtures\n        </NavigationMenu.Link>\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n  </NavigationMenu.List>\n  <NavigationMenu.Viewport />\n</NavigationMenu.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/navigation-menu",
+  "mdUrl": "/docs/components/navigation-menu.md",
+  "jsonUrl": "/r/components/navigation-menu.json",
+  "specimens": [
+    {
+      "title": "NavigationMenu",
+      "group": "chrome",
+      "components": [
+        "NavigationMenu"
+      ],
+      "code": "<NavigationMenu.Root>\n  <NavigationMenu.List>\n    <NavigationMenu.Item>\n      <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>\n      <NavigationMenu.Content className=\"w-[20rem]\">\n        <NavigationMenu.Link href=\"#dmxhub\" description=\"Art-Net and sACN bridge.\">\n          dmxhub\n        </NavigationMenu.Link>\n        <NavigationMenu.Link href=\"#venu\" description=\"Show control.\" active>\n          VENU.studio\n        </NavigationMenu.Link>\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n    <NavigationMenu.Item>\n      <NavigationMenu.Trigger caret={false}>Docs</NavigationMenu.Trigger>\n      <NavigationMenu.Content className=\"w-[16rem]\">\n        <NavigationMenu.Link href=\"#tokens\">Tokens</NavigationMenu.Link>\n        <NavigationMenu.Link href=\"#components\">Components</NavigationMenu.Link>\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n  </NavigationMenu.List>\n  <NavigationMenu.Viewport />\n</NavigationMenu.Root>",
+      "note": "A menu bar whose panels are portalled through the stamping contract, so they keep the theme and density of the island they were opened from.",
+      "interaction": "hover opens after a short delay; Escape closes and returns focus to the trigger."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/node-card.json

@@ -0,0 +1,109 @@
+{
+  "name": "NodeCard",
+  "slug": "node-card",
+  "group": "flow",
+  "importPath": "@cueplusplus/ui/flow",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A node on a graph canvas, drawn in this system's language.\n\nFramed with an **outline, never a border**. React Flow is told a node's height\nup front — every layout that stacks nodes computes it — and a 1px border on\neach side makes the rendered box 2px taller than the number the layout used,\nwhich is how node stacks end up overlapping by a hairline that grows with the\nnode count. An outline is painted outside the box model entirely and costs\nnothing, so the formula and the DOM agree. `-outline-offset-1` then pulls it\nback inside the corner radius.\n\nThe frame's colour is the node's state (see `_frame.ts`): selected beats live\nbeats identity. When neither `tone` nor `state` is given the card paints no\ncolour of its own and inherits `--cue-node-frame` from the node wrapper, which\nis how `useFlowTheme().nodeStyles` colours a whole class of nodes at once.\n\nThe header band is the drag handle — pass\n`dragHandle: '[data-slot=\"node-card-header\"]'` on the node so a pointer inside\nthe body edits instead of dragging.\n\nNothing here imports `@xyflow/react`: a node card is a div, and the same card\ndraws a static diagram on a marketing page with no graph engine shipped. It\nalso never clips — handles straddle the rim, so an `overflow-hidden` in\n`className` would slice every connection point in half.",
+  "props": [
+    {
+      "name": "tone",
+      "type": "\"input\" | \"output\" | \"processing\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Where the node sits in the signal path. Inks the frame at rest."
+    },
+    {
+      "name": "state",
+      "type": "\"disabled\" | \"idle\" | \"selected\" | \"live\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the node is doing right now. Outranks `tone`.\n\nPass React Flow's own `selected` through:\n`state={selected ? \"selected\" : \"idle\"}`."
+    },
+    {
+      "name": "header",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The summary band: a label, a toggle, a badge. Also the drag handle."
+    },
+    {
+      "name": "expanded",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Whether the body is shown. Defaults to `true`; `false` renders the band alone."
+    },
+    {
+      "name": "onExpandedChange",
+      "type": "((expanded: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the requested state when the caret is clicked. Supplying it is\nwhat makes the caret appear — a card nobody can collapse should not offer to."
+    },
+    {
+      "name": "toggleLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the caret. Defaults to `\"Collapse\"` / `\"Expand\"`."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The body: rows, bars, fields. Full-bleed — rows own their own padding."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-info",
+    "--cue-node-frame",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-1",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "A node on a graph canvas, drawn in this system's language.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "function MergeNode({ selected }: NodeProps) {\n  const [open, setOpen] = React.useState(true);\n  return (\n    <NodeCard\n      tone=\"processing\"\n      state={selected ? \"selected\" : \"live\"}\n      header={<span className=\"truncate\">merge · universe 3</span>}\n      expanded={open}\n      onExpandedChange={setOpen}\n    >\n      <DmxBar data={frame} />\n    </NodeCard>\n  );\n}",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/node-card",
+  "mdUrl": "/docs/components/node-card.md",
+  "jsonUrl": "/r/components/node-card.json",
+  "specimens": [
+    {
+      "title": "NodeCard",
+      "group": "flow",
+      "components": [
+        "NodeCard"
+      ],
+      "code": "<Specimens>\n  {([\"input\", \"processing\", \"output\"] as const).map((tone) => (\n    <Specimen key={tone} label={tone}>\n      <NodeCard tone={tone} header={tone} className=\"w-[10rem]\">\n        <span className=\"font-mono text-(length:--cue-text-micro) text-fg-subtle\">\n          512 slots\n        </span>\n      </NodeCard>\n    </Specimen>\n  ))}\n  {([\"idle\", \"live\", \"selected\", \"disabled\"] as const).map((state) => (\n    <Specimen key={state} label={state}>\n      <NodeCard state={state} header={state} className=\"w-[10rem]\">\n        <StatusDot tone={state === \"live\" ? \"ok\" : \"idle\"} label={state} />\n      </NodeCard>\n    </Specimen>\n  ))}\n  <Specimen label=\"collapsed\">\n    <NodeCard header=\"Collapsible\" expanded={false} className=\"w-[10rem]\">\n      <span>Hidden body</span>\n    </NodeCard>\n  </Specimen>\n</Specimens>",
+      "note": "Framed with an outline rather than a border, so a node's rendered height is exactly the height the layout was told. The frame colour is the state: selected is `fg`, input is `info`, output and live are accent, idle is `fg-subtle`.",
+      "interaction": "the expand toggle is a real button; the frame colour changes with `state`, never with hover alone."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/node-handle.json

@@ -0,0 +1,69 @@
+{
+  "name": "NodeHandle",
+  "slug": "node-handle",
+  "group": "flow",
+  "importPath": "@cueplusplus/ui/flow",
+  "peerDependencies": [
+    "@xyflow/react"
+  ],
+  "clientOnly": true,
+  "description": "A connection point on a node, drawn as a pin rather than a dot.\n\nEverything visual is **inline style, not a class**, and that is deliberate:\n`.react-flow__handle` sets `background-color`, `border` and `width`/`height`\nfrom the library's own unlayered stylesheet, while Tailwind's utilities live in\na cascade layer — and any layered rule loses to an unlayered one of the same\nspecificity, whatever order the files load in. An inline declaration is the\nonly paint that reliably wins, which is also how the port did it.\n\nThe pin is ringed in `--cue-bg` rather than in the card's own surface, so it\nreads as lifted off the edge it straddles no matter which surface rung the\nnode is on.",
+  "props": [
+    {
+      "name": "tone",
+      "type": "\"danger\" | \"accent\" | \"busy\" | \"muted\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "accent",
+      "description": "What the connection carries. Defaults to `\"accent\"`."
+    },
+    {
+      "name": "size",
+      "type": "number",
+      "required": false,
+      "defaultValue": "9",
+      "description": "Diameter in px at the 16px root, emitted as `rem`. Defaults to `9`."
+    }
+  ],
+  "typeReferences": [
+    "HandleProps"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-bg",
+    "--cue-border-strong",
+    "--cue-busy",
+    "--cue-danger",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-warn"
+  ],
+  "summary": "A connection point on a node, drawn as a pin rather than a dot.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<NodeHandle type=\"source\" position={Position.Right} id=\"u1\" />\n<NodeHandle type=\"target\" position={Position.Left} id=\"in\" tone=\"muted\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/node-handle",
+  "mdUrl": "/docs/components/node-handle.md",
+  "jsonUrl": "/r/components/node-handle.json",
+  "specimens": [
+    {
+      "title": "NodeHandle",
+      "group": "flow",
+      "components": [
+        "NodeHandle"
+      ],
+      "code": "<div className=\"h-[9rem] w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n  <ReactFlow\n    nodes={TONE_NODES}\n    edges={[]}\n    nodeTypes={NODE_TYPES}\n    colorMode={theme.colorMode}\n    style={theme.style}\n    nodesDraggable={false}\n    panOnDrag={false}\n    zoomOnScroll={false}\n    proOptions={{ hideAttribution: true }}\n  />\n</div>",
+      "note": "A 9px connection pin in the system's tones, painted with inline `var(--cue-*)` references. That is deliberate: the library's own stylesheet is unlayered while Tailwind's utilities are layered, and a layered rule loses to an unlayered one of equal specificity whatever the import order. Shown on a node, because a handle only exists inside a canvas.",
+      "interaction": "the hit area is larger than the dot; the pin resolves its colour from the live custom properties, so a theme switch repaints it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/number-field.json

@@ -0,0 +1,107 @@
+{
+  "name": "NumberField",
+  "slug": "number-field",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A numeric control with explicit − / + affordances and no native spinners.\n\nNative `<input type=\"number\">` spinners are unusable at console density — a\npair of 4px arrows that only appear on hover — so this is a text input with\n`inputMode=\"numeric\"` flanked by real buttons, which is also what makes it\ntouch-usable. Arrow keys step, Shift steps by `largeStep`, Alt by `smallStep`,\nand values typed out of range are clamped to `min`/`max` on blur.\n\nThe group owns the rim; the input and both buttons render bare inside it, so\nthe whole cluster reads as one field and focus feedback moves to\n`focus-within`.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the group chassis."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the text control, when no {@link FieldLabel } names it."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Placeholder shown while the field is empty."
+    },
+    {
+      "name": "decrementLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Decrease",
+      "description": "Accessible name for the decrement button. Defaults to `\"Decrease\"`."
+    },
+    {
+      "name": "incrementLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Increase",
+      "description": "Accessible name for the increment button. Defaults to `\"Increase\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseNumberField.Root.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A numeric control with explicit − / + affordances and no native spinners.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<NumberField aria-label=\"Fade time\" defaultValue={3} min={0} max={600} step={0.5} />\n<Field><FieldLabel>Universe</FieldLabel><NumberField min={1} max={512} /></Field>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/number-field",
+  "mdUrl": "/docs/components/number-field.md",
+  "jsonUrl": "/r/components/number-field.json",
+  "specimens": [
+    {
+      "title": "NumberField",
+      "group": "forms",
+      "components": [
+        "NumberField"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <NumberField aria-label=\"Fade time\" defaultValue={3} min={0} max={600} step={0.5} />\n  </Specimen>\n  <Specimen label=\"sm\">\n    <NumberField aria-label=\"Fade time, small\" defaultValue={3} size=\"sm\" />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <NumberField aria-label=\"Fade time, disabled\" defaultValue={3} disabled />\n  </Specimen>\n</Specimens>",
+      "note": "Stepper buttons on the chassis, with tabular figures so a changing digit does not shift the column.",
+      "interaction": "arrow keys step, shift-arrow steps by ten, the scroll wheel is deliberately inert."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/number-ticker.json

@@ -0,0 +1,61 @@
+{
+  "name": "NumberTicker",
+  "slug": "number-ticker",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Digits that roll into place as a count updates in real time.",
+  "props": [
+    {
+      "name": "value",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Numeric value whose digits roll into place as it changes."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Mono caption rendered under the rolling number."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"value\" | \"label\"> & {\n  /** Numeric value whose digits roll into place as it changes. */\n  value: number;\n  /** Mono caption rendered under the rolling number. */\n  label: string;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-subtle",
+    "--cue-text-title"
+  ],
+  "summary": "Digits that roll into place as a count updates in real time.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { NumberTicker } from \"@cueplusplus/ui/elements\";\n\n<NumberTicker value={1284} label=\"tokens / sec\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/number-ticker",
+  "mdUrl": "/docs/components/number-ticker.md",
+  "jsonUrl": "/r/components/number-ticker.json",
+  "specimens": [
+    {
+      "title": "NumberTicker",
+      "group": "elements-knowledge",
+      "components": [
+        "NumberTicker"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"channels patched\">\n    <NumberTicker value={48} label=\"channels patched\" />\n  </Specimen>\n  <Specimen label=\"a larger figure\">\n    <NumberTicker value={22300} label=\"lumens\" />\n  </Specimen>\n</Specimens>",
+      "note": "A count that rolls rather than jumps: each digit is a column of ten sliding into place, so 47 to 48 moves one wheel and leaves the other alone. The whole figure is announced once as text, which is what keeps ten rolling columns from being read out as ten numbers.",
+      "interaction": "none. The columns translate on a long ease and stop moving entirely under reduced motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/onboarding.json

@@ -0,0 +1,84 @@
+{
+  "name": "Onboarding",
+  "slug": "onboarding",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "First run: three moves that teach what this assistant is actually for.",
+  "props": [
+    {
+      "name": "steps",
+      "type": "readonly OnboardingStep[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "What to teach, in order. Three is usually the limit before it is skipped."
+    },
+    {
+      "name": "index",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which step is showing. The final step's action reads Start instead of Next."
+    },
+    {
+      "name": "onNext",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to advance."
+    },
+    {
+      "name": "onSkip",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to dismiss. Always offer it."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"steps\" | \"index\" | \"onNext\" | \"onSkip\"\n> & {\n  /** What to teach, in order. Three is usually the limit before it is skipped. */\n  steps: readonly OnboardingStep[];\n  /** Which step is showing. The final step's action reads Start instead of Next. */\n  index: number;\n  /** Called to advance. */\n  onNext?: () => void;\n  /** Called to dismiss. Always offer it. */\n  onSkip?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-ui"
+  ],
+  "summary": "First run: three moves that teach what this assistant is actually for.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { Onboarding } from \"@cueplusplus/ui/elements\";\n\n<Onboarding steps={steps} index={index} onNext={next} onSkip={skip} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/onboarding",
+  "mdUrl": "/docs/components/onboarding.md",
+  "jsonUrl": "/r/components/onboarding.json",
+  "specimens": [
+    {
+      "title": "Onboarding",
+      "group": "elements-composer",
+      "components": [
+        "Onboarding"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"walking it\" wide>\n    <Onboarding\n      steps={ONBOARDING}\n      index={step}\n      onNext={() => setStep((current) => Math.min(current + 1, ONBOARDING.length - 1))}\n      onSkip={() => setStep(0)}\n    />\n  </Specimen>\n  <Specimen label=\"last step\" wide>\n    <Onboarding steps={ONBOARDING} index={ONBOARDING.length - 1} />\n  </Specimen>\n</Specimens>",
+      "note": "First run: three moves that teach what this assistant is actually for, each with a prompt you could send verbatim. Showing beats describing, which is why every step carries an example rather than a screenshot. The dots are the progress and the final step's action reads `Start` instead of `Next`, so the end of the tour is visible from the second step.",
+      "interaction": "skip is always offered and always in the same place — a tour with no way out is a modal wearing a card."
+    }
+  ],
+  "todo": true
+}