@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/toggle.json

@@ -0,0 +1,109 @@
+{
+  "name": "Toggle",
+  "slug": "toggle",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A two-state button: solo, mute, snap-to-grid, \"show hidden\".\n\nDistinct from {@link Switch }, which sets a *setting* and reads as a physical\nthrow; a toggle is a **button that stays down**, so it belongs in a toolbar\nnext to other buttons rather than in a settings list. `aria-pressed` — not\n`aria-checked` — is what says so to assistive technology, and Base UI wires\nthat for us.\n\nInside a {@link ToggleGroup } it inherits the group's density rung and joins\nits roving-focus ring; on its own it is a perfectly good standalone control.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the recipe."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The label. Leave it off for an icon-only toggle — and then pass `aria-label`."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rung of the control ladder. Defaults to the enclosing {@link ToggleGroup }'s\nrung, or `\"md\"` outside one."
+    },
+    {
+      "name": "icon",
+      "type": "ElementType<any, keyof IntrinsicElements>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional leading icon component (e.g. a lucide icon). Rendered `aria-hidden`\nand sized to the density icon token. With no `children` the toggle collapses\nto a square target instead of a wide pill."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseToggle.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "square": [
+      "true",
+      "false"
+    ]
+  },
+  "defaultVariants": {
+    "size": "md",
+    "square": "false"
+  },
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A two-state button: solo, mute, snap-to-grid, \"show hidden\".",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Toggle aria-label=\"Solo\" icon={Headphones} pressed={solo} onPressedChange={setSolo} />\n<Toggle defaultPressed>Snap</Toggle>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/toggle",
+  "mdUrl": "/docs/components/toggle.md",
+  "jsonUrl": "/r/components/toggle.json",
+  "specimens": [
+    {
+      "title": "Toggle / ToggleGroup",
+      "group": "forms",
+      "components": [
+        "Toggle",
+        "ToggleGroup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"off\">\n    <Toggle aria-label=\"Highlight\" icon={Lightbulb} />\n  </Specimen>\n  <Specimen label=\"on\">\n    <Toggle aria-label=\"Highlight, on\" icon={Lightbulb} defaultPressed />\n  </Specimen>\n  <Specimen label=\"with label\">\n    <Toggle icon={Lightbulb}>Highlight</Toggle>\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <Toggle aria-label=\"Highlight, disabled\" icon={Lightbulb} disabled />\n  </Specimen>\n  <Specimen label=\"group\">\n    <ToggleGroup aria-label=\"Text style\" defaultValue={[\"bold\"]}>\n      <Toggle value=\"bold\" aria-label=\"Bold\" icon={Bold} />\n      <Toggle value=\"italic\" aria-label=\"Italic\" icon={Italic} />\n      <Toggle value=\"underline\" aria-label=\"Underline\" icon={Underline} />\n    </ToggleGroup>\n  </Specimen>\n</Specimens>",
+      "note": "A button that stays pressed, and a set of them. `aria-pressed` carries the state.",
+      "interaction": "hover tints the ground; pressed is accent-soft, on the same ruling as the active tab."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/token-editor.json

@@ -0,0 +1,90 @@
+{
+  "name": "TokenEditor",
+  "slug": "token-editor",
+  "group": "configurator",
+  "importPath": "@cueplusplus/ui/configurator",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "The grouped colour rows.\n\nStateless by design: it renders the values it is handed and reports edits\nback. The configurator owns the override model, and so does anything else\nthat wants to reuse these rows.\n\n`react-aria-components` is an **optional peer** (it arrives with\n`ColorPicker`): import this from `@cueplusplus/ui/configurator`.",
+  "props": [
+    {
+      "name": "values",
+      "type": "Record<string, string>",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current values, keyed by `--cue-*` property."
+    },
+    {
+      "name": "overridden",
+      "type": "ReadonlySet<string>",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which properties carry an override rather than the preset's value."
+    },
+    {
+      "name": "onTokenChange",
+      "type": "(token: string, value: string) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the `--cue-*` property and its new value."
+    },
+    {
+      "name": "onTokenReset",
+      "type": "(token: string) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the `--cue-*` property to put back to the preset's value."
+    },
+    {
+      "name": "groups",
+      "type": "readonly TokenGroup[]",
+      "required": false,
+      "defaultValue": "[\n  {\n    id: \"ground\",\n    label: \"Ground & surfaces\",\n    tokens: [\"bg\", \"sunken\", \"surface-1\", \"surface-2\", \"surface-3\", \"data-ground\", \"scrim\"],\n  },\n  { id: \"ink\", label: \"Ink\", tokens: [\"fg\", \"fg-muted\", \"fg-subtle\"] },\n  { id: \"borders\", label: \"Borders\", tokens: [\"border\", \"border-strong\", \"border-overlay\"] },\n  {\n    id: \"accent\",\n    label: \"Accent\",\n    tokens: [\"accent\", \"accent-hover\", \"accent-fg\", \"focus\", \"selection\"],\n  },\n  { id: \"status\", label: \"Status\", tokens: [\"ok\", \"busy\", \"warn\", \"danger\", \"info\"] },\n]",
+      "description": "Groups to render. Defaults to {@link COLOR_TOKEN_GROUPS}."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the list."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--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-radius-scale",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "The grouped colour rows.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<TokenEditor\n  values={resolvedTokens(overrides, scope)}\n  overridden={new Set(Object.keys(overrides.themes[scopeKey(scope)] ?? {}))}\n  onTokenChange={(token, value) => setOverrides(setOverride(overrides, scope, token, value))}\n  onTokenReset={(token) => setOverrides(clearOverride(overrides, scope, token))}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/token-editor",
+  "mdUrl": "/docs/components/token-editor.md",
+  "jsonUrl": "/r/components/token-editor.json",
+  "todo": true
+}

package/manifest/components/toolbar.json

@@ -0,0 +1,163 @@
+{
+  "name": "Toolbar",
+  "slug": "toolbar",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The strip of controls across the top of a view.\n\nWraps Base UI's `Toolbar`, so the whole bar is one tab stop with arrow-key\nroving focus inside it — which is the entire point of the ARIA toolbar\npattern and the reason not to hand-roll this out of a flex row of buttons.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Button",
+    "Group",
+    "Separator"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Toolbar.Root",
+      "description": "The bar itself: chrome-toolbar tall, hairline underneath, surface fill.\n\nHeight comes from `--cue-chrome-toolbar`, which is a *chrome* token rather\nthan a control token — the bar is part of the window furniture and gets its\nown rung of the density ladder, one that stays legible when the controls\ninside it shrink.\n\nThe bar element is also its own scroller, rather than sitting inside one:\nthat is what keeps the height, the hairline and the fill on the element with\n`role=\"toolbar\"`, so a bar that overflows still looks like one bar rather\nthan a strip inside a box. The wrapper the scrolling shape adds is an\nunpainted `relative` frame whose only job is to hold the pager chevrons.\n\nGive it an `aria-label`: a toolbar with no name is announced as \"toolbar\".",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the bar."
+        },
+        {
+          "name": "overflow",
+          "type": "\"clip\" | \"scroll\"",
+          "required": false,
+          "defaultValue": "scroll",
+          "description": "What the bar does when its controls do not fit. Defaults to `\"scroll\"`.\n\n`\"scroll\"` is the library's one overflow behaviour (see\n`./_edge-scroller` for why it is scrolling rather than wrapping or a \"more\"\nmenu): the bar keeps its single chrome-rung height, the controls scroll\ninside it, the overflowing edge is faded and a pager chevron appears there.\nA bar whose controls all fit renders exactly as it did before — no mask, no\nchevrons, no compositing layer.\n\n`\"clip\"` restores the old behaviour and adds no wrapper element, for a bar\nthat is already inside something which scrolls.\n\nA vertical toolbar ignores this: the affordance is horizontal, and a\nvertical bar overflows on the axis this does not measure."
+        },
+        {
+          "name": "previousLabel",
+          "type": "string",
+          "required": false,
+          "defaultValue": "Show earlier controls",
+          "description": "Accessible name for the chevron that reveals controls off the leading edge."
+        },
+        {
+          "name": "nextLabel",
+          "type": "string",
+          "required": false,
+          "defaultValue": "Show later controls",
+          "description": "Accessible name for the chevron that reveals controls off the trailing edge."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseToolbar.Root.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Button",
+      "usage": "Toolbar.Button",
+      "description": "A borderless toolbar control.\n\nDeliberately not a `Button`: inside a bar, six rimmed buttons in a row read\nas six competing objects. Toolbar controls speak through text colour and a\nhover fill only (the venu convention), which keeps the bar reading as one\nstrip. Reach for `<Toolbar.Button render={<Button variant=\"primary\" />}>`\nwhen exactly one action in the bar must be loud.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the button."
+        },
+        {
+          "name": "icon",
+          "type": "ElementType<any, keyof IntrinsicElements>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Optional leading icon (e.g. a lucide icon), drawn `aria-hidden`."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseToolbar.Button.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Group",
+      "usage": "Toolbar.Group",
+      "description": "A tight cluster of related controls inside the bar.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the group."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseToolbar.Group.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Separator",
+      "usage": "Toolbar.Separator",
+      "description": "A hairline between clusters. Base UI orients it perpendicular to the bar, so\na horizontal toolbar gets a vertical rule with no prop to remember; the\nclasses follow `data-orientation` for the same reason.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the rule."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseToolbar.Separator.Props, \"className\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-chrome-toolbar",
+    "--cue-control-md",
+    "--cue-edge-fade",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-pad-row-x",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-ui"
+  ],
+  "summary": "The strip of controls across the top of a view.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Toolbar.Root aria-label=\"Cue actions\">\n  <Toolbar.Group aria-label=\"Playback\">\n    <Toolbar.Button icon={Play}>Go</Toolbar.Button>\n    <Toolbar.Button icon={Square}>Stop</Toolbar.Button>\n  </Toolbar.Group>\n  <Toolbar.Separator />\n  <Toolbar.Button icon={Save}>Save</Toolbar.Button>\n</Toolbar.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/toolbar",
+  "mdUrl": "/docs/components/toolbar.md",
+  "jsonUrl": "/r/components/toolbar.json",
+  "specimens": [
+    {
+      "title": "Toolbar",
+      "group": "chrome",
+      "components": [
+        "Toolbar"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  <Toolbar.Root aria-label=\"Text formatting\">\n    <Toolbar.Group>\n      <Toolbar.Button icon={Bold} aria-label=\"Bold\" />\n      <Toolbar.Button icon={Italic} aria-label=\"Italic\" />\n      <Toolbar.Button icon={Underline} aria-label=\"Underline\" />\n    </Toolbar.Group>\n    <Toolbar.Separator />\n    <Toolbar.Group>\n      <Toolbar.Button icon={List}>Cue list</Toolbar.Button>\n      <Toolbar.Button icon={Monitor} disabled>\n        Preview\n      </Toolbar.Button>\n    </Toolbar.Group>\n  </Toolbar.Root>\n\n  <div className=\"w-full max-w-[16rem] overflow-hidden rounded-(--radius-surface) border border-border\">\n    <Toolbar.Root aria-label=\"Playback, boxed\">\n      <Toolbar.Button icon={List}>Cue list</Toolbar.Button>\n      <Toolbar.Separator />\n      <Toolbar.Button icon={Monitor}>Preview</Toolbar.Button>\n      <Toolbar.Button icon={Plus}>Add cue</Toolbar.Button>\n      <Toolbar.Button icon={Eye}>Blind</Toolbar.Button>\n    </Toolbar.Root>\n  </div>\n</div>",
+      "note": "Borderless text-colour feedback: a pressed tool changes ink, not ground. Boxed to 16rem below, the bar scrolls rather than clipping — it stays one chrome rung tall, because a second row would be stolen from the work area.",
+      "interaction": "hover lifts the ink to `--cue-fg`; arrow keys move between tools and reach the ones off-screen, Tab leaves the toolbar."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/tooltip.json

@@ -0,0 +1,164 @@
+{
+  "name": "Tooltip",
+  "slug": "tooltip",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A short label revealed on hover or keyboard focus — what an icon-only control\ndoes, what an abbreviated column header means.\n\nWraps Base UI's `Tooltip` and adds the two things a design system must not\nleave to the caller: the `role=\"tooltip\"` / `aria-describedby` pairing, and\nthe portal theme stamp. For anything longer than a label, reach for\n{@link InfoTip } (a focusable badge) or a `Popover` instead — hover-only\ncontent is unreachable on touch.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Provider",
+    "Root",
+    "Trigger",
+    "Content"
+  ],
+  "parts": [
+    {
+      "name": "Provider",
+      "usage": "Tooltip.Provider",
+      "description": "Shares one hover delay across a group of tooltips: once the first one has\nopened, its neighbours open instantly, so scanning a toolbar does not mean\nwaiting out the delay at every button.",
+      "props": [],
+      "typeReferences": [
+        "BaseTooltip.Provider.Props"
+      ]
+    },
+    {
+      "name": "Root",
+      "usage": "Tooltip.Root",
+      "description": "Groups the parts of one tooltip. Renders no element.",
+      "props": [],
+      "typeReferences": [
+        "BaseTooltip.Root.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "Tooltip.Trigger",
+      "description": "The element the tooltip describes. A `<button>` by default; pass\n`render={…}` to attach the tooltip to something else.\n\nOpens on hover after {@link TooltipTriggerProps.delay} and instantly on\nkeyboard focus — a tooltip nobody can reach with the keyboard is a decoration.",
+      "props": [],
+      "typeReferences": [
+        "BaseTooltip.Trigger.Props"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "Tooltip.Content",
+      "description": "The tooltip's portal, positioner and popup.\n\nCarries `role=\"tooltip\"` and the id the trigger describes itself with.\nPortalled through {@link useCuePortalProps} so it renders in the caller's\ntheme and density.",
+      "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": null,
+          "description": "Alignment along that side. Defaults to `\"center\"`."
+        },
+        {
+          "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": "top",
+          "description": "Preferred side of the trigger. Defaults to `\"top\"`."
+        },
+        {
+          "name": "alignOffset",
+          "type": "number | OffsetFunction",
+          "required": false,
+          "defaultValue": null,
+          "description": "Nudge along the alignment axis, in px."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseTooltip.Popup.Props, \"className\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--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-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A short description of the control under the pointer or the focus ring.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Tooltip.Root>\n  <Tooltip.Trigger render={<IconButton aria-label=\"Blackout\" icon={Power} />} />\n  <Tooltip.Content>Fades every channel to zero</Tooltip.Content>\n</Tooltip.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/tooltip",
+  "mdUrl": "/docs/components/tooltip.md",
+  "jsonUrl": "/r/components/tooltip.json",
+  "whenToUse": [
+    "Naming an icon-only control, or adding the keyboard shortcut for it.",
+    "Around a cluster of them, `Tooltip.Provider` so the open delay is paid once for the whole toolbar."
+  ],
+  "whenNotToUse": [
+    "Information the user actually needs. A tooltip is unreachable on touch; put it in the page, or use `InfoTip`.",
+    "Anything interactive. Nothing inside a tooltip can be clicked."
+  ],
+  "commonMistakes": [
+    "Attaching one to an element that cannot take focus, which hides it from every keyboard user.",
+    "Repeating the visible label of the control it points at."
+  ],
+  "specimens": [
+    {
+      "title": "Tooltip / InfoTip",
+      "group": "overlays",
+      "components": [
+        "Tooltip",
+        "InfoTip"
+      ],
+      "code": "<Tooltip.Provider>\n  <Specimens>\n    <Specimen label=\"tooltip\">\n      <Tooltip.Root>\n        <Tooltip.Trigger render={<IconButton aria-label=\"Go\" icon={Play} />} />\n        <Tooltip.Content>Fire the selected cue</Tooltip.Content>\n      </Tooltip.Root>\n    </Specimen>\n    <Specimen label=\"side bottom\">\n      <Tooltip.Root>\n        <Tooltip.Trigger render={<IconButton aria-label=\"Copy address\" icon={Copy} />} />\n        <Tooltip.Content side=\"bottom\">Copy 10.0.0.42</Tooltip.Content>\n      </Tooltip.Root>\n    </Specimen>\n    <Specimen label=\"info tip\">\n      <span className=\"flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n        Pace tick\n        <InfoTip text=\"Where the meter would be if usage were flat across the period.\" />\n      </span>\n    </Specimen>\n    <Specimen label=\"wide info tip\">\n      <InfoTip\n        width={320}\n        label=\"About provenance\"\n        text=\"Vendor numbers are measured, estimated ones are hatched, and an unbounded meter draws no percentage at all.\"\n      />\n    </Specimen>\n  </Specimens>\n</Tooltip.Provider>",
+      "note": "A tooltip names a control; an InfoTip is the 13px `i` badge that explains one.",
+      "interaction": "tooltips open on hover and on keyboard focus, and never on touch; the InfoTip badge is a real button."
+    }
+  ]
+}

package/manifest/components/tree-visibility-toggle.json

@@ -0,0 +1,84 @@
+{
+  "name": "TreeVisibilityToggle",
+  "slug": "tree-visibility-toggle",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The outliner's three-state visibility control: shown → ghosted → hidden.\n\nThree states rather than a checkbox because a rig has three answers, not two:\n*there*, *there but out of the way*, and *not drawn*. Ghost is the one that\nearns the extra state — it is how you keep a truss as spatial reference while\nworking behind it — and collapsing it into \"hidden\" is what makes people\ntoggle things off and lose their bearings.\n\nMeant for {@link TreeProps.rowControls}. The accessible name states the\n*current* state (\"Visibility: ghosted\") rather than the next action, because\nwith three states \"toggle\" names nothing useful; pressing cycles.",
+  "props": [
+    {
+      "name": "value",
+      "type": "\"hidden\" | \"visible\" | \"ghost\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "The node's current visibility."
+    },
+    {
+      "name": "onValueChange",
+      "type": "(value: TreeVisibility) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the next state in the cycle."
+    },
+    {
+      "name": "labels",
+      "type": "Partial<Record<TreeVisibility, string>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Override the state names used in the accessible label."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"button\">, \"value\" | \"onChange\" | \"children\">"
+  ],
+  "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": "The outliner's three-state visibility control: shown → ghosted → hidden.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<TreeVisibilityToggle value={state} onValueChange={setState} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/tree-visibility-toggle",
+  "mdUrl": "/docs/components/tree-visibility-toggle.md",
+  "jsonUrl": "/r/components/tree-visibility-toggle.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
+}