@cueplusplus/ui 0.9.0 → 0.11.0

package/manifest/components/inspector.json

@@ -0,0 +1,199 @@
+{
+  "name": "Inspector",
+  "slug": "inspector",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The shape a settings panel, a properties sidebar and a wrench menu share:\ntitled sections of label-and-control rows, with a footer.\n\nLayout and nothing else — the controls are the library's own. A section is\na group headed by a `SectionHeader`; a row is a label then its control, one\ncolumn in a narrow container and two from 18rem; the footer holds a quiet\nnote and one action.\n\n**Static markup — no hooks, no `\"use client\"`**, so a server page can draw\none. Labels are strings for the same reason: a row with no `htmlFor` lays its\nlabel on its control as `aria-label`, rather than pointing at an id nobody\nhas generated. The row itself carries no role.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Section",
+    "Row",
+    "Footer"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Inspector.Root",
+      "description": "The inspector's frame: a size container, so each row's columns follow the\ninspector's own width — a popover's, a sidebar's — and not the viewport's.\nIt holds the sections, then the footer.",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The sections, then the footer.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Section",
+      "usage": "Inspector.Section",
+      "description": "One titled group of rows: a `SectionHeader` carrying its `label`, and a group named by the same words.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "required": true,
+          "defaultValue": null,
+          "description": "The section's title — \"Variants\", \"Stage\". Drawn by a `SectionHeader` and read as the group's name.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The section's rows.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Row",
+      "usage": "Inspector.Row",
+      "description": "One label and its control: one column in a narrow inspector, two from 18rem.\nWith `htmlFor` the label is a `<label>` for that control; without it the\nlabel is laid on the control as its `aria-label`, unless the control already\nnames itself. The row carries no role.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "required": true,
+          "defaultValue": null,
+          "description": "What the control sets — \"Size\", \"Theme\". Drawn before it, and read as its\nname: a `<label>` for it when `htmlFor` is given, and otherwise laid on\nthe control as `aria-label`, unless the control already names itself.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "htmlFor",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "The control's `id`, when it takes one: the label then becomes a `<label>` for it.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The control — one element, any of the library's own. A row names a single control.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Footer",
+      "usage": "Inspector.Footer",
+      "description": "The inspector's closing strip: a quiet `note` on the left and one `action` on the right, each drawn only when given.",
+      "props": [
+        {
+          "name": "note",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "A quiet line on the left: which preset this is, or that none matches.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The footer's one action, on the right — by convention a small `Button`.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "Titled sections of label-and-control rows, with a footer: the layout of a settings panel, a properties sidebar or a wrench menu.",
+  "examples": [
+    {
+      "title": "A wrench menu",
+      "code": "<Inspector.Root>\n  <Inspector.Section label=\"Variants\">\n    <Inspector.Row label=\"Size\">\n      <SegmentedControl aria-label=\"Size\" items={sizes} defaultValue=\"md\" />\n    </Inspector.Row>\n    <Inspector.Row label=\"Label\" htmlFor=\"label\">\n      <Input id=\"label\" defaultValue=\"Take cue\" />\n    </Inspector.Row>\n  </Inspector.Section>\n  <Inspector.Footer note=\"preset · button-hero\" action={<Button size=\"sm\">Reset</Button>} />\n</Inspector.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Inspector.Root>\n  <Inspector.Section label=\"Variants\">\n    <Inspector.Row label=\"Size\"><SegmentedControl items={sizes} /></Inspector.Row>\n    <Inspector.Row label=\"Label\" htmlFor=\"label\"><Input id=\"label\" /></Inspector.Row>\n  </Inspector.Section>\n  <Inspector.Footer note=\"preset · button-hero\" action={<Button size=\"sm\">Reset</Button>} />\n</Inspector.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/inspector",
+  "mdUrl": "/docs/components/inspector.md",
+  "jsonUrl": "/r/components/inspector.json",
+  "whenToUse": [
+    "A popover or sidebar that edits several properties of one thing, grouped under a few headings.",
+    "Any panel whose rows are a label and a control — the controls stay the library's own; this lays them out."
+  ],
+  "whenNotToUse": [
+    "A form someone submits. That is `Field` and its family, which carry validation and descriptions an inspector row does not.",
+    "A list of records. That is `Panel` with `Row`."
+  ],
+  "commonMistakes": [
+    "Leaving a text input's row without `htmlFor`. The row then lays its words on the input as `aria-label`, which names it but gives it no `<label>` to click — give the input an `id` and the row `htmlFor`.",
+    "Putting two controls in one row. A row names one control; two controls are two rows.",
+    "Nesting sections. An inspector is one level of headings; a section inside a section is a second panel."
+  ],
+  "specimens": [
+    {
+      "title": "Inspector",
+      "group": "chrome",
+      "components": [
+        "Inspector"
+      ],
+      "code": "<div className=\"w-full max-w-[20rem] rounded-(--radius-surface) border border-border bg-surface-2\">\n  <Inspector.Root>\n    {/*\n      Data first, Variants second: `seedFromSpecimen` (`@repo/docgen`)\n      takes each prop's first tag-order value across the whole bench,\n      per prop name and not per row, so `defaults@Inspector.Row`'s\n      `label` and `htmlFor` have to come off the same row to name a\n      coherent pair — and `htmlFor` is only ever set on this one, the\n      only row whose control is a single labelable element. Putting\n      it first makes it that row for both props at once. Reordering\n      Size and Icon ahead of it would seed `label: \"Size\"` (the first\n      `Inspector.Row` tag) beside this row's `htmlFor`, pointing a\n      `<label for>` at an id that scope's control never renders.\n    */}\n    <Inspector.Section label=\"Data\">\n      <Inspector.Row label=\"Label\" htmlFor=\"inspector-bench-label\">\n        <Input id=\"inspector-bench-label\" defaultValue=\"Take cue\" />\n      </Inspector.Row>\n    </Inspector.Section>\n    <Inspector.Section label=\"Variants\">\n      <Inspector.Row label=\"Size\">\n        <SegmentedControl\n          aria-label=\"Size\"\n          size=\"sm\"\n          items={[\n            { value: \"sm\", label: \"sm\" },\n            { value: \"md\", label: \"md\" },\n            { value: \"lg\", label: \"lg\" },\n          ]}\n          defaultValue=\"md\"\n        />\n      </Inspector.Row>\n      <Inspector.Row label=\"Icon\">\n        <Switch aria-label=\"Icon\" defaultChecked />\n      </Inspector.Row>\n    </Inspector.Section>\n    <Inspector.Footer\n      note=\"preset · button-hero\"\n      action={\n        <Button size=\"sm\" variant=\"secondary\">\n          Reset\n        </Button>\n      }\n    />\n  </Inspector.Root>\n</div>",
+      "note": "Titled sections of label-and-control rows, with a footer — the shape of a settings panel, a properties sidebar and the docs' wrench menu. Layout only: the controls are the ones you already use.",
+      "interaction": "nothing of its own takes focus. Each row's control is a real one: a row given `htmlFor` labels its control with a `<label>`, and one without lays its label on the control as `aria-label`. A row is never a group of its own."
+    }
+  ]
+}

package/manifest/components/item.json

@@ -12,56 +12,90 @@
       "type": "ReactNode",
       "required": false,
       "defaultValue": null,
-      "description": "Leading slot: an icon, an avatar, a status dot."
+      "description": "Leading slot: an icon, an avatar, a status dot.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     },
     {
       "name": "title",
       "type": "ReactNode",
       "required": false,
       "defaultValue": null,
-      "description": "The item's name — one line, truncated rather than wrapped."
+      "description": "The item's name — one line, truncated rather than wrapped.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     },
     {
       "name": "description",
       "type": "ReactNode",
       "required": false,
       "defaultValue": null,
-      "description": "One supporting line under the title, a rung smaller and muted."
+      "description": "One supporting line under the title, a rung smaller and muted.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     },
     {
       "name": "actions",
       "type": "ReactNode",
       "required": false,
       "defaultValue": null,
-      "description": "Trailing slot: a value, a chip, a control.\n\nDo not combine with `interactive` — the whole item is then a `<button>`,\nand a button may not contain another one. Put the controls beside the item\ninstead, or drop `interactive` and make the title itself the link."
+      "description": "Trailing slot: a value, a chip, a control.\n\nDo not combine with `interactive` — the whole item is then a `<button>`,\nand a button may not contain another one. Put the controls beside the item\ninstead, or drop `interactive` and make the title itself the link.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     },
     {
       "name": "variant",
       "type": "\"plain\" | \"outline\" | \"soft\"",
       "required": false,
       "defaultValue": null,
-      "description": "Which framing to paint. Defaults to `\"plain\"`."
+      "description": "Which framing to paint. Defaults to `\"plain\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "plain",
+          "outline",
+          "soft"
+        ]
+      }
     },
     {
       "name": "interactive",
       "type": "boolean",
       "required": false,
       "defaultValue": "false",
-      "description": "Render as a `<button>` with hover feedback and a focus ring instead of a\nstatic `<div>`. Use for items that select, open or toggle something."
+      "description": "Render as a `<button>` with hover feedback and a focus ring instead of a\nstatic `<div>`. Use for items that select, open or toggle something.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "disabled",
       "type": "boolean",
       "required": false,
       "defaultValue": null,
-      "description": "Disable the interactive form. Ignored when `interactive` is not set."
+      "description": "Disable the interactive form. Ignored when `interactive` is not set.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "children",
       "type": "ReactNode",
       "required": false,
       "defaultValue": null,
-      "description": "Extra content between the text column and the action slot."
+      "description": "Extra content between the text column and the action slot.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/job-progress.json

@@ -14,42 +14,61 @@
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "What the job is doing."
+      "description": "What the job is doing.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "stages",
       "type": "readonly JobStage[]",
       "required": true,
       "defaultValue": null,
-      "description": "Stages with relative weights, so a long install does not read the same as a fast\nclone."
+      "description": "Stages with relative weights, so a long install does not read the same as a fast\nclone.",
+      "control": {
+        "kind": "array"
+      }
     },
     {
       "name": "stageIndex",
       "type": "number",
       "required": true,
       "defaultValue": null,
-      "description": "Which stage is running. Passing stages.length marks the job finished, and the bar\nnever runs past its track."
+      "description": "Which stage is running. Passing stages.length marks the job finished, and the bar\nnever runs past its track.",
+      "control": {
+        "kind": "number"
+      }
     },
     {
       "name": "stageProgress",
       "type": "number",
       "required": true,
       "defaultValue": null,
-      "description": "Progress inside the current stage, 0 to 1."
+      "description": "Progress inside the current stage, 0 to 1.",
+      "control": {
+        "kind": "number"
+      }
     },
     {
       "name": "eta",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "Pre-formatted estimate. Replaced by done once finished."
+      "description": "Pre-formatted estimate. Replaced by done once finished.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "onCancel",
       "type": "(() => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called to stop the job. Hidden once it finishes."
+      "description": "Called to stop the job. Hidden once it finishes.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/launcher-bubble.json

@@ -14,49 +14,74 @@
       "type": "boolean",
       "required": true,
       "defaultValue": null,
-      "description": "Whether the panel is showing. The trigger icon crossfades either way."
+      "description": "Whether the panel is showing. The trigger icon crossfades either way.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "unread",
       "type": "number",
       "required": true,
       "defaultValue": null,
-      "description": "Badge count on the closed bubble. Hidden at zero and while open."
+      "description": "Badge count on the closed bubble. Hidden at zero and while open.",
+      "control": {
+        "kind": "number"
+      }
     },
     {
       "name": "greeting",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "Opening line in the panel."
+      "description": "Opening line in the panel.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "prompts",
       "type": "readonly string[]",
       "required": true,
       "defaultValue": null,
-      "description": "Ways in, so the first message does not have to be invented."
+      "description": "Ways in, so the first message does not have to be invented.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
     },
     {
       "name": "onToggle",
       "type": "(() => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called when the bubble is pressed."
+      "description": "Called when the bubble is pressed.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "onPick",
       "type": "((prompt: string) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called when a starter prompt is chosen."
+      "description": "Called when a starter prompt is chosen.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "onStart",
       "type": "(() => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called from the Start a conversation action, for opening an empty thread."
+      "description": "Called from the Start a conversation action, for opening an empty thread.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     }
   ],
   "typeReferences": [