@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/chart-ramp.json

@@ -0,0 +1,72 @@
+{
+  "name": "ChartRamp",
+  "slug": "chart-ramp",
+  "group": "charts",
+  "importPath": "@cueplusplus/ui/charts",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A ramp drawn as a strip: equal cells, no gaps, in order.\n\nEqual cells rather than a CSS gradient, because a ramp *is* discrete — a\ngradient would show steps the data cannot address, and would quietly disagree\nwith the same ramp used to fill bars. No seams either, for the same reason the\ncells are equal: a seam reads as a category boundary, and a sequential scale\nhas none.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "colors",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The ramp, in order. Any CSS colours."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the ramp encodes. Required: it is the strip's accessible name."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "8",
+      "description": "Strip height in px at the 16px root, emitted as `rem`. Defaults to `8`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-text-label"
+  ],
+  "summary": "A ramp drawn as a strip: equal cells, no gaps, in order.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ChartRamp label=\"Density\" colors={accentRamp()} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/chart-ramp",
+  "mdUrl": "/docs/components/chart-ramp.md",
+  "jsonUrl": "/r/components/chart-ramp.json",
+  "specimens": [
+    {
+      "title": "RAMPS / accentRamp()",
+      "group": "charts",
+      "components": [
+        "ChartRamp"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  {RAMP_NAMES.map((name) => (\n    <ChartRamp\n      key={name}\n      label={name}\n      colors={RAMPS[name].map((band) => band.color)}\n    />\n  ))}\n  {ramp.length === 0 ? null : <ChartRamp label=\"accent, 9 steps\" colors={ramp} />}\n</div>",
+      "note": "Ordered scales rather than categorical ones: four ported frequency ramps that never re-hue (a listener who has learnt `bass is red` must not relearn it), and one sequential ramp derived from the live accent.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/chart-swatch.json

@@ -0,0 +1,65 @@
+{
+  "name": "ChartSwatch",
+  "slug": "chart-swatch",
+  "group": "charts",
+  "importPath": "@cueplusplus/ui/charts",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "One colour and what it means: the atom a chart legend is built from.\n\nThe chip is `aria-hidden` and the label is plain text, so the meaning survives\nwithout colour vision (WCAG 1.4.1). A swatch with no label is decoration and\nannounces nothing at all, which is the honest reading of a colour with no\ncaption.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "color",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The colour to show. Any CSS colour, including a `var()` reference."
+    },
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the colour stands for. Omit for a bare chip."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"span\">, \"children\" | \"color\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-text-label"
+  ],
+  "summary": "One colour and what it means: the atom a chart legend is built from.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "{BANDS_7.map((band) => <ChartSwatch key={band.id} color={band.color} label={band.label} />)}",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/chart-swatch",
+  "mdUrl": "/docs/components/chart-swatch.md",
+  "jsonUrl": "/r/components/chart-swatch.json",
+  "specimens": [
+    {
+      "title": "chartTones() / ChartSwatch",
+      "group": "charts",
+      "components": [
+        "ChartSwatch"
+      ],
+      "code": "<Panel className=\"flex w-full flex-wrap gap-(--cue-space-4) p-(--cue-space-4)\">\n  {CHART_TONE_TOKENS.map((token, index) => (\n    <ChartSwatch key={token} color={chartToneVar(index)} label={token} />\n  ))}\n  {Array.from({ length: 9 }, (_, index) => (\n    <ChartSwatch\n      key={`extended-${index}`}\n      color={chartToneVar(CHART_TONE_TOKENS.length + index)}\n      label={`hue ${index + 1}`}\n    />\n  ))}\n</Panel>",
+      "note": "The categorical palette: the theme's six status colours first, then nine generated oklch hues at fixed lightness and chroma for when six run out. Resolved at render, so switching theme reharmonises every chart on the page without a subscription.",
+      "interaction": "none. A swatch is a readout."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/chart-tooltip-content.json

@@ -0,0 +1,114 @@
+{
+  "name": "ChartTooltipContent",
+  "slug": "chart-tooltip-content",
+  "group": "charts",
+  "importPath": "@cueplusplus/ui/charts",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The tooltip surface: an overlay, styled like every other overlay.\n\nA chart tooltip *is* a floating surface, so it gets exactly what a Popover\ngets — `surface-2` fill, the overlay rim, one soft shadow — from\n`_surface.ts` rather than from a second, chart-only recipe that would drift.\nWhat it adds is the reading discipline the rest of the system uses for\nnumbers: mono, tabular figures, values right-aligned so a column of them lines\nup under the pointer.\n\nReturns `null` when the pointer is off the plot or the payload is empty,\nbecause recharts keeps the content mounted between hovers.\n\n`formatter` and `labelFormatter` may equally be set on the `<Tooltip>` itself:\nrecharts forwards its own configuration into cloned content, so both spellings\nland here. Everything else in that configuration is dropped rather than\nrendered — see {@link domProps} — which also means a handler passed to this\ncomponent does not reach the surface. Nothing would fire on it anyway: the\ntooltip is drawn under the pointer, not in its path.",
+  "props": [
+    {
+      "name": "active",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Whether the pointer is on the plot. Recharts supplies this."
+    },
+    {
+      "name": "payload",
+      "type": "readonly ChartTooltipEntry[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "One entry per series at the hovered index. Recharts supplies this."
+    },
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The hovered category — the x value. Recharts supplies this."
+    },
+    {
+      "name": "hideLabel",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Drop the label line, for a chart whose x axis needs no restating."
+    },
+    {
+      "name": "hideIndicator",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Drop the per-row colour chips, for a single-series chart."
+    },
+    {
+      "name": "labelFormatter",
+      "type": "((label: ReactNode, payload: readonly ChartTooltipEntry[]) => ReactNode)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Format the label line."
+    },
+    {
+      "name": "formatter",
+      "type": "((value: string | number | readonly (string | number)[], name: ReactNode, entry: ChartTooltipEntry, index: number) => ReactNode)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Format one row's value. Return the unit too if you want to own it."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"content\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--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": "The tooltip surface: an overlay, styled like every other overlay.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Tooltip cursor={chartTooltipCursor} content={<ChartTooltipContent />} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/chart-tooltip-content",
+  "mdUrl": "/docs/components/chart-tooltip-content.md",
+  "jsonUrl": "/r/components/chart-tooltip-content.json",
+  "specimens": [
+    {
+      "title": "ChartTooltipContent",
+      "group": "charts",
+      "components": [
+        "ChartTooltipContent"
+      ],
+      "code": "<div className=\"w-fit\">\n  <ChartTooltipContent\n    active\n    label=\"19:30\"\n    payload={[\n      { name: \"output\", value: 68, color: \"var(--cue-accent)\", unit: \"%\" },\n      { name: \"dropped\", value: 3, color: \"var(--cue-danger)\", unit: \"%\" },\n    ]}\n  />\n</div>",
+      "note": "The tooltip surface on its own, so a chart drawn from raw recharts parts can still wear it. Shown here mounted rather than hovered.",
+      "interaction": "in a chart it is positioned by recharts; the styling is the same either way."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/chart.json

@@ -0,0 +1,93 @@
+{
+  "name": "Chart",
+  "slug": "chart",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Area, line, and bars, with points landing one at a time as the series streams in.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the series measures."
+    },
+    {
+      "name": "value",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The headline figure, pre-formatted. The chart never formats numbers itself."
+    },
+    {
+      "name": "delta",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Change against the previous window. Renders green unless it starts with a minus sign."
+    },
+    {
+      "name": "points",
+      "type": "readonly number[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The full series. The scale is computed from all of it, so the axis does not jump\nwhile streaming."
+    },
+    {
+      "name": "visibleCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many points have arrived."
+    },
+    {
+      "name": "variant",
+      "type": "\"area\" | \"line\" | \"bars\"",
+      "required": false,
+      "defaultValue": "area",
+      "description": "Mark type. The last point stays emphasized in all three."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"label\"\n  | \"value\"\n  | \"delta\"\n  | \"points\"\n  | \"visibleCount\"\n  | \"variant\"\n> & {\n  /** What the series measures. */\n  label: string;\n  /** The headline figure, pre-formatted. The chart never formats numbers itself. */\n  value: string;\n  /** Change against the previous window. Renders green unless it starts with a minus sign. */\n  delta?: string;\n  /**\n   * The full series. The scale is computed from all of it, so the axis does not jump\n   * while streaming.\n   */\n  points: readonly number[];\n  /** How many points have arrived. */\n  visibleCount: number;\n  /** Mark type. The last point stays emphasized in all three. */\n  variant?: ChartVariant;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-text-title"
+  ],
+  "summary": "Area, line, and bars, with points landing one at a time as the series streams in.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { Chart } from \"@cueplusplus/ui/elements\";\n\n<Chart\n  label=\"Runs this week\"\n  value=\"92\"\n  delta=\"+34%\"\n  points={points}\n  visibleCount={points.length}\n  variant=\"area\"\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/chart",
+  "mdUrl": "/docs/components/chart.md",
+  "jsonUrl": "/r/components/chart.json",
+  "specimens": [
+    {
+      "title": "Chart",
+      "group": "elements-knowledge",
+      "components": [
+        "Chart"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"area\" wide>\n    <Chart\n      label=\"FOH leg\"\n      value=\"29.1 A\"\n      delta=\"+18.1\"\n      points={LOAD}\n      visibleCount={LOAD.length}\n    />\n  </Specimen>\n  <Specimen label=\"line, still arriving\" wide>\n    <Chart label=\"FOH leg\" value=\"17.4 A\" points={LOAD} visibleCount={4} variant=\"line\" />\n  </Specimen>\n  <Specimen label=\"bars, falling\" wide>\n    <Chart\n      label=\"Headroom\"\n      value=\"2.9 A\"\n      delta=\"−8.1\"\n      points={[...LOAD].reverse()}\n      visibleCount={LOAD.length}\n      variant=\"bars\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "One series, three ways, on one scale: an area, a bare line, or bars with the newest one lit. It draws its own SVG at a fixed viewBox and stretches — there is no charting library under this, which is the point of it being an element rather than an instrument.",
+      "interaction": "none, and it is not a substitute for the charts group: no axes, no legend, no tooltip. The `<svg>` carries role='img' and a label built from the figure beside it."
+    }
+  ],
+  "todo": true
+}

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

@@ -0,0 +1,55 @@
+{
+  "name": "ChatEmptyState",
+  "slug": "chat-empty-state",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The first screen: a greeting, three ways in, and the composer front and center.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "The first screen: a greeting, three ways in, and the composer front and center.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import {\n  EmptyState,\n  EmptyStateComposer,\n  EmptyStateGreeting,\n  EmptyStateSuggestion,\n  EmptyStateSuggestions,\n} from \"@cueplusplus/ui/elements\";\n\n<EmptyState>\n  <EmptyStateGreeting>What are we building?</EmptyStateGreeting>\n  <EmptyStateSuggestions>\n    {items.map((item, i) => (\n      <EmptyStateSuggestion key={item} index={i} onClick={() => send(item)}>\n        {item}\n      </EmptyStateSuggestion>\n    ))}\n  </EmptyStateSuggestions>\n  <EmptyStateComposer placeholder=\"Ask anything\" onSend={send} />\n</EmptyState>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/chat-empty-state",
+  "mdUrl": "/docs/components/chat-empty-state.md",
+  "jsonUrl": "/r/components/chat-empty-state.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/chat-panel-assistant-message.json

@@ -0,0 +1,51 @@
+{
+  "name": "ChatPanelAssistantMessage",
+  "slug": "chat-panel-assistant-message",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "One message from the model: plain text on the leading edge, no bubble.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"p\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "One message from the model: plain text on the leading edge, no bubble.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/chat-panel-assistant-message",
+  "mdUrl": "/docs/components/chat-panel-assistant-message.md",
+  "jsonUrl": "/r/components/chat-panel-assistant-message.json",
+  "specimens": [
+    {
+      "title": "ChatPanel",
+      "group": "elements",
+      "components": [
+        "ChatPanel",
+        "ChatPanelMessages",
+        "ChatPanelUserMessage",
+        "ChatPanelAssistantMessage",
+        "ChatPanelTyping",
+        "ChatPanelComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"a turn\" wide>\n    <ChatPanel>\n      <ChatPanelMessages>\n        <ChatPanelUserMessage>\n          Patch the front truss on universe 3 and tell me what moved.\n        </ChatPanelUserMessage>\n        {replied ? (\n          <ChatPanelAssistantMessage>\n            6 fixtures on channels 1 to 48. Cue 1 holds at 3.0s.\n          </ChatPanelAssistantMessage>\n        ) : (\n          <ChatPanelTyping />\n        )}\n      </ChatPanelMessages>\n      <ChatPanelComposer\n        placeholder=\"Ask the rig\"\n        onSend={() => setReplied((was) => !was)}\n      />\n    </ChatPanel>\n  </Specimen>\n</Specimens>",
+      "note": "The six parts working together, which is what the whole family is for. The person's turn is a filled bubble on the trailing edge, the model's is plain text on the leading one, and the transcript is bottom-aligned so a short conversation sits on the composer rather than floating.",
+      "interaction": "the send control is the only live thing here; use it and the reply is replaced by the three-dot pause, then comes back."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/chat-panel-composer.json

@@ -0,0 +1,66 @@
+{
+  "name": "ChatPanelComposer",
+  "slug": "chat-panel-composer",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The panel's composer row. It is a display of a composer rather than a working one —\nthe placeholder is a string and the send button takes a handler.",
+  "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-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "The panel's composer row.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/chat-panel-composer",
+  "mdUrl": "/docs/components/chat-panel-composer.md",
+  "jsonUrl": "/r/components/chat-panel-composer.json",
+  "specimens": [
+    {
+      "title": "ChatPanel",
+      "group": "elements",
+      "components": [
+        "ChatPanel",
+        "ChatPanelMessages",
+        "ChatPanelUserMessage",
+        "ChatPanelAssistantMessage",
+        "ChatPanelTyping",
+        "ChatPanelComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"a turn\" wide>\n    <ChatPanel>\n      <ChatPanelMessages>\n        <ChatPanelUserMessage>\n          Patch the front truss on universe 3 and tell me what moved.\n        </ChatPanelUserMessage>\n        {replied ? (\n          <ChatPanelAssistantMessage>\n            6 fixtures on channels 1 to 48. Cue 1 holds at 3.0s.\n          </ChatPanelAssistantMessage>\n        ) : (\n          <ChatPanelTyping />\n        )}\n      </ChatPanelMessages>\n      <ChatPanelComposer\n        placeholder=\"Ask the rig\"\n        onSend={() => setReplied((was) => !was)}\n      />\n    </ChatPanel>\n  </Specimen>\n</Specimens>",
+      "note": "The six parts working together, which is what the whole family is for. The person's turn is a filled bubble on the trailing edge, the model's is plain text on the leading one, and the transcript is bottom-aligned so a short conversation sits on the composer rather than floating.",
+      "interaction": "the send control is the only live thing here; use it and the reply is replaced by the three-dot pause, then comes back."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/chat-panel-messages.json

@@ -0,0 +1,51 @@
+{
+  "name": "ChatPanelMessages",
+  "slug": "chat-panel-messages",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The scrolling transcript inside a `ChatPanel`. Bottom-aligned, so a short\nconversation sits on the composer rather than floating at the top of the panel.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "The scrolling transcript inside a `ChatPanel`.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/chat-panel-messages",
+  "mdUrl": "/docs/components/chat-panel-messages.md",
+  "jsonUrl": "/r/components/chat-panel-messages.json",
+  "specimens": [
+    {
+      "title": "ChatPanel",
+      "group": "elements",
+      "components": [
+        "ChatPanel",
+        "ChatPanelMessages",
+        "ChatPanelUserMessage",
+        "ChatPanelAssistantMessage",
+        "ChatPanelTyping",
+        "ChatPanelComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"a turn\" wide>\n    <ChatPanel>\n      <ChatPanelMessages>\n        <ChatPanelUserMessage>\n          Patch the front truss on universe 3 and tell me what moved.\n        </ChatPanelUserMessage>\n        {replied ? (\n          <ChatPanelAssistantMessage>\n            6 fixtures on channels 1 to 48. Cue 1 holds at 3.0s.\n          </ChatPanelAssistantMessage>\n        ) : (\n          <ChatPanelTyping />\n        )}\n      </ChatPanelMessages>\n      <ChatPanelComposer\n        placeholder=\"Ask the rig\"\n        onSend={() => setReplied((was) => !was)}\n      />\n    </ChatPanel>\n  </Specimen>\n</Specimens>",
+      "note": "The six parts working together, which is what the whole family is for. The person's turn is a filled bubble on the trailing edge, the model's is plain text on the leading one, and the transcript is bottom-aligned so a short conversation sits on the composer rather than floating.",
+      "interaction": "the send control is the only live thing here; use it and the reply is replaced by the three-dot pause, then comes back."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/chat-panel-typing.json

@@ -0,0 +1,51 @@
+{
+  "name": "ChatPanelTyping",
+  "slug": "chat-panel-typing",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The three-dot rest state, for the gap between sending and the first token.",
+  "props": [],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "The three-dot rest state, for the gap between sending and the first token.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/chat-panel-typing",
+  "mdUrl": "/docs/components/chat-panel-typing.md",
+  "jsonUrl": "/r/components/chat-panel-typing.json",
+  "specimens": [
+    {
+      "title": "ChatPanel",
+      "group": "elements",
+      "components": [
+        "ChatPanel",
+        "ChatPanelMessages",
+        "ChatPanelUserMessage",
+        "ChatPanelAssistantMessage",
+        "ChatPanelTyping",
+        "ChatPanelComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"a turn\" wide>\n    <ChatPanel>\n      <ChatPanelMessages>\n        <ChatPanelUserMessage>\n          Patch the front truss on universe 3 and tell me what moved.\n        </ChatPanelUserMessage>\n        {replied ? (\n          <ChatPanelAssistantMessage>\n            6 fixtures on channels 1 to 48. Cue 1 holds at 3.0s.\n          </ChatPanelAssistantMessage>\n        ) : (\n          <ChatPanelTyping />\n        )}\n      </ChatPanelMessages>\n      <ChatPanelComposer\n        placeholder=\"Ask the rig\"\n        onSend={() => setReplied((was) => !was)}\n      />\n    </ChatPanel>\n  </Specimen>\n</Specimens>",
+      "note": "The six parts working together, which is what the whole family is for. The person's turn is a filled bubble on the trailing edge, the model's is plain text on the leading one, and the transcript is bottom-aligned so a short conversation sits on the composer rather than floating.",
+      "interaction": "the send control is the only live thing here; use it and the reply is replaced by the three-dot pause, then comes back."
+    }
+  ],
+  "todo": true
+}