@cueplusplus/ui 0.3.0 → 0.6.0

package/manifest/components/composer-context.json

@@ -0,0 +1,67 @@
+{
+  "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."
+    }
+  ],
+  "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
+}

package/manifest/components/composer-input.json

@@ -0,0 +1,73 @@
+{
+  "name": "ComposerInput",
+  "slug": "composer-input",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The text field. Enter submits, guarded against IME composition so accepting a\ncandidate does not send the message.",
+  "props": [
+    {
+      "name": "onSubmit",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called on Enter, guarded against IME composition so accepting a candidate does not\nsend."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"input\">, \"onSubmit\"> & {\n  /**\n   * Called on Enter, guarded against IME composition so accepting a candidate does not\n   * send.\n   */\n  onSubmit?: () => 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": "The text field.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-input",
+  "mdUrl": "/docs/components/composer-input.md",
+  "jsonUrl": "/r/components/composer-input.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-menu-item.json

@@ -0,0 +1,72 @@
+{
+  "name": "ComposerMenuItem",
+  "slug": "composer-menu-item",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "One row of a `ComposerMenu`, and the chassis the command, person and model rows are\nbuilt on.",
+  "props": [
+    {
+      "name": "active",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Whether this is the row the keyboard is on."
+    }
+  ],
+  "typeReferences": [
+    "ComponentProps<\"button\"> & {\n  /** Whether this is the row the keyboard is on. */\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": "One row of a `ComposerMenu`, and the chassis the command, person and model rows are built on.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-menu-item",
+  "mdUrl": "/docs/components/composer-menu-item.md",
+  "jsonUrl": "/r/components/composer-menu-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-menu.json

@@ -0,0 +1,79 @@
+{
+  "name": "ComposerMenu",
+  "slug": "composer-menu",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The popover the slash and mention menus are drawn in, anchored above the bar. It\nanimates open rather than mounting, so the caret never moves under it.",
+  "props": [
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the menu is showing. Closed is animated out, not unmounted."
+    },
+    {
+      "name": "align",
+      "type": "\"end\" | \"start\"",
+      "required": false,
+      "defaultValue": "start",
+      "description": "Which edge of the composer the menu hangs from."
+    }
+  ],
+  "typeReferences": [
+    "ComponentProps<\"div\"> & {\n  /** Whether the menu is showing. Closed is animated out, not unmounted. */\n  open: boolean;\n  /** Which edge of the composer the menu hangs from. */\n  align?: \"start\" | \"end\";\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 popover the slash and mention menus are drawn in, anchored above the bar.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-menu",
+  "mdUrl": "/docs/components/composer-menu.md",
+  "jsonUrl": "/r/components/composer-menu.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-model-item.json

@@ -0,0 +1,75 @@
+{
+  "name": "ComposerModelItem",
+  "slug": "composer-model-item",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "One model in the menu, with its metadata and a tick on the chosen one.",
+  "props": [
+    {
+      "name": "entry",
+      "type": "ComposerModel",
+      "required": true,
+      "defaultValue": null,
+      "description": "The model this row offers."
+    },
+    {
+      "name": "selected",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether this is the model in use. Draws the tick."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"button\">, \"children\"> & {\n  /** The model this row offers. */\n  entry: ComposerModel;\n  /** Whether this is the model in use. Draws the tick. */\n  selected: 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": "One model in the menu, with its metadata and a tick on the chosen one.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-model-item",
+  "mdUrl": "/docs/components/composer-model-item.md",
+  "jsonUrl": "/r/components/composer-model-item.json",
+  "specimens": [
+    {
+      "title": "ComposerModelTrigger / ComposerModelItem",
+      "group": "elements-composer",
+      "components": [
+        "ComposerModelTrigger",
+        "ComposerModelItem"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"menu open\" wide>\n    <div className=\"flex min-h-56 w-full max-w-lg items-end\">\n      <ElementsComposer>\n        <ComposerMenu open={modelOpen} align=\"start\">\n          {MODELS.map((entry) => (\n            <ComposerModelItem\n              key={entry.name}\n              entry={entry}\n              selected={entry.name === model}\n              onClick={() => {\n                setModel(entry.name);\n                setModelOpen(false);\n              }}\n            />\n          ))}\n        </ComposerMenu>\n        <ComposerBar>\n          <ComposerToolbar>\n            <ComposerActions>\n              <ComposerModelTrigger\n                model={model}\n                open={modelOpen}\n                onClick={() => setModelOpen((open) => !open)}\n              />\n            </ComposerActions>\n            <ComposerActions>\n              <ComposerSend streaming={false} idle />\n            </ComposerActions>\n          </ComposerToolbar>\n        </ComposerBar>\n      </ElementsComposer>\n    </div>\n  </Specimen>\n  <Specimen label=\"closed\">\n    <ComposerModelTrigger model=\"Haiku 5\" open={false} />\n  </Specimen>\n</Specimens>",
+      "note": "The model as a word in the toolbar rather than a settings page. The trigger shows what is in use and carries `aria-expanded` for the menu it opens; each row shows the model and its one line of metadata, with a tick on the chosen one. Three rows is the point at which this stops being right and `ModelPicker` starts.",
+      "interaction": "the trigger is a plain button and the menu is the same `ComposerMenu` the slash and mention lists use — nothing here portals, so an island's values reach it without any carriage."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-model-trigger.json

@@ -0,0 +1,75 @@
+{
+  "name": "ComposerModelTrigger",
+  "slug": "composer-model-trigger",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The model name in the toolbar, which opens the model menu. Carries `aria-expanded`\nfor it.",
+  "props": [
+    {
+      "name": "model",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The name to show, which is the selected model."
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the menu it opens is showing. Announced as `aria-expanded`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"button\">, \"children\"> & {\n  /** The name to show, which is the selected model. */\n  model: string;\n  /** Whether the menu it opens is showing. Announced as `aria-expanded`. */\n  open: 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 model name in the toolbar, which opens the model menu.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-model-trigger",
+  "mdUrl": "/docs/components/composer-model-trigger.md",
+  "jsonUrl": "/r/components/composer-model-trigger.json",
+  "specimens": [
+    {
+      "title": "ComposerModelTrigger / ComposerModelItem",
+      "group": "elements-composer",
+      "components": [
+        "ComposerModelTrigger",
+        "ComposerModelItem"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"menu open\" wide>\n    <div className=\"flex min-h-56 w-full max-w-lg items-end\">\n      <ElementsComposer>\n        <ComposerMenu open={modelOpen} align=\"start\">\n          {MODELS.map((entry) => (\n            <ComposerModelItem\n              key={entry.name}\n              entry={entry}\n              selected={entry.name === model}\n              onClick={() => {\n                setModel(entry.name);\n                setModelOpen(false);\n              }}\n            />\n          ))}\n        </ComposerMenu>\n        <ComposerBar>\n          <ComposerToolbar>\n            <ComposerActions>\n              <ComposerModelTrigger\n                model={model}\n                open={modelOpen}\n                onClick={() => setModelOpen((open) => !open)}\n              />\n            </ComposerActions>\n            <ComposerActions>\n              <ComposerSend streaming={false} idle />\n            </ComposerActions>\n          </ComposerToolbar>\n        </ComposerBar>\n      </ElementsComposer>\n    </div>\n  </Specimen>\n  <Specimen label=\"closed\">\n    <ComposerModelTrigger model=\"Haiku 5\" open={false} />\n  </Specimen>\n</Specimens>",
+      "note": "The model as a word in the toolbar rather than a settings page. The trigger shows what is in use and carries `aria-expanded` for the menu it opens; each row shows the model and its one line of metadata, with a tick on the chosen one. Three rows is the point at which this stops being right and `ModelPicker` starts.",
+      "interaction": "the trigger is a plain button and the menu is the same `ComposerMenu` the slash and mention lists use — nothing here portals, so an island's values reach it without any carriage."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-person-item.json

@@ -0,0 +1,79 @@
+{
+  "name": "ComposerPersonItem",
+  "slug": "composer-person-item",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A mentionable person in the menu: their initial, their name, and whether they are an\nagent or a human.",
+  "props": [
+    {
+      "name": "person",
+      "type": "ComposerPerson",
+      "required": true,
+      "defaultValue": null,
+      "description": "The person this row would mention."
+    },
+    {
+      "name": "active",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether this is the row Enter would pick."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"button\">, \"children\"> & {\n  /** The person this row would mention. */\n  person: ComposerPerson;\n  /** Whether this is the row Enter would pick. */\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 mentionable person in the menu: their initial, their name, and whether they are an agent or a human.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-person-item",
+  "mdUrl": "/docs/components/composer-person-item.md",
+  "jsonUrl": "/r/components/composer-person-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-send.json

@@ -0,0 +1,80 @@
+{
+  "name": "ComposerSend",
+  "slug": "composer-send",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Send, which becomes stop while the model is streaming. Dim when the input is empty\nand there is nothing to send; the arrow and the square cross-fade rather than swap.",
+  "props": [
+    {
+      "name": "streaming",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Swaps the arrow for a stop square."
+    },
+    {
+      "name": "idle",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the input is empty. Dims the button when there is nothing to send."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"button\">, \"children\"> & {\n  /** Swaps the arrow for a stop square. */\n  streaming: boolean;\n  /** Whether the input is empty. Dims the button when there is nothing to send. */\n  idle: 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": "Send, which becomes stop while the model is streaming.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-send",
+  "mdUrl": "/docs/components/composer-send.md",
+  "jsonUrl": "/r/components/composer-send.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
+}