@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/password-input.json

@@ -0,0 +1,119 @@
+{
+  "name": "PasswordInput",
+  "slug": "password-input",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A masked text field with a reveal control.\n\nThe reveal is a **toggle button carrying `aria-pressed`**, not a checkbox and\nnot a bare icon: a screen-reader user needs to know both what it does and\nwhich way it currently is, and `aria-pressed` is the one attribute that says\nboth. The label swaps with the state for the same reason.\n\nRevealing switches `type` between `password` and `text` rather than painting\nover the characters, so the browser's own autofill and password managers keep\nworking.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the group that wraps the input and the reveal button."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "hideLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Hide password",
+      "description": "Accessible name while revealed. Defaults to `\"Hide password\"`."
+    },
+    {
+      "name": "revealed",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Reveal the value. Use with `onRevealedChange` for a controlled toggle."
+    },
+    {
+      "name": "defaultRevealed",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Initially revealed, for an uncontrolled toggle. Defaults to `false`."
+    },
+    {
+      "name": "onRevealedChange",
+      "type": "((revealed: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the new reveal state."
+    },
+    {
+      "name": "showReveal",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Offer the reveal affordance at all. Defaults to `true`. Switch it off for a\nvalue the product must never re-display — a stored secret the user is\nreplacing rather than reading."
+    },
+    {
+      "name": "revealLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Show password",
+      "description": "Accessible name while masked. Defaults to `\"Show password\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<InputProps, \"type\" | \"size\">"
+  ],
+  "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-radius-control",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A masked text field with a reveal control.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<PasswordInput aria-label=\"Service key\" value={key} onValueChange={setKey} />\n<Field><FieldLabel>Token</FieldLabel><PasswordInput showReveal={false} /></Field>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/password-input",
+  "mdUrl": "/docs/components/password-input.md",
+  "jsonUrl": "/r/components/password-input.json",
+  "specimens": [
+    {
+      "title": "PasswordInput",
+      "group": "forms",
+      "components": [
+        "PasswordInput"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"hidden\">\n    <PasswordInput aria-label=\"Console password\" defaultValue=\"hunter2\" />\n  </Specimen>\n  <Specimen label=\"revealed\">\n    <PasswordInput aria-label=\"Console password, revealed\" defaultValue=\"hunter2\" defaultRevealed />\n  </Specimen>\n  <Specimen label=\"no toggle\">\n    <PasswordInput aria-label=\"Password, no reveal\" defaultValue=\"hunter2\" showReveal={false} />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <PasswordInput aria-label=\"Password, disabled\" defaultValue=\"hunter2\" disabled />\n  </Specimen>\n</Specimens>",
+      "note": "Input plus a reveal toggle carrying `aria-pressed`, so the state is spoken rather than implied by an icon swap.",
+      "interaction": "the toggle is in the tab order after the field."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/piano-keyboard.json

@@ -0,0 +1,120 @@
+{
+  "name": "PianoKeyboard",
+  "slug": "piano-keyboard",
+  "group": "midi",
+  "importPath": "@cueplusplus/ui/midi",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A piano keyboard as a range control: drag the markers, or arrow the edges.\n\nPorted from ableton-sync's note-range picker, geometry intact — 16px whites,\n10px blacks over the seams — and rebuilt around three things the original did\nnot have:\n\n1. **The edges are sliders.** The port moved its markers with `mousedown` and\n   a window listener, which means no keyboard, no screen reader and no touch.\n   Here each marker is a `role=\"slider\"` announcing its note by name, so\n   \"set the low end to C2\" is reachable without a pointer.\n2. **The board holds still while you drag.** The window is centred on the\n   selection, so moving an edge moves the window, which moves the note under\n   the cursor — the port's markers slid away from the pointer mid-drag. The\n   window is frozen for the length of a gesture instead.\n3. **It is drawn in console materials, not in white and black.** A photo of a\n   piano inverts in a light theme; a `surface-3` white key and a\n   `--cue-data-ground` black key read the same in both. The information — what\n   is in range, what is sounding — is carried by the accent, which is the only\n   thing here that a theme is allowed to move.",
+  "props": [
+    {
+      "name": "range",
+      "type": "NoteRange",
+      "required": false,
+      "defaultValue": null,
+      "description": "The selected range. Use with `onRangeChange` for a controlled widget."
+    },
+    {
+      "name": "defaultRange",
+      "type": "NoteRange",
+      "required": false,
+      "defaultValue": "{ start: 48, end: 72 }",
+      "description": "Initial range for an uncontrolled widget. Defaults to C2–C4."
+    },
+    {
+      "name": "onRangeChange",
+      "type": "((range: NoteRange) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the range each edit produces."
+    },
+    {
+      "name": "octaves",
+      "type": "number",
+      "required": false,
+      "defaultValue": "3",
+      "description": "How many octaves to draw. Defaults to `3`."
+    },
+    {
+      "name": "highlight",
+      "type": "readonly number[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Notes sounding right now, painted solid."
+    },
+    {
+      "name": "keyHeight",
+      "type": "number",
+      "required": false,
+      "defaultValue": "48",
+      "description": "White-key height in px at the 16px root, emitted as `rem`. Defaults to `48`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Note range",
+      "description": "What the range is *of*. Names the group and both markers. Defaults to `\"Note range\"`."
+    },
+    {
+      "name": "readout",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Print the range and its size under the board. Defaults to `true`."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Refuse every edit. The board still draws."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"onChange\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-data-ground",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-sunken",
+    "--cue-surface-3",
+    "--cue-text-micro"
+  ],
+  "summary": "A piano keyboard as a range control: drag the markers, or arrow the edges.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<PianoKeyboard range={range} onRangeChange={setRange} highlight={sounding} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/piano-keyboard",
+  "mdUrl": "/docs/components/piano-keyboard.md",
+  "jsonUrl": "/r/components/piano-keyboard.json",
+  "specimens": [
+    {
+      "title": "PianoKeyboard",
+      "group": "midi",
+      "components": [
+        "PianoKeyboard"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  <PianoKeyboard\n    range={range}\n    onRangeChange={setRange}\n    octaves={4}\n    label=\"Trigger range\"\n  />\n  <span className=\"font-mono text-(length:--cue-text-micro) text-fg-subtle\">\n    {noteName(range.start)} to {noteName(range.end)}\n  </span>\n  <PianoKeyboard\n    octaves={2}\n    highlight={[60, 64, 67]}\n    keyHeight={56}\n    readout={false}\n    label=\"Chord highlight\"\n  />\n  <PianoKeyboard octaves={2} disabled label=\"Keyboard, disabled\" />\n</div>",
+      "note": "Exact key geometry from the shared layout module, in-range tinting, and draggable start and end markers.",
+      "interaction": "each marker is a `role=slider` that announces the note it sits on, so the drag is a fast path rather than the only path."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/plussie.json

@@ -0,0 +1,111 @@
+{
+  "name": "Plussie",
+  "slug": "plussie",
+  "group": "brand",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "Plussie, the CUE++ character — the mark, with its eyes free to move.\n\nThe same circle and the same two \"+\" glyphs {@link CueMark } draws, out of the\nsame geometry module, because they are the same drawing: the mark's glyphs\n*are* the character's eyes. What this adds is that the eyes are their own\ngroups, so an `expression` can slide or shut them.\n\nStatic-first. The eight Remotion animations this character was rigged for\nstay in the site that renders video; a heavy, video-oriented peer has no\nbusiness in a component library, so what is ported here is the geometry and\nthe poses. Everything else a caller wants — a look that follows the cursor, a\nblink on a timer of their own — is a `expression` prop away, driven by their\nown runtime.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "expression",
+      "type": "\"default\" | \"blink\" | \"wink\" | \"look-left\" | \"look-right\" | \"look-up\" | \"look-down\"",
+      "required": false,
+      "defaultValue": "default",
+      "description": "Which pose to hold. Defaults to `\"default\"`, eyes open and level.\n\nEvery pose is a still from the character's own animations rather than a\nnew drawing, so a screen that holds one and a video that plays through it\nagree."
+    },
+    {
+      "name": "idle",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Blink every few seconds, on a CSS keyframe. Defaults to `false`.\n\nOff by default because a mark that moves in the corner of the eye is a\ndistraction on a console screen, and off again for a reader who has asked\nfor reduced motion — the rule that drives it is inside a\n`prefers-reduced-motion` guard, so there is no state to keep and nothing to\nturn off a second time.\n\nIt composes with `expression`: a winking Plussie blinks its open eye."
+    },
+    {
+      "name": "size",
+      "type": "number | BrandSize",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the density control ladder to draw at, or an explicit height in px.\nDefaults to `\"md\"`.\n\nHeight, always — every asset here keeps its own aspect ratio, so the width\nfollows from the artwork rather than from the caller."
+    },
+    {
+      "name": "tone",
+      "type": "\"inherit\" | \"fg\" | \"accent\"",
+      "required": false,
+      "defaultValue": "inherit",
+      "description": "Where the ink comes from: `currentColor`, the foreground token, or the\naccent. Defaults to `\"inherit\"`."
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The accessible name.\n\nOmit it and the asset is decorative — `aria-hidden`, announced by nothing.\nPass one only when the mark is the *only* thing naming what it sits on: a\nbare logo link, a splash screen with no heading."
+    }
+  ],
+  "typeReferences": [
+    "BrandAssetProps"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-bg",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg"
+  ],
+  "summary": "Plussie, the CUE++ character: the mark with its eyes free to move.",
+  "examples": [
+    {
+      "title": "An empty state",
+      "code": "import { Plussie } from \"@cueplusplus/ui\";\n\n<div className=\"flex flex-col items-center gap-(--cue-space-4)\">\n  <Plussie size={96} expression=\"look-down\" />\n  <p>No cues yet.</p>\n</div>;",
+      "language": "tsx"
+    },
+    {
+      "title": "With the optional idle blink",
+      "code": "<Plussie size={96} idle title=\"Plussie\" />;",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Plussie size=\"lg\" title=\"Plussie\" />\n<Plussie expression=\"wink\" tone=\"accent\" />\n<Plussie size={96} idle />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/plussie",
+  "mdUrl": "/docs/components/plussie.md",
+  "jsonUrl": "/r/components/plussie.json",
+  "whenToUse": [
+    "An empty state, an onboarding step, an error page — somewhere a screen has room for a face.",
+    "A long-running job's companion, where `expression` says what the job is doing without a second sentence.",
+    "Anywhere you would have embedded the character's video and only needed one frame of it."
+  ],
+  "whenNotToUse": [
+    "In dense console chrome. A face in a toolbar is a distraction; use `CueMark`.",
+    "As a loading indicator. Use `Spinner` or `Progress`, which announce themselves.",
+    "For an animation with a script. The eight rigged animations live in the site that renders video, and this library will not take Remotion as a peer."
+  ],
+  "commonMistakes": [
+    "Inventing a pose by nudging the eyes with CSS. Every value `expression` holds is a still from a real animation, and a hand-tuned one will not match the video.",
+    "Turning `idle` on across a page. It is off by default because a mark moving in the corner of the eye is a distraction, and it is off again under `prefers-reduced-motion`.",
+    "Expecting `expression` to animate between poses. It sets a pose; transitions belong to the caller."
+  ],
+  "specimens": [
+    {
+      "title": "Plussie",
+      "group": "brand",
+      "components": [
+        "Plussie"
+      ],
+      "code": "<Specimens>\n  {EXPRESSIONS.map((expression) => (\n    <Specimen key={expression} label={expression}>\n      <Plussie size={56} expression={expression} />\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  {SIZES.map((size) => (\n    <Specimen key={size} label={`size ${size}`}>\n      <Plussie size={size} />\n    </Specimen>\n  ))}\n  <Specimen label=\"tone accent\">\n    <Plussie size={56} tone=\"accent\" expression=\"wink\" />\n  </Specimen>\n  <Specimen label=\"idle\">\n    <Plussie size={56} idle title=\"Plussie\" />\n  </Specimen>\n</Specimens>",
+      "note": "The same circle and the same two '+' the mark draws, out of the same geometry module, with the eyes in their own groups so a pose can move them. Every pose is a still from one of the character's own animations.",
+      "interaction": "none by default. Pass `idle` for a CSS-only blink, which stops for a reader who has asked for reduced motion."
+    }
+  ]
+}

package/manifest/components/popover.json

@@ -0,0 +1,193 @@
+{
+  "name": "Popover",
+  "slug": "popover",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A small floating surface anchored to a control — a filter form, an inspector,\na colour picker.\n\nWraps Base UI's `Popover`, so anchoring, collision flipping, Escape and\noutside-press dismissal are the primitive's. This layer adds the token skin,\nthe portal theme stamp and the canvas-safe wheel dismissal.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Trigger",
+    "Content",
+    "Title",
+    "Description",
+    "Close"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Popover.Root",
+      "description": "Groups the parts of a popover and owns its open state. Renders no element.",
+      "props": [
+        {
+          "name": "closeOnWheel",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Close the popover when the viewport moves under it — a wheel anywhere\noutside the popup, or a window resize. Defaults to `true`.\n\nAn anchored popup is positioned from its trigger's rect. A canvas that pans\nby mutating a CSS transform fires no `scroll` event, so without this the\npopup silently detaches from the thing it belongs to. Set `false` when the\npopover must survive page scrolling (a pinned inspector, say)."
+        }
+      ],
+      "typeReferences": [
+        "BasePopover.Root.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "Popover.Trigger",
+      "description": "The control the popover is anchored to. Unstyled — pass\n`render={<Button />}` or `render={<IconButton …/>}` so the button's own\nvariant classes stay the last word on how it looks.",
+      "props": [],
+      "typeReferences": [
+        "BasePopover.Trigger.Props"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "Popover.Content",
+      "description": "The popover's portal, positioner and popup.\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>`. Flipping and shifting to stay on screen is Base UI's; the wheel\ndismissal is ours (see {@link PopoverRootProps.closeOnWheel}).",
+      "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": 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<BasePopover.Popup.Props, \"className\">"
+      ]
+    },
+    {
+      "name": "Title",
+      "usage": "Popover.Title",
+      "description": "The popover's heading, wired to the popup's `aria-labelledby`.",
+      "props": [],
+      "typeReferences": [
+        "BasePopover.Title.Props"
+      ]
+    },
+    {
+      "name": "Description",
+      "usage": "Popover.Description",
+      "description": "The supporting line under the title, published as `aria-describedby`.",
+      "props": [],
+      "typeReferences": [
+        "BasePopover.Description.Props"
+      ]
+    },
+    {
+      "name": "Close",
+      "usage": "Popover.Close",
+      "description": "A control that closes the popover. Unstyled — wrap it in a `Button`.",
+      "props": [],
+      "typeReferences": [
+        "BasePopover.Close.Props"
+      ]
+    }
+  ],
+  "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-space-4",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A panel anchored to the control that opened it.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Popover.Root>\n  <Popover.Trigger render={<IconButton aria-label=\"Filter\" icon={Filter} />} />\n  <Popover.Content side=\"bottom\" align=\"end\">\n    <Popover.Title>Filter cues</Popover.Title>\n    <SearchInput aria-label=\"Query\" />\n  </Popover.Content>\n</Popover.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/popover",
+  "mdUrl": "/docs/components/popover.md",
+  "jsonUrl": "/r/components/popover.json",
+  "whenToUse": [
+    "Secondary controls that belong to one trigger: a filter set, a colour picker, a row's properties.",
+    "When the page behind has to stay readable while the panel is open."
+  ],
+  "whenNotToUse": [
+    "A list of commands. Use `DropdownMenu`, which brings roving focus, typeahead and the menu roles.",
+    "Text that only describes the trigger. Use `Tooltip`, or `InfoTip` for the question-mark affordance.",
+    "Anything that must be answered before the user moves on. Use `Dialog`."
+  ],
+  "commonMistakes": [
+    "Turning `closeOnWheel` off on a canvas that pans by CSS transform. No scroll event fires there, so the popup silently detaches from its trigger.",
+    "Filling it with a form whose first control cannot take focus, which strands keyboard users on the trigger."
+  ],
+  "specimens": [
+    {
+      "title": "Popover",
+      "group": "overlays",
+      "components": [
+        "Popover"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <Popover.Root>\n      <Popover.Trigger render={<Button>Fixture</Button>} />\n      <Popover.Content>\n        <Popover.Title>Source Four 26°</Popover.Title>\n        <Popover.Description>Universe 1, channels 12 to 19.</Popover.Description>\n        <Popover.Close render={<Button size=\"sm\">Close</Button>} />\n      </Popover.Content>\n    </Popover.Root>\n  </Specimen>\n  <Specimen label=\"side right\">\n    <Popover.Root>\n      <Popover.Trigger render={<Button>Right</Button>} />\n      <Popover.Content side=\"right\" align=\"start\">\n        <Popover.Title>Anchored right</Popover.Title>\n        <Popover.Description>Flips when there is no room.</Popover.Description>\n      </Popover.Content>\n    </Popover.Root>\n  </Specimen>\n</Specimens>",
+      "note": "An anchored surface with a title, a description and arbitrary content.",
+      "interaction": "closes on outside mousedown, on scroll, on wheel and on Escape. The wheel case is the one a canvas that pans by CSS transform needs."
+    }
+  ]
+}

package/manifest/components/preset-section.json

@@ -0,0 +1,73 @@
+{
+  "name": "PresetSection",
+  "slug": "preset-section",
+  "group": "configurator",
+  "importPath": "@cueplusplus/ui/configurator",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "Section 1 — the four choices that are not token edits at all.\n\nPreset, mode and density are *provider* state: picking one restamps the\ndocument and every portal under it, which is why they live here rather than\nin the colour list. Text scale and zoom are the two relief valves the spec\npairs with the density ladder — one scales the type ramp inside the layout,\nthe other scales the finished layout itself.",
+  "props": [
+    {
+      "name": "edits",
+      "type": "TokenEdits",
+      "required": true,
+      "defaultValue": null,
+      "description": "The panel's edit surface."
+    },
+    {
+      "name": "zoom",
+      "type": "ZoomValve",
+      "required": true,
+      "defaultValue": null,
+      "description": "The root zoom valve the panel owns."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the section."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-density",
+    "--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-control",
+    "--cue-radius-scale",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "Section 1 — the four choices that are not token edits at all.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<PresetSection edits={edits} zoom={zoom} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/preset-section",
+  "mdUrl": "/docs/components/preset-section.md",
+  "jsonUrl": "/r/components/preset-section.json",
+  "todo": true
+}