@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/tree.json

@@ -0,0 +1,140 @@
+{
+  "name": "Tree",
+  "slug": "tree",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A hierarchical outline: a rig, a scene graph, a folder of shows.\n\nHand-built rather than wrapped, because the pattern's whole cost is in three\ndetails no primitive here provides together:\n\n- **Roving tabindex.** The tree is one tab stop; the arrow keys move inside\n  it. Eighty rows must never mean eighty presses of Tab.\n- **A flat DOM.** Rows carry `aria-level` / `aria-posinset` / `aria-setsize`\n  instead of nesting `role=\"group\"` wrappers, which is both valid ARIA and the\n  shape a virtualizer needs when the outline grows past a screenful.\n- **The gutter.** `└ ├ │` in the mono grid, `aria-hidden` — structure you can\n  see at a glance without indentation alone having to carry it.\n\nSelection is a tint (`accent-soft` ground, accent ink), never a solid fill —\nthe same ruling as the sidebar item and the active tab.",
+  "props": [
+    {
+      "name": "items",
+      "type": "readonly TreeItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The roots, in display order."
+    },
+    {
+      "name": "expanded",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Expanded ids when controlled. Pass with `onExpandedChange`."
+    },
+    {
+      "name": "defaultExpanded",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initially expanded ids when uncontrolled."
+    },
+    {
+      "name": "onExpandedChange",
+      "type": "((expanded: string[]) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the whole next expanded set whenever a row is folded or unfolded."
+    },
+    {
+      "name": "selected",
+      "type": "string | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "Selected id when controlled. Pass with `onSelect`."
+    },
+    {
+      "name": "defaultSelected",
+      "type": "string | null",
+      "required": false,
+      "defaultValue": "null",
+      "description": "Initially selected id when uncontrolled."
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the id of the row the user selected."
+    },
+    {
+      "name": "renderRow",
+      "type": "((row: TreeRow) => ReactNode)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace the *body* of a row — the icon, label and badge.\n\nThe row element itself, its ARIA, its tab index and its indent gutter stay\nwith the component on purpose: those are the parts a call site cannot get\nwrong without breaking keyboard navigation for everyone."
+    },
+    {
+      "name": "rowControls",
+      "type": "((item: TreeItem, row: TreeRow) => ReactNode)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Controls hung off the right of each row, revealed on hover or focus.\n\nThis is where the three-state visibility idiom goes — see\n{@link TreeVisibilityToggle} — along with focus, rename and delete\naffordances. Anything essential belongs in the row body or a context menu\ninstead: hover-revealed controls are invisible on touch."
+    },
+    {
+      "name": "guides",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Draw the box-drawing indent gutter. Defaults to `true`."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the tree. Required in practice — name what it lists."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onSelect\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-info",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-surface-2",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "A hierarchical outline: a rig, a scene graph, a folder of shows.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Tree\n  aria-label=\"Rig\"\n  items={rig}\n  selected={selected}\n  onSelect={setSelected}\n  rowControls={(item) => (\n    <TreeVisibilityToggle value={visibility[item.id]} onValueChange={set(item.id)} />\n  )}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/tree",
+  "mdUrl": "/docs/components/tree.md",
+  "jsonUrl": "/r/components/tree.json",
+  "specimens": [
+    {
+      "title": "Tree",
+      "group": "chrome",
+      "components": [
+        "Tree",
+        "TreeVisibilityToggle"
+      ],
+      "code": "<Panel className=\"w-full max-w-[30rem] p-(--cue-space-2)\">\n  <Tree\n    items={TREE_ITEMS}\n    expanded={expanded}\n    onExpandedChange={setExpanded}\n    selected={selected}\n    onSelect={setSelected}\n    rowControls={(item) => (\n      <TreeVisibilityToggle\n        value={visibility[item.id] ?? \"visible\"}\n        onValueChange={(next) =>\n          setVisibility((current) => ({ ...current, [item.id]: next }))\n        }\n      />\n    )}\n  />\n</Panel>",
+      "note": "Roving tabindex, `└` indent guides, a hover-revealed control slot and the three-state visibility toggle.",
+      "interaction": "arrow keys move and expand, Enter selects; the row controls appear on hover and stay put for keyboard users."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/two-step-button.json

@@ -0,0 +1,113 @@
+{
+  "name": "TwoStepButton",
+  "slug": "two-step-button",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Arm, then confirm: a destructive action that takes two deliberate presses.\n\nThe most-reused interaction in the portfolio (fifteen call sites, three\nhand-rolled implementations) and the right shape for a destructive action\nthat is *routine* — deleting a cue, clearing a patch. A modal\n`AlertDialog` is the right shape for a rare and expensive one; putting a\ndialog in front of an action people take twenty times an hour just teaches\nthem to dismiss dialogs.\n\nFour ways out, because an armed button left lying around is a trap: Cancel,\nEscape, moving focus away, and a timeout. Focus lands on **Cancel** when the\npair arms, never on the destructive half — the same ruling as a destructive\ndialog's default button, and it means a stuck Enter key cannot walk through\nboth steps.",
+  "props": [
+    {
+      "name": "onConfirm",
+      "type": "() => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Fired once, when the *second* press lands."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The idle label — name the action, not the button (\"Delete rig\", not \"Delete\")."
+    },
+    {
+      "name": "confirmLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Confirm",
+      "description": "Label on the armed half. Defaults to `\"Confirm\"`."
+    },
+    {
+      "name": "cancelLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Cancel",
+      "description": "Label on the escape hatch. Defaults to `\"Cancel\"`."
+    },
+    {
+      "name": "tone",
+      "type": "\"danger\" | \"warn\"",
+      "required": false,
+      "defaultValue": "danger",
+      "description": "How severe this is. Defaults to `\"danger\"`."
+    },
+    {
+      "name": "timeout",
+      "type": "number",
+      "required": false,
+      "defaultValue": "4000",
+      "description": "ms before an untouched armed state disarms itself. `0` disables. Defaults to `4000`."
+    },
+    {
+      "name": "onArmedChange",
+      "type": "((armed: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the new armed state on every arm and disarm."
+    },
+    {
+      "name": "render",
+      "type": "RenderProp<Record<string, unknown>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace the rendered element (Base UI render prop). Accepts an element —\n`render={<a href=\"/x\" />}` — or a function returning one. When set, the\ndefault `type=\"button\"` is dropped so non-button elements stay valid."
+    },
+    {
+      "name": "icon",
+      "type": "ElementType<any, keyof IntrinsicElements>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional leading icon component (e.g. a lucide icon). Rendered\n`aria-hidden` and sized to the density icon token, so it tracks the density\nlevel without the caller passing a pixel size."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ButtonProps, \"onClick\" | \"variant\" | \"onConfirm\" | \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-danger-fg",
+    "--cue-space-2",
+    "--cue-warn",
+    "--cue-warn-fg"
+  ],
+  "summary": "Arm, then confirm: a destructive action that takes two deliberate presses.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<TwoStepButton onConfirm={() => deleteRig(id)}>Delete rig</TwoStepButton>\n<TwoStepButton tone=\"warn\" timeout={0} confirmLabel=\"Reset it\" onConfirm={reset}>\n  Reset patch\n</TwoStepButton>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/two-step-button",
+  "mdUrl": "/docs/components/two-step-button.md",
+  "jsonUrl": "/r/components/two-step-button.json",
+  "specimens": [
+    {
+      "title": "TwoStepButton",
+      "group": "instruments",
+      "components": [
+        "TwoStepButton"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"danger\">\n    <TwoStepButton\n      tone=\"danger\"\n      onConfirm={() => setConfirmed((count) => count + 1)}\n      confirmLabel={COPY.destructive.action}\n    >\n      {COPY.destructive.action}\n    </TwoStepButton>\n  </Specimen>\n  <Specimen label=\"warn\">\n    <TwoStepButton tone=\"warn\" onConfirm={() => setConfirmed((count) => count + 1)}>\n      Reset patch\n    </TwoStepButton>\n  </Specimen>\n  <Specimen label=\"short timeout\">\n    <TwoStepButton timeout={2000} onConfirm={() => setConfirmed((count) => count + 1)}>\n      Unpatch all\n    </TwoStepButton>\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <TwoStepButton disabled onConfirm={() => {}}>\n      Unpatch all\n    </TwoStepButton>\n  </Specimen>\n  <Specimen label=\"confirmed\">\n    <Chip tone={confirmed === 0 ? \"neutral\" : \"ok\"}>{confirmed} confirmed</Chip>\n  </Specimen>\n</Specimens>",
+      "note": "Arm, then confirm. The portfolio's most-reused interaction, unified from three upstream implementations.",
+      "interaction": "Escape, blur and the timeout all disarm; the armed state shows a visible Cancel next to a tone-solid confirm."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/universe-grid.json

@@ -0,0 +1,127 @@
+{
+  "name": "UniverseGrid",
+  "slug": "universe-grid",
+  "group": "dmx",
+  "importPath": "@cueplusplus/ui/dmx",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A universe as 512 slots of occupancy: who holds what, and where two fixtures\nwere given the same address.\n\nPorted from stagetool's patching panel, which is the only audited product with\na real patch model behind it. What it draws is deliberately not a table:\n\n- **Position is the address.** A block's left edge *is* channel `start`, so the\n  shape of a patch — the gaps, the drift, the fixture that starts at 497 —\n  reads without anyone counting.\n- **A one-channel fixture is still visible.** Blocks have a two-pixel floor,\n  which is the whole reason the bar can honestly claim to show everything\n  patched.\n- **A conflict is drawn twice.** Both offending blocks get a danger ring *and*\n  the contested slots get a band, because \"these two overlap\" and \"here is\n  where\" are two different questions.\n\nAccessibility follows the `GroupBar` rule: colour is never the only channel.\nWithout `onSelect` the bar is one `role=\"img\"` whose name spells the whole\npatch out; with it, each block becomes a named button and the bar becomes a\ngroup.",
+  "props": [
+    {
+      "name": "allocations",
+      "type": "readonly DmxAllocation[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The patch. Order is display order; overlaps are found, not assumed away."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Which universe this is. Names the graphic; also the group label when selectable."
+    },
+    {
+      "name": "slots",
+      "type": "number",
+      "required": false,
+      "defaultValue": "512",
+      "description": "Frame length. Defaults to a full universe of 512."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "18",
+      "description": "Bar height in px at the 16px root, emitted as `rem`. Defaults to `18`."
+    },
+    {
+      "name": "ruler",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Draw the address ruler. Defaults to `true`."
+    },
+    {
+      "name": "legend",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Draw the legend row. Defaults to `true`."
+    },
+    {
+      "name": "legendMax",
+      "type": "number",
+      "required": false,
+      "defaultValue": "6",
+      "description": "Legend entries before the tail collapses. Defaults to `6`."
+    },
+    {
+      "name": "onSelect",
+      "type": "((allocation: DmxAllocation) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Make the blocks buttons. Without it they are decoration inside one\n`role=\"img\"`, which is what keeps a 40-fixture patch from becoming 40 tab\nstops."
+    },
+    {
+      "name": "emptyLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "No patch assignments",
+      "description": "What to say when nothing is patched. Defaults to `\"No patch assignments\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"onSelect\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-busy",
+    "--cue-danger",
+    "--cue-danger-soft",
+    "--cue-data-ground",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-warn"
+  ],
+  "summary": "A universe as 512 slots of occupancy: who holds what, and where two fixtures were given the same address.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<UniverseGrid\n  label=\"Universe 1\"\n  allocations={[\n    { label: \"wash\", start: 1, size: 24, tone: \"accent\" },\n    { label: \"movers\", start: 129, size: 32, tone: \"info\" },\n  ]}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/universe-grid",
+  "mdUrl": "/docs/components/universe-grid.md",
+  "jsonUrl": "/r/components/universe-grid.json",
+  "specimens": [
+    {
+      "title": "UniverseGrid",
+      "group": "dmx",
+      "components": [
+        "UniverseGrid"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-5)\">\n  <UniverseGrid allocations={ALLOCATIONS} label=\"Universe 1 patch\" />\n  <UniverseGrid\n    allocations={[\n      { label: \"Front truss\", start: 1, size: 48, tone: \"accent\" },\n      { label: \"Movers\", start: 40, size: 32, tone: \"info\" },\n    ]}\n    label=\"Universe 2 patch, with a conflict\"\n  />\n  <UniverseGrid allocations={[]} label=\"Universe 3 patch\" emptyLabel={COPY.empty.title} />\n  <UniverseGrid\n    allocations={ALLOCATIONS}\n    ruler={false}\n    legend={false}\n    height={10}\n    label=\"Universe 1 patch, bare\"\n  />\n</div>",
+      "note": "512 slots of occupancy: minimum 2px slivers so a two-channel fixture is still visible, a conflict ring where two allocations overlap, a tick ruler at 1/64/…/512 and a legend that folds to `+N more`.",
+      "interaction": "each block is a button; the accessible name spells the whole patch out, so the picture is not the only channel."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/usage-chart.json

@@ -0,0 +1,124 @@
+{
+  "name": "UsageChart",
+  "slug": "usage-chart",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A quota trace: where you sit against the ceiling, over time.\n\nDependency-free inline SVG — a charting library is a large price for one\nline and five gridlines, and none of them draws the three things that make\nthis chart honest:\n\n1. **The y axis is always 0–100.** A quota chart auto-scaled to its own range\n   makes a flat 3% look identical to a flat 95%. The ceiling is the reading,\n   so the ceiling is always drawn.\n2. **Gaps are gaps.** When the sweep does not run, the line breaks. Joining\n   across a hole invents data — and worse, invents a *smooth* trend across\n   exactly the window nothing is known about. The area fill stops at the\n   break for the same reason.\n3. **Out-of-range values are clamped, not plotted.** Upstream numbers are\n   reverse-engineered and can be anything; 140% should read as a flat line on\n   the ceiling, not as a path drawn over the axis labels.",
+  "props": [
+    {
+      "name": "points",
+      "type": "readonly UsageChartPoint[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The series. Sorted and cleaned internally; order in is not order out."
+    },
+    {
+      "name": "tone",
+      "type": "\"accent\" | \"danger\" | \"busy\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "accent",
+      "description": "Stroke tone. Defaults to `\"accent\"`."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "120",
+      "description": "Plot height in px at the 16px root. Defaults to `120`."
+    },
+    {
+      "name": "gapMs",
+      "type": "number",
+      "required": false,
+      "defaultValue": "15 * 60 * 1000",
+      "description": "Break the line when consecutive samples are further apart than this, in ms."
+    },
+    {
+      "name": "threshold",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Draw a dashed rule at this percentage — where throttling starts, say."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The accessible name. Name the series; the shape is not self-describing."
+    },
+    {
+      "name": "emptyLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "No data yet",
+      "description": "What to say when there is nothing to plot. Defaults to `\"No data yet\"`."
+    },
+    {
+      "name": "formatTimestamp",
+      "type": "((t: number) => string)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Format a sample's timestamp for the tooltip. Defaults to a short local date-time."
+    },
+    {
+      "name": "formatValue",
+      "type": "((v: number) => string)",
+      "required": false,
+      "defaultValue": "(value) => `${Math.round(value)}%`",
+      "description": "Format a sample's value for the tooltip. Defaults to `\"87%\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-busy",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-3",
+    "--cue-surface-2",
+    "--cue-text-label",
+    "--cue-warn"
+  ],
+  "summary": "A quota trace: where you sit against the ceiling, over time.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<UsageChart label=\"API requests\" points={series} threshold={80} tone=\"warn\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/usage-chart",
+  "mdUrl": "/docs/components/usage-chart.md",
+  "jsonUrl": "/r/components/usage-chart.json",
+  "specimens": [
+    {
+      "title": "UsageChart",
+      "group": "instruments",
+      "components": [
+        "UsageChart"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <UsageChart points={USAGE} gapMs={2 * MINUTE} threshold={80} label=\"Output level\" />\n  <UsageChart points={[]} label=\"No samples\" emptyLabel={COPY.empty.title} />\n</div>",
+      "note": "A dependency-free SVG chart pinned to 0–100, with gap-aware path segmentation: a hole in the data is a hole in the line, not a straight edge across it.",
+      "interaction": "hover draws a crosshair at the nearest point and a tooltip chip; the whole chart carries a text summary for readers who get no hover."
+    }
+  ],
+  "todo": true
+}