@cueplusplus/ui 0.11.1 → 0.12.0

package/manifest/components/preview.json

@@ -5,7 +5,7 @@
   "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.",
+  "description": "A card for one component: a stage that is its own theme island, a slot for\ntools at the top right, and a footer.\n\n**Two presentations, one stage.** `\"panel\"`, the default and what every\nexisting caller gets, is that card: a border, a fill, a dot grid under the\nspecimen, and the tools floating over the stage's top right. `\"frame\"` is a\ndesign-canvas frame — no card, no border, no fill; the name, the count and\nthe tools sit in a row *above* the stage rather than over it, four crosshairs\nmark the stage's outer corners, and the stage paints nothing by default, so\nwhatever canvas the frame sits on shows through. Everything below holds in\nboth.\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 its slots, each saying what it is.",
   "props": [
     {
       "name": "children",
@@ -121,6 +121,66 @@
         "kind": "node",
         "fixture": "children.text"
       }
+    },
+    {
+      "name": "presentation",
+      "type": "\"frame\" | \"panel\"",
+      "required": false,
+      "defaultValue": "panel",
+      "description": "`\"panel\"` (the default, and what every existing caller gets): a bordered\ncard, `tools` floating at the stage's top right, `footer` under it.\n`\"frame\"`: a design-canvas frame — the label row drawn *above* the stage\nrather than over it, four crosshair corners at the stage's outer corners,\nand a transparent stage so whatever the frame sits on shows through.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "frame",
+          "panel"
+        ]
+      }
+    },
+    {
+      "name": "name",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The label row's leading slot, drawn only in `\"frame\"`. A plain node, or a\ncontrol: apps/docs passes a `DropdownMenu` whose trigger is the frame's\nname. Unset, the row opens with `label` as text.\n\nA slot and not a built-in menu, because `Preview` imports no overlay today\nand `/` draws seventeen of it under a 766-byte headroom.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "count",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "The count drawn after the name — how many items this frame holds. Frame only.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "ground",
+      "type": "\"none\" | \"plain\" | \"dots\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "The stage's ground. Defaults to `\"dots\"` in `\"panel\"` and `\"none\"` in\n`\"frame\"`, where the canvas under it already carries a ground and two dot\ngrids at different pitches read as a moiré.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "none",
+          "plain",
+          "dots"
+        ]
+      }
+    },
+    {
+      "name": "captions",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Whether `Frames.Item` captions are shown inside this stage. Defaults to\n`true`. Off is paint and nothing more: a hidden caption is still rendered,\nstill in the tree and still read aloud (§4.1 Decision 4).",
+      "control": {
+        "kind": "boolean"
+      }
     }
   ],
   "typeReferences": [
@@ -137,6 +197,7 @@
     "--cue-control-sm",
     "--cue-fg",
     "--cue-fg-muted",
+    "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-hair-strong",
     "--cue-radius-control",
@@ -149,9 +210,10 @@
     "--cue-surface-1",
     "--cue-surface-2",
     "--cue-surface-3",
-    "--cue-text-label"
+    "--cue-text-label",
+    "--cue-text-micro"
   ],
-  "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.",
+  "summary": "A card for one component: a stage that is its own theme island, tools at the top right — or, in the `frame` presentation a design canvas draws, in a label row above the stage beside the name and the count — a footer, and grips that resize it on both axes.",
   "examples": [
     {
       "title": "Inheriting the page, resizable",
@@ -163,9 +225,19 @@
       "code": "<Preview label=\"Chip preview\" theme=\"terminal\" density=\"compact\">\n  <Chip tone=\"accent\">Standby</Chip>\n</Preview>",
       "language": "tsx"
     },
+    {
+      "title": "A canvas frame",
+      "code": "<Preview\n  presentation=\"frame\"\n  label=\"Button tone\"\n  name={<ToneMenu />}\n  count={3}\n  tools={<IconButton aria-label=\"Configure Button tone\" icon={Wrench} />}\n>\n  <div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">\n    <Frames.Item caption=\"accent\">\n      <Button variant=\"primary\">Take cue</Button>\n    </Frames.Item>\n  </div>\n</Preview>",
+      "language": "tsx"
+    },
+    {
+      "title": "A frame with its captions off",
+      "code": "<Preview presentation=\"frame\" label=\"Button density\" count={2} captions={false}>\n  <div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">\n    <Frames.Item caption=\"compact\">\n      <Button size=\"sm\">Go</Button>\n    </Frames.Item>\n    <Frames.Item caption=\"normal\">\n      <Button>Go</Button>\n    </Frames.Item>\n  </div>\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>",
+      "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>\n<Preview label=\"Button\" presentation=\"frame\" count={3}>\n  <Button variant=\"primary\">Take cue</Button>\n</Preview>",
       "language": "tsx"
     }
   ],
@@ -176,16 +248,21 @@
   "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."
+    "Letting a reader watch a component respond to its container: pass `resizable` and drag it narrow, or short.",
+    "Drawing one axis of a component on a design canvas: `presentation=\"frame\"` moves the label row above the stage, puts `tools` in it, makes the stage transparent and marks the four corners."
   ],
   "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."
+    "Split panes a user resizes as part of an app. That is `Resizable`; a Preview's grips resize a stage, not a layout.",
+    "Building the frame's name menu into the Preview. `name` is a slot: pass your own `DropdownMenu`. This component imports no overlay, and a page that draws seventeen Previews cannot afford one."
   ],
   "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."
+    "Putting the controls that configure the specimen in `children`. They would take the stage's theme; put them in `tools`, which follows the page.",
+    "Setting `presentation=\"frame\"` and leaving `ground` alone on a page that already draws a dot grid. A frame's ground defaults to `none` for exactly that reason; naming `dots` puts a second grid at a second pitch over the first, and the two read as a moiré.",
+    "Reading `count` as something the Preview works out. It counts nothing — `count` is what the caller knows, and `0` is a count it will draw.",
+    "Passing `resizable` to a `presentation=\"frame\"` Preview. The crosshair marks follow the frame box, not a resized stage, so dragging the grips puts the marks off the stage's corners — use `resizable` on a panel, or keep the frame a fixed size."
   ],
   "specimens": [
     {
@@ -195,7 +272,7 @@
         "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.",
+      "note": "A card 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/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "library": "@cueplusplus/ui",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "themes": [
     "cue",
@@ -29,7 +29,7 @@
   ],
   "tokens": {
     "path": "./tokens.json",
-    "sha256": "dd0f46031463c67d4d49a3a3dfd1db01a4c2d1dea19ac434c33d3a5e32f818fb"
+    "sha256": "c2f61ee292302f6154b6eecf136b40292de23d78e2960d1cb5d1e78361fcfe40"
   },
   "systemApis": [
     {
@@ -3780,7 +3780,7 @@
       "mdUrl": "/docs/components/bento.md",
       "jsonUrl": "/r/components/bento.json",
       "path": "./components/bento.json",
-      "sha256": "9f271195040830e79b990c8e21229d822fc889d6e7dcc59d28b55a4970822fba"
+      "sha256": "e08b72c850136994ce6b9e350b70784b024a71157eb9389e4b8c2b7bd8c9026a"
     },
     {
       "name": "Breadcrumb",
@@ -3873,6 +3873,19 @@
       "path": "./components/disclosure.json",
       "sha256": "b4ab6140983f381772a9aaa8827ef777952d76ec08b43a85b062a388e6af2210"
     },
+    {
+      "name": "Frames",
+      "slug": "frames",
+      "group": "layout",
+      "importPath": "@cueplusplus/ui",
+      "summary": "A design canvas: frames side by side, each holding one axis of one component. Short, wide, scrollable sideways, focusable, and pannable with the pointer.",
+      "status": "stable",
+      "url": "/docs/components/frames",
+      "mdUrl": "/docs/components/frames.md",
+      "jsonUrl": "/r/components/frames.json",
+      "path": "./components/frames.json",
+      "sha256": "abc9270ea2b49eaba8ce52a0dacf103acfb536ebb46b5a2db282f2a3490e7048"
+    },
     {
       "name": "Grid",
       "slug": "grid",
@@ -3930,13 +3943,13 @@
       "slug": "preview",
       "group": "layout",
       "importPath": "@cueplusplus/ui",
-      "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.",
+      "summary": "A card for one component: a stage that is its own theme island, tools at the top right — or, in the `frame` presentation a design canvas draws, in a label row above the stage beside the name and the count — a footer, and grips that resize it on both axes.",
       "status": "stable",
       "url": "/docs/components/preview",
       "mdUrl": "/docs/components/preview.md",
       "jsonUrl": "/r/components/preview.json",
       "path": "./components/preview.json",
-      "sha256": "5d76161163185776ed88381d903742ba9c6bd079ff10c9a817024cac95bcb6b8"
+      "sha256": "2f06e1d13bc234c6a7a393f953a481955723674ef734416f37fa27db3e461cde"
     },
     {
       "name": "Resizable",

package/manifest/tokens.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "library": "@cueplusplus/tokens",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "themes": [
     {
       "name": "cue",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueplusplus/ui",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "CUE++ design system components: Tailwind v4 styled wrappers over Base UI, driven by @cueplusplus/tokens.",
   "license": "MIT",
   "type": "module",
@@ -144,7 +144,7 @@
     "culori": "^4.0.2",
     "tailwind-merge": "^3.6.0",
     "@cueplusplus/theme-base": "^1.0.1",
-    "@cueplusplus/tokens": "0.11.1"
+    "@cueplusplus/tokens": "0.12.0"
   },
   "peerDependencies": {
     "@assistant-ui/react": "^0.15.16",
@@ -258,10 +258,10 @@
     "tsdown": "0.22.14",
     "typescript": "^5.7.0",
     "vitest": "^4.1.10",
-    "@repo/eslint-config": "0.0.0",
-    "@cueplusplus/theme-tools": "1.0.1",
+    "@repo/typescript-config": "0.0.0",
     "@repo/docgen": "0.0.0",
-    "@repo/typescript-config": "0.0.0"
+    "@cueplusplus/theme-tools": "1.0.2",
+    "@repo/eslint-config": "0.0.0"
   },
   "scripts": {
     "build": "pnpm run check:manifest && tsdown",