@cueplusplus/ui 0.9.0 → 0.11.0

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/progress.json

@@ -12,42 +12,61 @@
       "type": "ReactNode",
       "required": false,
       "defaultValue": null,
-      "description": "Caption above the bar. Rendered as Base UI's `Progress.Label`, so it also\nbecomes the bar's accessible name — pass one, or an `aria-label`."
+      "description": "Caption above the bar. Rendered as Base UI's `Progress.Label`, so it also\nbecomes the bar's accessible name — pass one, or an `aria-label`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     },
     {
       "name": "className",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Extra classes for the frame that holds the header and the track."
+      "description": "Extra classes for the frame that holds the header and the track.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "height",
       "type": "number",
       "required": false,
       "defaultValue": "5",
-      "description": "Track height in px at the 16px root, emitted as `rem`. Defaults to `5`."
+      "description": "Track height in px at the 16px root, emitted as `rem`. Defaults to `5`.",
+      "control": {
+        "kind": "number"
+      }
     },
     {
       "name": "showValue",
       "type": "boolean",
       "required": false,
       "defaultValue": "false",
-      "description": "Show the formatted value opposite the label. Defaults to `false`."
+      "description": "Show the formatted value opposite the label. Defaults to `false`.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "trackClassName",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Extra classes for the track."
+      "description": "Extra classes for the track.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "indicatorClassName",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Extra classes for the fill."
+      "description": "Extra classes for the fill.",
+      "control": {
+        "kind": "string"
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/prompt-library.json

@@ -14,42 +14,63 @@
       "type": "readonly SavedPrompt[]",
       "required": true,
       "defaultValue": null,
-      "description": "Everything saved. Filtering happens inside against the name."
+      "description": "Everything saved. Filtering happens inside against the name.",
+      "control": {
+        "kind": "array"
+      }
     },
     {
       "name": "query",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "Current search text."
+      "description": "Current search text.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "selectedId",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "Which prompt is previewed below the list."
+      "description": "Which prompt is previewed below the list.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "onQueryChange",
       "type": "((query: string) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called as the search is typed."
+      "description": "Called as the search is typed.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "onSelect",
       "type": "((id: string) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called when a prompt is highlighted."
+      "description": "Called when a prompt is highlighted.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "onInsert",
       "type": "((id: string) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called on double click, to drop the prompt into the composer."
+      "description": "Called on double click, to drop the prompt into the composer.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/queue-dock.json

@@ -14,56 +14,84 @@
       "type": "readonly QueuedFollowUp[]",
       "required": true,
       "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."
+      "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"
+      }
     },
     {
       "name": "open",
       "type": "boolean",
       "required": true,
       "defaultValue": null,
-      "description": "Whether the entries are showing, or only the summary line."
+      "description": "Whether the entries are showing, or only the summary line.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "onOpenChange",
       "type": "((open: boolean) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called when the dock is expanded or collapsed."
+      "description": "Called when the dock is expanded or collapsed.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "onEdit",
       "type": "((id: string) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Put this turn back in the composer to be rewritten. The control exists\nonly when this is given."
+      "description": "Put this turn back in the composer to be rewritten. The control exists\nonly when this is given.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "onSendNow",
       "type": "((id: string) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Send this turn now rather than waiting for the run to finish — Cursor's\n`Send now`, Zed's steer button. The control exists only when this is given."
+      "description": "Send this turn now rather than waiting for the run to finish — Cursor's\n`Send now`, Zed's steer button. The control exists only when this is given.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "onRemove",
       "type": "((id: string) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Drop this turn before it ever sends. The control exists only when this is\ngiven."
+      "description": "Drop this turn before it ever sends. The control exists only when this is\ngiven.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "summary",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "The summary line, replacing the one {@link formatQueueSummary} would build\n— for a dock that counts something else: `2 follow-ups`, `3 steps queued`."
+      "description": "The summary line, replacing the one {@link formatQueueSummary} would build\n— for a dock that counts something else: `2 follow-ups`, `3 steps queued`.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "labels",
       "type": "Partial<QueueLabels>",
       "required": false,
       "defaultValue": null,
-      "description": "Copy for the five controls, merged over `QUEUE_LABELS`. Partial: overriding\n`sendNow` does not cost you the other four."
+      "description": "Copy for the five controls, merged over `QUEUE_LABELS`. Partial: overriding\n`sendNow` does not cost you the other four.",
+      "control": {
+        "kind": "opaque"
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/quota-banner.json

@@ -12,42 +12,61 @@
       "type": "number",
       "required": true,
       "defaultValue": null,
-      "description": "How much has been consumed."
+      "description": "How much has been consumed.",
+      "control": {
+        "kind": "number"
+      }
     },
     {
       "name": "limit",
       "type": "number",
       "required": true,
       "defaultValue": null,
-      "description": "The allowance. The banner turns amber at 90 percent."
+      "description": "The allowance. The banner turns amber at 90 percent.",
+      "control": {
+        "kind": "number"
+      }
     },
     {
       "name": "unit",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "What is being counted: messages, runs, credits."
+      "description": "What is being counted: messages, runs, credits.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "resetsIn",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "Pre-formatted time until the window rolls over."
+      "description": "Pre-formatted time until the window rolls over.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "upgradeLabel",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "Label for the way out."
+      "description": "Label for the way out.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "onUpgrade",
       "type": "(() => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called from the upgrade action."
+      "description": "Called from the upgrade action.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/quote-reply.json

@@ -14,49 +14,71 @@
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "Text preceding the selection."
+      "description": "Text preceding the selection.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "selection",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "The highlighted run the actions apply to."
+      "description": "The highlighted run the actions apply to.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "after",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "Text following the selection."
+      "description": "Text following the selection.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "actions",
       "type": "readonly QuoteAction[]",
       "required": true,
       "defaultValue": null,
-      "description": "What the toolbar offers. Each action names one of the three built-in icons."
+      "description": "What the toolbar offers. Each action names one of the three built-in icons.",
+      "control": {
+        "kind": "array"
+      }
     },
     {
       "name": "toolbarVisible",
       "type": "boolean",
       "required": true,
       "defaultValue": null,
-      "description": "Whether the floating toolbar is showing. Drive it from your own selection handler."
+      "description": "Whether the floating toolbar is showing. Drive it from your own selection handler.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "quoted",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Once quoted, the text carried into the composer, shown under a rule."
+      "description": "Once quoted, the text carried into the composer, shown under a rule.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "onAction",
       "type": "((key: string) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called with the key of the action that was chosen."
+      "description": "Called with the key of the action that was chosen.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/radio-group.json

@@ -12,14 +12,24 @@
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Extra classes, merged over the stack defaults."
+      "description": "Extra classes, merged over the stack defaults.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "orientation",
       "type": "\"horizontal\" | \"vertical\"",
       "required": false,
       "defaultValue": "vertical",
-      "description": "Lay the options out in a column (default) or a row."
+      "description": "Lay the options out in a column (default) or a row.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "horizontal",
+          "vertical"
+        ]
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/radio.json

@@ -12,21 +12,35 @@
       "type": "ReactNode",
       "required": false,
       "defaultValue": null,
-      "description": "Inline label rendered beside the dot and wrapped with it in a `<label>`, so\nthe text is both the accessible name and part of the hit target."
+      "description": "Inline label rendered beside the dot and wrapped with it in a `<label>`, so\nthe text is both the accessible name and part of the hit target.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     },
     {
       "name": "className",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Extra classes, merged over the dot defaults."
+      "description": "Extra classes, merged over the dot defaults.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "size",
       "type": "\"sm\" | \"md\"",
       "required": false,
       "defaultValue": "md",
-      "description": "Rung of the density icon ladder for the dot. Defaults to `\"md\"`."
+      "description": "Rung of the density icon ladder for the dot. Defaults to `\"md\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "sm",
+          "md"
+        ]
+      }
     }
   ],
   "typeReferences": [