@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/voice-conversation.json

@@ -0,0 +1,109 @@
+{
+  "name": "VoiceConversation",
+  "slug": "voice-conversation",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A live call: the orb tracks your voice, the caption names the turn, the transcript\nfollows.",
+  "props": [
+    {
+      "name": "mode",
+      "type": "\"thinking\" | \"connecting\" | \"listening\" | \"speaking\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Drives the orb and the caption. Only listening and speaking react to amplitude."
+    },
+    {
+      "name": "amplitude",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current level from 0 to 1, clamped internally. Feed it from the analyser node."
+    },
+    {
+      "name": "transcript",
+      "type": "readonly VoiceTurn[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Turns so far, oldest first."
+    },
+    {
+      "name": "muted",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Marks the mic control as engaged and swaps the hint."
+    },
+    {
+      "name": "onToggleMute",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the mic is muted or unmuted."
+    },
+    {
+      "name": "onInterrupt",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the orb is pressed while the assistant is speaking. The orb is inert\nin every other mode, so the caption only offers the interrupt when one is\npossible."
+    },
+    {
+      "name": "onEnd",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the call is ended."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"mode\"\n  | \"amplitude\"\n  | \"transcript\"\n  | \"muted\"\n  | \"onToggleMute\"\n  | \"onInterrupt\"\n  | \"onEnd\"\n> & {\n  /** Drives the orb and the caption. Only listening and speaking react to amplitude. */\n  mode: VoiceMode;\n  /** Current level from 0 to 1, clamped internally. Feed it from the analyser node. */\n  amplitude: number;\n  /** Turns so far, oldest first. */\n  transcript: readonly VoiceTurn[];\n  /** Marks the mic control as engaged and swaps the hint. */\n  muted?: boolean;\n  /** Called when the mic is muted or unmuted. */\n  onToggleMute?: () => void;\n  /**\n   * Called when the orb is pressed while the assistant is speaking. The orb is inert\n   * in every other mode, so the caption only offers the interrupt when one is\n   * possible.\n   */\n  onInterrupt?: () => void;\n  /** Called when the call is ended. */\n  onEnd?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-danger-fg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "A live call: the orb tracks your voice, the caption names the turn, the transcript follows.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { VoiceConversation } from \"@cueplusplus/ui/elements\";\n\n<VoiceConversation\n  mode=\"listening\"\n  amplitude={0.6}\n  transcript={transcript}\n  onToggleMute={toggleMute}\n  onEnd={hangUp}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/voice-conversation",
+  "mdUrl": "/docs/components/voice-conversation.md",
+  "jsonUrl": "/r/components/voice-conversation.json",
+  "specimens": [
+    {
+      "title": "VoiceConversation",
+      "group": "elements-composer",
+      "components": [
+        "VoiceConversation"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"connecting\">\n    <VoiceConversation mode=\"connecting\" amplitude={0} transcript={[]} />\n  </Specimen>\n  <Specimen label=\"listening\">\n    <VoiceConversation\n      mode=\"listening\"\n      amplitude={0.72}\n      transcript={VOICE.slice(0, 1)}\n      onToggleMute={() => undefined}\n      onEnd={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"thinking\">\n    <VoiceConversation mode=\"thinking\" amplitude={0} transcript={VOICE.slice(0, 1)} />\n  </Specimen>\n  <Specimen label=\"speaking, interruptible\">\n    <VoiceConversation\n      mode=\"speaking\"\n      amplitude={0.44}\n      transcript={VOICE}\n      onInterrupt={() => undefined}\n      onToggleMute={() => undefined}\n      onEnd={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"muted\">\n    <VoiceConversation\n      mode=\"listening\"\n      amplitude={0}\n      transcript={VOICE}\n      muted\n      onToggleMute={() => undefined}\n      onEnd={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "A live call as a surface of its own: the orb tracks your voice, the caption names the turn, and the transcript follows underneath. Only `listening` and `speaking` react to amplitude — a connecting or thinking orb pulses on its own, because pretending to track a level nobody is producing is a lie the eye catches. The transcript keeps a minimum height so the card does not grow as the call goes on.",
+      "interaction": "the orb is only pressable while the assistant is speaking, and the hint under the caption says so (`Tap to interrupt`) — an inert orb offers nothing rather than looking pressable and doing nothing."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/web-preview.json

@@ -0,0 +1,87 @@
+{
+  "name": "WebPreview",
+  "slug": "web-preview",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Chrome around a preview: a URL bar, reload, and open-in-new. It renders\n`children` as given and enforces no isolation of its own, so the caller is\nresponsible for passing an already-sandboxed frame.",
+  "props": [
+    {
+      "name": "origin",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Host the content is served from. Show the sandbox origin, not your own, so the\nisolation is legible. Displaying it does not create the isolation; the frame you\npass as children must already be sandboxed."
+    },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Fades the frame out and shimmers a status while the sandbox is being set up."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The frame itself. In production this is a sandboxed iframe, not inline markup."
+    },
+    {
+      "name": "onReload",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the reload control."
+    },
+    {
+      "name": "onOpenExternal",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the open-in-new-tab control."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"origin\" | \"loading\" | \"children\" | \"onReload\" | \"onOpenExternal\"\n> & {\n  /**\n   * Host the content is served from. Show the sandbox origin, not your own, so the\n   * isolation is legible. Displaying it does not create the isolation; the frame you\n   * pass as children must already be sandboxed.\n   */\n  origin: string;\n  /** Fades the frame out and shimmers a status while the sandbox is being set up. */\n  loading: boolean;\n  /** The frame itself. In production this is a sandboxed iframe, not inline markup. */\n  children: React.ReactNode;\n  /** Called from the reload control. */\n  onReload?: () => void;\n  /** Called from the open-in-new-tab control. */\n  onOpenExternal?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-text-ui"
+  ],
+  "summary": "Chrome around a preview: a URL bar, reload, and open-in-new.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { WebPreview } from \"@cueplusplus/ui/elements\";\n\n<WebPreview origin=\"scf.auiusercontent.com\" loading={false} onReload={reload}>\n  <iframe title=\"Preview\" src={sandboxUrl} sandbox=\"allow-scripts\" />\n</WebPreview>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/web-preview",
+  "mdUrl": "/docs/components/web-preview.md",
+  "jsonUrl": "/r/components/web-preview.json",
+  "specimens": [
+    {
+      "title": "WebPreview",
+      "group": "elements-knowledge",
+      "components": [
+        "WebPreview"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"loaded\" wide>\n    <WebPreview\n      origin=\"robe.cz/esprite\"\n      loading={previewLoading}\n      onReload={() => setPreviewLoading((current) => !current)}\n      onOpenExternal={() => undefined}\n    >\n      <div className=\"flex flex-col gap-2 p-4\">\n        <p className=\"text-(length:--cue-text-emphasis) font-medium\">ESPRITE</p>\n        <p className=\"text-fg-muted text-(length:--cue-text-ui) leading-relaxed\">\n          1000 W LED profile, 6.5–50° zoom, framing shutters, 22,300 lm.\n        </p>\n      </div>\n    </WebPreview>\n  </Specimen>\n  <Specimen label=\"loading\" wide>\n    <WebPreview origin=\"etcconnect.com/source-four-led\" loading>\n      <div className=\"p-4\">Source Four LED Series 3</div>\n    </WebPreview>\n  </Specimen>\n</Specimens>",
+      "note": "Chrome around a page the agent opened: origin, reload, open-in-new. It renders whatever you hand it and isolates nothing of its own — an `iframe` here has to arrive already sandboxed, and that is the caller's job, not the element's.",
+      "interaction": "reload and open-in-new are named buttons; while `loading` the reload glyph spins, the frame is hidden from assistive tech, and a shimmering label sits in its place."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/web-search.json

@@ -0,0 +1,92 @@
+{
+  "name": "WebSearch",
+  "slug": "web-search",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A search query and its results landing one by one as the agent reads.",
+  "props": [
+    {
+      "name": "query",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Search query shown in the query pill."
+    },
+    {
+      "name": "results",
+      "type": "readonly WebSearchResult[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Result cards available to reveal one by one."
+    },
+    {
+      "name": "visibleResults",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many results from the start are currently shown."
+    },
+    {
+      "name": "searching",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true a shimmering Searching label replaces the result count."
+    },
+    {
+      "name": "cycle",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Identity key that remounts the list so entrance animation can replay."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"query\" | \"results\" | \"visibleResults\" | \"searching\" | \"cycle\"\n> & {\n  /** Search query shown in the query pill. */\n  query: string;\n  /** Result cards available to reveal one by one. */\n  results: readonly WebSearchResult[];\n  /** How many results from the start are currently shown. */\n  visibleResults: number;\n  /** When true a shimmering Searching label replaces the result count. */\n  searching: boolean;\n  /** Identity key that remounts the list so entrance animation can replay. */\n  cycle: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "A search query and its results landing one by one as the agent reads.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { WebSearch } from \"@cueplusplus/ui/elements\";\n\n<WebSearch\n  query=\"assistant-ui composer\"\n  results={[{ title: \"Composer guide\", domain: \"docs.example.com\" }]}\n  visibleResults={1}\n  searching={false}\n  cycle={0}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/web-search",
+  "mdUrl": "/docs/components/web-search.md",
+  "jsonUrl": "/r/components/web-search.json",
+  "specimens": [
+    {
+      "title": "WebSearch",
+      "group": "elements-knowledge",
+      "components": [
+        "WebSearch"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"searching\" wide>\n    <WebSearch\n      query=\"LED profile 8m throw front wash\"\n      results={RESULTS}\n      visibleResults={1}\n      searching\n      cycle={0}\n    />\n  </Specimen>\n  <Specimen label=\"read\" wide>\n    <WebSearch\n      query=\"LED profile 8m throw front wash\"\n      results={RESULTS}\n      visibleResults={RESULTS.length}\n      searching={false}\n      cycle={1}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The query as a pill, then the pages landing under it one at a time as they are read. It is the counterpart to `RetrievalChunks`: the same shape of answer, from outside rather than from the corpus, and the same rule that the caller advances the count.",
+      "interaction": "none. `cycle` keys the rows, so a new search re-runs the entrance instead of mutating three lines in place."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/work-collapse.json

@@ -0,0 +1,102 @@
+{
+  "name": "WorkCollapse",
+  "slug": "work-collapse",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A finished run, folded into one row: `Worked for 4m 12s and made 14 tool calls`.\n\nThe counterpart to {@link TailStatus }. That one says what is happening while\nit happens; this one is what fourteen rows of it become once nobody needs\nthem — and it is the element that makes a long transcript readable at a\nglance without hiding anything, because the rows are still there, one click\naway, in their original order.\n\nThe expanded body deliberately draws no rail, no indent and no border. That\nis Cline's decision and its reasoning is worth keeping: the rows inside a\nwork group are tool disclosures and reasoning panels that already carry their\nown nesting when *they* open, and a second level of indent around them makes\na transcript that steps rightwards every time it explains itself. So an open\n`WorkCollapse` looks exactly like the transcript would have looked, plus one\nsummary line above it.\n\nOpen state is a prop, like everything else here: a scripted replay of this\ncomponent is a caller changing `open`, and a component that owned the\ndisclosure could not be replayed at all.",
+  "props": [
+    {
+      "name": "durationMs",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "How long the run took, in milliseconds. Omit when it is not known."
+    },
+    {
+      "name": "toolCalls",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "How many tool calls it made. Omit when it is not counted."
+    },
+    {
+      "name": "running",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Whether the run is still going: the label goes present tense and the sweep\nruns. Hermes's rule, and the one that keeps a collapsed live run from\nclaiming to be finished."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The whole summary line, replacing the one {@link formatWorkLabel} would\nbuild. This is where a category summary goes — \"Explored 3 files, ran 5\ncommands\", composed from `VERB_TRIADS` — which is a sentence no formatter\nover a duration and a count could produce."
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the rows are showing."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the row is expanded or collapsed."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The rows the run folded away: tool calls, reasoning, whatever ran."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"onToggle\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-surface-1",
+    "--cue-text-ui"
+  ],
+  "summary": "A finished run, folded into one row: `Worked for 4m 12s and made 14 tool calls`.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { WorkCollapse } from \"@cueplusplus/ui/elements\";\n\n<WorkCollapse durationMs={252_000} toolCalls={14} open={open} onOpenChange={setOpen}>\n  {rows}\n</WorkCollapse>\n// Live, in the present tense, with the label composed from the verb table.\n<WorkCollapse running toolCalls={5} label=\"Exploring 3 files, running 5 commands\" open={false} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/work-collapse",
+  "mdUrl": "/docs/components/work-collapse.md",
+  "jsonUrl": "/r/components/work-collapse.json",
+  "specimens": [
+    {
+      "title": "WorkCollapse",
+      "group": "elements-thread",
+      "components": [
+        "WorkCollapse"
+      ],
+      "code": "<Specimens>\n  <Specimen label={workOpen ? \"open, at transcript level\" : \"folded\"} wide>\n    <div className=\"w-full max-w-md\">\n      <WorkCollapse\n        durationMs={252_000}\n        toolCalls={14}\n        open={workOpen}\n        onOpenChange={setWorkOpen}\n      >\n        {FOLDED_CALLS.map((call) => (\n          <ToolCall\n            key={call.id}\n            {...call}\n            open={foldedCall === call.id}\n            onOpenChange={(next) => setFoldedCall(next ? call.id : null)}\n          />\n        ))}\n      </WorkCollapse>\n    </div>\n  </Specimen>\n  <Specimen label=\"still running\" wide>\n    <div className=\"w-full max-w-md\">\n      <WorkCollapse running durationMs={41_000} toolCalls={5} open={false} />\n    </div>\n  </Specimen>\n  <Specimen label=\"a composed category summary\" wide>\n    <div className=\"w-full max-w-md\">\n      <WorkCollapse\n        running\n        label=\"Exploring 3 files, running 5 commands\"\n        open={false}\n      />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "Fourteen rows of work, folded into the one sentence a reader wants: Worked for 4m 12s and made 14 tool calls. It is the counterpart to TailStatus — that one narrates while it happens, this one is what the narration becomes once nobody needs it — and the open body deliberately draws no rail and no indent, because the rows inside already nest themselves when they open. formatWorkLabel has an answer for every combination including the empty one, since a trigger labelled undefined is a row nobody can decide whether to open.",
+      "interaction": "the summary line is the whole trigger and carries aria-expanded. Open it and the calls come back at transcript level, each still its own disclosure; a live run keeps the present tense and sweeps the label instead."
+    }
+  ],
+  "todo": true
+}