@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/density.json

@@ -0,0 +1,58 @@
+{
+  "name": "Density",
+  "slug": "density",
+  "group": "system",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Re-scope any subtree to a different density level.\n\nRenders a plain `<div data-density=\"…\">`: the geometry custom properties are\nre-declared by the attribute selector and inherit down, so nesting is free and\nneeds no JS. The matching React context is published alongside for the rare\nJS reads (`useDensity()`, `useControlHeight()`, portal stamping) — the DOM\nattribute, not the context, is what actually restyles the tree.\n\nTheme and mode are deliberately *not* re-scoped here: density is the only axis\nan island may override (spec §6).",
+  "props": [
+    {
+      "name": "density",
+      "type": "\"normal\" | \"large\" | \"compact\" | \"ultra-compact\" | \"ultra-large\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Level to apply to this subtree: `ultra-compact`, `compact`, `normal`,\n`large` or `ultra-large`."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "Subtree that should render at `density`."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the island element. It is an ordinary `<div>` — style it like one."
+    },
+    {
+      "name": "style",
+      "type": "CSSProperties",
+      "required": false,
+      "defaultValue": null,
+      "description": "Inline styles for the island element."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "Re-scope any subtree to a different density level.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Density density=\"ultra-compact\">\n  <Toolbar />\n</Density>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/density",
+  "mdUrl": "/docs/components/density.md",
+  "jsonUrl": "/r/components/density.json",
+  "todo": true
+}

package/manifest/components/description-list.json

@@ -0,0 +1,84 @@
+{
+  "name": "DescriptionList",
+  "slug": "description-list",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The `<dl>` family: {@link DescriptionListRoot}, `Term` and `Detail`.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Term",
+    "Detail"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "DescriptionList.Root",
+      "description": "A key/value block: the honest `<dl>`, styled for a console.\n\nTerms are set in the mono micro caption idiom shared with `SectionHeader` and\nmenu group labels, so a metadata block reads as annotation rather than as\ncompeting body text.\n\nStatic markup — no `\"use client\"`.",
+      "props": [
+        {
+          "name": "layout",
+          "type": "\"inline\" | \"stacked\"",
+          "required": false,
+          "defaultValue": "inline",
+          "description": "`\"inline\"` (default) puts the detail beside its term in a two-column grid;\n`\"stacked\"` puts it underneath. Stack when the details are long enough to\nwrap, which turns the aligned column into ragged text anyway."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"dl\">"
+      ]
+    },
+    {
+      "name": "Term",
+      "usage": "DescriptionList.Term",
+      "description": "One key. Mono, uppercase, widely tracked — annotation, not body text.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"dt\">"
+      ]
+    },
+    {
+      "name": "Detail",
+      "usage": "DescriptionList.Detail",
+      "description": "One value. `m-0` resets the browser's inherited `<dd>` indent, which would\notherwise push every detail 40px right of the grid column it belongs to.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"dd\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The `<dl>` family: {@link DescriptionListRoot}, `Term` and `Detail`.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/description-list",
+  "mdUrl": "/docs/components/description-list.md",
+  "jsonUrl": "/r/components/description-list.json",
+  "specimens": [
+    {
+      "title": "DescriptionList",
+      "group": "layout",
+      "components": [
+        "DescriptionList"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Panel className=\"p-(--cue-space-5)\">\n    <DescriptionList.Root>\n      <DescriptionList.Term>Protocol</DescriptionList.Term>\n      <DescriptionList.Detail>Art-Net</DescriptionList.Detail>\n      <DescriptionList.Term>Host</DescriptionList.Term>\n      <DescriptionList.Detail>10.0.0.42</DescriptionList.Detail>\n      <DescriptionList.Term>Rate</DescriptionList.Term>\n      <DescriptionList.Detail>\n        <span className=\"flex items-center gap-(--cue-space-2)\">\n          44 Hz <StatusDot tone=\"ok\" label=\"Nominal\" />\n        </span>\n      </DescriptionList.Detail>\n    </DescriptionList.Root>\n  </Panel>\n  <Panel className=\"p-(--cue-space-5)\">\n    <DescriptionList.Root layout=\"stacked\">\n      <DescriptionList.Term>Protocol</DescriptionList.Term>\n      <DescriptionList.Detail>Art-Net</DescriptionList.Detail>\n      <DescriptionList.Term>Host</DescriptionList.Term>\n      <DescriptionList.Detail>10.0.0.42</DescriptionList.Detail>\n    </DescriptionList.Root>\n  </Panel>\n</div>",
+      "note": "Two layouts: inline pairs for a sidebar, stacked for a page.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/diagram.json

@@ -0,0 +1,100 @@
+{
+  "name": "Diagram",
+  "slug": "diagram",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A drawn answer with zoom, reset, and a full-bleed view; you hand it the rendered\ngraphic.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the diagram shows."
+    },
+    {
+      "name": "zoom",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Scale factor applied to the content. 1 is fit; the header prints it as a percentage."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The rendered graphic. The element owns the frame and never parses or injects\nmarkup itself, so whatever renders your chart stays your choice."
+    },
+    {
+      "name": "onZoomIn",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the zoom-in control. Clamp the range yourself."
+    },
+    {
+      "name": "onZoomOut",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the zoom-out control."
+    },
+    {
+      "name": "onReset",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to return to the default view."
+    },
+    {
+      "name": "onExpand",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to open the diagram full screen."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"title\"\n  | \"zoom\"\n  | \"children\"\n  | \"onZoomIn\"\n  | \"onZoomOut\"\n  | \"onReset\"\n  | \"onExpand\"\n> & {\n  /** What the diagram shows. */\n  title: string;\n  /** Scale factor applied to the content. 1 is fit; the header prints it as a percentage. */\n  zoom: number;\n  /**\n   * The rendered graphic. The element owns the frame and never parses or injects\n   * markup itself, so whatever renders your chart stays your choice.\n   */\n  children: React.ReactNode;\n  /** Called from the zoom-in control. Clamp the range yourself. */\n  onZoomIn?: () => void;\n  /** Called from the zoom-out control. */\n  onZoomOut?: () => void;\n  /** Called to return to the default view. */\n  onReset?: () => void;\n  /** Called to open the diagram full screen. */\n  onExpand?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-text-body"
+  ],
+  "summary": "A drawn answer with zoom, reset, and a full-bleed view; you hand it the rendered graphic.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { Diagram } from \"@cueplusplus/ui/elements\";\n\n<Diagram title=\"message flow\" zoom={zoom} onZoomIn={zoomIn} onReset={reset}>\n  <MermaidSvg chart={chart} />\n</Diagram>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/diagram",
+  "mdUrl": "/docs/components/diagram.md",
+  "jsonUrl": "/r/components/diagram.json",
+  "specimens": [
+    {
+      "title": "Diagram",
+      "group": "elements-knowledge",
+      "components": [
+        "Diagram"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"the front truss, zoomable\" wide>\n    <Diagram\n      title=\"Front truss — 6 fixtures on 3.2 m centres\"\n      zoom={zoom}\n      onZoomIn={() => setZoom((current) => Math.min(1.6, current + 0.2))}\n      onZoomOut={() => setZoom((current) => Math.max(0.6, current - 0.2))}\n      onReset={() => setZoom(1)}\n    >\n      <svg\n        viewBox=\"0 0 200 60\"\n        width=\"200\"\n        height=\"60\"\n        role=\"img\"\n        aria-label=\"Six fixtures hung along one truss\"\n      >\n        <line x1=\"6\" y1=\"20\" x2=\"194\" y2=\"20\" className=\"stroke-fg-subtle\" strokeWidth=\"2\" />\n        {[16, 51, 86, 121, 156, 186].map((x) => (\n          <rect key={x} x={x - 6} y=\"26\" width=\"12\" height=\"16\" rx=\"2\" className=\"fill-stream\" />\n        ))}\n      </svg>\n    </Diagram>\n  </Specimen>\n  <Specimen label=\"zoomed out, nothing to expand to\" wide>\n    <Diagram title=\"Front truss\" zoom={0.7}>\n      <svg viewBox=\"0 0 200 40\" width=\"200\" height=\"40\" role=\"img\" aria-label=\"One truss\">\n        <line x1=\"6\" y1=\"20\" x2=\"194\" y2=\"20\" className=\"stroke-fg-subtle\" strokeWidth=\"2\" />\n      </svg>\n    </Diagram>\n  </Specimen>\n</Specimens>",
+      "note": "A drawn answer with a viewport around it: zoom, reset, full-bleed. The graphic is yours — the element supplies the frame, the percentage readout and the transform, and never parses or renders anything itself.",
+      "interaction": "four named icon buttons; expand disables itself when no handler is given, which is the honest state for a bench with nowhere to expand to. The scale transition stops under reduced motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/dialog.json

@@ -0,0 +1,198 @@
+{
+  "name": "Dialog",
+  "slug": "dialog",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A modal surface for a focused task: patching a fixture, renaming a cue,\nconfirming an import.\n\nWraps Base UI's `Dialog`, so every part of the behaviour contract — focus\ntrap, focus restoration on close, Escape, outside press, scroll lock, the\n`aria-labelledby`/`aria-describedby` wiring — is the primitive's, and this\nlayer supplies only the token-driven skin plus the portal theme stamp.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Trigger",
+    "Content",
+    "Title",
+    "Description",
+    "Footer",
+    "Close"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Dialog.Root",
+      "description": "Groups the parts of a dialog and owns its open state. Renders no element.",
+      "props": [],
+      "typeReferences": [
+        "BaseDialog.Root.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "Dialog.Trigger",
+      "description": "The control that opens the dialog. A `<button>` by default.\n\nDeliberately unstyled: pass `render={<Button />}` to give it a skin, so the\nbutton's variant classes stay the last word on how it looks. Styling the\ntrigger here would let those classes lose a `tailwind-merge` tie-break.",
+      "props": [],
+      "typeReferences": [
+        "BaseDialog.Trigger.Props"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "Dialog.Content",
+      "description": "The dialog's portal, scrim and popup in one part.\n\nThe portal container comes from {@link useCuePortalProps}, so the surface\ncarries the caller's `data-theme` / `data-density` / `data-mode` even though\nit mounts at the end of `<body>` — a dialog opened from an ultra-compact\nisland stays ultra-compact.\n\nFocus trapping, focus restoration, Escape and outside-press dismissal, and\nscroll locking all come from Base UI; this layer only paints.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the popup surface."
+        },
+        {
+          "name": "width",
+          "type": "\"sm\" | \"md\" | \"lg\"",
+          "required": false,
+          "defaultValue": "md",
+          "description": ""
+        },
+        {
+          "name": "closeLabel",
+          "type": "string",
+          "required": false,
+          "defaultValue": "Close",
+          "description": "Accessible name for the corner close affordance. Defaults to `\"Close\"`."
+        },
+        {
+          "name": "keepMounted",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Keep the popup mounted while closed, so its content is not re-created."
+        },
+        {
+          "name": "backdropClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the scrim behind it."
+        },
+        {
+          "name": "showCloseButton",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Show the corner close affordance. Defaults to `true`."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseDialog.Popup.Props, \"className\">",
+        "VariantProps<typeof dialogPopupVariants>"
+      ]
+    },
+    {
+      "name": "Title",
+      "usage": "Dialog.Title",
+      "description": "The dialog's heading. Base UI wires it to the popup's `aria-labelledby`, so a\ndialog with a title needs no `aria-label`.",
+      "props": [],
+      "typeReferences": [
+        "BaseDialog.Title.Props"
+      ]
+    },
+    {
+      "name": "Description",
+      "usage": "Dialog.Description",
+      "description": "The supporting line under the title, published as `aria-describedby`.",
+      "props": [],
+      "typeReferences": [
+        "BaseDialog.Description.Props"
+      ]
+    },
+    {
+      "name": "Footer",
+      "usage": "Dialog.Footer",
+      "description": "The right-aligned action strip at the foot of the popup.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Close",
+      "usage": "Dialog.Close",
+      "description": "A control that closes the dialog. Unstyled for the same reason as the\ntrigger — wrap it: `<Dialog.Close render={<Button>Cancel</Button>} />`.",
+      "props": [],
+      "typeReferences": [
+        "BaseDialog.Close.Props"
+      ]
+    }
+  ],
+  "variants": {
+    "width": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "defaultVariants": {
+    "width": "md"
+  },
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-6",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The centred modal: focus trapped, page behind it inert.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Dialog.Root>\n  <Dialog.Trigger render={<Button>Patch</Button>} />\n  <Dialog.Content>\n    <Dialog.Title>Patch fixture</Dialog.Title>\n    <Dialog.Description>Choose a universe and a start address.</Dialog.Description>\n    <Dialog.Footer>\n      <Dialog.Close render={<Button variant=\"ghost\">Cancel</Button>} />\n      <Button variant=\"primary\">Patch</Button>\n    </Dialog.Footer>\n  </Dialog.Content>\n</Dialog.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/dialog",
+  "mdUrl": "/docs/components/dialog.md",
+  "jsonUrl": "/r/components/dialog.json",
+  "whenToUse": [
+    "A task that must be finished or cancelled before the page continues.",
+    "A form too large for a popover, at one of the three width rungs."
+  ],
+  "whenNotToUse": [
+    "Confirming something destructive. Use `AlertDialog`, which announces as one and keeps focus on the safe answer.",
+    "Detail that hangs off a control. Use `Popover`, `HoverCard` or `Tooltip`.",
+    "A side panel that leaves the page usable. Use `Sheet` or `Drawer`."
+  ],
+  "commonMistakes": [
+    "Styling `Dialog.Trigger` directly instead of passing `render={<Button />}`, which is what keeps the button's variant classes authoritative.",
+    "Opening a second dialog on top of the first. Swap the content of the one that is already open."
+  ],
+  "specimens": [
+    {
+      "title": "Dialog",
+      "group": "overlays",
+      "components": [
+        "Dialog"
+      ],
+      "code": "<Specimens>\n  {([\"sm\", \"md\", \"lg\"] as const).map((width) => (\n    <Specimen key={width} label={width}>\n      <Dialog.Root>\n        <Dialog.Trigger render={<Button>Patch, {width}</Button>} />\n        <Dialog.Content width={width}>\n          <Dialog.Title>Patch fixture</Dialog.Title>\n          <Dialog.Description>\n            Universe 1, channels 1 to 8. The fixture takes the next free block.\n          </Dialog.Description>\n          <div className=\"flex flex-col gap-(--cue-space-5)\">\n            <Field name=\"label\">\n              <FieldLabel>Label</FieldLabel>\n              <Input defaultValue=\"Front wash\" />\n            </Field>\n            <Field name=\"blend\">\n              <FieldLabel>Blend</FieldLabel>\n              <Select aria-label=\"Blend mode\" items={[...BLEND_MODES]} defaultValue=\"htp\" />\n            </Field>\n          </div>\n          <Dialog.Footer>\n            <Dialog.Close render={<Button>Cancel</Button>} />\n            <Dialog.Close render={<Button variant=\"primary\">Patch</Button>} />\n          </Dialog.Footer>\n        </Dialog.Content>\n      </Dialog.Root>\n    </Specimen>\n  ))}\n  <Specimen label=\"no close button\">\n    <Dialog.Root>\n      <Dialog.Trigger render={<Button>Bare</Button>} />\n      <Dialog.Content showCloseButton={false}>\n        <Dialog.Title>{COPY.loading.title}</Dialog.Title>\n        <Dialog.Description>{COPY.loading.hint}</Dialog.Description>\n        <Dialog.Footer>\n          <Dialog.Close render={<Button>Close</Button>} />\n        </Dialog.Footer>\n      </Dialog.Content>\n    </Dialog.Root>\n  </Specimen>\n</Specimens>",
+      "note": "Three widths, a scrim at `--cue-scrim`, and a close button that can be turned off when the footer already owns dismissal.",
+      "interaction": "focus is trapped and returns to the trigger on close; Escape and a click on the scrim both dismiss."
+    }
+  ]
+}

package/manifest/components/disclosure.json

@@ -0,0 +1,109 @@
+{
+  "name": "Disclosure",
+  "slug": "disclosure",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The \"advanced\" idiom: a chromeless `▸ advanced` toggle over the fields most\nusers never touch.\n\nProgressive disclosure, drawn as quietly as the system can draw anything — no\nrim, no fill, mono micro caption ink, one triangle. It is deliberately *not*\na `Collapsible`: a collapsible section is a peer of the sections around it,\nwhile this is an annotation on the form it sits in, and giving it a summary\nrow that looks like a section header is what makes forms read as twice as\nlong as they are.\n\nPorted from dmxhub's `advBtn`, which is repeated at every route editor.",
+  "props": [
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "advanced",
+      "description": "What the toggle says. Defaults to `\"advanced\"`."
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Open state when controlled. Pass with `onOpenChange`."
+    },
+    {
+      "name": "defaultOpen",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initial open state when uncontrolled."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean, eventDetails: CollapsibleRootChangeEventDetails) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the new open state."
+    },
+    {
+      "name": "rootClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the frame around toggle and body."
+    },
+    {
+      "name": "bodyClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the revealed body."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The rarely-used fields to reveal."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"button\">, \"children\" | \"onChange\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-control-md",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-pad-row-x",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The \"advanced\" idiom: a chromeless `▸ advanced` toggle over the fields most users never touch.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Disclosure>\n  <Field label=\"failover ttl\"><NumberField /></Field>\n</Disclosure>\n<Disclosure label=\"output\" open={open} onOpenChange={setOpen}>…</Disclosure>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/disclosure",
+  "mdUrl": "/docs/components/disclosure.md",
+  "jsonUrl": "/r/components/disclosure.json",
+  "specimens": [
+    {
+      "title": "Disclosure",
+      "group": "layout",
+      "components": [
+        "Disclosure"
+      ],
+      "code": "<div className=\"flex w-full max-w-[36rem] flex-col gap-(--cue-space-3)\">\n  <Disclosure label=\"Advanced\">\n    <div className=\"flex flex-col gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      <span>Refresh rate 44 Hz</span>\n      <span>Full frames every 800 ms</span>\n    </div>\n  </Disclosure>\n  <Disclosure label=\"Open by default\" defaultOpen>\n    <span className=\"font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      Already expanded.\n    </span>\n  </Disclosure>\n</div>",
+      "note": "The `advanced` idiom: a chromeless mono `▸ label` toggle for the settings most people never open.",
+      "interaction": "the caret rotates; nothing else moves."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/dmx-bar.json

@@ -0,0 +1,94 @@
+{
+  "name": "DmxBar",
+  "slug": "dmx-bar",
+  "group": "dmx",
+  "importPath": "@cueplusplus/ui/dmx",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The whole universe as one strip: 512 columns, black at 0, white at 255.\n\nPorted from dmxhub's bridge, where it sits under every node in the routing\ngraph and updates at the wire rate. Three decisions are what make it cheap\nenough to leave running:\n\n1. **It is a 512×1 texture, stretched.** One `putImageData` per frame paints\n   every channel; the browser scales it. Drawing 512 rectangles would be 512\n   state changes for the same picture.\n2. **The pixels are never smoothed.** `image-rendering: pixelated` keeps one\n   channel one hard column. Interpolation here would invent levels between\n   channels, which is the one thing a monitoring bar must not do.\n3. **The crosshair is anchored in percent, not pixels.** The bar routinely\n   sits inside a zoom transform (a node graph, a canvas). A pixel offset gets\n   scaled with the parent and drifts off the cursor; a percentage resolves in\n   the bar's own width and lands correctly at any zoom.\n\nThe ground is `--cue-data-ground`, true black in every theme: a level of 0 is\n*nothing*, and it should not read as the panel it happens to sit on.",
+  "props": [
+    {
+      "name": "data",
+      "type": "Uint8Array<ArrayBufferLike>",
+      "required": false,
+      "defaultValue": null,
+      "description": "The current frame: one byte per channel, 512 long.\n\nRepainting is keyed on the array's *identity*, which is what a frame decoder\nnaturally produces (a fresh buffer per packet). A buffer mutated in place\nwill not repaint — hand a new view, or use `ChannelMatrix`, which owns an\nanimation loop for exactly that case."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "12",
+      "description": "Bar height in px at the 16px root, emitted as `rem`. Defaults to `12`."
+    },
+    {
+      "name": "live",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Whether frames are still arriving. Defaults to `true`. When `false` the bar\ndims and says so in its accessible name — a stalled stream and a blacked-out\nuniverse look identical otherwise."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "What this universe is. Defaults to `\"DMX output\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-sm",
+    "--cue-data-ground",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The whole universe as one strip: 512 columns, black at 0, white at 255.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<DmxBar label=\"Universe 0\" data={frame} live={connected} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/dmx-bar",
+  "mdUrl": "/docs/components/dmx-bar.md",
+  "jsonUrl": "/r/components/dmx-bar.json",
+  "specimens": [
+    {
+      "title": "DmxBar",
+      "group": "dmx",
+      "components": [
+        "DmxBar"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-5)\">\n  <Panel className=\"p-(--cue-space-4)\">\n    <PanelHeader\n      title=\"Universe 1\"\n      actions={<Chip tone=\"ok\">{activeChannels(data)} active</Chip>}\n    />\n    <div className=\"pt-(--cue-space-4)\">\n      <DmxBar data={data} label=\"Universe 1 output\" />\n    </div>\n  </Panel>\n  <Specimens>\n    <Specimen label=\"tall\" wide>\n      <DmxBar data={data} height={28} label=\"Universe 1, tall\" />\n    </Specimen>\n    <Specimen label=\"sparse\" wide>\n      <DmxBar data={sparse} label=\"Universe 1, first 48 channels only\" />\n    </Specimen>\n    <Specimen label=\"no data\" wide>\n      <DmxBar label=\"Universe 1, no frame\" />\n    </Specimen>\n  </Specimens>\n</div>",
+      "note": "The whole universe as one 512×1 texture, scaled up with `image-rendering: pixelated` on a true-black ground. Interpolating between two channels would draw levels nobody sent.",
+      "interaction": "hovering reports `CH n · v` through a portaled readout, positioned by percentage so it survives a scaled container; the number is written to a span through a ref rather than re-rendering at 40 Hz."
+    }
+  ],
+  "todo": true
+}