@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/multi-select.json

@@ -0,0 +1,190 @@
+{
+  "name": "MultiSelect",
+  "slug": "multi-select",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Several values out of a known set, each shown as a removable chip.\n\nThe chips live *inside* the field rather than under it, which is what makes\nthe control honest about its own size: a selection of nine trusses is visibly\nnine trusses tall, and nothing is hidden behind a \"+6 more\" the user has to\nopen something to read. That is also why the field takes `min-h-control-*`\ninstead of a fixed height.\n\nBackspace in an empty input removes the last chip and the chips themselves are\narrow-key navigable — both come from Base UI's `Combobox.Chips`, and both are\nthe parts hand-rolled multi-selects forget.",
+  "props": [
+    {
+      "name": "items",
+      "type": "readonly ComboboxOption[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The rows, in display order. Base UI filters them against what is typed."
+    },
+    {
+      "name": "value",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Selected values. Use with `onValueChange` for a controlled field."
+    },
+    {
+      "name": "defaultValue",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initially selected values for an uncontrolled field."
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string[]) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the full selection after every add or remove."
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Shown while nothing is selected — suppressed once chips fill the field."
+    },
+    {
+      "name": "emptyMessage",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "No matches",
+      "description": "Shown in place of the list when the query matches nothing."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Prevent opening and grey the field out."
+    },
+    {
+      "name": "required",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Require at least one value before the owning form submits."
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Name for the hidden input, when the field is part of a form."
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id forwarded to the text input."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the input, when no {@link FieldLabel } names it."
+    },
+    {
+      "name": "aria-labelledby",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id of the element naming the input."
+    },
+    {
+      "name": "removeLabel",
+      "type": "((label: string) => string)",
+      "required": false,
+      "defaultValue": "(label) => `Remove ${label}`",
+      "description": "Accessible name for a chip's remove button, given the row's label. Defaults\nto ``(label) => `Remove ${label}` ``."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the field."
+    },
+    {
+      "name": "popupClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the popup surface."
+    },
+    {
+      "name": "sideOffset",
+      "type": "number",
+      "required": false,
+      "defaultValue": "4",
+      "description": "Distance in px between the field and the popup. Defaults to `4`."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-chip-h",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "Several values out of a known set, each shown as a removable chip.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<MultiSelect aria-label=\"Trusses\" items={trusses} value={picked} onValueChange={setPicked} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/multi-select",
+  "mdUrl": "/docs/components/multi-select.md",
+  "jsonUrl": "/r/components/multi-select.json",
+  "specimens": [
+    {
+      "title": "MultiSelect",
+      "group": "forms",
+      "components": [
+        "MultiSelect"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <MultiSelect\n    aria-label=\"Fixture types\"\n    items={FIXTURE_OPTIONS}\n    defaultValue={[\"par64\", \"s4\"]}\n    placeholder=\"Fixture types\"\n  />\n  <MultiSelect\n    aria-label=\"Fixture types, disabled\"\n    items={FIXTURE_OPTIONS}\n    defaultValue={[\"sharpy\"]}\n    disabled\n  />\n</div>",
+      "note": "Several values in one control, rendered as removable chips.",
+      "interaction": "each chip's remove button has its own accessible name; Backspace removes the last one."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/musical-time-input.json

@@ -0,0 +1,113 @@
+{
+  "name": "MusicalTimeInput",
+  "slug": "musical-time-input",
+  "group": "midi",
+  "importPath": "@cueplusplus/ui/midi",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "`bars.beats.sixteenths` — a position in a song, typed the way a song is\ncounted.\n\nA number field would ask for 4.25 and mean \"bar 2, beat 1, one sixteenth in\",\nwhich is a conversion the musician has to do in their head every time. This\nfield does it instead: three segments, each one stepping in its own musical\nunit, and the carry between them handled by the arithmetic rather than by the\ntypist (bar 1 beat 4 plus one beat is bar 2 beat 1).\n\nThree interactions, because the three are used at different moments: **arrows**\nfor a nudge while listening, **scroll** for a sweep, and **typing** for a\nposition read off a cue sheet. Tab moves between the segments on its own — the\nported version intercepted Tab to reimplement the focus order the browser\nalready had, which broke Shift+Tab out of the field entirely.\n\nThe scroll gesture is bound natively rather than through React's `onWheel`,\nbecause React attaches wheel listeners passively at the root: `preventDefault`\nthere is a no-op and the page scrolls away underneath the edit.",
+  "props": [
+    {
+      "name": "value",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "The position, in quarter-note beats. Always controlled."
+    },
+    {
+      "name": "onChange",
+      "type": "(beats: number) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the new position after every edit."
+    },
+    {
+      "name": "timeSignature",
+      "type": "TimeSignature",
+      "required": false,
+      "defaultValue": "{ numerator: 4, denominator: 4 }",
+      "description": "The signature the display counts in. Defaults to 4/4."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "total",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Print the total in beats after the segments. Defaults to `true`."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Refuse every edit."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Musical time",
+      "description": "Accessible name for the field as a whole. Defaults to `\"Musical time\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onChange\" | \"defaultValue\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "`bars.beats.sixteenths` — a position in a song, typed the way a song is counted.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<MusicalTimeInput value={beats} onChange={setBeats} />\n<MusicalTimeInput value={beats} onChange={setBeats} timeSignature={{ numerator: 6, denominator: 8 }} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/musical-time-input",
+  "mdUrl": "/docs/components/musical-time-input.md",
+  "jsonUrl": "/r/components/musical-time-input.json",
+  "specimens": [
+    {
+      "title": "MusicalTimeInput",
+      "group": "midi",
+      "components": [
+        "MusicalTimeInput"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"4/4\">\n    <MusicalTimeInput value={beats} onChange={setBeats} label=\"Loop start\" />\n  </Specimen>\n  <Specimen label=\"7/8\">\n    <MusicalTimeInput\n      value={beats}\n      onChange={setBeats}\n      timeSignature={{ numerator: 7, denominator: 8 }}\n      label=\"Loop start, 7/8\"\n    />\n  </Specimen>\n  <Specimen label=\"no total\">\n    <MusicalTimeInput value={beats} onChange={setBeats} total={false} size=\"sm\" label=\"Compact\" />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <MusicalTimeInput value={beats} onChange={setBeats} disabled label=\"Locked\" />\n  </Specimen>\n  <Specimen label=\"formatted\">\n    <Chip tone=\"accent\">{formatMusicalTime(beatsToMusical(beats))}</Chip>\n  </Specimen>\n</Specimens>",
+      "note": "`bars.beats.sixteenths` as three segments, time-signature aware, with the total-beats readout beside it.",
+      "interaction": "arrow keys and the scroll wheel step the segment under the caret; Tab moves between segments and overflow carries into the next one."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/navigation-menu.json

@@ -0,0 +1,226 @@
+{
+  "name": "NavigationMenu",
+  "slug": "navigation-menu",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The marketing-shaped navigation header: a strip of words, each opening a panel\nof destinations.\n\nWraps Base UI's `NavigationMenu`, which is the right primitive because a\nnavigation menu is *not* a menu: its rows are links, not commands, so it must\nnot take `role=\"menu\"` (which tells a screen reader to expect commands and\nswallows the browser's own link affordances). Hover intent, the shared\nresizing popup, focus handling and the landmark are all the primitive's.\n\nReach for {@link Menubar } when the entries run commands, `Tabs` when they\nswitch a panel in place, and `Sidebar` when the console has more than about\nsix destinations.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "List",
+    "Item",
+    "Trigger",
+    "Content",
+    "Link",
+    "Viewport"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "NavigationMenu.Root",
+      "description": "The navigation landmark. Renders a `<nav>` at the top level.\n\nGive it an `aria-label`: a page with more than one navigation landmark and no\nnames on them is a page a screen-reader user cannot navigate by landmark,\nwhich is the only reason the landmark exists.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the `<nav>`."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseNavigationMenu.Root.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "List",
+      "usage": "NavigationMenu.List",
+      "description": "The horizontal strip of top-level items. Renders a `<ul>`.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the strip of items."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseNavigationMenu.List.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Item",
+      "usage": "NavigationMenu.Item",
+      "description": "One top-level entry: a trigger with a panel, or a bare\n{@link NavigationMenuLink}. Renders an `<li>`.",
+      "props": [],
+      "typeReferences": [
+        "BaseNavigationMenu.Item.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "NavigationMenu.Trigger",
+      "description": "A top-level word that opens a panel.\n\nOpen is `accent-soft` plus full-strength ink — the same tint the active tab\nand the highlighted menu row use, never a solid accent block. The caret is a\nchild of the trigger rather than a sibling so it inherits the ink and rotates\nwith the open state for free.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the trigger."
+        },
+        {
+          "name": "caret",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Draw the caret that says a panel opens below. Defaults to `true`."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseNavigationMenu.Trigger.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "NavigationMenu.Content",
+      "description": "One item's panel. Only the open item's content is mounted into the shared\n{@link NavigationMenuViewport}, which is what lets the popup resize smoothly\nbetween items instead of one panel per popup.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the panel body."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseNavigationMenu.Content.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Link",
+      "usage": "NavigationMenu.Link",
+      "description": "One destination inside a panel.\n\nNever underlined at rest — the same rule as `Link` — because a panel of eight\nunderlined rows is a wall of rules. Hover moves the ink and the ground, which\nis louder and quieter at the same time.\n\nPass `render={<NextLink href=\"…\" />}` for client-side routing.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the link row."
+        },
+        {
+          "name": "active",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Mark this link as the current destination."
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "Supporting line under the label."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseNavigationMenu.Link.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Viewport",
+      "usage": "NavigationMenu.Viewport",
+      "description": "The single floating panel every item shares: portal, positioner, popup and\nviewport in one part.\n\nPut exactly one of these inside a {@link NavigationMenuRoot}, after the list.\nIt is one popup rather than one-per-item on purpose — that is what makes\nmoving between two open items a resize instead of a close-and-reopen — and it\nis portalled through {@link useCuePortalProps} so it carries the caller's\ntheme, density and mode.\n\nThe popup animates its own `width`/`height` from the `--popup-width` /\n`--popup-height` custom properties Base UI publishes as the active panel\nchanges.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the popup surface."
+        },
+        {
+          "name": "align",
+          "type": "\"center\" | \"end\" | \"start\"",
+          "required": false,
+          "defaultValue": "start",
+          "description": "Alignment along the bottom of the active trigger. Defaults to `\"start\"`."
+        },
+        {
+          "name": "positionerClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the positioner that places the popup."
+        },
+        {
+          "name": "sideOffset",
+          "type": "number | OffsetFunction",
+          "required": false,
+          "defaultValue": "4",
+          "description": "Gap in px between the strip and the popup. Defaults to `4`."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseNavigationMenu.Popup.Props, \"className\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The marketing-shaped navigation header: a strip of words, each opening a panel of destinations.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<NavigationMenu.Root aria-label=\"Console\">\n  <NavigationMenu.List>\n    <NavigationMenu.Item>\n      <NavigationMenu.Trigger>Patch</NavigationMenu.Trigger>\n      <NavigationMenu.Content>\n        <NavigationMenu.Link href=\"/patch/fixtures\" description=\"Everything addressed\">\n          Fixtures\n        </NavigationMenu.Link>\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n  </NavigationMenu.List>\n  <NavigationMenu.Viewport />\n</NavigationMenu.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/navigation-menu",
+  "mdUrl": "/docs/components/navigation-menu.md",
+  "jsonUrl": "/r/components/navigation-menu.json",
+  "specimens": [
+    {
+      "title": "NavigationMenu",
+      "group": "chrome",
+      "components": [
+        "NavigationMenu"
+      ],
+      "code": "<NavigationMenu.Root>\n  <NavigationMenu.List>\n    <NavigationMenu.Item>\n      <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>\n      <NavigationMenu.Content className=\"w-[20rem]\">\n        <NavigationMenu.Link href=\"#dmxhub\" description=\"Art-Net and sACN bridge.\">\n          dmxhub\n        </NavigationMenu.Link>\n        <NavigationMenu.Link href=\"#venu\" description=\"Show control.\" active>\n          VENU.studio\n        </NavigationMenu.Link>\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n    <NavigationMenu.Item>\n      <NavigationMenu.Trigger caret={false}>Docs</NavigationMenu.Trigger>\n      <NavigationMenu.Content className=\"w-[16rem]\">\n        <NavigationMenu.Link href=\"#tokens\">Tokens</NavigationMenu.Link>\n        <NavigationMenu.Link href=\"#components\">Components</NavigationMenu.Link>\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n  </NavigationMenu.List>\n  <NavigationMenu.Viewport />\n</NavigationMenu.Root>",
+      "note": "A menu bar whose panels are portalled through the stamping contract, so they keep the theme and density of the island they were opened from.",
+      "interaction": "hover opens after a short delay; Escape closes and returns focus to the trigger."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/node-card.json

@@ -0,0 +1,109 @@
+{
+  "name": "NodeCard",
+  "slug": "node-card",
+  "group": "flow",
+  "importPath": "@cueplusplus/ui/flow",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A node on a graph canvas, drawn in this system's language.\n\nFramed with an **outline, never a border**. React Flow is told a node's height\nup front — every layout that stacks nodes computes it — and a 1px border on\neach side makes the rendered box 2px taller than the number the layout used,\nwhich is how node stacks end up overlapping by a hairline that grows with the\nnode count. An outline is painted outside the box model entirely and costs\nnothing, so the formula and the DOM agree. `-outline-offset-1` then pulls it\nback inside the corner radius.\n\nThe frame's colour is the node's state (see `_frame.ts`): selected beats live\nbeats identity. When neither `tone` nor `state` is given the card paints no\ncolour of its own and inherits `--cue-node-frame` from the node wrapper, which\nis how `useFlowTheme().nodeStyles` colours a whole class of nodes at once.\n\nThe header band is the drag handle — pass\n`dragHandle: '[data-slot=\"node-card-header\"]'` on the node so a pointer inside\nthe body edits instead of dragging.\n\nNothing here imports `@xyflow/react`: a node card is a div, and the same card\ndraws a static diagram on a marketing page with no graph engine shipped. It\nalso never clips — handles straddle the rim, so an `overflow-hidden` in\n`className` would slice every connection point in half.",
+  "props": [
+    {
+      "name": "tone",
+      "type": "\"input\" | \"output\" | \"processing\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Where the node sits in the signal path. Inks the frame at rest."
+    },
+    {
+      "name": "state",
+      "type": "\"idle\" | \"selected\" | \"disabled\" | \"live\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the node is doing right now. Outranks `tone`.\n\nPass React Flow's own `selected` through:\n`state={selected ? \"selected\" : \"idle\"}`."
+    },
+    {
+      "name": "header",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The summary band: a label, a toggle, a badge. Also the drag handle."
+    },
+    {
+      "name": "expanded",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Whether the body is shown. Defaults to `true`; `false` renders the band alone."
+    },
+    {
+      "name": "onExpandedChange",
+      "type": "((expanded: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the requested state when the caret is clicked. Supplying it is\nwhat makes the caret appear — a card nobody can collapse should not offer to."
+    },
+    {
+      "name": "toggleLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the caret. Defaults to `\"Collapse\"` / `\"Expand\"`."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The body: rows, bars, fields. Full-bleed — rows own their own padding."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-info",
+    "--cue-node-frame",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-1",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "A node on a graph canvas, drawn in this system's language.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "function MergeNode({ selected }: NodeProps) {\n  const [open, setOpen] = React.useState(true);\n  return (\n    <NodeCard\n      tone=\"processing\"\n      state={selected ? \"selected\" : \"live\"}\n      header={<span className=\"truncate\">merge · universe 3</span>}\n      expanded={open}\n      onExpandedChange={setOpen}\n    >\n      <DmxBar data={frame} />\n    </NodeCard>\n  );\n}",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/node-card",
+  "mdUrl": "/docs/components/node-card.md",
+  "jsonUrl": "/r/components/node-card.json",
+  "specimens": [
+    {
+      "title": "NodeCard",
+      "group": "flow",
+      "components": [
+        "NodeCard"
+      ],
+      "code": "<Specimens>\n  {([\"input\", \"processing\", \"output\"] as const).map((tone) => (\n    <Specimen key={tone} label={tone}>\n      <NodeCard tone={tone} header={tone} className=\"w-[10rem]\">\n        <span className=\"font-mono text-(length:--cue-text-micro) text-fg-subtle\">\n          512 slots\n        </span>\n      </NodeCard>\n    </Specimen>\n  ))}\n  {([\"idle\", \"live\", \"selected\", \"disabled\"] as const).map((state) => (\n    <Specimen key={state} label={state}>\n      <NodeCard state={state} header={state} className=\"w-[10rem]\">\n        <StatusDot tone={state === \"live\" ? \"ok\" : \"idle\"} label={state} />\n      </NodeCard>\n    </Specimen>\n  ))}\n  <Specimen label=\"collapsed\">\n    <NodeCard header=\"Collapsible\" expanded={false} className=\"w-[10rem]\">\n      <span>Hidden body</span>\n    </NodeCard>\n  </Specimen>\n</Specimens>",
+      "note": "Framed with an outline rather than a border, so a node's rendered height is exactly the height the layout was told. The frame colour is the state: selected is `fg`, input is `info`, output and live are accent, idle is `fg-subtle`.",
+      "interaction": "the expand toggle is a real button; the frame colour changes with `state`, never with hover alone."
+    }
+  ],
+  "todo": true
+}