@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/color-picker.json

@@ -0,0 +1,175 @@
+{
+  "name": "ColorPicker",
+  "slug": "color-picker",
+  "group": "color",
+  "importPath": "@cueplusplus/ui/color",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "A colour, edited in a popover: two-axis area, hue rail, optional alpha rail,\na text field that speaks hex *and* oklch, and an eyedropper where the browser\nhas one.\n\nComposed from the React Aria colour parts rather than wrapping a single\nprimitive, because no primitive owns the combination. Two decisions are this\ncomponent's own:\n\n- **Notation in, notation out.** React Aria only parses sRGB; this system's\n  tokens are authored in `oklch()`. The picker converts on both edges\n  (culori), and writes back in the notation it was given unless `format` says\n  otherwise. This is what makes it usable as the theme configurator's editor.\n- **Hue survives black.** The working colour is held as HSB and only re-read\n  from the incoming string when that string changes for some *other* reason,\n  so dragging the area down to black and back does not reset the hue — the\n  defect every naive \"derive state from the value\" picker has.\n\n`react-aria-components` is an **optional peer**: import this from\n`@cueplusplus/ui/color`.",
+  "props": [
+    {
+      "name": "value",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The colour, in any notation this suite reads. Use with `onValueChange`."
+    },
+    {
+      "name": "defaultValue",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initial colour for an uncontrolled picker. Defaults to `\"#000000\"`."
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the new colour, written in the picker's output notation."
+    },
+    {
+      "name": "format",
+      "type": "\"hex\" | \"oklch\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Notation to write back. Defaults to the notation the current value arrived\nin — hand it an `oklch()` token and you get `oklch()` back, so editing a\ntheme file never silently rewrites it into hex."
+    },
+    {
+      "name": "alpha",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Show the alpha rail and keep alpha in the output. Defaults to `false`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Color",
+      "description": "Accessible name for the trigger. Defaults to `\"Color\"`."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Prevent opening and grey the trigger out."
+    },
+    {
+      "name": "showValue",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Print the value beside the swatch on the trigger. Defaults to `true`."
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Name for the hidden input, when the picker is part of a form."
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id forwarded to the trigger."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the trigger."
+    },
+    {
+      "name": "popupClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the popup surface."
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Open state, for a controlled popover."
+    },
+    {
+      "name": "defaultOpen",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initial open state."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the popover opens or closes."
+    }
+  ],
+  "typeReferences": [],
+  "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-ui"
+  ],
+  "summary": "A colour, edited in a popover: two-axis area, hue rail, optional alpha rail, a text field that speaks hex *and* oklch, and an eyedropper where the browser has one.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ColorPicker label=\"Accent\" value={accent} onValueChange={setAccent} />\n<ColorPicker label=\"Scrim\" value=\"oklch(0.2 0 0 / 0.55)\" alpha format=\"oklch\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/color-picker",
+  "mdUrl": "/docs/components/color-picker.md",
+  "jsonUrl": "/r/components/color-picker.json",
+  "specimens": [
+    {
+      "title": "ColorPicker",
+      "group": "color",
+      "components": [
+        "ColorPicker"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"hex\">\n    <ColorPicker label=\"Accent\" value={hex} onValueChange={setHex} showValue />\n  </Specimen>\n  <Specimen label=\"oklch\">\n    <ColorPicker\n      label=\"Accent, oklch\"\n      format=\"oklch\"\n      value={oklch}\n      onValueChange={setOklch}\n      showValue\n    />\n  </Specimen>\n  <Specimen label=\"with alpha\">\n    <ColorPicker label=\"Scrim\" defaultValue=\"#0000008c\" alpha showValue />\n  </Specimen>\n  <Specimen label=\"sm\">\n    <ColorPicker label=\"Accent, small\" defaultValue=\"#3ecf8e\" size=\"sm\" />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <ColorPicker label=\"Accent, locked\" defaultValue=\"#5b8def\" disabled />\n  </Specimen>\n</Specimens>\n<Panel>\n  <PanelHeader title=\"Round trip\" />\n  <Row>\n    <span className=\"w-[8rem] shrink-0 font-mono text-fg-muted\">hex in</span>\n    <span className=\"flex-1 font-mono\">{hex}</span>\n    <span className=\"font-mono text-fg-muted\">\n      {formatColorString(hex, \"oklch\") ?? \"unparsed\"}\n    </span>\n  </Row>\n  <Row>\n    <span className=\"w-[8rem] shrink-0 font-mono text-fg-muted\">oklch in</span>\n    <span className=\"flex-1 font-mono\">{oklch}</span>\n    <span className=\"font-mono text-fg-muted\">\n      {formatColorString(oklch, \"hex\") ?? \"unparsed\"}\n    </span>\n  </Row>\n</Panel>",
+      "note": "Swatch, popover, area, hue slider and a text field, in one control. Reads and writes hex or oklch, so a token authored in oklch survives a round trip unchanged.",
+      "interaction": "the swatch is the trigger; inside the popup, the area takes both arrow axes and the slider takes one."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/color-slider.json

@@ -0,0 +1,75 @@
+{
+  "name": "ColorSlider",
+  "slug": "color-slider",
+  "group": "color",
+  "importPath": "@cueplusplus/ui/color",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "One channel of a colour, as a rail: hue, alpha, lightness, a single RGB\nchannel.\n\nWraps React Aria's `ColorSlider`, which paints the channel's gradient and\nowns the keyboard and pointer behaviour. The alpha channel gets the\ntransparency checkerboard — without it, \"half transparent\" and \"half grey\"\nare the same picture. It goes on the frame rather than the track because\nReact Aria writes the gradient into the track's inline `background`, which\nwould paint straight over a checkerboard set by a class.\n\n`react-aria-components` is an **optional peer**: import this from\n`@cueplusplus/ui/color`.",
+  "props": [
+    {
+      "name": "frameClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the frame around the track."
+    },
+    {
+      "name": "trackClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the gradient track."
+    },
+    {
+      "name": "thumbClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the thumb."
+    }
+  ],
+  "typeReferences": [
+    "Omit<AriaColorSliderProps, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-fg",
+    "--cue-icon-sm",
+    "--cue-surface-1",
+    "--cue-surface-3"
+  ],
+  "summary": "One channel of a colour, as a rail: hue, alpha, lightness, a single RGB channel.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ColorSlider aria-label=\"Hue\" channel=\"hue\" value={color} onChange={setColor} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/color-slider",
+  "mdUrl": "/docs/components/color-slider.md",
+  "jsonUrl": "/r/components/color-slider.json",
+  "specimens": [
+    {
+      "title": "ColorSlider",
+      "group": "color",
+      "components": [
+        "ColorSlider"
+      ],
+      "code": "<div className=\"flex w-full max-w-[24rem] flex-col gap-(--cue-space-4)\">\n  <ColorSlider channel=\"hue\" defaultValue=\"hsl(24, 100%, 59%)\" aria-label=\"Hue\" />\n  <ColorSlider\n    channel=\"saturation\"\n    colorSpace=\"hsl\"\n    defaultValue=\"hsl(24, 100%, 59%)\"\n    aria-label=\"Saturation\"\n  />\n  <ColorSlider channel=\"alpha\" defaultValue=\"#ff6a2e\" aria-label=\"Alpha\" />\n</div>",
+      "note": "One channel at a time. The track paints the gradient for the channel it controls.",
+      "interaction": "arrow keys step, Home and End jump to the channel bounds; the value is spoken as a colour, not a number."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/color-swatch.json

@@ -0,0 +1,68 @@
+{
+  "name": "ColorSwatch",
+  "slug": "color-swatch",
+  "group": "color",
+  "importPath": "@cueplusplus/ui/color",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "A colour, shown as a chip.\n\nTwo elements rather than one: the frame carries the rim, the radius and the\ntransparency checkerboard, and React Aria's `ColorSwatch` paints the colour\non top of it. One element cannot do both — the library writes the colour into\nthe inline `background-color`, which paints *behind* a background image, so a\ncheckerboard set on the same element would cover the colour instead of\nbacking it.\n\nTakes any notation this suite reads, `oklch()` included.\n\n`react-aria-components` is an **optional peer**: import this from\n`@cueplusplus/ui/color`.",
+  "props": [
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the icon ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the frame."
+    }
+  ],
+  "typeReferences": [
+    "Omit<AriaColorSwatchProps, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-control-sm",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-surface-1",
+    "--cue-surface-3"
+  ],
+  "summary": "A colour, shown as a chip.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ColorSwatch color=\"oklch(0.7 0.15 30)\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/color-swatch",
+  "mdUrl": "/docs/components/color-swatch.md",
+  "jsonUrl": "/r/components/color-swatch.json",
+  "specimens": [
+    {
+      "title": "ColorSwatch",
+      "group": "color",
+      "components": [
+        "ColorSwatch"
+      ],
+      "code": "<Specimens>\n  {SWATCHES.map((swatch) => (\n    <Specimen key={swatch.label} label={swatch.label}>\n      <ColorSwatch color={swatch.value} />\n    </Specimen>\n  ))}\n  <Specimen label=\"sm\">\n    <ColorSwatch color=\"#ff6a2e\" size=\"sm\" />\n  </Specimen>\n  <Specimen label=\"lg\">\n    <ColorSwatch color=\"#ff6a2e\" size=\"lg\" />\n  </Specimen>\n  <Specimen label=\"translucent\">\n    <ColorSwatch color=\"#ff6a2e66\" size=\"lg\" />\n  </Specimen>\n</Specimens>",
+      "note": "A colour as a readable object: three sizes, a checkerboard behind anything translucent, and a spoken description of the colour.",
+      "interaction": "none. A swatch is a readout unless a picker wraps it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/colors-section.json

@@ -0,0 +1,66 @@
+{
+  "name": "ColorsSection",
+  "slug": "colors-section",
+  "group": "configurator",
+  "importPath": "@cueplusplus/ui/configurator",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "Section 2 — every colour the active theme declares, one row each.\n\nThe rows are grouped by what the colour does; the editing itself lives in\n{@link TokenEditor}, which is stateless and reusable.",
+  "props": [
+    {
+      "name": "edits",
+      "type": "TokenEdits",
+      "required": true,
+      "defaultValue": null,
+      "description": "The panel's edit surface."
+    },
+    {
+      "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 2 — every colour the active theme declares, one row each.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ColorsSection edits={edits} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/colors-section",
+  "mdUrl": "/docs/components/colors-section.md",
+  "jsonUrl": "/r/components/colors-section.json",
+  "todo": true
+}

package/manifest/components/combobox.json

@@ -0,0 +1,198 @@
+{
+  "name": "Combobox",
+  "slug": "combobox",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A {@link Select } you can type into: one value out of a known, filterable set.\n\nThe line between this and {@link Autocomplete } is worth holding: a combobox's\nvalue is always one of `items` — the text is a *filter*, and anything not in\nthe list cannot be chosen. An autocomplete's value is whatever the user typed\nand the list is only a suggestion. Pick the one whose contract matches what\nhappens to the value downstream.\n\nThe public API is string-valued like `Select`'s, even though Base UI's item\nvalues are the option objects: a caller stores `\"wash\"`, not an object it has\nto keep referentially stable across renders.\n\nThe popup is portalled through {@link useCuePortalProps}, so it carries the\ncaller's `data-theme` / `data-density` / `data-mode` even though it mounts at\nthe end of `<body>`.",
+  "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": "string | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "Selected value. Use with `onValueChange` for a controlled combobox."
+    },
+    {
+      "name": "defaultValue",
+      "type": "string | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initially selected value for an uncontrolled combobox."
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string | null) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the newly selected value (`null` when cleared)."
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Shown while the input is empty."
+    },
+    {
+      "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": null,
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "autoHighlight",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Highlight the first match automatically so Enter picks it."
+    },
+    {
+      "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 a value before the owning form submits."
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Name for the hidden input, when the combobox 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": "clearLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Clear selection",
+      "description": "Accessible name for the clear button. Defaults to `\"Clear selection\"`."
+    },
+    {
+      "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-md",
+    "--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": "A {@link Select } you can type into: one value out of a known, filterable set.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Combobox aria-label=\"Fixture\" items={fixtures} value={fixture} onValueChange={setFixture} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/combobox",
+  "mdUrl": "/docs/components/combobox.md",
+  "jsonUrl": "/r/components/combobox.json",
+  "specimens": [
+    {
+      "title": "Combobox",
+      "group": "forms",
+      "components": [
+        "Combobox"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-3\">\n  <Combobox\n    aria-label=\"Fixture type\"\n    items={FIXTURE_OPTIONS}\n    defaultValue=\"s4\"\n    placeholder=\"Fixture type\"\n  />\n  <Combobox\n    aria-label=\"Fixture type, empty\"\n    items={FIXTURE_OPTIONS}\n    placeholder=\"Fixture type\"\n    emptyMessage={COPY.empty.title}\n  />\n  <Combobox\n    aria-label=\"Fixture type, disabled\"\n    items={FIXTURE_OPTIONS}\n    defaultValue=\"par64\"\n    disabled\n  />\n</div>",
+      "note": "A filtered list with a committed value. An item can be disabled; the empty message is a real string, not a blank popup.",
+      "interaction": "arrow keys move the highlight, Enter commits, Escape reverts to the committed value."
+    }
+  ],
+  "todo": true
+}