@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/drawer.json

@@ -0,0 +1,179 @@
+{
+  "name": "Drawer",
+  "slug": "drawer",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A swipe-dismissable edge panel — the touch-first cousin of {@link Sheet }.\n\nWraps Base UI's `Drawer`, so the drag tracking, the velocity-aware dismissal,\nthe nested-drawer stacking and the focus trap are the primitive's. What this\nlayer adds is the shared overlay surface, the portal theme stamp, and one\ndecision the caller should not have to make twice: `swipeDirection` picks the\nedge *and* the gesture together, so a drawer can never be dragged in a\ndirection that would push it further onto the screen.\n\nPrefer `Sheet` on a pointer-first console — a swipe is not discoverable with a\nmouse — and reach for this on touch, or wherever the panel is glanceable\nenough that dismissing it should cost one gesture.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Trigger",
+    "Content",
+    "Title",
+    "Description",
+    "Footer",
+    "Close"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Drawer.Root",
+      "description": "Groups the parts of a drawer and owns its open state. Renders no element.",
+      "props": [
+        {
+          "name": "swipeDirection",
+          "type": "\"up\" | \"down\" | \"left\" | \"right\"",
+          "required": false,
+          "defaultValue": "down",
+          "description": "Which way the drawer is dragged to dismiss it, which also decides the edge\nit lives on. Defaults to `\"down\"` — the bottom sheet."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseDrawer.Root.Props, \"swipeDirection\">"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "Drawer.Trigger",
+      "description": "The control that opens the drawer. Unstyled — pass `render={<Button />}` so\nthe button's own variant classes stay the last word.",
+      "props": [],
+      "typeReferences": [
+        "BaseDrawer.Trigger.Props"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "Drawer.Content",
+      "description": "The drawer's portal, scrim, viewport and popup in one part.\n\nPortalled through {@link useCuePortalProps}, so the surface carries the\ncaller's theme, density and mode even though it mounts at the end of\n`<body>`. The swipe gesture, the rubber-banding, the velocity-aware dismissal\nand the focus trap are all Base UI's; this layer supplies the edge geometry\nand the token skin.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the popup surface."
+        },
+        {
+          "name": "keepMounted",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Keep the popup mounted while closed, so its content is not re-created."
+        },
+        {
+          "name": "viewportClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the full-viewport box that parks the popup on its edge."
+        },
+        {
+          "name": "backdropClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the scrim behind it."
+        },
+        {
+          "name": "grabHandle",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Draw the grab bar that advertises the swipe. Defaults to `true`.\n\nPurely decorative — the whole popup is draggable — so it is `aria-hidden`\nand there is no keyboard equivalent to lose by turning it off."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseDrawer.Popup.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Title",
+      "usage": "Drawer.Title",
+      "description": "The drawer's heading, wired to the popup's `aria-labelledby`.",
+      "props": [],
+      "typeReferences": [
+        "BaseDrawer.Title.Props"
+      ]
+    },
+    {
+      "name": "Description",
+      "usage": "Drawer.Description",
+      "description": "The supporting line under the title, published as `aria-describedby`.",
+      "props": [],
+      "typeReferences": [
+        "BaseDrawer.Description.Props"
+      ]
+    },
+    {
+      "name": "Footer",
+      "usage": "Drawer.Footer",
+      "description": "The action strip at the foot of the drawer.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Close",
+      "usage": "Drawer.Close",
+      "description": "A control that closes the drawer. Unstyled — wrap it in a `Button`.",
+      "props": [],
+      "typeReferences": [
+        "BaseDrawer.Close.Props"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-border-strong",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-6",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A swipe-dismissable edge panel — the touch-first cousin of {@link Sheet }.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Drawer.Root swipeDirection=\"down\">\n  <Drawer.Trigger render={<Button>Cue stack</Button>} />\n  <Drawer.Content>\n    <Drawer.Title>Cue stack</Drawer.Title>\n    <Drawer.Footer><Drawer.Close render={<Button>Done</Button>} /></Drawer.Footer>\n  </Drawer.Content>\n</Drawer.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/drawer",
+  "mdUrl": "/docs/components/drawer.md",
+  "jsonUrl": "/r/components/drawer.json",
+  "specimens": [
+    {
+      "title": "Drawer",
+      "group": "overlays",
+      "components": [
+        "Drawer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"bottom\">\n    <Drawer.Root>\n      <Drawer.Trigger render={<Button>Open drawer</Button>} />\n      <Drawer.Content>\n        <Drawer.Title>Quick patch</Drawer.Title>\n        <Drawer.Description>The next free block on universe 1.</Drawer.Description>\n        <Drawer.Footer>\n          <Drawer.Close render={<Button>Cancel</Button>} />\n          <Drawer.Close render={<Button variant=\"primary\">Patch</Button>} />\n        </Drawer.Footer>\n      </Drawer.Content>\n    </Drawer.Root>\n  </Specimen>\n  <Specimen label=\"no grab handle\">\n    <Drawer.Root>\n      <Drawer.Trigger render={<Button>Bare drawer</Button>} />\n      <Drawer.Content grabHandle={false}>\n        <Drawer.Title>Quick patch</Drawer.Title>\n        <Drawer.Description>The next free block on universe 1.</Drawer.Description>\n        <Drawer.Footer>\n          <Drawer.Close render={<Button>Close</Button>} />\n        </Drawer.Footer>\n      </Drawer.Content>\n    </Drawer.Root>\n  </Specimen>\n</Specimens>",
+      "note": "The touch-first sheet: a grab handle and a swipe direction.",
+      "interaction": "drag the handle to dismiss; on a pointer device it behaves as an ordinary sheet."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/dropdown-menu.json

@@ -0,0 +1,229 @@
+{
+  "name": "DropdownMenu",
+  "slug": "dropdown-menu",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A command list hung off a button: row actions, view options, an account menu.\n\nWraps Base UI's `Menu`, so roving focus, typeahead, submenu handling, Escape\nand outside-press dismissal are the primitive's. This layer adds the token\nskin, the portal theme stamp and the canvas-safe wheel dismissal\n(see {@link DropdownMenuRootProps.closeOnWheel}).",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Trigger",
+    "Content",
+    "Group",
+    "Label",
+    "Item",
+    "CheckboxItem",
+    "Separator"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "DropdownMenu.Root",
+      "description": "Groups the parts of a menu and owns its open state. Renders no element.",
+      "props": [
+        {
+          "name": "closeOnWheel",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Close the menu when the viewport moves under it — a wheel anywhere outside\nthe popup, or a window resize. Defaults to `true`.\n\nThe menu is positioned from its trigger's rect, and a canvas that pans by\nmutating a CSS transform fires no `scroll` event, so without this a menu\nover the patch grid detaches from its button the moment the user scrolls.\nA wheel *inside* the popup is left alone — that is a long menu scrolling."
+        }
+      ],
+      "typeReferences": [
+        "BaseMenu.Root.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "DropdownMenu.Trigger",
+      "description": "The control that opens the menu. Unstyled — pass `render={<Button />}` or\n`render={<IconButton …/>}` so the button's variant classes win.",
+      "props": [],
+      "typeReferences": [
+        "BaseMenu.Trigger.Props"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "DropdownMenu.Content",
+      "description": "The menu's portal, positioner and popup.\n\nPortalled through {@link useCuePortalProps} so the rows render at the\ncaller's density; roving focus, typeahead and Escape come from Base UI.",
+      "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 that side. Defaults to `\"start\"`."
+        },
+        {
+          "name": "keepMounted",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Keep the popup mounted while closed."
+        },
+        {
+          "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 trigger and popup. Defaults to `4`."
+        },
+        {
+          "name": "side",
+          "type": "\"left\" | \"right\" | \"top\" | \"bottom\" | \"inline-end\" | \"inline-start\"",
+          "required": false,
+          "defaultValue": null,
+          "description": "Preferred side of the trigger. Defaults to `\"bottom\"`."
+        },
+        {
+          "name": "alignOffset",
+          "type": "number | OffsetFunction",
+          "required": false,
+          "defaultValue": null,
+          "description": "Nudge along the alignment axis, in px."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseMenu.Popup.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Group",
+      "usage": "DropdownMenu.Group",
+      "description": "A labelled block of rows. Give it a {@link DropdownMenuLabel} as its first child.",
+      "props": [],
+      "typeReferences": [
+        "BaseMenu.Group.Props"
+      ]
+    },
+    {
+      "name": "Label",
+      "usage": "DropdownMenu.Label",
+      "description": "The uppercase mono caption over a group. Names the group for assistive tech,\nso it belongs inside a {@link DropdownMenuGroup}, not loose in the popup.",
+      "props": [],
+      "typeReferences": [
+        "BaseMenu.GroupLabel.Props"
+      ]
+    },
+    {
+      "name": "Item",
+      "usage": "DropdownMenu.Item",
+      "description": "One command. Closes the menu on press unless `closeOnClick={false}`.\n\nHighlighted with `accent-soft` rather than a solid accent fill: at console\ndensity a solid bar under the pointer is far too loud (the luma defect\nruling), and the soft tint still passes contrast against the row text.",
+      "props": [
+        {
+          "name": "icon",
+          "type": "ElementType<any, keyof IntrinsicElements>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Optional leading icon component, sized to the density icon token."
+        },
+        {
+          "name": "trailing",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "Trailing slot — a `Kbd` shortcut hint, a count, a chevron."
+        }
+      ],
+      "typeReferences": [
+        "BaseMenu.Item.Props"
+      ]
+    },
+    {
+      "name": "CheckboxItem",
+      "usage": "DropdownMenu.CheckboxItem",
+      "description": "A row that toggles a setting. Stays open on press — toggling three view\noptions should not mean opening the menu three times.\n\nThe tick gutter is always reserved, so labels do not jog sideways as items\nare ticked.",
+      "props": [],
+      "typeReferences": [
+        "BaseMenu.CheckboxItem.Props"
+      ]
+    },
+    {
+      "name": "Separator",
+      "usage": "DropdownMenu.Separator",
+      "description": "The hairline between groups of rows.",
+      "props": [],
+      "typeReferences": [
+        "BaseMenu.Separator.Props"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--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-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A command list hung off a button.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<DropdownMenu.Root>\n  <DropdownMenu.Trigger render={<IconButton aria-label=\"Cue actions\" icon={MoreVertical} />} />\n  <DropdownMenu.Content align=\"end\">\n    <DropdownMenu.Group>\n      <DropdownMenu.Label>Playback</DropdownMenu.Label>\n      <DropdownMenu.Item onClick={go}>Go</DropdownMenu.Item>\n    </DropdownMenu.Group>\n    <DropdownMenu.Separator />\n    <DropdownMenu.CheckboxItem checked={follow} onCheckedChange={setFollow}>\n      Follow\n    </DropdownMenu.CheckboxItem>\n  </DropdownMenu.Content>\n</DropdownMenu.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/dropdown-menu",
+  "mdUrl": "/docs/components/dropdown-menu.md",
+  "jsonUrl": "/r/components/dropdown-menu.json",
+  "whenToUse": [
+    "Row actions, view options, an account menu: a list of things to do.",
+    "Toggling view state with `DropdownMenu.CheckboxItem`, which stays open so three toggles cost one trip."
+  ],
+  "whenNotToUse": [
+    "Choosing a value that a form will submit. Use `Select`.",
+    "Arbitrary content. A menu is a list of commands, not a layout container.",
+    "Right-click actions on a surface. Use `ContextMenu`."
+  ],
+  "commonMistakes": [
+    "Putting an input inside a menu item, where typeahead and roving focus fight the field for every keystroke.",
+    "Leaving a `DropdownMenu.Group` without a `DropdownMenu.Label`, which leaves the group unnamed for assistive tech."
+  ],
+  "specimens": [
+    {
+      "title": "DropdownMenu",
+      "group": "overlays",
+      "components": [
+        "DropdownMenu"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <DropdownMenu.Root>\n      <DropdownMenu.Trigger render={<IconButton aria-label=\"Cue actions\" icon={MoreVertical} />} />\n      <DropdownMenu.Content align=\"end\">\n        <DropdownMenu.Group>\n          <DropdownMenu.Label>Cue</DropdownMenu.Label>\n          <DropdownMenu.Item icon={Play} trailing={<Kbd>G</Kbd>}>\n            Go\n          </DropdownMenu.Item>\n          <DropdownMenu.Item icon={Copy} trailing={<Kbd>⌘D</Kbd>}>\n            Duplicate\n          </DropdownMenu.Item>\n        </DropdownMenu.Group>\n        <DropdownMenu.Separator />\n        <DropdownMenu.CheckboxItem checked={follow} onCheckedChange={setFollow}>\n          Follow\n        </DropdownMenu.CheckboxItem>\n        <DropdownMenu.Separator />\n        <DropdownMenu.Item icon={Trash2} disabled>\n          Delete\n        </DropdownMenu.Item>\n      </DropdownMenu.Content>\n    </DropdownMenu.Root>\n  </Specimen>\n  <Specimen label=\"from a density island\">\n    <Density density=\"ultra-compact\">\n      <DropdownMenu.Root>\n        <DropdownMenu.Trigger render={<Button>Ultra-compact</Button>} />\n        <DropdownMenu.Content>\n          <DropdownMenu.Item>The popup is ultra-compact too</DropdownMenu.Item>\n          <DropdownMenu.Item>Because the portal is stamped</DropdownMenu.Item>\n        </DropdownMenu.Content>\n      </DropdownMenu.Root>\n    </Density>\n  </Specimen>\n</Specimens>",
+      "note": "Groups, labels, icons, trailing shortcuts, checkbox items and separators, on the shared menu surface.",
+      "interaction": "closes on wheel as well as on scroll, so a menu opened over a pannable canvas cannot be left floating over nothing."
+    }
+  ]
+}

package/manifest/components/empty-state.json

@@ -0,0 +1,90 @@
+{
+  "name": "EmptyState",
+  "slug": "empty-state",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The \"there is nothing here\" panel body.\n\nCentred and quiet: an empty state is a report, not an alarm, so it uses the\nmuted ramp throughout and gets its emphasis from position rather than colour.\nThe icon is decorative — the title carries the meaning, so a screen reader\nhears one sentence instead of a shrug emoji.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is missing. One short line: \"No cues yet\"."
+    },
+    {
+      "name": "hint",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "How to fix it. One sentence, muted."
+    },
+    {
+      "name": "action",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The way out — normally a single `Button`."
+    },
+    {
+      "name": "icon",
+      "type": "ElementType<any, keyof IntrinsicElements>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional glyph above the title (e.g. a lucide icon), drawn `aria-hidden`."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra content between the hint and the action — rarely needed."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"title\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-6",
+    "--cue-space-7",
+    "--cue-text-emphasis",
+    "--cue-text-ui"
+  ],
+  "summary": "The \"there is nothing here\" panel body.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Panel>\n  <EmptyState\n    icon={ListX}\n    title=\"No cues yet\"\n    hint=\"Record one from the live look, or import a show file.\"\n    action={<Button variant=\"primary\">Record cue</Button>}\n  />\n</Panel>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state",
+  "mdUrl": "/docs/components/empty-state.md",
+  "jsonUrl": "/r/components/empty-state.json",
+  "specimens": [
+    {
+      "title": "EmptyState",
+      "group": "chrome",
+      "components": [
+        "EmptyState"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Panel>\n    <EmptyState\n      icon={List}\n      title={COPY.empty.title}\n      hint={COPY.empty.hint}\n      action={<Button variant=\"primary\">{COPY.empty.action}</Button>}\n    />\n  </Panel>\n  <Panel>\n    <EmptyState\n      icon={Eye}\n      title={COPY.error.title}\n      hint={COPY.error.hint}\n      action={<Button>{COPY.error.action}</Button>}\n    >\n      <StatusDot tone=\"danger\" label=\"No reply\" />\n    </EmptyState>\n  </Panel>\n</div>",
+      "note": "The standard empty copy, from lib/samples.tsx. Same words everywhere in the app.",
+      "interaction": "the action is an ordinary Button and behaves like one."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/env-var-input.json

@@ -0,0 +1,150 @@
+{
+  "name": "EnvVarInput",
+  "slug": "env-var-input",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A config value that may be a literal *or* a reference to an environment\nvariable — and looks unmistakably different in each case.\n\nWhen the value matches `env(NAME)` the text box is replaced by a warn-toned\npill naming the variable. That swap is the entire point: a config screen full\nof identical text boxes gives no way to tell \"this is the key\" from \"this is\nwhere the key comes from\", and the difference decides whether the value is\nsafe to screenshot, commit or paste into a ticket. Warn is the system's amber,\nso the pill reads as \"resolved elsewhere — check the environment\" rather than\nas an error.\n\nPorted from supbuddy's config editor, where the pattern earned its keep.",
+  "props": [
+    {
+      "name": "value",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The value — a literal, or an `env(NAME)` reference. Use with `onValueChange`."
+    },
+    {
+      "name": "defaultValue",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initial value for an uncontrolled field."
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the new value: on every keystroke in the literal state, and with\n`\"\"` when the variable pill is cleared. One argument, because the pill's\nclear button has no DOM change event to hand on."
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Shown while the literal field is empty."
+    },
+    {
+      "name": "secret",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Mask the literal value. The reference is never masked — a name is not a secret."
+    },
+    {
+      "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 editing and grey the control out."
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Name for the underlying input, when the field is part of a form."
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id forwarded to the underlying input."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the field, when no {@link FieldLabel } names it."
+    },
+    {
+      "name": "clearLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Clear environment variable",
+      "description": "Accessible name for the pill's clear button. Defaults to `\"Clear environment variable\"`."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the wrapper."
+    }
+  ],
+  "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-icon-md",
+    "--cue-icon-sm",
+    "--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-ui",
+    "--cue-warn"
+  ],
+  "summary": "A config value that may be a literal *or* a reference to an environment variable — and looks unmistakably different in each case.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<EnvVarInput aria-label=\"Service key\" secret value={key} onValueChange={setKey} />\n<EnvVarInput aria-label=\"Project URL\" defaultValue={envReference(\"SUPABASE_URL\")} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/env-var-input",
+  "mdUrl": "/docs/components/env-var-input.md",
+  "jsonUrl": "/r/components/env-var-input.json",
+  "specimens": [
+    {
+      "title": "EnvVarInput",
+      "group": "forms",
+      "components": [
+        "EnvVarInput"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"literal\">\n    <EnvVarInput aria-label=\"Node address, literal\" defaultValue=\"10.0.0.42\" />\n  </Specimen>\n  <Specimen label=\"env reference\">\n    <EnvVarInput aria-label=\"Node address, reference\" defaultValue=\"env(ARTNET_HOST)\" />\n  </Specimen>\n  <Specimen label=\"secret\">\n    <EnvVarInput aria-label=\"API token\" defaultValue=\"env(CUE_API_TOKEN)\" secret />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <EnvVarInput aria-label=\"Locked reference\" defaultValue=\"env(ARTNET_HOST)\" disabled />\n  </Specimen>\n</Specimens>",
+      "note": "A literal value and an `env(NAME)` reference are different things, so they do not look the same: the reference swaps to an amber token pill.",
+      "interaction": "the mode switch is a button; typing `env(` in the field is enough to flip it."
+    }
+  ],
+  "todo": true
+}