@cueplusplus/ui 0.3.0 → 0.6.0

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
+}

package/manifest/components/composer-bar.json

@@ -0,0 +1,73 @@
+{
+  "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."
+    }
+  ],
+  "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,79 @@
+{
+  "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."
+    },
+    {
+      "name": "active",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether this is the row Enter would run."
+    }
+  ],
+  "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
+}