@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/command-palette.json

@@ -0,0 +1,177 @@
+{
+  "name": "CommandPalette",
+  "slug": "command-palette",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The ⌘K surface: type a few letters, run a command.\n\nA Base UI `Combobox` living inside a Base UI `Dialog`, which is what buys the\ntwo halves nobody hand-rolls correctly. The dialog gives a real focus trap,\nfocus restoration and outside-press dismissal; the combobox gives\n`role=\"listbox\"`, `aria-activedescendant` tracking the highlighted row, and\narrow/Home/End/Enter navigation that a screen reader announces — the gap in\nevery home-grown palette, snuffle's included, where the list is a `div` of\nbuttons and the input never says which one Enter would run.\n\nMatching is debounced (see {@link CommandPaletteProps.debounceMs}) while the\nfield is not, and the first surviving command is highlighted automatically, so\n\"type three letters, press Enter\" always does the obvious thing.\n\nThe whole thing is portalled through the system's portal contract, so a\npalette opened from an ultra-compact island renders at that density.",
+  "props": [
+    {
+      "name": "items",
+      "type": "readonly CommandPaletteItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Every command the palette can run, in the order they should appear."
+    },
+    {
+      "name": "onSelect",
+      "type": "(item: CommandPaletteItem) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the command the user ran. The palette closes itself afterwards."
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Open state when controlled. Pass with `onOpenChange`."
+    },
+    {
+      "name": "defaultOpen",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Initial open state when uncontrolled. Defaults to `false`."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called whenever the palette wants to open or close."
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Type a command",
+      "description": "Shown while the query is empty. Defaults to `\"Type a command\"`."
+    },
+    {
+      "name": "emptyMessage",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "No commands match",
+      "description": "Shown in place of the list when nothing matches. Defaults to `\"No commands match\"`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Command palette",
+      "description": "Accessible name for the dialog and the input. Defaults to `\"Command palette\"`."
+    },
+    {
+      "name": "footer",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "(\n  <>\n    <span>↑↓ navigate</span>\n    <span>⏎ run</span>\n    <span>esc close</span>\n  </>\n)",
+      "description": "The hint strip along the foot. Pass `null` to drop it."
+    },
+    {
+      "name": "debounceMs",
+      "type": "number",
+      "required": false,
+      "defaultValue": "200",
+      "description": "Quiet period in ms before the query is re-matched. Defaults to `200`.\n\nThe field itself never waits — only the matching does — so typing stays at\none frame per keystroke however long the command list is."
+    },
+    {
+      "name": "filter",
+      "type": "((items: readonly CommandPaletteItem[], query: string) => CommandPaletteItem[])",
+      "required": false,
+      "defaultValue": "defaultFilter",
+      "description": "Replace the matcher. Defaults to a case-insensitive substring match over\n`label` and `keywords`. Return the surviving commands in display order."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the palette surface."
+    },
+    {
+      "name": "backdropClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the scrim behind it."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-sunken",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The keyboard entry point: type, filter, run.",
+  "examples": [
+    {
+      "title": "Wired to a shortcut",
+      "code": "<CommandPalette\n  open={open}\n  onOpenChange={setOpen}\n  items={[\n    { id: \"blackout\", label: \"Blackout\", group: \"Transport\", keywords: [\"panic\"] },\n    { id: \"patch\", label: \"Open patch\", group: \"Navigate\" },\n  ]}\n  onSelect={(item) => run(item.id)}\n/>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<CommandPalette\n  open={open}\n  onOpenChange={setOpen}\n  items={[\n    { id: \"go\", label: \"Go\", group: \"Playback\", hint: <Kbd>⏎</Kbd> },\n    { id: \"patch\", label: \"Patch fixture\", group: \"Patch\", keywords: [\"dmx\", \"address\"] },\n  ]}\n  onSelect={(command) => run(command.id)}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/command-palette",
+  "mdUrl": "/docs/components/command-palette.md",
+  "jsonUrl": "/r/components/command-palette.json",
+  "whenToUse": [
+    "An app with more commands than a toolbar can hold.",
+    "Giving power users one shortcut that reaches everything, usually Cmd/Ctrl-K."
+  ],
+  "whenNotToUse": [
+    "Choosing a value in a form. Use `Combobox`.",
+    "As the only route to a command. Everything in the palette should also be reachable in the UI."
+  ],
+  "commonMistakes": [
+    "Re-sorting `items` per keystroke. Commands keep the order they are given, and groups keep the order they first appear in.",
+    "Debouncing the field itself. Only the matching waits; the input stays at one frame per keystroke."
+  ],
+  "specimens": [
+    {
+      "title": "CommandPalette",
+      "group": "overlays",
+      "components": [
+        "CommandPalette"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"trigger\">\n    <Button onClick={() => setPaletteOpen(true)}>\n      Open palette <Kbd>⌘K</Kbd>\n    </Button>\n  </Specimen>\n  <Specimen label=\"last command\">\n    <Chip tone={lastCommand === null ? \"neutral\" : \"accent\"}>{lastCommand ?? \"none\"}</Chip>\n  </Specimen>\n</Specimens>\n<CommandPalette\n  items={PALETTE_ITEMS}\n  open={paletteOpen}\n  onOpenChange={setPaletteOpen}\n  onSelect={(item) => setLastCommand(item.label)}\n  placeholder=\"Run a command\"\n  emptyMessage={COPY.empty.title}\n  footer={\n    <span className=\"flex items-center gap-(--cue-space-2)\">\n      <Kbd>↑</Kbd>\n      <Kbd>↓</Kbd> to move\n      <Kbd>↵</Kbd> to run\n    </span>\n  }\n/>",
+      "note": "A combobox inside a dialog: grouped items, a 200 ms debounce, full arrow-key navigation and `aria-activedescendant` on the input.",
+      "interaction": "the whole list is reachable from the keyboard without ever moving DOM focus off the field."
+    }
+  ]
+}

package/manifest/components/compaction-row.json

@@ -0,0 +1,100 @@
+{
+  "name": "CompactionRow",
+  "slug": "compaction-row",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The rule that says the conversation was compacted, and by how much.\n\nA `role=\"separator\"` like {@link TimeBoundary }, because that is what it is:\nthe transcript above it is not the transcript below it any more. What makes\nit worth a component rather than a line of prose is the pair of numbers —\nbefore and after, on both axes — since \"compacted\" alone tells a reader\nnothing they can act on, while `128k → 24k tokens · 214 → 31 messages` tells\nthem why the model stopped remembering the thing they mentioned an hour ago.\n\nFive states, which is two more than most implementations have and exactly the\ntwo that matter: a compaction that **failed** leaves the window full, and one\nthat was **skipped** leaves it full on purpose. Both are the states a reader\nmeets when something is about to go wrong, and both are the states a UI that\nonly draws the happy path renders as nothing at all.\n\nThe numbers render as far as they are known. While `started`, pass the before\nfigures and no after ones and the row reads `128k tokens · 214 messages`; the\narrows arrive with the answer.",
+  "props": [
+    {
+      "name": "state",
+      "type": "\"failed\" | \"started\" | \"completed\" | \"cancelled\" | \"skipped\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Where the compaction got to. See `COMPACTION_STATES`."
+    },
+    {
+      "name": "tokensBefore",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Tokens in the window before it ran."
+    },
+    {
+      "name": "tokensAfter",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Tokens after. Omit while it is running, or when it did not finish."
+    },
+    {
+      "name": "messagesBefore",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Messages in the window before it ran."
+    },
+    {
+      "name": "messagesAfter",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Messages after. Omit while it is running, or when it did not finish."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the rule says, replacing the one `COMPACTION_LABELS` supplies for this\nstate."
+    },
+    {
+      "name": "reason",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Why, for the two states that owe an answer: `context window still under\n60%`, `the summariser refused`. Roo's rule — a compaction that did not\nhappen, or that lost something, should say so in words rather than leave a\nreader to infer it from a number that did not move."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-danger",
+    "--cue-fg-subtle",
+    "--cue-stream"
+  ],
+  "summary": "The rule that says the conversation was compacted, and by how much.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { CompactionRow } from \"@cueplusplus/ui/elements\";\n\n<CompactionRow\n  state=\"completed\"\n  tokensBefore={128_000}\n  tokensAfter={24_000}\n  messagesBefore={214}\n  messagesAfter={31}\n/>\n<CompactionRow state=\"skipped\" reason=\"context window still under 60%\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/compaction-row",
+  "mdUrl": "/docs/components/compaction-row.md",
+  "jsonUrl": "/r/components/compaction-row.json",
+  "specimens": [
+    {
+      "title": "CompactionRow",
+      "group": "elements-thread",
+      "components": [
+        "CompactionRow"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"started\" wide>\n    <div className=\"w-full max-w-md\">\n      <CompactionRow state=\"started\" tokensBefore={128_000} messagesBefore={214} />\n    </div>\n  </Specimen>\n  <Specimen label=\"completed\" wide>\n    <div className=\"w-full max-w-md\">\n      <CompactionRow\n        state=\"completed\"\n        tokensBefore={128_000}\n        tokensAfter={24_000}\n        messagesBefore={214}\n        messagesAfter={31}\n      />\n    </div>\n  </Specimen>\n  <Specimen label=\"failed\" wide>\n    <div className=\"w-full max-w-md\">\n      <CompactionRow\n        state=\"failed\"\n        tokensBefore={128_000}\n        reason=\"the summariser refused\"\n      />\n    </div>\n  </Specimen>\n  <Specimen label=\"cancelled\" wide>\n    <div className=\"w-full max-w-md\">\n      <CompactionRow state=\"cancelled\" tokensBefore={128_000} />\n    </div>\n  </Specimen>\n  <Specimen label=\"skipped\" wide>\n    <div className=\"w-full max-w-md\">\n      <CompactionRow state=\"skipped\" reason=\"context window still under 60%\" />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "A rule like TimeBoundary, because that is what it is: the transcript above it is not the transcript below it any more. What makes it a component is the pair of numbers on both axes — 'compacted' alone tells a reader nothing they can act on, while 128k → 24k tokens · 214 → 31 messages tells them why the model stopped remembering the thing they mentioned an hour ago. Five states, which is two more than most implementations have and exactly the two that matter: failed leaves the window full, and skipped leaves it full on purpose.",
+      "interaction": "none. The whole rule is one accessible name, because a separator announces its label and never its children."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/comparison-card.json

@@ -0,0 +1,83 @@
+{
+  "name": "ComparisonCard",
+  "slug": "comparison-card",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Two options weighed side by side, with the pick named and argued.",
+  "props": [
+    {
+      "name": "traitLabels",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The dimensions compared, in order. Used as the fallback label when an option lacks\na trait."
+    },
+    {
+      "name": "options",
+      "type": "readonly ComparisonOption[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Two or three options. More than that wants a table, not a comparison."
+    },
+    {
+      "name": "recommendedId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which option is the pick. It is tinted and labelled rather than merely ordered first."
+    },
+    {
+      "name": "reason",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Why that one, in the user's terms. A comparison without a recommendation is an\nunanswered question."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"traitLabels\" | \"options\" | \"recommendedId\" | \"reason\"\n> & {\n  /**\n   * The dimensions compared, in order. Used as the fallback label when an option lacks\n   * a trait.\n   */\n  traitLabels: readonly string[];\n  /** Two or three options. More than that wants a table, not a comparison. */\n  options: readonly ComparisonOption[];\n  /** Which option is the pick. It is tinted and labelled rather than merely ordered first. */\n  recommendedId: string;\n  /**\n   * Why that one, in the user's terms. A comparison without a recommendation is an\n   * unanswered question.\n   */\n  reason: string;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Two options weighed side by side, with the pick named and argued.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ComparisonCard } from \"@cueplusplus/ui/elements\";\n\n<ComparisonCard\n  traitLabels={traits}\n  options={options}\n  recommendedId=\"local\"\n  reason=\"You already hold messages in your own store.\"\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/comparison-card",
+  "mdUrl": "/docs/components/comparison-card.md",
+  "jsonUrl": "/r/components/comparison-card.json",
+  "specimens": [
+    {
+      "title": "ComparisonCard",
+      "group": "elements-knowledge",
+      "components": [
+        "ComparisonCard"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"the ESPRITE picked\" wide>\n    <ComparisonCard\n      traitLabels={[\"Output\", \"Power\", \"Stock\", \"Shutters\"]}\n      options={OPTIONS}\n      recommendedId=\"esprite\"\n      reason=\"The ESPRITE clears the wash at 8.4 m with zoom to spare; the S4's fixed 26° needs a second bar.\"\n    />\n  </Specimen>\n  <Specimen label=\"the other way round\" wide>\n    <ComparisonCard\n      traitLabels={[\"Output\", \"Power\", \"Stock\", \"Shutters\"]}\n      options={OPTIONS}\n      recommendedId=\"s4\"\n      reason=\"On the power installed, six S4s fit the FOH leg with 8 A to spare; six ESPRITEs do not.\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Two options side by side with the pick named, argued, and tinted in the streaming hue — not left for the reader to infer from a longer column. A trait that is `false` collapses to the label in grey with a minus, so the absence lines up with the presences instead of leaving a hole.",
+      "interaction": "none. It is a read-only comparison; choosing is `RecommendationCard`'s job, one bench along."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-actions.json

@@ -0,0 +1,65 @@
+{
+  "name": "ComposerActions",
+  "slug": "composer-actions",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "One cluster of controls in the toolbar. Two of them, one at each end.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "One cluster of controls in the toolbar.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-actions",
+  "mdUrl": "/docs/components/composer-actions.md",
+  "jsonUrl": "/r/components/composer-actions.json",
+  "specimens": [
+    {
+      "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
+      "group": "elements-composer",
+      "components": [
+        "ElementsComposer",
+        "ComposerBar",
+        "ComposerInput",
+        "ComposerToolbar",
+        "ComposerActions",
+        "ComposerAttachButton",
+        "ComposerSend"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"empty\" wide>\n    <ElementsComposer>\n      <ComposerBar>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value=\"\"\n          placeholder=\"Ask about the rig\"\n          readOnly\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton onClick={() => undefined} />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerSend streaming={false} idle />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n\n  <Specimen label=\"typed\" wide>\n    <ElementsComposer>\n      <ComposerBar>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value={message}\n          placeholder=\"Ask about the rig\"\n          onChange={(event) => setMessage(event.target.value)}\n          onSubmit={() => setMessage(\"\")}\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton onClick={() => undefined} />\n            <ComposerModelTrigger model={model} open={false} />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerContext usage={USAGE} />\n            <ComposerVoiceButton active={false} />\n            <ComposerSend streaming={false} idle={message === \"\"} />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n\n  <Specimen label=\"streaming, file over the bar\" wide>\n    <ElementsComposer>\n      <ComposerBar dragActive>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value=\"\"\n          placeholder=\"Drop the truss drawing here\"\n          readOnly\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerSend streaming idle={false} />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n</Specimens>",
+      "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
+      "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-attach-button.json

@@ -0,0 +1,65 @@
+{
+  "name": "ComposerAttachButton",
+  "slug": "composer-attach-button",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The paperclip, as a plus. Disabled when no handler is given, rather than rendering a\ncontrol that does nothing.",
+  "props": [],
+  "typeReferences": [
+    "Omit<ComponentProps<\"button\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The paperclip, as a plus.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-attach-button",
+  "mdUrl": "/docs/components/composer-attach-button.md",
+  "jsonUrl": "/r/components/composer-attach-button.json",
+  "specimens": [
+    {
+      "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
+      "group": "elements-composer",
+      "components": [
+        "ElementsComposer",
+        "ComposerBar",
+        "ComposerInput",
+        "ComposerToolbar",
+        "ComposerActions",
+        "ComposerAttachButton",
+        "ComposerSend"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"empty\" wide>\n    <ElementsComposer>\n      <ComposerBar>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value=\"\"\n          placeholder=\"Ask about the rig\"\n          readOnly\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton onClick={() => undefined} />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerSend streaming={false} idle />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n\n  <Specimen label=\"typed\" wide>\n    <ElementsComposer>\n      <ComposerBar>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value={message}\n          placeholder=\"Ask about the rig\"\n          onChange={(event) => setMessage(event.target.value)}\n          onSubmit={() => setMessage(\"\")}\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton onClick={() => undefined} />\n            <ComposerModelTrigger model={model} open={false} />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerContext usage={USAGE} />\n            <ComposerVoiceButton active={false} />\n            <ComposerSend streaming={false} idle={message === \"\"} />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n\n  <Specimen label=\"streaming, file over the bar\" wide>\n    <ElementsComposer>\n      <ComposerBar dragActive>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value=\"\"\n          placeholder=\"Drop the truss drawing here\"\n          readOnly\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerSend streaming idle={false} />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n</Specimens>",
+      "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
+      "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-attachment-chip.json

@@ -0,0 +1,75 @@
+{
+  "name": "ComposerAttachmentChip",
+  "slug": "composer-attachment-chip",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "One attached file as a chip: an icon for its kind, its name and size, and — while it\nuploads — a progress hairline along the bottom edge. A finished one offers remove, a\nfailed one says so in its meta line.",
+  "props": [
+    {
+      "name": "attachment",
+      "type": "ComposerAttachment",
+      "required": true,
+      "defaultValue": null,
+      "description": "The file this chip stands for."
+    },
+    {
+      "name": "onRemove",
+      "type": "((name: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the attachment's name. Omit it and a finished chip shows a tick\ninstead of a remove button."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\"> & {\n  /** The file this chip stands for. */\n  attachment: ComposerAttachment;\n  /**\n   * Called with the attachment's name. Omit it and a finished chip shows a tick\n   * instead of a remove button.\n   */\n  onRemove?: (name: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "One attached file as a chip: an icon for its kind, its name and size, and — while it uploads — a progress hairline along the bottom edge.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-attachment-chip",
+  "mdUrl": "/docs/components/composer-attachment-chip.md",
+  "jsonUrl": "/r/components/composer-attachment-chip.json",
+  "specimens": [
+    {
+      "title": "ComposerAttachments / ComposerAttachmentChip",
+      "group": "elements-composer",
+      "components": [
+        "ComposerAttachments",
+        "ComposerAttachmentChip"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"three states\" wide>\n    <ComposerAttachments>\n      {chips.map((attachment) => (\n        <ComposerAttachmentChip\n          key={attachment.name}\n          attachment={attachment}\n          onRemove={(name) => setAttached((current) => [...current, name])}\n        />\n      ))}\n    </ComposerAttachments>\n  </Specimen>\n  <Specimen label=\"one, settled, nothing to remove\" wide>\n    <ComposerAttachments>\n      <ComposerAttachmentChip\n        attachment={{\n          name: \"front-truss.pdf\",\n          meta: \"1.2 MB\",\n          state: \"done\",\n          kind: \"text\",\n        }}\n      />\n    </ComposerAttachments>\n  </Specimen>\n</Specimens>",
+      "note": "The rail above the input, and one chip per file. A chip carries its own state: uploading draws a hairline of progress along its bottom edge, done offers a remove button, and a failure says why in the line that would otherwise hold a size. The icon is the file's kind, not its extension, so an unknown type still lands on something.",
+      "interaction": "remove is a labelled icon button (`Remove front-truss.pdf`) and only exists on a finished chip — there is nothing to remove from an upload that has not landed, and a failed one is removed by fixing it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-attachments.json

@@ -0,0 +1,60 @@
+{
+  "name": "ComposerAttachments",
+  "slug": "composer-attachments",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The rail the attachment chips wrap in, above the input.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The rail the attachment chips wrap in, above the input.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-attachments",
+  "mdUrl": "/docs/components/composer-attachments.md",
+  "jsonUrl": "/r/components/composer-attachments.json",
+  "specimens": [
+    {
+      "title": "ComposerAttachments / ComposerAttachmentChip",
+      "group": "elements-composer",
+      "components": [
+        "ComposerAttachments",
+        "ComposerAttachmentChip"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"three states\" wide>\n    <ComposerAttachments>\n      {chips.map((attachment) => (\n        <ComposerAttachmentChip\n          key={attachment.name}\n          attachment={attachment}\n          onRemove={(name) => setAttached((current) => [...current, name])}\n        />\n      ))}\n    </ComposerAttachments>\n  </Specimen>\n  <Specimen label=\"one, settled, nothing to remove\" wide>\n    <ComposerAttachments>\n      <ComposerAttachmentChip\n        attachment={{\n          name: \"front-truss.pdf\",\n          meta: \"1.2 MB\",\n          state: \"done\",\n          kind: \"text\",\n        }}\n      />\n    </ComposerAttachments>\n  </Specimen>\n</Specimens>",
+      "note": "The rail above the input, and one chip per file. A chip carries its own state: uploading draws a hairline of progress along its bottom edge, done offers a remove button, and a failure says why in the line that would otherwise hold a size. The icon is the file's kind, not its extension, so an unknown type still lands on something.",
+      "interaction": "remove is a labelled icon button (`Remove front-truss.pdf`) and only exists on a finished chip — there is nothing to remove from an upload that has not landed, and a failed one is removed by fixing it."
+    }
+  ],
+  "todo": true
+}