@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/terminal-frame.json

@@ -0,0 +1,119 @@
+{
+  "name": "TerminalFrame",
+  "slug": "terminal-frame",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A recessed terminal: mono, `$`-prefixed commands, optional typed playback.\n\nRecessed rather than raised — `bg-sunken` sits the transcript *into* the page\nthe way a real console does (the snuffle convention, where the terminal\nsurface is the only thing darker than the background).\n\nThe `simulate` player is deliberately not a GIF or a video: it is text, so it\ncopies, it scales with the type ramp, it re-themes, and it costs nothing to\nload. Keystrokes are jittered from a seed so a marketing screenshot is\nreproducible, and the whole animation is replaced by its final frame under\n`prefers-reduced-motion` — with no timers scheduled at all, rather than an\nanimation that runs invisibly.",
+  "props": [
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Name above the transcript — a log file, a host, a task."
+    },
+    {
+      "name": "lines",
+      "type": "readonly TerminalFrameLine[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Static transcript. Rendered as a preamble when `simulate` is also set."
+    },
+    {
+      "name": "prompt",
+      "type": "string",
+      "required": false,
+      "defaultValue": "$",
+      "description": "The prompt glyph in front of a command line. Defaults to `\"$\"`."
+    },
+    {
+      "name": "copy",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Show a `CopyButton` in the title bar for the commands in the transcript."
+    },
+    {
+      "name": "copyValue",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the copy button puts on the clipboard. Defaults to the command lines, one per line."
+    },
+    {
+      "name": "simulate",
+      "type": "TerminalScript",
+      "required": false,
+      "defaultValue": null,
+      "description": "Play the transcript out as a typed session.\n\nPass a stable reference (a module constant, or memoised) — the player\nrestarts whenever this prop changes identity. Under\n`prefers-reduced-motion` the finished transcript renders instantly and no\ntimer is ever scheduled."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Fixed body height in px at the 16px root. Leave unset to grow with the content."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra content under the transcript — an input row, a hint strip."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"title\" | \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-md",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-pad-row-x",
+    "--cue-radius-surface",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-label",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "A recessed terminal: mono, `$`-prefixed commands, optional typed playback.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<TerminalFrame\n  title=\"install\"\n  copy\n  lines={[{ text: \"pnpm add\nconst SCRIPT = { steps: [{ command: \"cue build\", pending: \"compiling\", output: [\"12 cues\"] }] };\n<TerminalFrame simulate={SCRIPT} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/terminal-frame",
+  "mdUrl": "/docs/components/terminal-frame.md",
+  "jsonUrl": "/r/components/terminal-frame.json",
+  "specimens": [
+    {
+      "title": "TerminalFrame",
+      "group": "instruments",
+      "components": [
+        "TerminalFrame"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <TerminalFrame\n    title=\"install\"\n    copy\n    lines={[\n      { text: \"pnpm add @cueplusplus/ui @cueplusplus/tokens\", command: true },\n      \"+ @cueplusplus/ui\",\n      \"+ @cueplusplus/tokens\",\n      { text: \"done in 1.4s\", tone: \"ok\" },\n    ]}\n  />\n  <TerminalFrame\n    title=\"patch\"\n    simulate={{\n      seed: 7,\n      keystrokeMs: 40,\n      steps: [\n        {\n          command: \"cue patch --universe 1 --profile s4\",\n          pending: \"resolving profile\",\n          pendingMs: 400,\n          output: [{ text: \"patched 8 channels\", tone: \"ok\" }],\n        },\n      ],\n    }}\n  />\n</div>",
+      "note": "A sunken mono frame with `$`-prefixed command lines and a copy affordance. `simulate` turns it into a typing player with jittered keystrokes.",
+      "interaction": "the reduced-motion path renders the finished transcript instantly rather than typing it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/textarea.json

@@ -0,0 +1,76 @@
+{
+  "name": "Textarea",
+  "slug": "textarea",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The multi-line text control.\n\nRendered through Base UI's `Field.Control`, so it joins a {@link Field } on the\nsame terms as {@link Input } — label wiring, `aria-describedby`, `data-invalid`\n— while still being a real `<textarea>`.\n\nWears the recessed chassis minus the fixed control height: a textarea's job is\nto be taller than one rung. Height comes from `rows`, and the user may drag it\ntaller (`resize-y`) but never wider, which would break the panel grid.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the chassis."
+    },
+    {
+      "name": "rows",
+      "type": "number",
+      "required": false,
+      "defaultValue": "3",
+      "description": "Visible rows before the box starts scrolling. Defaults to `3`."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"textarea\">"
+  ],
+  "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-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The multi-line text control.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Textarea placeholder=\"Notes for the operator\" />\n<Field><FieldLabel>Cue notes</FieldLabel><Textarea rows={6} /></Field>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/textarea",
+  "mdUrl": "/docs/components/textarea.md",
+  "jsonUrl": "/r/components/textarea.json",
+  "specimens": [
+    {
+      "title": "Textarea",
+      "group": "forms",
+      "components": [
+        "Textarea"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-3\">\n  <Textarea aria-label=\"Cue notes\" rows={3} defaultValue={\"House to half.\\nHold for VO.\"} />\n  <Textarea aria-label=\"Empty notes\" rows={3} placeholder=\"Notes for the operator\" />\n  <Textarea aria-label=\"Disabled notes\" rows={3} defaultValue=\"Read-only\" disabled />\n</div>",
+      "note": "The same chassis, grown to a block.",
+      "interaction": "same rim and ring as Input."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/theme-configurator.json

@@ -0,0 +1,124 @@
+{
+  "name": "ThemeConfigurator",
+  "slug": "theme-configurator",
+  "group": "configurator",
+  "importPath": "@cueplusplus/ui/configurator",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "The floating theme configurator: the panel that edits the design system it is\ndrawn with.\n\nIt is a **component**, not a devtool bolted onto the kitchensink — mount it in\nany app behind a flag and a designer can retune that app's theme in place. The\nwhole thing rests on one rule, and the rule is what keeps it from being a toy:\n*everything it does is a `--cue-*` declaration in one stylesheet.* No inline\nstyles on the root, no parallel token vocabulary, no runtime theme engine. The\nCSS it exports is byte for byte the CSS the page is wearing, which is the only\nreason the export dialog can promise a round trip at all.\n\nWhat it owns:\n\n- **Preset, mode and density** are the provider's, driven through `useTheme()`\n  so a switch restamps `<html>`, every portal, and the persisted preference.\n- **Colour, type and geometry overrides** go into\n  `<style id=\"cue-configurator-overrides\">`, scoped so they win where they\n  have to and lose where they should — the cascade reasoning is in\n  `_overrides.ts`, and it is the interesting part of this group.\n- **Text scale and root zoom**, the two relief valves the density ladder is\n  paired with.\n- **Its own placement**, furled state and every override, in `localStorage`\n  under one key.\n\nRenders in place as a `position: fixed` region, so mount it inside the\nprovider — it needs the theme context — but outside any transformed ancestor,\nwhich would turn `fixed` into `absolute` and take the panel with the page.",
+  "props": [
+    {
+      "name": "position",
+      "type": "\"floating\" | \"docked-right\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Placement, controlled. Pair with `onPositionChange`."
+    },
+    {
+      "name": "defaultPosition",
+      "type": "\"floating\" | \"docked-right\"",
+      "required": false,
+      "defaultValue": "floating",
+      "description": "Initial placement. A stored one wins. Defaults to `\"floating\"`."
+    },
+    {
+      "name": "onPositionChange",
+      "type": "((position: ConfiguratorPosition) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the user docks or floats the panel."
+    },
+    {
+      "name": "defaultCollapsed",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Start furled to the title bar. A stored value wins. Defaults to `false`."
+    },
+    {
+      "name": "storageKey",
+      "type": "string",
+      "required": false,
+      "defaultValue": "cue-configurator",
+      "description": "`localStorage` key holding the overrides, the placement and the zoom.\nDefaults to `\"cue-configurator\"`."
+    },
+    {
+      "name": "onChange",
+      "type": "((tokens: Record<string, string>) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the full resolved `--cue-*` map — never a diff — whenever the\noverrides, the theme or the mode change, and once on mount."
+    },
+    {
+      "name": "zoomShortcuts",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Bind ⌘/Ctrl with `+`, `-` and `0` to the zoom valve. Defaults to `true`."
+    },
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Theme",
+      "description": "Panel heading. Defaults to `\"Theme\"`."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the panel."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-lg",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-font-pairing-mono",
+    "--cue-font-sans",
+    "--cue-font-scale",
+    "--cue-font-theme-mono",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-scale",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The floating theme configurator: the panel that edits the design system it is drawn with.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ThemeProvider>\n  <App />\n  {devMode ? <ThemeConfigurator /> : null}\n</ThemeProvider>\n<ThemeConfigurator position=\"docked-right\" onChange={(tokens) => report(tokens)} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/theme-configurator",
+  "mdUrl": "/docs/components/theme-configurator.md",
+  "jsonUrl": "/r/components/theme-configurator.json",
+  "todo": true
+}

package/manifest/components/theme-provider.json

@@ -0,0 +1,134 @@
+{
+  "name": "ThemeProvider",
+  "slug": "theme-provider",
+  "group": "system",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`\nso the token layer resolves, puts `data-font` on `<html>`, publishes\n`--cue-font-scale`, and owns the persisted user preference.\n\nRendering: `<div data-cue-root data-theme data-density data-mode style={{ colorScheme, --cue-font-scale }}>`\n(or the single child when `asChild`). The `theme`/`density`/`font`/`mode` props are\n*initial* values — the provider holds the state so `setTheme` and friends can\ndrive it — but a changed prop is adopted after mount, so a controlling parent\nstill works.\n\nThe font pairing is the one axis that never lands on this element: it has no\nisland form, `<html>` is its only home, and restating it here would shadow the\npre-paint stamp for the whole page on the first frame. See the `stamp` object\nbelow.\n\nPersistence and the pre-paint contract: setters write\n`{ theme, density, font, mode }` to `localStorage[storageKey]`, which is exactly what\n{@link prepaintScript } reads to stamp `<html>` before the first paint. The\noutermost provider keeps `<html>` in sync while the app runs (and restores the\nprevious stamp on unmount) so the page ground, UA scrollbars and form controls\nfollow the theme; nested providers never touch `<html>`, and never own the\nfont pairing — `useTheme().font` and `setFont` inside one are the root's.",
+  "props": [
+    {
+      "name": "theme",
+      "type": "\"terminal\" | \"signal\" | \"cue\" | \"venu\" | \"hivehub\" | \"dusk\" | \"luma\" | \"snuffle\" | \"requestport\" | \"quotamate\"",
+      "required": false,
+      "defaultValue": "cue",
+      "description": "Initial theme preset. Defaults to `\"cue\"`. Changing it after mount adopts the new value."
+    },
+    {
+      "name": "density",
+      "type": "\"ultra-compact\" | \"compact\" | \"normal\" | \"large\" | \"ultra-large\"",
+      "required": false,
+      "defaultValue": "compact",
+      "description": "Initial density level. Defaults to `\"compact\"`."
+    },
+    {
+      "name": "mode",
+      "type": "\"system\" | \"dark\" | \"light\"",
+      "required": false,
+      "defaultValue": "dark",
+      "description": "Initial mode. Defaults to `\"dark\"`; `\"system\"` tracks `prefers-color-scheme`."
+    },
+    {
+      "name": "font",
+      "type": "\"source\" | \"system\" | \"geist\" | \"inter\" | \"plex\" | \"roboto\" | \"apple\" | \"office\"",
+      "required": false,
+      "defaultValue": "DEFAULT_FONT",
+      "description": "Initial font pairing. Defaults to `\"system\"` — the platform's own faces,\nnothing downloaded, and the theme keeps whatever monospace it authored.\n\nA pairing that needs delivering is a set of *names*: this library ships no\nfont files, and a pairing nobody delivers falls through its stack to the\nplatform rather than failing. See `FONT_PAIRINGS[font].faces` for the\ncustom properties an app assigns to make one resolve.\n\n**Root-level only.** There is no font island: a nested provider forwards\nthis axis to the root, ignores this prop, and its `setFont` drives the root.\nA page that changed face halfway down is a page with a bug, and a specimen\nthat genuinely wants one — a picker row, a docs page showing all eight —\nneeds nothing from this library but `data-font` on a `<div>`."
+    },
+    {
+      "name": "fontScale",
+      "type": "number",
+      "required": false,
+      "defaultValue": "1",
+      "description": "Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`."
+    },
+    {
+      "name": "fontFamilies",
+      "type": "FontFamilies",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional app-owned font stacks, published as inline CUE font custom properties."
+    },
+    {
+      "name": "storageKey",
+      "type": "string",
+      "required": false,
+      "defaultValue": "cue-ui",
+      "description": "localStorage key holding `{ theme, density, font, mode }`. Defaults to `\"cue-ui\"`.\nOnly the outermost provider reads or writes it — a nested provider is an\nisland whose explicit props are the point, not a second preference store."
+    },
+    {
+      "name": "persistPreferences",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Restore and write root preferences in localStorage. Defaults to `true`."
+    },
+    {
+      "name": "asChild",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Stamp the single child element instead of rendering a wrapper `<div>`."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the provider root."
+    },
+    {
+      "name": "style",
+      "type": "CSSProperties",
+      "required": false,
+      "defaultValue": null,
+      "description": "Inline styles for the provider root, merged after the token style."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The application subtree."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-font-mono",
+    "--cue-font-sans",
+    "--cue-font-scale"
+  ],
+  "summary": "The root that stamps theme, density and mode, and publishes the setters.",
+  "examples": [
+    {
+      "title": "The document root",
+      "code": "<html lang=\"en\" suppressHydrationWarning>\n  <head>\n    <script dangerouslySetInnerHTML={{ __html: prepaintScript() }} />\n  </head>\n  <body>\n    <ThemeProvider theme=\"terminal\" density=\"normal\">\n      {children}\n    </ThemeProvider>\n  </body>\n</html>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<ThemeProvider theme=\"terminal\" density=\"ultra-compact\" font=\"plex\" mode=\"system\">\n  <App />\n</ThemeProvider>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/theme-provider",
+  "mdUrl": "/docs/components/theme-provider.md",
+  "jsonUrl": "/r/components/theme-provider.json",
+  "whenToUse": [
+    "Once at the root of an app, around everything that renders a component.",
+    "Around a subtree that has to render in a fixed preset, such as a theme preview pane."
+  ],
+  "whenNotToUse": [
+    "Changing geometry for one region. Use `Density`, which stamps the density attribute and leaves colour alone.",
+    "Holding app state. It owns theme, density and mode, and nothing else."
+  ],
+  "commonMistakes": [
+    "Leaving `prepaintScript()` out of the document head, which paints the default theme for one frame and then flips.",
+    "Mounting two providers on the same `storageKey`, which makes them fight over the stored preference."
+  ]
+}

package/manifest/components/threshold-rail.json

@@ -0,0 +1,160 @@
+{
+  "name": "ThresholdRail",
+  "slug": "threshold-rail",
+  "group": "midi",
+  "importPath": "@cueplusplus/ui/midi",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The trigger level, set by dragging it along the signal it triggers on.\n\nA threshold is a number, and a number field would hold it perfectly well —\nbut a threshold is only ever chosen *relative to a signal*, and this control\nis the one place both are visible at once: the live level fills the rail, the\npeak-hold needle marks how far it got, and the handle sits where the trigger\nfires. Unified from ableton-sync's three near-identical threshold editors.\n\nTwo thresholds make it a window rather than a floor: supply `lower` and the\nrail arms *between* the handles, which is how a band-triggered cue avoids\nfiring on a peak it was never meant to catch.\n\nWhat the ports did not have is a keyboard. Their handles moved on `mousedown`\nplus a document listener, so a threshold could not be set by anyone not using\na mouse, and no screen reader was ever told what the number was. Here each\nhandle is a `role=\"slider\"` announcing a percentage, arrow keys step, page\nkeys jump, and Home/End go to the limits — the drag is the fast path, not the\nonly path.\n\nThe `onChange`/`onCommit` split is the same undo-coalescing contract as\n`Slider` and `ScrubInput`: one drag is one undo entry.",
+  "props": [
+    {
+      "name": "value",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "The (upper) threshold, `0`–`1`. Always controlled."
+    },
+    {
+      "name": "onChange",
+      "type": "(value: number) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the next upper threshold."
+    },
+    {
+      "name": "lower",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "The lower threshold. Supplying it turns the rail into a window."
+    },
+    {
+      "name": "onLowerChange",
+      "type": "((value: number) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the next lower threshold."
+    },
+    {
+      "name": "onCommit",
+      "type": "((thresholds: { upper: number; lower?: number; }) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called once per finished gesture with both thresholds: pointer-up after a\ndrag, or each key step. Hang undo entries and network writes here —\n`onChange` fires on every frame of a drag."
+    },
+    {
+      "name": "level",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Live signal level, `0`–`1`, drawn as a fill. Absent draws no fill."
+    },
+    {
+      "name": "peak",
+      "type": "number | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "Peak-hold position, `0`–`1`. `null` or absent draws no needle."
+    },
+    {
+      "name": "step",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0.01",
+      "description": "Grid the handles snap to. Defaults to `0.01`."
+    },
+    {
+      "name": "minGap",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0.01",
+      "description": "Closest the two handles may get. Defaults to `0.01`."
+    },
+    {
+      "name": "belowTone",
+      "type": "\"accent\" | \"danger\" | \"busy\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "danger",
+      "description": "Ink for the zones outside the window. Defaults to `\"danger\"`."
+    },
+    {
+      "name": "aboveTone",
+      "type": "\"accent\" | \"danger\" | \"busy\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "ok",
+      "description": "Ink for the armed zone. Defaults to `\"ok\"`."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Refuse every gesture."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Threshold",
+      "description": "What is being thresholded. Names the handles. Defaults to `\"Threshold\"`."
+    },
+    {
+      "name": "formatValue",
+      "type": "((value: number) => string)",
+      "required": false,
+      "defaultValue": "(fraction) => `${Math.round(fraction * 100)}%`",
+      "description": "Format a value for the handle's spoken text. Defaults to `\"62%\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onChange\" | \"defaultValue\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-busy",
+    "--cue-busy-soft",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-danger-soft",
+    "--cue-fg",
+    "--cue-info",
+    "--cue-info-soft",
+    "--cue-ok",
+    "--cue-ok-soft",
+    "--cue-sunken",
+    "--cue-warn",
+    "--cue-warn-soft"
+  ],
+  "summary": "The trigger level, set by dragging it along the signal it triggers on.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ThresholdRail value={threshold} onChange={setThreshold} level={rms} peak={peak} />\n<ThresholdRail value={high} lower={low} onChange={setHigh} onLowerChange={setLow} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/threshold-rail",
+  "mdUrl": "/docs/components/threshold-rail.md",
+  "jsonUrl": "/r/components/threshold-rail.json",
+  "specimens": [
+    {
+      "title": "ThresholdRail",
+      "group": "midi",
+      "components": [
+        "ThresholdRail"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-6)\">\n  <ThresholdRail\n    value={upper}\n    onChange={setUpper}\n    lower={lower}\n    onLowerChange={setLower}\n    level={0.58}\n    peak={0.81}\n    label=\"Trigger thresholds\"\n  />\n  <ThresholdRail\n    value={upper}\n    onChange={setUpper}\n    level={0.34}\n    belowTone=\"info\"\n    aboveTone=\"danger\"\n    label=\"Single threshold\"\n  />\n  <ThresholdRail value={0.6} onChange={() => {}} disabled label=\"Threshold, locked\" />\n</div>",
+      "note": "A dual-handle rail with tone zones below and above, a level bar and a peak-hold needle.",
+      "interaction": "each handle is a slider with its own name; both scale up while dragging, and `onCommit` fires once on release."
+    }
+  ],
+  "todo": true
+}