@cueplusplus/ui 0.3.0 → 0.6.0

package/manifest/components/delegation-card.json

@@ -37,7 +37,7 @@
     },
     {
       "name": "status",
-      "type": "\"idle\" | \"done\" | \"working\" | \"failed\"",
+      "type": "\"done\" | \"working\" | \"failed\" | \"idle\"",
       "required": false,
       "defaultValue": null,
       "description": "Where the work has got to. Omit to draw no status line at all."

package/manifest/components/density.json

@@ -9,7 +9,7 @@
   "props": [
     {
       "name": "density",
-      "type": "\"ultra-compact\" | \"compact\" | \"normal\" | \"large\" | \"ultra-large\"",
+      "type": "\"normal\" | \"large\" | \"compact\" | \"ultra-compact\" | \"ultra-large\"",
       "required": true,
       "defaultValue": null,
       "description": "Level to apply to this subtree: `ultra-compact`, `compact`, `normal`,\n`large` or `ultra-large`."

package/manifest/components/diagram.json

@@ -0,0 +1,100 @@
+{
+  "name": "Diagram",
+  "slug": "diagram",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A drawn answer with zoom, reset, and a full-bleed view; you hand it the rendered\ngraphic.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the diagram shows."
+    },
+    {
+      "name": "zoom",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Scale factor applied to the content. 1 is fit; the header prints it as a percentage."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The rendered graphic. The element owns the frame and never parses or injects\nmarkup itself, so whatever renders your chart stays your choice."
+    },
+    {
+      "name": "onZoomIn",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the zoom-in control. Clamp the range yourself."
+    },
+    {
+      "name": "onZoomOut",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the zoom-out control."
+    },
+    {
+      "name": "onReset",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to return to the default view."
+    },
+    {
+      "name": "onExpand",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to open the diagram full screen."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"title\"\n  | \"zoom\"\n  | \"children\"\n  | \"onZoomIn\"\n  | \"onZoomOut\"\n  | \"onReset\"\n  | \"onExpand\"\n> & {\n  /** What the diagram shows. */\n  title: string;\n  /** Scale factor applied to the content. 1 is fit; the header prints it as a percentage. */\n  zoom: number;\n  /**\n   * The rendered graphic. The element owns the frame and never parses or injects\n   * markup itself, so whatever renders your chart stays your choice.\n   */\n  children: React.ReactNode;\n  /** Called from the zoom-in control. Clamp the range yourself. */\n  onZoomIn?: () => void;\n  /** Called from the zoom-out control. */\n  onZoomOut?: () => void;\n  /** Called to return to the default view. */\n  onReset?: () => void;\n  /** Called to open the diagram full screen. */\n  onExpand?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-text-body"
+  ],
+  "summary": "A drawn answer with zoom, reset, and a full-bleed view; you hand it the rendered graphic.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { Diagram } from \"@cueplusplus/ui/elements\";\n\n<Diagram title=\"message flow\" zoom={zoom} onZoomIn={zoomIn} onReset={reset}>\n  <MermaidSvg chart={chart} />\n</Diagram>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/diagram",
+  "mdUrl": "/docs/components/diagram.md",
+  "jsonUrl": "/r/components/diagram.json",
+  "specimens": [
+    {
+      "title": "Diagram",
+      "group": "elements-knowledge",
+      "components": [
+        "Diagram"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"the front truss, zoomable\" wide>\n    <Diagram\n      title=\"Front truss — 6 fixtures on 3.2 m centres\"\n      zoom={zoom}\n      onZoomIn={() => setZoom((current) => Math.min(1.6, current + 0.2))}\n      onZoomOut={() => setZoom((current) => Math.max(0.6, current - 0.2))}\n      onReset={() => setZoom(1)}\n    >\n      <svg\n        viewBox=\"0 0 200 60\"\n        width=\"200\"\n        height=\"60\"\n        role=\"img\"\n        aria-label=\"Six fixtures hung along one truss\"\n      >\n        <line x1=\"6\" y1=\"20\" x2=\"194\" y2=\"20\" className=\"stroke-fg-subtle\" strokeWidth=\"2\" />\n        {[16, 51, 86, 121, 156, 186].map((x) => (\n          <rect key={x} x={x - 6} y=\"26\" width=\"12\" height=\"16\" rx=\"2\" className=\"fill-stream\" />\n        ))}\n      </svg>\n    </Diagram>\n  </Specimen>\n  <Specimen label=\"zoomed out, nothing to expand to\" wide>\n    <Diagram title=\"Front truss\" zoom={0.7}>\n      <svg viewBox=\"0 0 200 40\" width=\"200\" height=\"40\" role=\"img\" aria-label=\"One truss\">\n        <line x1=\"6\" y1=\"20\" x2=\"194\" y2=\"20\" className=\"stroke-fg-subtle\" strokeWidth=\"2\" />\n      </svg>\n    </Diagram>\n  </Specimen>\n</Specimens>",
+      "note": "A drawn answer with a viewport around it: zoom, reset, full-bleed. The graphic is yours — the element supplies the frame, the percentage readout and the transform, and never parses or renders anything itself.",
+      "interaction": "four named icon buttons; expand disables itself when no handler is given, which is the honest state for a bench with nowhere to expand to. The scale transition stops under reduced motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/document-reference.json

@@ -0,0 +1,90 @@
+{
+  "name": "DocumentReference",
+  "slug": "document-reference",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A document the answer leans on, with the quoted passage and the page to jump to.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Document name."
+    },
+    {
+      "name": "pages",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Total page count."
+    },
+    {
+      "name": "anchors",
+      "type": "readonly DocumentAnchor[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The passages the answer drew on, each pinned to a page."
+    },
+    {
+      "name": "activePage",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which anchor is highlighted. A page with no anchor highlights nothing."
+    },
+    {
+      "name": "onJump",
+      "type": "((page: number) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the page to open."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"title\" | \"pages\" | \"anchors\" | \"activePage\" | \"onJump\"\n> & {\n  /** Document name. */\n  title: string;\n  /** Total page count. */\n  pages: number;\n  /** The passages the answer drew on, each pinned to a page. */\n  anchors: readonly DocumentAnchor[];\n  /** Which anchor is highlighted. A page with no anchor highlights nothing. */\n  activePage: number;\n  /** Called with the page to open. */\n  onJump?: (page: number) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "A document the answer leans on, with the quoted passage and the page to jump to.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { DocumentReference } from \"@cueplusplus/ui/elements\";\n\n<DocumentReference\n  title=\"migration-0.14.pdf\"\n  pages={14}\n  anchors={anchors}\n  activePage={4}\n  onJump={setPage}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/document-reference",
+  "mdUrl": "/docs/components/document-reference.md",
+  "jsonUrl": "/r/components/document-reference.json",
+  "specimens": [
+    {
+      "title": "DocumentReference",
+      "group": "elements-knowledge",
+      "components": [
+        "DocumentReference"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"page 31 active\" wide>\n    <DocumentReference\n      title=\"ESPRITE user manual, rev. 8\"\n      pages={94}\n      anchors={ANCHORS}\n      activePage={page}\n      onJump={setPage}\n    />\n  </Specimen>\n  <Specimen label=\"one anchor\" wide>\n    <DocumentReference\n      title=\"Truss loading guidance\"\n      pages={18}\n      anchors={ANCHORS.slice(0, 1)}\n      activePage={12}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "One document the answer leans on, with the passages it quoted and the page each is on. Several anchors can cite one page — two of these are both page 31 — so the current one is marked by `aria-current` rather than by matching the number, which is what stops the wrong row lighting up.",
+      "interaction": "every quote is a button that reports its page to `onJump`; the active row takes the recessed field ground, the others only on hover."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/draft-restore.json

@@ -0,0 +1,82 @@
+{
+  "name": "DraftRestore",
+  "slug": "draft-restore",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Come back to a thread and the sentence you never sent is still waiting.",
+  "props": [
+    {
+      "name": "draft",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The unsent text, truncated to one line."
+    },
+    {
+      "name": "savedAt",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "When it was last touched, pre-formatted."
+    },
+    {
+      "name": "onRestore",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to put the draft back in the composer."
+    },
+    {
+      "name": "onDiscard",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to throw the draft away."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"draft\" | \"savedAt\" | \"onRestore\" | \"onDiscard\"\n> & {\n  /** The unsent text, truncated to one line. */\n  draft: string;\n  /** When it was last touched, pre-formatted. */\n  savedAt: string;\n  /** Called to put the draft back in the composer. */\n  onRestore?: () => void;\n  /** Called to throw the draft away. */\n  onDiscard?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Come back to a thread and the sentence you never sent is still waiting.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { DraftRestore } from \"@cueplusplus/ui/elements\";\n\n<DraftRestore\n  draft=\"Add a regression test for draft restore\"\n  savedAt=\"2 minutes ago\"\n  onRestore={restore}\n  onDiscard={discard}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/draft-restore",
+  "mdUrl": "/docs/components/draft-restore.md",
+  "jsonUrl": "/r/components/draft-restore.json",
+  "specimens": [
+    {
+      "title": "DraftRestore",
+      "group": "elements-composer",
+      "components": [
+        "DraftRestore"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"waiting\" wide>\n    <DraftRestore\n      draft=\"Patch the back truss too, but leave universe 4 alone\"\n      savedAt=\"14 minutes ago\"\n      onRestore={() => undefined}\n      onDiscard={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"long draft\" wide>\n    <DraftRestore\n      draft=\"Check whether the ESPRITEs on the back truss are still in mode 4 and, if they are, tell me before changing anything\"\n      savedAt=\"yesterday\"\n      onRestore={() => undefined}\n      onDiscard={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Come back to a thread and the sentence you never sent is still sitting there. One line of what it was, when it was saved, and the two answers anybody ever has for it. `savedAt` is pre-formatted like every other time in this family — the element does no date maths, so a server-rendered draft and a client-rendered one cannot disagree.",
+      "interaction": "restore is a worded button and discard is a labelled icon (`Discard the draft`): the destructive one is the one that has to be aimed at."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/drawer.json

@@ -25,7 +25,7 @@
       "props": [
         {
           "name": "swipeDirection",
-          "type": "\"up\" | \"down\" | \"left\" | \"right\"",
+          "type": "\"left\" | \"right\" | \"up\" | \"down\"",
           "required": false,
           "defaultValue": "down",
           "description": "Which way the drawer is dragged to dismiss it, which also decides the edge\nit lives on. Defaults to `\"down\"` — the bottom sheet."

package/manifest/components/dropdown-menu.json

@@ -87,7 +87,7 @@
         },
         {
           "name": "side",
-          "type": "\"left\" | \"right\" | \"top\" | \"bottom\" | \"inline-end\" | \"inline-start\"",
+          "type": "\"left\" | \"right\" | \"bottom\" | \"top\" | \"inline-end\" | \"inline-start\"",
           "required": false,
           "defaultValue": null,
           "description": "Preferred side of the trigger. Defaults to `\"bottom\"`."

package/manifest/components/edit-message.json

@@ -0,0 +1,105 @@
+{
+  "name": "EditMessage",
+  "slug": "edit-message",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Rewrite a turn in place, told up front how many replies the edit throws away.",
+  "props": [
+    {
+      "name": "value",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The message text, read when resting and edited when open."
+    },
+    {
+      "name": "discardedReplies",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many replies sending would drop. The warning hides at zero."
+    },
+    {
+      "name": "editing",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Swaps between the resting bubble and the edit composer."
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called as the message is edited."
+    },
+    {
+      "name": "onSave",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the edited message is sent."
+    },
+    {
+      "name": "onCancel",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the edit is abandoned. Restore the original yourself."
+    },
+    {
+      "name": "onStartEdit",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the resting bubble is clicked."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"value\"\n  | \"discardedReplies\"\n  | \"editing\"\n  | \"onValueChange\"\n  | \"onSave\"\n  | \"onCancel\"\n  | \"onStartEdit\"\n> & {\n  /** The message text, read when resting and edited when open. */\n  value: string;\n  /** How many replies sending would drop. The warning hides at zero. */\n  discardedReplies: number;\n  /** Swaps between the resting bubble and the edit composer. */\n  editing: boolean;\n  /** Called as the message is edited. */\n  onValueChange?: (value: string) => void;\n  /** Called when the edited message is sent. */\n  onSave?: () => void;\n  /** Called when the edit is abandoned. Restore the original yourself. */\n  onCancel?: () => void;\n  /** Called when the resting bubble is clicked. */\n  onStartEdit?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "Rewrite a turn in place, told up front how many replies the edit throws away.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { EditMessage } from \"@cueplusplus/ui/elements\";\n\n<EditMessage\n  value={value}\n  discardedReplies={3}\n  editing={editing}\n  onValueChange={setValue}\n  onStartEdit={() => setEditing(true)}\n  onCancel={cancel}\n  onSave={save}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/edit-message",
+  "mdUrl": "/docs/components/edit-message.md",
+  "jsonUrl": "/r/components/edit-message.json",
+  "specimens": [
+    {
+      "title": "EditMessage",
+      "group": "elements-thread",
+      "components": [
+        "EditMessage"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"editing · 2 replies at stake\" wide>\n    <EditMessage\n      value={draft}\n      discardedReplies={2}\n      editing={editing}\n      onValueChange={setDraft}\n      onSave={() => setEditing(false)}\n      onCancel={() => setEditing(false)}\n      onStartEdit={() => setEditing(true)}\n    />\n  </Specimen>\n  <Specimen label=\"editing · nothing at stake\" wide>\n    <EditMessage value={draft} discardedReplies={0} editing onValueChange={setDraft} />\n  </Specimen>\n  <Specimen label=\"resting\" wide>\n    <EditMessage\n      value=\"Plot's in. Front truss, universe 3.\"\n      discardedReplies={2}\n      editing={false}\n      onStartEdit={() => setEditing(true)}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Rewriting a turn you already sent, told up front what it throws away. The count is the point: editing the third message of a thread discards everything after it, and a control that hid that would be a data-loss trap wearing a pencil icon.",
+      "interaction": "resting, the whole bubble is the button that starts an edit. Editing, the textarea is labelled and takes cue's focus ring; Send leads and Cancel is a ghost."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/elements-command-palette.json

@@ -0,0 +1,100 @@
+{
+  "name": "ElementsCommandPalette",
+  "slug": "elements-command-palette",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Everything the app can do, one keystroke away and grouped by where it acts.",
+  "props": [
+    {
+      "name": "commands",
+      "type": "readonly PaletteCommand[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Everything runnable. Groups are derived from the entries and keep first-seen order."
+    },
+    {
+      "name": "query",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current filter text."
+    },
+    {
+      "name": "activeId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which row is highlighted. Arrow keys move it and Enter runs it, both handled by\nthe element; it reports the move through onActiveChange."
+    },
+    {
+      "name": "onQueryChange",
+      "type": "((query: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called as the filter is typed."
+    },
+    {
+      "name": "onActiveChange",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called as the arrow keys walk the list. The element owns the key handling and\nreports where it landed, so activeId stays yours to hold."
+    },
+    {
+      "name": "onRun",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a command is chosen."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"commands\"\n  | \"query\"\n  | \"activeId\"\n  | \"onQueryChange\"\n  | \"onActiveChange\"\n  | \"onRun\"\n> & {\n  /** Everything runnable. Groups are derived from the entries and keep first-seen order. */\n  commands: readonly PaletteCommand[];\n  /** Current filter text. */\n  query: string;\n  /**\n   * Which row is highlighted. Arrow keys move it and Enter runs it, both handled by\n   * the element; it reports the move through onActiveChange.\n   */\n  activeId: string;\n  /** Called as the filter is typed. */\n  onQueryChange?: (query: string) => void;\n  /**\n   * Called as the arrow keys walk the list. The element owns the key handling and\n   * reports where it landed, so activeId stays yours to hold.\n   */\n  onActiveChange?: (id: string) => void;\n  /** Called when a command is chosen. */\n  onRun?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Everything the app can do, one keystroke away and grouped by where it acts.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { CommandPalette } from \"@cueplusplus/ui/elements\";\n\n<CommandPalette\n  commands={commands}\n  query={query}\n  activeId={activeId}\n  onQueryChange={setQuery}\n  onRun={run}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/elements-command-palette",
+  "mdUrl": "/docs/components/elements-command-palette.md",
+  "jsonUrl": "/r/components/elements-command-palette.json",
+  "specimens": [
+    {
+      "title": "ElementsCommandPalette",
+      "group": "elements-composer",
+      "components": [
+        "ElementsCommandPalette"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"everything\" wide>\n    <ElementsCommandPalette\n      commands={PALETTE}\n      query={query}\n      activeId={activeCommand}\n      onQueryChange={setQuery}\n      onActiveChange={setActiveCommand}\n      onRun={setActiveCommand}\n    />\n  </Specimen>\n  <Specimen label=\"filtered to one group\" wide>\n    <ElementsCommandPalette commands={PALETTE} query=\"patch\" activeId=\"patch\" />\n  </Specimen>\n  <Specimen label=\"nothing matches\" wide>\n    <ElementsCommandPalette commands={PALETTE} query=\"haze\" activeId=\"patch\" />\n  </Specimen>\n</Specimens>",
+      "note": "Everything the console can do, one keystroke away and grouped by where it acts. The element owns the arrow keys and reports where they landed, so the highlighted row stays the caller's state — and `aria-activedescendant` moves the highlight without moving focus, which is what keeps typing and walking the list the same gesture. Groups are derived from the commands and keep first-seen order, so the palette cannot be re-ordered by accident.",
+      "interaction": "the input is a combobox over a listbox; arrows walk, Enter runs, and a query that filters the active row out drops the descendant reference rather than pointing at nothing."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/elements-composer.json

@@ -0,0 +1,71 @@
+{
+  "name": "ElementsComposer",
+  "slug": "elements-composer",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The unified input: attachments, commands, mentions, models, voice, and context in\none surface.",
+  "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 unified input: attachments, commands, mentions, models, voice, and context in one surface.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import {\n  Composer,\n  ComposerActions,\n  ComposerAttachButton,\n  ComposerBar,\n  ComposerInput,\n  ComposerSend,\n  ComposerToolbar,\n} from \"@cueplusplus/ui/elements\";\n\n<Composer>\n  <ComposerBar>\n    <ComposerInput value={value} placeholder=\"Ask anything\" onChange={onChange} onSubmit={send} />\n    <ComposerToolbar>\n      <ComposerActions><ComposerAttachButton onClick={pick} /></ComposerActions>\n      <ComposerActions><ComposerSend streaming={false} idle={!value} onClick={send} /></ComposerActions>\n    </ComposerToolbar>\n  </ComposerBar>\n</Composer>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/elements-composer",
+  "mdUrl": "/docs/components/elements-composer.md",
+  "jsonUrl": "/r/components/elements-composer.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
+}