@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/meter.json

@@ -0,0 +1,114 @@
+{
+  "name": "Meter",
+  "slug": "meter",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A quota bar that shows **pace**, not just fill.\n\nA bare percentage answers \"how much is gone\" but not the question that\nactually matters: *will it last*. 93% used is fine in the last hour of a\nweekly window and an emergency on the first day. So the meter carries a\nsecond mark — how far through the window we are in time — and reads the two\ntogether: fill ahead of the tick is burning faster than the window refills.\n\nThe tick is deliberately quiet: a 1px rule, not a second bar. It annotates\nthe fill and stays ignorable when someone only wants the number.\n\nSeverity is never invented here — `tone` comes from whoever owns the\nthresholds. Likewise `provenance`: the bar changes its own texture rather\nthan letting an estimate or a missing denominator look like a measurement.\n\nThe over-pace pulse stills under `prefers-reduced-motion`; the state stays\nreadable as `data-over-pace`.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "percent",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How full, 0–100. Clamped; a non-finite value reads as 0."
+    },
+    {
+      "name": "tone",
+      "type": "\"danger\" | \"busy\" | \"ok\" | \"warn\"",
+      "required": false,
+      "defaultValue": "ok",
+      "description": "Status colour for the fill. Defaults to `\"ok\"`."
+    },
+    {
+      "name": "paceTick",
+      "type": "number | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "How far through the window we are *by time*, 0–1. Drawn as a 1px rule\nacross the bar so the fill can be read against its pace: fill ahead of the\ntick means burning faster than the window refills. Pass `null` when there\nis no window."
+    },
+    {
+      "name": "empty",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Render the striped \"no data\" treatment instead of a level."
+    },
+    {
+      "name": "provenance",
+      "type": "\"none\" | \"vendor\" | \"estimated\" | \"unbounded\"",
+      "required": false,
+      "defaultValue": "vendor",
+      "description": "Where the ceiling came from. Defaults to `\"vendor\"`."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "4",
+      "description": "Bar height in px at the 16px root, emitted as `rem`. Defaults to `4`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Usage",
+      "description": "The accessible name. A meter is nearly always a usage readout, so that is\nthe default; override it for anything else. When there is no level to\nreport (`empty`, or an unbounded ceiling) the state is appended to it, as\nin `\"Usage: No data\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-border",
+    "--cue-busy",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-ok",
+    "--cue-surface-3",
+    "--cue-warn"
+  ],
+  "summary": "A quota bar that shows pace, not just fill.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Meter percent={72} tone=\"warn\" paceTick={0.5} />\n<Meter percent={0} empty label=\"Requests this month\" />\n<Meter percent={40} provenance=\"estimated\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/meter",
+  "mdUrl": "/docs/components/meter.md",
+  "jsonUrl": "/r/components/meter.json",
+  "whenToUse": [
+    "A bounded quantity against a ceiling: quota used, storage, a dimmer level.",
+    "When the reader needs to know whether usage is ahead of the clock. Pass `paceTick`."
+  ],
+  "whenNotToUse": [
+    "How far a task has got. Use `Progress`.",
+    "A number with no ceiling. Use `Stat`.",
+    "A value over time. Use `Sparkline` or `UsageChart`."
+  ],
+  "commonMistakes": [
+    "Passing a fraction. `percent` is 0-100, not 0-1.",
+    "Leaving `provenance` at `vendor` for a ceiling somebody typed. `estimated` hatches the bar, which is what keeps a guess from wearing the authority of a reported number."
+  ],
+  "specimens": [
+    {
+      "title": "Meter",
+      "group": "instruments",
+      "components": [
+        "Meter"
+      ],
+      "code": "<Panel className=\"w-full max-w-[36rem]\">\n  {CHANNELS.map((channel) => (\n    <Row key={channel.name} className=\"gap-(--cue-space-4)\">\n      <span className=\"w-[7rem] shrink-0 truncate\">{channel.name}</span>\n      <Meter percent={channel.level} tone={channel.tone} className=\"flex-1\" />\n      <span className=\"w-[3rem] shrink-0 text-right font-mono tabular-nums\">\n        {channel.level}%\n      </span>\n    </Row>\n  ))}\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">Pace tick</span>\n    <Meter percent={64} paceTick={50} className=\"flex-1\" label=\"64% used, 50% of period elapsed\" />\n  </Row>\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">Estimated</span>\n    <Meter percent={40} provenance=\"estimated\" className=\"flex-1\" />\n  </Row>\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">Unbounded</span>\n    <Meter percent={0} provenance=\"unbounded\" className=\"flex-1\" />\n  </Row>\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">No data</span>\n    <Meter percent={0} empty className=\"flex-1\" />\n  </Row>\n</Panel>",
+      "note": "Never invents a number: an unbounded meter draws no percentage, an empty one draws stripes rather than a zero, and an estimated ceiling is hatched so it cannot pass for a measurement.",
+      "interaction": "the over-pace pulse stills under prefers-reduced-motion and stays readable as a data attribute."
+    }
+  ]
+}

package/manifest/components/mobile-composer.json

@@ -0,0 +1,126 @@
+{
+  "name": "MobileComposer",
+  "slug": "mobile-composer",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The bottom sheet: keyboard-aware, quick actions above, thumb-sized targets.",
+  "props": [
+    {
+      "name": "value",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current input. The field is 16px so iOS does not zoom on focus."
+    },
+    {
+      "name": "keyboardOpen",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Collapses the quick actions and the home indicator inset when the keyboard is up."
+    },
+    {
+      "name": "running",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Swaps send for stop, and suppresses Return-to-send while a run is in flight."
+    },
+    {
+      "name": "actions",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Quick actions above the field, scrolled horizontally."
+    },
+    {
+      "name": "onAction",
+      "type": "((action: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a quick action is tapped. Omit it and the chips render disabled, since\nactions is required and the row would otherwise be inert."
+    },
+    {
+      "name": "onAttach",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the attachment control. Omit it and the control renders disabled."
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called as the message is typed."
+    },
+    {
+      "name": "onSend",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to send."
+    },
+    {
+      "name": "onStop",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to stop a run in flight."
+    },
+    {
+      "name": "onFocus",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the field takes focus; drive keyboardOpen from it."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"value\"\n  | \"keyboardOpen\"\n  | \"running\"\n  | \"actions\"\n  | \"onAction\"\n  | \"onAttach\"\n  | \"onValueChange\"\n  | \"onSend\"\n  | \"onStop\"\n  | \"onFocus\"\n> & {\n  /** Current input. The field is 16px so iOS does not zoom on focus. */\n  value: string;\n  /** Collapses the quick actions and the home indicator inset when the keyboard is up. */\n  keyboardOpen: boolean;\n  /** Swaps send for stop, and suppresses Return-to-send while a run is in flight. */\n  running: boolean;\n  /** Quick actions above the field, scrolled horizontally. */\n  actions: readonly string[];\n  /**\n   * Called when a quick action is tapped. Omit it and the chips render disabled, since\n   * actions is required and the row would otherwise be inert.\n   */\n  onAction?: (action: string) => void;\n  /** Called from the attachment control. Omit it and the control renders disabled. */\n  onAttach?: () => void;\n  /** Called as the message is typed. */\n  onValueChange?: (value: string) => void;\n  /** Called to send. */\n  onSend?: () => void;\n  /** Called to stop a run in flight. */\n  onStop?: () => void;\n  /** Called when the field takes focus; drive keyboardOpen from it. */\n  onFocus?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-3",
+    "--cue-text-emphasis",
+    "--cue-text-ui"
+  ],
+  "summary": "The bottom sheet: keyboard-aware, quick actions above, thumb-sized targets.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { MobileComposer } from \"@cueplusplus/ui/elements\";\n\n<MobileComposer\n  value={value}\n  keyboardOpen={keyboardOpen}\n  running={false}\n  actions={actions}\n  onValueChange={setValue}\n  onSend={send}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/mobile-composer",
+  "mdUrl": "/docs/components/mobile-composer.md",
+  "jsonUrl": "/r/components/mobile-composer.json",
+  "specimens": [
+    {
+      "title": "MobileComposer",
+      "group": "elements-composer",
+      "components": [
+        "MobileComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"keyboard down\" wide>\n    <MobileComposer\n      value={phone}\n      keyboardOpen={false}\n      running={false}\n      actions={[\"Patch\", \"Plot\", \"Rig check\", \"Render pre-vis\"]}\n      onAction={(action) => setPhone(action)}\n      onAttach={() => undefined}\n      onValueChange={setPhone}\n      onSend={() => setPhone(\"\")}\n    />\n  </Specimen>\n  <Specimen label=\"keyboard up\" wide>\n    <MobileComposer\n      value=\"six ESPRITEs on universe 3\"\n      keyboardOpen\n      running={false}\n      actions={[\"Patch\", \"Plot\"]}\n      onValueChange={() => undefined}\n      onSend={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"running\" wide>\n    <MobileComposer\n      value=\"\"\n      keyboardOpen\n      running\n      actions={[\"Patch\", \"Plot\"]}\n      onStop={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The same composer on a phone: a bottom sheet with thumb-sized targets, quick actions scrolling above the field, and a 16px input so iOS does not zoom when it takes focus. `keyboardOpen` is the whole layout switch — the quick actions and the home-indicator inset both belong to the state where the keyboard is down.",
+      "interaction": "send becomes stop while a run is in flight, and Return stops sending — a second send during a stream is almost always a mistake, so the element refuses it rather than queueing it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/model-picker.json

@@ -0,0 +1,76 @@
+{
+  "name": "ModelPicker",
+  "slug": "model-picker",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The full list rather than the rail: grouped by family, priced, with what each one\ncan do.",
+  "props": [
+    {
+      "name": "models",
+      "type": "readonly PickableModel[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Every model on offer. Families are derived from the entries and keep their\nfirst-seen order."
+    },
+    {
+      "name": "selectedId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which model is active."
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a model is picked."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"models\" | \"selectedId\" | \"onSelect\"\n> & {\n  /**\n   * Every model on offer. Families are derived from the entries and keep their\n   * first-seen order.\n   */\n  models: readonly PickableModel[];\n  /** Which model is active. */\n  selectedId: string;\n  /** Called when a model is picked. */\n  onSelect?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "The full list rather than the rail: grouped by family, priced, with what each one can do.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ModelPicker } from \"@cueplusplus/ui/elements\";\n\n<ModelPicker models={models} selectedId={selectedId} onSelect={setSelectedId} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/model-picker",
+  "mdUrl": "/docs/components/model-picker.md",
+  "jsonUrl": "/r/components/model-picker.json",
+  "specimens": [
+    {
+      "title": "ModelPicker",
+      "group": "elements-composer",
+      "components": [
+        "ModelPicker"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"two families\" wide>\n    <ModelPicker models={PICKABLE} selectedId={pickedModel} onSelect={setPickedModel} />\n  </Specimen>\n  <Specimen label=\"one family, nothing chosen\" wide>\n    <ModelPicker models={PICKABLE.slice(0, 3)} selectedId=\"\" />\n  </Specimen>\n</Specimens>",
+      "note": "The full list rather than the rail: grouped by family, priced, and carrying what each one can actually do. This is the screen `ComposerModelTrigger` is a shortcut to, and the split is the point — the toolbar menu is for switching between models you already chose between, and this is where that choosing happens.",
+      "interaction": "each row is `aria-pressed`, which is the honest role for a control that stays chosen rather than performing an action once."
+    }
+  ],
+  "todo": true
+}

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
+}