@cueplusplus/ui 0.13.0

package/manifest/components/comparison-card.json

@@ -0,0 +1,98 @@
+{
+  "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.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "options",
+      "type": "readonly ComparisonOption[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Two or three options. More than that wants a table, not a comparison.",
+      "control": {
+        "kind": "array",
+        "fixture": "knowledge.fixture-options"
+      }
+    },
+    {
+      "name": "recommendedId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which option is the pick. It is tinted and labelled rather than merely ordered first.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "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-leading-ui",
+    "--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,83 @@
+{
+  "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.",
+      "control": {
+        "kind": "opaque",
+        "fixture": "composer.attachment"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "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
+}

package/manifest/components/composer-bar.json

@@ -0,0 +1,76 @@
+{
+  "name": "ComposerBar",
+  "slug": "composer-bar",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The bar itself: the paper the input, the attachments and the toolbar sit on.\n`dragActive` tints it while a file is over it, which is the only feedback a drop\ntarget gets before the drop.",
+  "props": [
+    {
+      "name": "dragActive",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Whether a file is being dragged over the bar.",
+      "control": {
+        "kind": "boolean"
+      }
+    }
+  ],
+  "typeReferences": [
+    "ComponentProps<\"div\"> & {\n  /** Whether a file is being dragged over the bar. */\n  dragActive?: boolean;\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": "The bar itself: the paper the input, the attachments and the toolbar sit on.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-bar",
+  "mdUrl": "/docs/components/composer-bar.md",
+  "jsonUrl": "/r/components/composer-bar.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-command-item.json

@@ -0,0 +1,85 @@
+{
+  "name": "ComposerCommandItem",
+  "slug": "composer-command-item",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A slash command in the menu: its icon, `/name`, what it does, and the return key on\nthe active row.",
+  "props": [
+    {
+      "name": "command",
+      "type": "ComposerCommand",
+      "required": true,
+      "defaultValue": null,
+      "description": "The command this row offers.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "active",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether this is the row Enter would run.",
+      "control": {
+        "kind": "boolean"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"button\">, \"children\"> & {\n  /** The command this row offers. */\n  command: ComposerCommand;\n  /** Whether this is the row Enter would run. */\n  active: boolean;\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": "A slash command in the menu: its icon, `/name`, what it does, and the return key on the active row.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-command-item",
+  "mdUrl": "/docs/components/composer-command-item.md",
+  "jsonUrl": "/r/components/composer-command-item.json",
+  "specimens": [
+    {
+      "title": "ComposerMenu / useSlashMatches / useMentionMatches",
+      "group": "elements-composer",
+      "components": [
+        "ComposerMenu",
+        "ComposerMenuItem",
+        "ComposerCommandItem",
+        "ComposerPersonItem",
+        "useSlashMatches",
+        "useMentionMatches"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"slash commands\" wide>\n    <div className=\"flex min-h-64 w-full max-w-lg items-end\">\n      <ElementsComposer>\n        <ComposerMenu open={slashMatches.length > 0} align=\"start\">\n          {slashMatches.map((command, index) => (\n            <ComposerCommandItem\n              key={command.name}\n              command={command}\n              active={index === 0}\n              onClick={() => setSlash(`/${command.name} `)}\n            />\n          ))}\n          <ComposerMenuItem onClick={() => setSlash(\"\")}>\n            Browse every command\n          </ComposerMenuItem>\n        </ComposerMenu>\n        <ComposerBar>\n          <ComposerInput\n            aria-label=\"Run a slash command\"\n            value={slash}\n            placeholder=\"Type / for commands\"\n            onChange={(event) => setSlash(event.target.value)}\n          />\n        </ComposerBar>\n      </ElementsComposer>\n    </div>\n  </Specimen>\n\n  <Specimen label=\"mentions\" wide>\n    <div className=\"flex min-h-64 w-full max-w-lg items-end\">\n      <ElementsComposer>\n        <ComposerMenu open={mentionMatches.length > 0} align=\"end\">\n          {mentionMatches.map((person, index) => (\n            <ComposerPersonItem\n              key={person.name}\n              person={person}\n              active={index === 0}\n              onClick={() => setMention(applyMention(mention, person.name))}\n            />\n          ))}\n        </ComposerMenu>\n        <ComposerBar>\n          <ComposerInput\n            aria-label=\"Mention an agent or a person\"\n            value={mention}\n            placeholder=\"Type @ to hand this to somebody\"\n            onChange={(event) => setMention(event.target.value)}\n          />\n        </ComposerBar>\n      </ElementsComposer>\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "One input, two menus, and two hooks that decide which of them has anything to say. `useSlashMatches` answers only while the value starts with a slash; `useMentionMatches` only while the caret is inside a trailing @word — so an empty result is the menu's own instruction to stay shut. `applyMention` writes the choice back into the value, which is the one piece of text editing the family does for you. Type in either field below and the menu above it follows.",
+      "interaction": "the menu animates rather than mounting, so the caret never moves under it. A row is a button and takes cue's focus ring; the active one shows the return key it would answer to."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-context.json

@@ -0,0 +1,71 @@
+{
+  "name": "ComposerContext",
+  "slug": "composer-context",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The context-window dial in the toolbar, with the breakdown on hover or focus. It\nturns danger-coloured past 85%, which is the point where the next long tool result\nstarts costing the conversation its own history.",
+  "props": [
+    {
+      "name": "usage",
+      "type": "ComposerUsage",
+      "required": true,
+      "defaultValue": null,
+      "description": "Where the window has gone, and how big it is.",
+      "control": {
+        "kind": "opaque",
+        "fixture": "composer.usage"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\"> & {\n  /** Where the window has gone, and how big it is. */\n  usage: ComposerUsage;\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": "The context-window dial in the toolbar, with the breakdown on hover or focus.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-context",
+  "mdUrl": "/docs/components/composer-context.md",
+  "jsonUrl": "/r/components/composer-context.json",
+  "specimens": [
+    {
+      "title": "ComposerContext",
+      "group": "elements-composer",
+      "components": [
+        "ComposerContext"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"early in the session\">\n    <ComposerContext usage={USAGE} />\n  </Specimen>\n  <Specimen label=\"past the warning line\">\n    <ComposerContext usage={USAGE_TIGHT} />\n  </Specimen>\n</Specimens>",
+      "note": "The context window as a dial small enough to leave in the toolbar, with the arithmetic behind it on hover or focus. It turns the danger hue past 85% — the point where the next long tool result starts costing the conversation its own history rather than its headroom. Everything is in thousands of tokens and nothing is rounded here: the element divides, the caller counts.",
+      "interaction": "the dial is a labelled button (`Context usage`) and the breakdown opens on hover *or* focus-within, so it is reachable from the keyboard without a click target that does nothing."
+    }
+  ],
+  "todo": true
+}