@cueplusplus/ui 0.10.0 → 0.11.1

package/manifest/components/password-input.json

@@ -17,6 +17,16 @@
         "kind": "string"
       }
     },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the input, when no `FieldLabel` names it. Declared here\nrather than left to the inherited attribute so the props table carries the\nrow: a bare input outside a `Field` has no other way to be named.",
+      "control": {
+        "kind": "string"
+      }
+    },
     {
       "name": "size",
       "type": "\"sm\" | \"md\" | \"lg\"",
@@ -42,6 +52,16 @@
         "kind": "string"
       }
     },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "An example of what goes in the field, shown while it is empty. Not a name:\nit disappears on the first keystroke, so pair it with `aria-label` or a\n`FieldLabel`. Declared for the props-table row, as `aria-label` is above.",
+      "control": {
+        "kind": "string"
+      }
+    },
     {
       "name": "revealed",
       "type": "boolean",

package/manifest/components/preview.json

@@ -0,0 +1,202 @@
+{
+  "name": "Preview",
+  "slug": "preview",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A frame for one component: a stage that is its own theme island, a slot for\ntools at the top right, and a footer.\n\n**The stage is the island; the chrome is not.** `theme`, `mode`, `density`\nand `font` land on the stage element only, and the stage republishes the\ntheme and density contexts so an overlay opened on it follows it. The tools,\nthe footer, the grips and anything they open stay in the scope around the\nPreview — a `terminal` preview's own controls do not turn cyan. With none of\nthe four set, the stage carries no attribute and costs what a `<div>` costs.\nA stage `theme` with no `mode` repeats the page's mode beside it.\n\n**`resizable` is handles of its own**, both axes by default: an edge grip per\naxis that is a keyboard-operable `separator` valued in pixels, and a corner\ngrip for the pointer. Double-click resets an axis. The width never outgrows\nthe frame: its bound in force is the frame's own width, observed live, when\nthat is under `maxWidth`. Not `Resizable`, which is split panes on an\noptional peer.\n\nProps, not a compound: one stage and two slots, each saying what it is.",
+  "props": [
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The specimen. It renders on the stage, inside whatever scope the stage sets.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The frame's accessible name — \"Button preview\". Required: a frame that holds\ncontrols and has no name is a group nobody can find.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "theme",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "A theme for the stage only. Unset, the stage inherits — no attribute is\nemitted at all. **Naming a theme does not load it**: the stage is scoped to\n`[data-theme=\"<name>\"]`, and that theme's stylesheet must already be on the\npage (`@cueplusplus/theme-<name>/theme.css`). The tools, the footer and\nanything they open stay in the page's theme. With no `mode`, the stage\nrepeats the page's mode beside the theme — `\"system\"` included — so a light\npage's stage paints the theme's light block, not its dark one, and agrees\nwith every overlay opened on it.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "mode",
+      "type": "\"system\" | \"dark\" | \"light\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Dark, light or system, for the stage only. A theme's light block is the\ncompound selector `[data-theme][data-mode]`, so with no `theme` the stage\nrestates the page's theme beside the mode; outside any `ThemeProvider` there\nis no theme to restate and the mode alone changes nothing. A stage\n`\"system\"` is stamped as it is, so the stylesheet's `[data-mode=\"system\"]`\nblock follows the OS; `useTheme().resolvedMode` read on the stage reports\nthe page's resolved mode.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "system",
+          "dark",
+          "light"
+        ]
+      }
+    },
+    {
+      "name": "density",
+      "type": "\"normal\" | \"large\" | \"compact\" | \"ultra-compact\" | \"ultra-large\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "A rung of the density ladder for the stage only, as a `<Density>` island would set it.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "normal",
+          "large",
+          "compact",
+          "ultra-compact",
+          "ultra-large"
+        ]
+      }
+    },
+    {
+      "name": "font",
+      "type": "\"source\" | \"system\" | \"geist\" | \"inter\" | \"plex\" | \"roboto\" | \"apple\" | \"office\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "A font pairing for the stage only, as `data-font`. Portals still follow the root's pairing.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "source",
+          "system",
+          "geist",
+          "inter",
+          "plex",
+          "roboto",
+          "apple",
+          "office"
+        ]
+      }
+    },
+    {
+      "name": "resizable",
+      "type": "boolean | PreviewResizeOptions",
+      "required": false,
+      "defaultValue": null,
+      "description": "Resize the stage by dragging or with the keyboard. `true` gives both axes\ninside the default bounds (160–1280 px wide, 96–960 px tall); an object\nnarrows the axis or moves the bounds. The width never outgrows the frame:\nits bound in force is the smaller of `maxWidth` and the frame's own width,\nobserved with a `ResizeObserver`, so a Preview in a grid track stays inside\nit as the viewport changes. The height is bounded by `maxHeight` alone, and\na taller stage grows its frame. Unset, the stage is fixed: no grips, and\nnothing measured or observed.\n\nA resizable frame fills its container's width (`w-full`), because the room\nit measures has to be its container's. In a flex row or a centred column a\nframe sized by its content would measure its own stage, and a stage bounded\nby itself can only shrink, with each step lowering the ceiling. A fixed\nPreview keeps sizing to its content; `className` can still set a width.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "tools",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The top-right slot — by convention a row of `IconButton`s. Drawn outside the stage.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "footer",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The strip under the stage: the thin text and the way out. Drawn outside the stage.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-hair-strong",
+    "--cue-radius-control",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-space-6",
+    "--cue-space-8",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-label"
+  ],
+  "summary": "A frame for one component: a stage that is its own theme island, tools at the top right, a footer, and grips that resize it on both axes.",
+  "examples": [
+    {
+      "title": "Inheriting the page, resizable",
+      "code": "<Preview label=\"Button preview\" resizable footer={<span>Button</span>}>\n  <Button variant=\"primary\">Take cue</Button>\n</Preview>",
+      "language": "tsx"
+    },
+    {
+      "title": "Its own theme and density",
+      "code": "<Preview label=\"Chip preview\" theme=\"terminal\" density=\"compact\">\n  <Chip tone=\"accent\">Standby</Chip>\n</Preview>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Preview label=\"Button preview\" tools={<IconButton aria-label=\"Configure Button\" icon={Wrench} />}>\n  <Button variant=\"primary\">Take cue</Button>\n</Preview>\n<Preview label=\"Chip preview\" theme=\"terminal\" density=\"compact\" resizable>\n  <Chip tone=\"accent\">Standby</Chip>\n</Preview>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/preview",
+  "mdUrl": "/docs/components/preview.md",
+  "jsonUrl": "/r/components/preview.json",
+  "whenToUse": [
+    "Showing one component in a state a reader can see and change — a gallery tile, a docs listing, a design review page.",
+    "Putting a component in a different theme, mode, density or font from the page around it, without re-theming the controls that change it.",
+    "Letting a reader watch a component respond to its container: pass `resizable` and drag it narrow, or short."
+  ],
+  "whenNotToUse": [
+    "Laying several components out side by side. That is `Bento` or `Grid`; a Preview holds one specimen.",
+    "Split panes a user resizes as part of an app. That is `Resizable`; a Preview's grips resize a stage, not a layout."
+  ],
+  "commonMistakes": [
+    "Naming a `theme` whose stylesheet is not on the page. The stage is scoped to `[data-theme]`, and a Preview loads no CSS — import `@cueplusplus/theme-<name>/theme.css` yourself, or the stage paints the blank base.",
+    "Setting `mode` outside any `ThemeProvider` and expecting a change. A theme's light block needs the theme on the same element, and with no provider there is no theme to restate.",
+    "Putting the controls that configure the specimen in `children`. They would take the stage's theme; put them in `tools`, which follows the page."
+  ],
+  "specimens": [
+    {
+      "title": "Preview",
+      "group": "layout",
+      "components": [
+        "Preview"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"inherits the page, resizable\" wide>\n    <Preview\n      label=\"Button preview\"\n      resizable\n      footer={<span className=\"font-mono text-(length:--cue-text-label) text-fg-subtle\">Button · inherits</span>}\n    >\n      <Button variant=\"primary\">Take cue</Button>\n    </Preview>\n  </Specimen>\n  <Specimen label=\"its own theme and density\" wide>\n    <Preview\n      label=\"Chip preview\"\n      theme=\"terminal\"\n      density=\"compact\"\n      footer={<span className=\"font-mono text-(length:--cue-text-label) text-fg-subtle\">Chip · terminal · compact</span>}\n    >\n      <Chip tone=\"accent\">Standby</Chip>\n    </Preview>\n  </Specimen>\n</Specimens>",
+      "note": "A frame for one component. The stage is its own theme island — theme, mode, density and font land on it and nowhere else — while the tools, the footer and anything they open follow the page.",
+      "interaction": "with `resizable`, the width and height grips are separators: Left and Right step the width, Up and Down the height, 8 px a press and 64 with Shift; Home and End reach the bounds, and a double-click resets an axis. The corner grip is a pointer convenience over the two."
+    }
+  ]
+}

package/manifest/components/prompt-library.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "Everything saved. Filtering happens inside against the name.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "composer.prompts"
       }
     },
     {

package/manifest/components/queue-dock.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "The turns waiting to send, in the order they will drain. Ordering is the\ncaller's: Cursor lets a person drag one up the list, and a component that\nsorted the array it was given could not be dragged.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "agents.follow-ups"
       }
     },
     {

package/manifest/components/quote-reply.json

@@ -46,7 +46,8 @@
       "defaultValue": null,
       "description": "What the toolbar offers. Each action names one of the three built-in icons.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.quote-actions"
       }
     },
     {

package/manifest/components/reasoning-effort.json

@@ -14,7 +14,8 @@
       "defaultValue": null,
       "description": "Every tier on offer, each carrying its own token budget.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.effort-levels"
       }
     },
     {

package/manifest/components/reasoning-panel.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "Full list of reasoning steps available to reveal.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.reasoning"
       }
     },
     {

package/manifest/components/regenerate-menu.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "What the turn can be re-run with.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.regenerate-models"
       }
     },
     {

package/manifest/components/research-report.json

@@ -26,7 +26,8 @@
       "defaultValue": null,
       "description": "The outline. It exists from the start and fills in, so the shape is legible before\nthe prose lands.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "knowledge.report"
       }
     },
     {

package/manifest/components/retrieval-chunks.json

@@ -26,7 +26,8 @@
       "defaultValue": null,
       "description": "Passages returned above the threshold, already sorted by score.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "knowledge.chunks"
       }
     },
     {

package/manifest/components/reviewable-diff.json

@@ -26,7 +26,8 @@
       "defaultValue": null,
       "description": "Each hunk carries its own decision. Apply stays disabled until none are pending.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "agent.diff-hunks"
       }
     },
     {

package/manifest/components/schedule-card.json

@@ -56,7 +56,8 @@
       "defaultValue": null,
       "description": "Recent runs, so a silently failing schedule is visible.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "knowledge.runs"
       }
     },
     {

package/manifest/components/score-breakdown.json

@@ -44,7 +44,8 @@
       "defaultValue": null,
       "description": "What produced the number, so the verdict can be argued with.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "knowledge.criteria"
       }
     },
     {

package/manifest/components/scroll-anchor.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "Conversation messages appended over time inside the scroll viewport.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.arriving"
       }
     },
     {

package/manifest/components/search-input.json

@@ -27,6 +27,16 @@
         "kind": "string"
       }
     },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the input, when no `FieldLabel` names it. Declared here\nrather than left to the inherited attribute so the props table carries the\nrow: a bare input outside a `Field` has no other way to be named.",
+      "control": {
+        "kind": "string"
+      }
+    },
     {
       "name": "size",
       "type": "\"sm\" | \"md\" | \"lg\"",
@@ -62,6 +72,16 @@
         "kind": "string"
       }
     },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "An example of what goes in the field, shown while it is empty. Not a name:\nit disappears on the first keystroke, so pair it with `aria-label` or a\n`FieldLabel`. Declared for the props-table row, as `aria-label` is above.",
+      "control": {
+        "kind": "string"
+      }
+    },
     {
       "name": "onValueChange",
       "type": "((value: string) => void)",

package/manifest/components/segmented-control.json

@@ -104,7 +104,8 @@
       "defaultValue": null,
       "description": "The segments, in display order.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "chrome.console-modes"
       }
     },
     {

package/manifest/components/settings-panel.json

@@ -55,7 +55,8 @@
       "defaultValue": null,
       "description": "Capability switches with a line each explaining what they turn on.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "composer.toggles"
       }
     },
     {

package/manifest/components/shared-conversation.json

@@ -46,7 +46,8 @@
       "defaultValue": null,
       "description": "The transcript, read only.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "composer.shared"
       }
     },
     {

package/manifest/components/sources.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "Citation cards revealed when the sources pill expands.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "knowledge.sources"
       }
     },
     {

package/manifest/components/speaker-identity.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "Turns in order, each naming who produced it.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "composer.speakers"
       }
     }
   ],

package/manifest/components/spec-sheet.json

@@ -34,7 +34,8 @@
       "defaultValue": null,
       "description": "Label and value pairs. Values are pre-formatted and right-aligned on tabular figures.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "knowledge.spec-rows"
       }
     },
     {

package/manifest/components/spectrum-visualizer.json

@@ -14,7 +14,8 @@
       "defaultValue": null,
       "description": "One level per band, `0`–`1`, in the ramp's own order.\n\nPositional rather than keyed by band id: an FFT hands back an array forty\ntimes a second, and building a lookup per frame to match it up is work for\nno information.",
       "control": {
-        "kind": "opaque"
+        "kind": "opaque",
+        "fixture": "midi.seven-band"
       }
     },
     {

package/manifest/components/stepper.json

@@ -14,7 +14,8 @@
       "defaultValue": null,
       "description": "The steps, in order.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "layout.patch-steps"
       }
     },
     {

package/manifest/components/streaming-text.json

@@ -14,7 +14,8 @@
       "defaultValue": null,
       "description": "Text chunks to stream, optionally marked mono for inline code chips.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.answer"
       }
     },
     {

package/manifest/components/sub.json

@@ -35,7 +35,7 @@
         "Sub",
         "Sup"
       ],
-      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={MATH.length} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
+      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={3} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
       "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
       "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
     }

package/manifest/components/subagent-list.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "Parallel workers shown as cards with name and model.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "agent.subagents"
       }
     },
     {
@@ -57,7 +58,8 @@
       "defaultValue": null,
       "description": "Agent shown in the summary card once showSummary is true.",
       "control": {
-        "kind": "opaque"
+        "kind": "opaque",
+        "fixture": "agent.summariser"
       }
     }
   ],

package/manifest/components/sup.json

@@ -35,7 +35,7 @@
         "Sub",
         "Sup"
       ],
-      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={MATH.length} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
+      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={3} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
       "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
       "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
     }

package/manifest/components/swap-label.json

@@ -30,7 +30,8 @@
       "defaultValue": null,
       "description": "Exactly two labels: the resting one and the active one.",
       "control": {
-        "kind": "opaque"
+        "kind": "opaque",
+        "fixture": "agent.swap-pair"
       }
     },
     {

package/manifest/components/textarea.json

@@ -26,6 +26,26 @@
       "control": {
         "kind": "number"
       }
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the textarea, when no `FieldLabel` names it. Declared\nhere rather than left to the inherited attribute so the props table carries\nthe row: a bare textarea outside a `Field` has no other way to be named.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "An example of what goes in the box, shown while it is empty. Not a name:\nit disappears on the first keystroke, so pair it with `aria-label` or a\n`FieldLabel`. Declared for the props-table row, as `aria-label` is above.",
+      "control": {
+        "kind": "string"
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/thread-list.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "Conversation rows with title, time, and optional unread mark.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "composer.threads"
       }
     },
     {

package/manifest/components/thread-search.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "All threads. Filtering matches title and preview together.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "composer.searchable"
       }
     },
     {

package/manifest/components/todo-list.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "The list as it stands right now. Each item carries its own status, so the agent\ncan add, reorder, and complete items in any order between renders.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "agent.todos"
       }
     },
     {

package/manifest/components/toggle.json

@@ -17,6 +17,16 @@
         "kind": "string"
       }
     },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name. An icon-only toggle has no text to be named by, so this is\nits name; declared here rather than left to the inherited attribute so the\nprops table carries the row the sentence above tells a caller to pass.",
+      "control": {
+        "kind": "string"
+      }
+    },
     {
       "name": "children",
       "type": "ReactNode",