@cueplusplus/ui 0.3.0 → 0.5.0

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

package/manifest/components/elements-data-table.json

@@ -0,0 +1,68 @@
+{
+  "name": "ElementsDataTable",
+  "slug": "elements-data-table",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A small comparison table the model can answer with directly.",
+  "props": [
+    {
+      "name": "rows",
+      "type": "readonly ModelUsage[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Table rows with model name, context window, and cost."
+    },
+    {
+      "name": "cycle",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Identity key that remounts the body so row entrance can replay."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-micro"
+  ],
+  "summary": "A small comparison table the model can answer with directly.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { DataTable } from \"@cueplusplus/ui/elements\";\n\n<DataTable\n  rows={[{ name: \"Sonnet\", context: \"200k\", cost: \"$3\" }]}\n  cycle={0}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/elements-data-table",
+  "mdUrl": "/docs/components/elements-data-table.md",
+  "jsonUrl": "/r/components/elements-data-table.json",
+  "specimens": [
+    {
+      "title": "ElementsDataTable",
+      "group": "elements-knowledge",
+      "components": [
+        "ElementsDataTable"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"what the research cost\" wide>\n    <ElementsDataTable rows={USAGE} cycle={0} />\n  </Specimen>\n  <Specimen label=\"one row\" wide>\n    <ElementsDataTable rows={USAGE.slice(0, 1)} cycle={1} />\n  </Specimen>\n</Specimens>",
+      "note": "A small table the model can answer with directly — three columns, no sorting, no virtualisation, no header menu. It is `ElementsDataTable` because the package already sells a real one at `@cueplusplus/ui/instruments`: that one is a data grid, this one is a paragraph shaped like a grid, and the rename keeps a consumer from reaching for the wrong one.",
+      "interaction": "none. `cycle` remounts the body, so a new answer's rows stagger in rather than mutating in place."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/elements-timeline.json

@@ -0,0 +1,69 @@
+{
+  "name": "ElementsTimeline",
+  "slug": "elements-timeline",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Events on a time axis, with what already happened and what is still coming.",
+  "props": [
+    {
+      "name": "events",
+      "type": "readonly TimelineEvent[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Events in chronological order, past and scheduled together."
+    },
+    {
+      "name": "visibleCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many events have been resolved."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"events\" | \"visibleCount\"> & {\n  /** Events in chronological order, past and scheduled together. */\n  events: readonly TimelineEvent[];\n  /** How many events have been resolved. */\n  visibleCount: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Events on a time axis, with what already happened and what is still coming.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { Timeline } from \"@cueplusplus/ui/elements\";\n\n<Timeline events={events} visibleCount={events.length} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/elements-timeline",
+  "mdUrl": "/docs/components/elements-timeline.md",
+  "jsonUrl": "/r/components/elements-timeline.json",
+  "specimens": [
+    {
+      "title": "ElementsTimeline",
+      "group": "elements-agents",
+      "components": [
+        "ElementsTimeline"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"past, now and scheduled\" wide>\n    <ElementsTimeline events={EVENTS} visibleCount={EVENTS.length} />\n  </Specimen>\n  <Specimen label=\"two events in\" wide>\n    <ElementsTimeline events={EVENTS} visibleCount={2} />\n  </Specimen>\n</Specimens>",
+      "note": "Events on one axis, with what already happened and what is still coming in the same list — `past`, `now` and `future` are one union, so a schedule and a history are the same component. It publishes as `ElementsTimeline` because cue already sells a `Timeline`; the spec asked for `ToolTimeline`, which turned out to be the next bench's name.",
+      "interaction": "none. The now marker is the only one that pulses, and it holds still for a reader who asked for less motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/elicitation-form.json

@@ -0,0 +1,103 @@
+{
+  "name": "ElicitationForm",
+  "slug": "elicitation-form",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A server pausing mid-tool-call to ask you for the fields it still needs.",
+  "props": [
+    {
+      "name": "server",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which server paused to ask."
+    },
+    {
+      "name": "message",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Why the input is needed, in the server's words."
+    },
+    {
+      "name": "fields",
+      "type": "readonly ElicitationField[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The schema the server sent, already resolved to display values."
+    },
+    {
+      "name": "state",
+      "type": "\"request\" | \"accepted\" | \"declined\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Swaps the action row for the outcome once the user answers."
+    },
+    {
+      "name": "onAccept",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the filled form is sent back."
+    },
+    {
+      "name": "onDecline",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the request is refused."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"server\"\n  | \"message\"\n  | \"fields\"\n  | \"state\"\n  | \"onAccept\"\n  | \"onDecline\"\n> & {\n  /** Which server paused to ask. */\n  server: string;\n  /** Why the input is needed, in the server's words. */\n  message: string;\n  /** The schema the server sent, already resolved to display values. */\n  fields: readonly ElicitationField[];\n  /** Swaps the action row for the outcome once the user answers. */\n  state: ElicitationState;\n  /** Called when the filled form is sent back. */\n  onAccept?: () => void;\n  /** Called when the request is refused. */\n  onDecline?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-bg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "A server pausing mid-tool-call to ask you for the fields it still needs.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ElicitationForm } from \"@cueplusplus/ui/elements\";\n\n<ElicitationForm\n  server=\"github-mcp\"\n  message=\"Confirm where the release notes should be published.\"\n  fields={fields}\n  state=\"request\"\n  onAccept={send}\n  onDecline={decline}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/elicitation-form",
+  "mdUrl": "/docs/components/elicitation-form.md",
+  "jsonUrl": "/r/components/elicitation-form.json",
+  "specimens": [
+    {
+      "title": "ElicitationForm",
+      "group": "elements-composer",
+      "components": [
+        "ElicitationForm"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"asking\" wide>\n    <ElicitationForm\n      server=\"eos-desk\"\n      message=\"Confirm which universe to patch into before I write anything to the show file.\"\n      fields={FIELDS}\n      state={elicitation}\n      onAccept={() => setElicitation(\"accepted\")}\n      onDecline={() => setElicitation(\"declined\")}\n    />\n  </Specimen>\n  <Specimen label=\"answered\" wide>\n    <ElicitationForm\n      server=\"eos-desk\"\n      message=\"Confirm which universe to patch into before I write anything to the show file.\"\n      fields={FIELDS}\n      state=\"accepted\"\n    />\n  </Specimen>\n  <Specimen label=\"refused\" wide>\n    <ElicitationForm\n      server=\"eos-desk\"\n      message=\"Confirm which universe to patch into before I write anything to the show file.\"\n      fields={FIELDS}\n      state=\"declined\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "A server pausing mid-tool-call to ask for the fields it still needs — MCP's elicitation, drawn. The fields arrive already resolved to display values, so the element renders a schema without ever having parsed one, and `state` swaps the two buttons for the outcome the moment the user answers. Declining is a first-class answer here, not a dismissal.",
+      "interaction": "each field's control is chosen by its `kind` — a value chip, a row of options, or a switch — and the required ones are marked on the label rather than announced only on failure."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state-composer.json

@@ -0,0 +1,64 @@
+{
+  "name": "EmptyStateComposer",
+  "slug": "empty-state-composer",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A composer-shaped invitation under the suggestions. It is a display rather than a\nworking input — the placeholder is a string and send takes a handler — for the\nscreen whose real composer is somewhere else.",
+  "props": [
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Resting text in the input bar."
+    },
+    {
+      "name": "onSend",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the send control. Omit it and the control renders disabled."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"placeholder\"> & {\n  /** Resting text in the input bar. */\n  placeholder: string;\n  /** Called from the send control. Omit it and the control renders disabled. */\n  onSend?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "A composer-shaped invitation under the suggestions.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state-composer",
+  "mdUrl": "/docs/components/empty-state-composer.md",
+  "jsonUrl": "/r/components/empty-state-composer.json",
+  "specimens": [
+    {
+      "title": "ChatEmptyState",
+      "group": "elements-composer",
+      "components": [
+        "ChatEmptyState",
+        "EmptyStateGreeting",
+        "EmptyStateSuggestions",
+        "EmptyStateSuggestion",
+        "EmptyStateComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"greeting, ways in, composer\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>What is the rig doing tonight?</EmptyStateGreeting>\n      <EmptyStateSuggestions>\n        {OPENERS.map((opener, index) => (\n          <EmptyStateSuggestion key={opener} index={index}>\n            {opener}\n          </EmptyStateSuggestion>\n        ))}\n      </EmptyStateSuggestions>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" onSend={() => undefined} />\n    </ChatEmptyState>\n  </Specimen>\n  <Specimen label=\"greeting only\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>Ready when you are.</EmptyStateGreeting>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" />\n    </ChatEmptyState>\n  </Specimen>\n</Specimens>",
+      "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
+      "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state-greeting.json

@@ -0,0 +1,49 @@
+{
+  "name": "EmptyStateGreeting",
+  "slug": "empty-state-greeting",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The one line at the top of a blank thread. A heading, so a screen reader lands on it.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"h2\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "The one line at the top of a blank thread.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state-greeting",
+  "mdUrl": "/docs/components/empty-state-greeting.md",
+  "jsonUrl": "/r/components/empty-state-greeting.json",
+  "specimens": [
+    {
+      "title": "ChatEmptyState",
+      "group": "elements-composer",
+      "components": [
+        "ChatEmptyState",
+        "EmptyStateGreeting",
+        "EmptyStateSuggestions",
+        "EmptyStateSuggestion",
+        "EmptyStateComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"greeting, ways in, composer\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>What is the rig doing tonight?</EmptyStateGreeting>\n      <EmptyStateSuggestions>\n        {OPENERS.map((opener, index) => (\n          <EmptyStateSuggestion key={opener} index={index}>\n            {opener}\n          </EmptyStateSuggestion>\n        ))}\n      </EmptyStateSuggestions>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" onSend={() => undefined} />\n    </ChatEmptyState>\n  </Specimen>\n  <Specimen label=\"greeting only\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>Ready when you are.</EmptyStateGreeting>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" />\n    </ChatEmptyState>\n  </Specimen>\n</Specimens>",
+      "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
+      "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
+    }
+  ],
+  "todo": true
+}