@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/dropdown-menu.json

@@ -0,0 +1,229 @@
+{
+  "name": "DropdownMenu",
+  "slug": "dropdown-menu",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A command list hung off a button: row actions, view options, an account menu.\n\nWraps Base UI's `Menu`, so roving focus, typeahead, submenu handling, Escape\nand outside-press dismissal are the primitive's. This layer adds the token\nskin, the portal theme stamp and the canvas-safe wheel dismissal\n(see {@link DropdownMenuRootProps.closeOnWheel}).",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Trigger",
+    "Content",
+    "Group",
+    "Label",
+    "Item",
+    "CheckboxItem",
+    "Separator"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "DropdownMenu.Root",
+      "description": "Groups the parts of a menu and owns its open state. Renders no element.",
+      "props": [
+        {
+          "name": "closeOnWheel",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Close the menu when the viewport moves under it — a wheel anywhere outside\nthe popup, or a window resize. Defaults to `true`.\n\nThe menu is positioned from its trigger's rect, and a canvas that pans by\nmutating a CSS transform fires no `scroll` event, so without this a menu\nover the patch grid detaches from its button the moment the user scrolls.\nA wheel *inside* the popup is left alone — that is a long menu scrolling."
+        }
+      ],
+      "typeReferences": [
+        "BaseMenu.Root.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "DropdownMenu.Trigger",
+      "description": "The control that opens the menu. Unstyled — pass `render={<Button />}` or\n`render={<IconButton …/>}` so the button's variant classes win.",
+      "props": [],
+      "typeReferences": [
+        "BaseMenu.Trigger.Props"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "DropdownMenu.Content",
+      "description": "The menu's portal, positioner and popup.\n\nPortalled through {@link useCuePortalProps} so the rows render at the\ncaller's density; roving focus, typeahead and Escape come from Base UI.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the popup surface."
+        },
+        {
+          "name": "align",
+          "type": "\"center\" | \"end\" | \"start\"",
+          "required": false,
+          "defaultValue": "start",
+          "description": "Alignment along that side. Defaults to `\"start\"`."
+        },
+        {
+          "name": "keepMounted",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Keep the popup mounted while closed."
+        },
+        {
+          "name": "positionerClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the positioner that places the popup."
+        },
+        {
+          "name": "sideOffset",
+          "type": "number | OffsetFunction",
+          "required": false,
+          "defaultValue": "4",
+          "description": "Gap in px between trigger and popup. Defaults to `4`."
+        },
+        {
+          "name": "side",
+          "type": "\"left\" | \"right\" | \"bottom\" | \"top\" | \"inline-end\" | \"inline-start\"",
+          "required": false,
+          "defaultValue": null,
+          "description": "Preferred side of the trigger. Defaults to `\"bottom\"`."
+        },
+        {
+          "name": "alignOffset",
+          "type": "number | OffsetFunction",
+          "required": false,
+          "defaultValue": null,
+          "description": "Nudge along the alignment axis, in px."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseMenu.Popup.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Group",
+      "usage": "DropdownMenu.Group",
+      "description": "A labelled block of rows. Give it a {@link DropdownMenuLabel} as its first child.",
+      "props": [],
+      "typeReferences": [
+        "BaseMenu.Group.Props"
+      ]
+    },
+    {
+      "name": "Label",
+      "usage": "DropdownMenu.Label",
+      "description": "The uppercase mono caption over a group. Names the group for assistive tech,\nso it belongs inside a {@link DropdownMenuGroup}, not loose in the popup.",
+      "props": [],
+      "typeReferences": [
+        "BaseMenu.GroupLabel.Props"
+      ]
+    },
+    {
+      "name": "Item",
+      "usage": "DropdownMenu.Item",
+      "description": "One command. Closes the menu on press unless `closeOnClick={false}`.\n\nHighlighted with `accent-soft` rather than a solid accent fill: at console\ndensity a solid bar under the pointer is far too loud (the luma defect\nruling), and the soft tint still passes contrast against the row text.",
+      "props": [
+        {
+          "name": "icon",
+          "type": "ElementType<any, keyof IntrinsicElements>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Optional leading icon component, sized to the density icon token."
+        },
+        {
+          "name": "trailing",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "Trailing slot — a `Kbd` shortcut hint, a count, a chevron."
+        }
+      ],
+      "typeReferences": [
+        "BaseMenu.Item.Props"
+      ]
+    },
+    {
+      "name": "CheckboxItem",
+      "usage": "DropdownMenu.CheckboxItem",
+      "description": "A row that toggles a setting. Stays open on press — toggling three view\noptions should not mean opening the menu three times.\n\nThe tick gutter is always reserved, so labels do not jog sideways as items\nare ticked.",
+      "props": [],
+      "typeReferences": [
+        "BaseMenu.CheckboxItem.Props"
+      ]
+    },
+    {
+      "name": "Separator",
+      "usage": "DropdownMenu.Separator",
+      "description": "The hairline between groups of rows.",
+      "props": [],
+      "typeReferences": [
+        "BaseMenu.Separator.Props"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A command list hung off a button.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<DropdownMenu.Root>\n  <DropdownMenu.Trigger render={<IconButton aria-label=\"Cue actions\" icon={MoreVertical} />} />\n  <DropdownMenu.Content align=\"end\">\n    <DropdownMenu.Group>\n      <DropdownMenu.Label>Playback</DropdownMenu.Label>\n      <DropdownMenu.Item onClick={go}>Go</DropdownMenu.Item>\n    </DropdownMenu.Group>\n    <DropdownMenu.Separator />\n    <DropdownMenu.CheckboxItem checked={follow} onCheckedChange={setFollow}>\n      Follow\n    </DropdownMenu.CheckboxItem>\n  </DropdownMenu.Content>\n</DropdownMenu.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/dropdown-menu",
+  "mdUrl": "/docs/components/dropdown-menu.md",
+  "jsonUrl": "/r/components/dropdown-menu.json",
+  "whenToUse": [
+    "Row actions, view options, an account menu: a list of things to do.",
+    "Toggling view state with `DropdownMenu.CheckboxItem`, which stays open so three toggles cost one trip."
+  ],
+  "whenNotToUse": [
+    "Choosing a value that a form will submit. Use `Select`.",
+    "Arbitrary content. A menu is a list of commands, not a layout container.",
+    "Right-click actions on a surface. Use `ContextMenu`."
+  ],
+  "commonMistakes": [
+    "Putting an input inside a menu item, where typeahead and roving focus fight the field for every keystroke.",
+    "Leaving a `DropdownMenu.Group` without a `DropdownMenu.Label`, which leaves the group unnamed for assistive tech."
+  ],
+  "specimens": [
+    {
+      "title": "DropdownMenu",
+      "group": "overlays",
+      "components": [
+        "DropdownMenu"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <DropdownMenu.Root>\n      <DropdownMenu.Trigger render={<IconButton aria-label=\"Cue actions\" icon={MoreVertical} />} />\n      <DropdownMenu.Content align=\"end\">\n        <DropdownMenu.Group>\n          <DropdownMenu.Label>Cue</DropdownMenu.Label>\n          <DropdownMenu.Item icon={Play} trailing={<Kbd>G</Kbd>}>\n            Go\n          </DropdownMenu.Item>\n          <DropdownMenu.Item icon={Copy} trailing={<Kbd>⌘D</Kbd>}>\n            Duplicate\n          </DropdownMenu.Item>\n        </DropdownMenu.Group>\n        <DropdownMenu.Separator />\n        <DropdownMenu.CheckboxItem checked={follow} onCheckedChange={setFollow}>\n          Follow\n        </DropdownMenu.CheckboxItem>\n        <DropdownMenu.Separator />\n        <DropdownMenu.Item icon={Trash2} disabled>\n          Delete\n        </DropdownMenu.Item>\n      </DropdownMenu.Content>\n    </DropdownMenu.Root>\n  </Specimen>\n  <Specimen label=\"from a density island\">\n    <Density density=\"ultra-compact\">\n      <DropdownMenu.Root>\n        <DropdownMenu.Trigger render={<Button>Ultra-compact</Button>} />\n        <DropdownMenu.Content>\n          <DropdownMenu.Item>The popup is ultra-compact too</DropdownMenu.Item>\n          <DropdownMenu.Item>Because the portal is stamped</DropdownMenu.Item>\n        </DropdownMenu.Content>\n      </DropdownMenu.Root>\n    </Density>\n  </Specimen>\n</Specimens>",
+      "note": "Groups, labels, icons, trailing shortcuts, checkbox items and separators, on the shared menu surface.",
+      "interaction": "closes on wheel as well as on scroll, so a menu opened over a pannable canvas cannot be left floating over nothing."
+    }
+  ]
+}

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