@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/avatar.json

@@ -0,0 +1,95 @@
+{
+  "name": "Avatar",
+  "slug": "avatar",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A round user/entity avatar sized off the density control ladder, so it lines\nup with the buttons and inputs on the same row.\n\nWraps Base UI's `Avatar`, which owns the image-loading state machine: the\nfallback shows immediately, is replaced when the image decodes, and comes\nback if the image errors.",
+  "props": [
+    {
+      "name": "src",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Image URL. Omit to go straight to the fallback."
+    },
+    {
+      "name": "alt",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Alt text for the image, and the name the default initials are derived from."
+    },
+    {
+      "name": "fallback",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "What to show while the image loads or after it fails. Defaults to initials from `alt`."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": ""
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"span\">, \"children\">",
+    "VariantProps<typeof avatarVariants>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "defaultVariants": {
+    "size": "md"
+  },
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "A round user/entity avatar sized off the density control ladder, so it lines up with the buttons and inputs on the same row.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Avatar alt=\"Ada Lovelace\" src=\"/ada.png\" />\n<Avatar alt=\"Ada Lovelace\" size=\"sm\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/avatar",
+  "mdUrl": "/docs/components/avatar.md",
+  "jsonUrl": "/r/components/avatar.json",
+  "specimens": [
+    {
+      "title": "Avatar",
+      "group": "primitives",
+      "components": [
+        "Avatar"
+      ],
+      "code": "<Specimens>\n  {SIZES.map((size) => (\n    <Specimen key={size} label={size}>\n      <Avatar size={size} fallback=\"CR\" />\n    </Specimen>\n  ))}\n  <Specimen label=\"image\">\n    <Avatar\n      src=\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' fill='%23888'/%3E%3C/svg%3E\"\n      alt=\"Operator portrait\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Initials fall back when there is no image; the ring is drawn in the background colour so a pile reads as separate faces.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/background-inbox.json

@@ -0,0 +1,71 @@
+{
+  "name": "BackgroundInbox",
+  "slug": "background-inbox",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Work still going somewhere else, and the results waiting to be collected.",
+  "props": [
+    {
+      "name": "runs",
+      "type": "readonly BackgroundRun[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Detached runs. The header counts what is ready rather than what is in flight,\nbecause ready is the thing that needs you."
+    },
+    {
+      "name": "onCollect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to pull a finished run back into the thread. Running rows are not clickable."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"runs\" | \"onCollect\"> & {\n  /**\n   * Detached runs. The header counts what is ready rather than what is in flight,\n   * because ready is the thing that needs you.\n   */\n  runs: readonly BackgroundRun[];\n  /** Called to pull a finished run back into the thread. Running rows are not clickable. */\n  onCollect?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-text-body"
+  ],
+  "summary": "Work still going somewhere else, and the results waiting to be collected.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { BackgroundInbox } from \"@cueplusplus/ui/elements\";\n\n<BackgroundInbox runs={runs} onCollect={collect} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/background-inbox",
+  "mdUrl": "/docs/components/background-inbox.md",
+  "jsonUrl": "/r/components/background-inbox.json",
+  "specimens": [
+    {
+      "title": "BackgroundInbox",
+      "group": "elements-agents",
+      "components": [
+        "BackgroundInbox"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"one ready\" wide>\n    <BackgroundInbox\n      runs={inbox}\n      onCollect={(id) => setCollected((current) => [...current, id])}\n    />\n  </Specimen>\n  <Specimen label=\"nothing back yet\" wide>\n    <BackgroundInbox\n      runs={INBOX.map((item) => ({ ...item, state: \"running\" as const, summary: undefined }))}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Work that left the conversation and is still going somewhere else. The header counts what is *ready* rather than what is in flight, because ready is the half that needs a person; a running row is not clickable at all, so there is nothing to press before there is something to collect.",
+      "interaction": "a ready or failed row is a button and takes cue's focus ring; a running one is `disabled`, which is what makes the spinner mean wait rather than try again."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/branch-picker.json

@@ -0,0 +1,124 @@
+{
+  "name": "BranchPicker",
+  "slug": "branch-picker",
+  "group": "agent-runtime",
+  "importPath": "@cueplusplus/ui/agent-runtime",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The `‹ 2 / 3 ›` stepper that walks a turn's regenerated siblings.\n\nIt keeps a segmented control's two promises — exactly one branch is on show,\nand the set cannot be emptied — without being one. A row of N numbered\nsegments is the wrong shape for a count that is usually 2 and occasionally 9,\nand a segmented control's recessed frame fights the message bubble it sits\nin. Two ghost icon buttons around a mono readout stay quiet until the reader\nhas a reason to look at them.\n\nA single branch is not a choice, so below two branches this renders nothing\nat all: the host can hand it every turn's `branch` without deciding which\nturns deserve a control. It belongs in an agent turn's `footer` — a user\nbubble is a solid accent fill, and a stepper drawn on it is unreadable.\n\nThe picker never moves the thread itself. It reports a direction and the host\nasks the runtime; under an ExternalStore runtime the switch arrives back at\nthe adapter's `setMessages`, which is the host's to write.",
+  "props": [
+    {
+      "name": "index",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "1-based position of the branch on show — what the readout prints."
+    },
+    {
+      "name": "count",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many sibling branches exist. Below 2 the picker renders nothing."
+    },
+    {
+      "name": "onNavigate",
+      "type": "(direction: BranchDirection) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the direction to move in. Never called past either end."
+    },
+    {
+      "name": "previousLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Previous branch",
+      "description": "Accessible name of the previous button. Defaults to `\"Previous branch\"`."
+    },
+    {
+      "name": "nextLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Next branch",
+      "description": "Accessible name of the next button. Defaults to `\"Next branch\"`."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Block both buttons — a run is in flight and the runtime cannot switch mid-run."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Branches",
+      "description": "Accessible name for the group. Defaults to `\"Branches\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onChange\" | \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-1",
+    "--cue-text-micro"
+  ],
+  "summary": "The `‹ 2 / 3 ›` stepper over a turn's regenerated siblings, and nothing at all below two.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Message agent=\"planner\" footer={<BranchPicker index={2} count={3} onNavigate={go} disabled={busy} />}>…</Message>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/branch-picker",
+  "mdUrl": "/docs/components/branch-picker.md",
+  "jsonUrl": "/r/components/branch-picker.json",
+  "whenToUse": [
+    "An agent turn's `footer`, once a regenerate has given the turn a sibling.",
+    "Any host that can move between branches: it reports a direction and lets you ask the runtime."
+  ],
+  "whenNotToUse": [
+    "A single branch. It renders nothing, on purpose, so a host can hand it every turn.",
+    "Picking between views or modes. That is `SegmentedControl`, which shows every option at once.",
+    "Paging through a list. That is `Pagination`; a branch set is one answer with alternatives, not a sequence.",
+    "Regenerating. The picker only moves between branches that exist; `useAgentThread().regenerate` makes a new one, and the host draws that control — a ghost `Button` in a turn's footer, as the demo does."
+  ],
+  "commonMistakes": [
+    "Putting it in a user bubble's footer. That bubble is a solid accent fill and a ghost stepper on it is unreadable.",
+    "Wiring `onNavigate` to a state setter without clamping, when the runtime is the one that knows the count.",
+    "Leaving it enabled during a run. Pass `disabled` while the thread is busy, because the runtime will not switch mid-run."
+  ],
+  "specimens": [
+    {
+      "title": "useAgentThread / ToolCallCard / BranchPicker",
+      "group": "agent-runtime",
+      "components": [
+        "useAgentThread",
+        "ToolCallCard",
+        "BranchPicker"
+      ],
+      "code": "<ScriptedThread />",
+      "note": "The hook reads an assistant-ui runtime and hands back the props the Chat group already takes: `busy`, `disabled`, `onSend` and `onStop` for the composer, `role`, `agent` and `pending` for each turn, `toolCalls` for the cards, `branch` and `switchBranch` for the stepper. No provider is mounted and no borrowed DOM is rendered, so every pixel here is this library's. The thread below plays a fixed script, because a docs page has no model behind it.",
+      "interaction": "the script streams once and stops on its own; Stop cancels it mid-sentence, Regenerate answers again under the same question, and the stepper that then appears walks the two answers."
+    },
+    {
+      "title": "BranchPicker",
+      "group": "agent-runtime",
+      "components": [
+        "BranchPicker"
+      ],
+      "code": "<div className=\"flex w-full max-w-[42rem] flex-col gap-(--cue-space-4)\">\n  <StatefulPicker />\n  <Message\n    agent=\"reviewer\"\n    author=\"Reviewer\"\n    footer={<BranchPicker index={1} count={2} onNavigate={() => {}} disabled />}\n  >\n    Blocked while a run is in flight: the runtime cannot switch branches mid-run.\n  </Message>\n</div>",
+      "note": "A stepper rather than a segmented row of numbers: a branch count is usually 2 and occasionally 9, and a segmented frame fights the bubble it sits in. It keeps the two promises that matter, which are that exactly one branch is on show and that the set cannot be emptied, and it renders nothing at all below two branches. It belongs in an agent turn's footer, never a user bubble's.",
+      "interaction": "each end button disables itself at its end of the run, and the position is read aloud as well as drawn."
+    }
+  ]
+}

package/manifest/components/breadcrumb.json

@@ -0,0 +1,74 @@
+{
+  "name": "Breadcrumb",
+  "slug": "breadcrumb",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "Where you are, and how to get back.\n\nThe last crumb is never a link: it is the page you are on, marked\n`aria-current=\"page\"` and set in full-strength ink so the trail has one\nvisible end. Separators are `aria-hidden` — a screen reader announcing\n\"console slash patch slash universe 1\" is reading punctuation, not structure.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "items",
+      "type": "readonly BreadcrumbItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The trail, root first. The last entry is the current page."
+    },
+    {
+      "name": "separator",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "/",
+      "description": "What sits between crumbs. Defaults to `\"/\"`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Breadcrumb",
+      "description": "The nav's accessible name. Defaults to `\"Breadcrumb\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"nav\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-text-label"
+  ],
+  "summary": "Where you are, and how to get back.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Breadcrumb items={[{ label: \"Console\", href: \"/\" }, { label: \"Patch\" }]} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/breadcrumb",
+  "mdUrl": "/docs/components/breadcrumb.md",
+  "jsonUrl": "/r/components/breadcrumb.json",
+  "specimens": [
+    {
+      "title": "Breadcrumb",
+      "group": "layout",
+      "components": [
+        "Breadcrumb"
+      ],
+      "code": "<Breadcrumb items={CRUMBS} />",
+      "note": "Where you are, with `aria-hidden` punctuation between the crumbs and the last one marked current.",
+      "interaction": "every crumb but the last is a link; the last is plain text."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/button-group.json

@@ -0,0 +1,74 @@
+{
+  "name": "ButtonGroup",
+  "slug": "button-group",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Several related actions drawn as one control.\n\nPurely presentational: it owns no state and imposes no roving focus, because\nits members are *actions*, each independently reachable by Tab. When the\nmembers represent a **choice** rather than actions, use {@link ToggleGroup }\n(several or none) or `SegmentedControl` (exactly one) — those carry the\npressed-state ARIA a group of plain buttons must not fake.\n\nThe children keep their own variants, so a `secondary`/`primary` pair reads as\n\"and here is the one you probably want\" without any extra API.",
+  "props": [
+    {
+      "name": "orientation",
+      "type": "\"horizontal\" | \"vertical\"",
+      "required": false,
+      "defaultValue": "horizontal",
+      "description": "Which way the children run. Defaults to `\"horizontal\"`."
+    },
+    {
+      "name": "attached",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Join the children into one control (shared rims, outer corners only).\nDefaults to `true`; pass `false` for a merely-adjacent row of buttons that\nshould still be announced as one group."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the cluster. A group of buttons with no name is a group\nof buttons; with one it is \"Blend mode\"."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The buttons — {@link Button }, {@link IconButton } or anything button-shaped."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-space-2"
+  ],
+  "summary": "Several related actions drawn as one control.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ButtonGroup aria-label=\"Blend mode\">\n  <Button>HTP</Button>\n  <Button variant=\"primary\">LTP</Button>\n</ButtonGroup>\n<ButtonGroup aria-label=\"Zoom\" orientation=\"vertical\">\n  <IconButton aria-label=\"Zoom in\" icon={Plus} variant=\"outline\" />\n  <IconButton aria-label=\"Zoom out\" icon={Minus} variant=\"outline\" />\n</ButtonGroup>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/button-group",
+  "mdUrl": "/docs/components/button-group.md",
+  "jsonUrl": "/r/components/button-group.json",
+  "specimens": [
+    {
+      "title": "ButtonGroup",
+      "group": "forms",
+      "components": [
+        "ButtonGroup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"attached\">\n    <ButtonGroup>\n      <Button>Patch</Button>\n      <Button>Unpatch</Button>\n      <Button>Swap</Button>\n    </ButtonGroup>\n  </Specimen>\n  <Specimen label=\"spaced\">\n    <ButtonGroup attached={false}>\n      <Button>Patch</Button>\n      <Button variant=\"primary\">Apply</Button>\n    </ButtonGroup>\n  </Specimen>\n  <Specimen label=\"vertical\">\n    <ButtonGroup orientation=\"vertical\">\n      <Button>Up</Button>\n      <Button>Down</Button>\n    </ButtonGroup>\n  </Specimen>\n</Specimens>",
+      "note": "Buttons welded into one control, horizontally or vertically.",
+      "interaction": "each button keeps its own focus ring; only the outer corners are rounded."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/button.json

@@ -0,0 +1,126 @@
+{
+  "name": "Button",
+  "slug": "button",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The system's primary action control.\n\nA real `<button>` by default, restyled entirely from tokens: height comes\nfrom the density control ladder, colour from the theme's accent/surface ramp.\nThe focus ring is an `outline`, never a `box-shadow`, so it survives inside\n`overflow: hidden` panels.",
+  "props": [
+    {
+      "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={<a href=\"/x\" />}` — or a function returning one. When set, the\ndefault `type=\"button\"` is dropped so non-button elements stay valid."
+    },
+    {
+      "name": "icon",
+      "type": "ElementType<any, keyof IntrinsicElements>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional leading icon component (e.g. a lucide icon). Rendered\n`aria-hidden` and sized to the density icon token, so it tracks the density\nlevel without the caller passing a pixel size."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": ""
+    },
+    {
+      "name": "variant",
+      "type": "\"danger\" | \"ghost\" | \"secondary\" | \"primary\" | \"outline\" | \"danger-outline\"",
+      "required": false,
+      "defaultValue": "secondary",
+      "description": ""
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"button\">",
+    "VariantProps<typeof buttonVariants>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "variant": [
+      "primary",
+      "secondary",
+      "ghost",
+      "outline",
+      "danger",
+      "danger-outline"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "defaultVariants": {
+    "variant": "secondary",
+    "size": "md"
+  },
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-accent-hover",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-danger-fg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-space-6",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-ui"
+  ],
+  "summary": "The action control: six variants across three density-sized heights.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Button variant=\"primary\" size=\"sm\" icon={Play}>Run cue</Button>\n// Compose with a router link instead of a <button>:\n<Button render={<Link href=\"/patch\" />}>Patch</Button>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/button",
+  "mdUrl": "/docs/components/button.md",
+  "jsonUrl": "/r/components/button.json",
+  "whenToUse": [
+    "An action that happens on this page: submit, run, open a dialog.",
+    "Something that must look like a button but render as something else. Pass `render={<Link href=\"/patch\" />}`."
+  ],
+  "whenNotToUse": [
+    "Navigation that should behave like a link (middle-click, copy address). Use `Link`.",
+    "An icon-only control. Use `IconButton`, which requires the `aria-label` a bare icon needs.",
+    "A destructive action that should be confirmed where it stands. Use `TwoStepButton`."
+  ],
+  "commonMistakes": [
+    "Reaching for `variant=\"primary\"` on every button. One primary per view; `secondary` is the default for a reason.",
+    "Styling a Base UI trigger directly instead of passing `render={<Button />}`, which drops the variant classes into a tailwind-merge tie-break.",
+    "Fixing the height with `h-8 px-3` instead of `size`, which stops tracking density."
+  ],
+  "specimens": [
+    {
+      "title": "Button",
+      "group": "primitives",
+      "components": [
+        "Button"
+      ],
+      "code": "<Specimens>\n  {BUTTON_VARIANTS.map((variant) => (\n    <Specimen key={variant} label={variant}>\n      <Button variant={variant}>Go</Button>\n    </Specimen>\n  ))}\n  <Specimen label=\"disabled\">\n    <Button disabled>Go</Button>\n  </Specimen>\n  <Specimen label=\"with icon\">\n    <Button variant=\"primary\" icon={Play}>\n      Go\n    </Button>\n  </Specimen>\n  <Specimen label=\"loading\">\n    <Button disabled>\n      <Spinner size=\"sm\" /> Patching\n    </Button>\n  </Specimen>\n</Specimens>\n<Specimens>\n  {SIZES.map((size) => (\n    <Specimen key={size} label={`size ${size}`}>\n      <Button size={size}>Go</Button>\n    </Specimen>\n  ))}\n</Specimens>",
+      "note": "Six variants, three sizes. The accent ink is theme-controlled, so `primary` is never a hardcoded white on blue.",
+      "interaction": "hover darkens the fill (or tints the ground, for the quiet variants); keyboard focus draws a 2px accent ring outside the border, so the border-colour convention and the ring never fight."
+    }
+  ]
+}

package/manifest/components/calendar.json

@@ -0,0 +1,65 @@
+{
+  "name": "Calendar",
+  "slug": "calendar",
+  "group": "date",
+  "importPath": "@cueplusplus/ui/date",
+  "peerDependencies": [
+    "react-day-picker"
+  ],
+  "clientOnly": true,
+  "description": "A month grid, on react-day-picker v10.\n\nSelection modes, keyboard navigation, the ARIA grid wiring and the date maths\n(date-fns under the hood) are the library's; this layer supplies the token\nskin and nothing else, so upgrading the library never means re-deriving\nbehaviour. Every `classNames` slot the caller passes is merged *over* the\nskin rather than replacing it.\n\n`react-day-picker` and `date-fns` are **optional peers**: import this from\n`@cueplusplus/ui/date`, never from the core barrel.",
+  "props": [],
+  "typeReferences": [
+    "DayPickerProps"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-accent-hover",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-surface-3",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "A month grid, on react-day-picker v10.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Calendar mode=\"single\" selected={date} onSelect={setDate} />\n<Calendar mode=\"range\" numberOfMonths={2} selected={range} onSelect={setRange} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/calendar",
+  "mdUrl": "/docs/components/calendar.md",
+  "jsonUrl": "/r/components/calendar.json",
+  "specimens": [
+    {
+      "title": "Calendar",
+      "group": "date",
+      "components": [
+        "Calendar"
+      ],
+      "code": "<div className=\"flex flex-wrap gap-(--cue-space-6)\">\n  <Specimen label=\"single\">\n    <Calendar\n      mode=\"single\"\n      month={TODAY}\n      selected={day}\n      onSelect={setDay}\n      aria-label=\"Go-live date\"\n    />\n  </Specimen>\n  <Specimen label=\"range\">\n    <Calendar\n      mode=\"range\"\n      month={TODAY}\n      selected={range}\n      onSelect={setRange}\n      aria-label=\"Run of the show\"\n    />\n  </Specimen>\n  <Specimen label=\"with disabled days\">\n    <Calendar\n      mode=\"single\"\n      month={TODAY}\n      disabled={{ dayOfWeek: [0, 6] }}\n      aria-label=\"Weekdays only\"\n    />\n  </Specimen>\n</div>",
+      "note": "react-day-picker's month grid, restyled from tokens. Speaks plain `Date`, because that is what a show file holds.",
+      "interaction": "arrow keys walk the grid, Page Up and Page Down change month; the selected day is accent-soft, today is ringed."
+    }
+  ],
+  "todo": true
+}