prime-ui-kit 0.7.13 → 0.9.1

package/src/components/color-picker/COMPONENT.md

@@ -1,195 +1,329 @@
 # ColorPicker
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** selection
+**Kind:** field
 
-## Canonical
+> Color selection: a full picker (hex field, area, channel sliders and fields, eyedropper, swatches) and `ColorPresets` for a quick color from a fixed palette.
 
-`ColorPicker` is a **react-aria-components** color surface: one shared `Color` flows through a 2D area, channel sliders, optional preset swatches, a kit **HexInput**, and a channel strip with an eyedropper slot. **`ColorPicker.Root`** owns state; **`FormatProvider`** is mandatory for **`FormatSelect`** and **`ChannelStrip`**. **`parseColor`** and **`onChange`** use RAC **`Color`**; persist with **`color.toString("hex")`**, **`"css"`**, or **`"hexa"`** as needed.
+## When to use
+- `ColorPicker` — any color is allowed: brand / theme color, chart series color, design tools. Usually a hex field with a swatch button that opens the panel in a Popover.
+- `ColorPresets` — a color from a fixed palette with an optional «no color»: label, project or calendar colors, one trigger per row.
+- `parseColor` — turning a CSS string into a `Color` for a controlled `ColorPicker`.
 
-- **Use for:** theme/accent tuning, brand palettes, variant swatches, or any form field that stores a CSS-parseable color.
-- **Do not use for:** hex-only entry with no visual benefit (prefer [Input](../input/COMPONENT.md)); full chrome always inline in dense UI (mount the panel in [Popover](../popover/COMPONENT.md), [Modal](../modal/COMPONENT.md), or [Drawer](../drawer/COMPONENT.md)); eyedropper as the only input path (it is absent without **`window.EyeDropper`**).
-
-Runnable TSX: **playground** snippets in [`playground/snippets/color-picker/`](../../../playground/snippets/color-picker/) (order matches `playground/sections/ColorPickerSection.tsx`); **package** recipes in [`examples/`](./examples/) importing **`prime-ui-kit`**.
-
-## Extended
-
-### About
-
-The picker composes RAC primitives with kit styling (checkerboard for transparency on tracks/swatches). **`TriggerSwatch`** mirrors the live color for button triggers but is **`aria-hidden`**—name the control via visible label text or **`aria-label`**. Sliders are fixed at visual size **`m`**; only **`HexInput`** exposes the kit **`size`** axis (**`s`**–**`xl`**).
-
-### Scenarios (playground)
-
-Same order as `playground/sections/ColorPickerSection.tsx`. Snippets use the `@/` alias.
-
-| Scenario | Snippet |
-|----------|---------|
-| Hex input sizes — four **`HexInput`** values (**`s`**–**`xl`**), each behind its own popover | [`hex-input-sizes.tsx`](../../../playground/snippets/color-picker/hex-input-sizes.tsx) |
-| Format variants — three popovers with **`FormatProvider`** **`defaultFormat`** **`hsl` / `rgb` / `hex`** | [`format-variants.tsx`](../../../playground/snippets/color-picker/format-variants.tsx) |
-| States — disabled **`SwatchPickerItem`** and disabled hue **`Slider`** | [`states.tsx`](../../../playground/snippets/color-picker/states.tsx) |
-| Panel placement — same panel with **`Popover.Content`** **`side="bottom"`** vs **`"top"`** | [`panel-placement.tsx`](../../../playground/snippets/color-picker/panel-placement.tsx) |
-| Controlled — **`value`** / **`onChange`**, CSS readout outside the popover | [`controlled.tsx`](../../../playground/snippets/color-picker/controlled.tsx) |
-| Composition — full panel: **`FormatSelect`**, area, sliders (incl. alpha), **`ChannelStrip`**, **`SwatchPicker`** | [`composition.tsx`](../../../playground/snippets/color-picker/composition.tsx) |
-| Full width — wide **`Popover.Content`** and inner surface stretched | [`full-width.tsx`](../../../playground/snippets/color-picker/full-width.tsx) |
-| Custom trigger readout — color square + CSS string on the button; **`ColorPicker.Root`** inside **`Popover.Content`** | [`popover.tsx`](../../../playground/snippets/color-picker/popover.tsx) |
-| Field + eyedropper — **`Field`** + **`EyeDropperButton`**, area, hue slider | [`features.tsx`](../../../playground/snippets/color-picker/features.tsx) |
-
-### Package examples (`examples/`)
-
-Recipes import **`prime-ui-kit`** (no playground `@/` alias). Several mirror a playground snippet; thematic recipes cover product-shaped use cases.
-
-| Scenario | File |
-|----------|------|
-| Minimal valid popover + **`FormatProvider`** skeleton | [`minimal-popover.tsx`](./examples/minimal-popover.tsx) |
-| Controlled accent + readout (aligned with playground **Controlled**) | [`theme-accent.tsx`](./examples/theme-accent.tsx) |
-| Form label, popover pick, **`HexInput`** beside the trigger | [`controlled-form-field.tsx`](./examples/controlled-form-field.tsx) |
-| Brand presets, area, sliders, strip, **`HexInput`** (close to **Composition**; no separate alpha slider) | [`brand-kit.tsx`](./examples/brand-kit.tsx) |
-| Product variant swatches + fine tune | [`product-variant-swatch.tsx`](./examples/product-variant-swatch.tsx) |
-| Hex **`size`** ladder | [`hex-input-sizes.tsx`](./examples/hex-input-sizes.tsx) |
-| **`defaultFormat`** HSL / RGB / hex | [`format-variants.tsx`](./examples/format-variants.tsx) |
-| Disabled swatch and disabled slider | [`states.tsx`](./examples/states.tsx) |
-| **`Popover.Content`** **`side`** bottom vs top | [`panel-placement.tsx`](./examples/panel-placement.tsx) |
-| Wide popover + stretched inner column | [`full-width.tsx`](./examples/full-width.tsx) |
-| Custom swatch on trigger + **`Root`** in content (playground **popover**) | [`readout-trigger.tsx`](./examples/readout-trigger.tsx) |
-| **`Field`** + **`EyeDropperButton`** + area + slider (playground **features**); uses **`react-aria-components`** **`Input`** | [`field-eyedropper.tsx`](./examples/field-eyedropper.tsx) |
-
-### Composition
-
-- **`ColorPicker.Root`** wraps every control that shares one color (trigger + panel). Keep **`TriggerSwatch`** under the same **`Root`** as the panel so the preview stays in sync.
-- Put the interactive surface (area, sliders, swatches, **`HexInput`**, **`ChannelStrip`**) inside **`Popover.Content`** (or modal/drawer) in product layouts; pair with [Button](../button/COMPONENT.md) + **`TriggerSwatch`** or an accessible trigger.
-- Wrap subtree that needs format switching or the strip in **`FormatProvider`** before **`FormatSelect`**, **`ChannelStrip`**, or strip-driven cells. **`FormatSelect`** returns **`null`** outside **`FormatProvider`**.
-- Typical panel order: **`FormatProvider`** → optional **`FormatSelect`** → **`Area`** + **`AreaThumb`** → **`Slider`** trees (**`SliderMeta`** optional, then **`SliderTrack`** → **`Thumb`**) → **`ChannelStrip`** (**`pipetteIcon`** required) → optional **`SwatchPicker`** / **`SwatchPickerItem`** / **`Swatch`** → optional **`HexInput`** or RAC **`Field`**.
-- **`EyeDropperButton`** is embedded in **`ChannelStrip`**; pass **`pipetteIcon`** (e.g. [Button.Icon](../button/COMPONENT.md) + icon). Standalone use is possible under the same **`Root`** with an explicit **`aria-label`** if needed.
-
-### Minimal example
+## When not to use
+- The color is a field of its own in a form or dialog (stage, label, project color) → use [ColorSwatches](../color-swatches/COMPONENT.md): the palette inline, no popover.
+- Picking one of the kit palette hues for a Badge in TagSelect — the row menu of [TagSelect](../tag-select/COMPONENT.md) already does it.
+- Choosing between a few named themes or modes → use [SegmentedControl](../segmented-control/COMPONENT.md) or [Select](../select/COMPONENT.md) instead.
+- A plain text field for a hex code without a picker → use [Input](../input/COMPONENT.md) instead.
 
+## Import
 ```tsx
-import { Button, ColorPicker, Popover } from "prime-ui-kit";
-
-export function MinimalColorField() {
-  return (
-    <ColorPicker.Root defaultValue="#3b82f6">
-      <Popover.Root>
-        <Popover.Trigger asChild>
-          <Button.Root mode="stroke" variant="neutral">
-            <ColorPicker.TriggerSwatch />
-            Color
-          </Button.Root>
-        </Popover.Trigger>
-        <Popover.Content align="start" side="bottom">
-          <ColorPicker.FormatProvider>
-            <ColorPicker.FormatSelect />
-            <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness">
-              <ColorPicker.AreaThumb />
-            </ColorPicker.Area>
-            <ColorPicker.ChannelStrip pipetteIcon={<span aria-hidden />} />
-          </ColorPicker.FormatProvider>
-        </Popover.Content>
-      </Popover.Root>
-    </ColorPicker.Root>
-  );
-}
+import { COLOR_PRESETS, ColorPresets } from "prime-ui-kit";
+import { ColorPicker, parseColor } from "prime-ui-kit/color-picker";
 ```
 
-### Rules
-
-- **Controlled:** **`value`** + **`onChange`** when the parent owns color; **`defaultValue`** when uncontrolled. **`onChange`** receives **`Color`**.
-- Type with **`ColorPickerColorValue`** (re-export of RAC **`Color`**) or import **`Color`** from **`react-aria-components`**. Initialize **`useState`** from strings via **`parseColor`** from **`prime-ui-kit`** (**throws** on invalid strings).
-- **`children`** on **`Root`** may be a render function receiving **`ColorPickerRenderProps`** (`{ color }`).
-- There is **no** single **`isDisabled`** on **`Root`**—disable **`Area`**, **`Slider`**, **`SwatchPickerItem`**, or use a disabled **`fieldset`** where appropriate.
-- **`ChannelStrip`** must receive **`pipetteIcon`**. Without **`EyeDropper`**, the control is disabled and **`aria-hidden`**—do not rely on it alone.
-- **`FormatProvider`** sets initial strip mode via **`defaultFormat`**: **`"hsl"`** | **`"rgb"`** | **`"hex"`**.
-- **`HexInput`** and strip hex cells **revert** invalid input on blur/Enter; numeric strip cells **ignore** non-numeric commits.
-- **`SwatchPicker`** needs an accessible name (**`aria-label`** or associated label). Follow RAC for **`SwatchPicker`** / **`SwatchPickerItem`** selection props.
-- **`Area`**, **`Slider`**, **`Swatch`**, etc. use RAC prop surfaces (e.g. **`Area`**: **`colorSpace`**, **`xChannel`**, **`yChannel`**; **`Slider`**: **`channel`**, optional **`colorSpace`**, **`orientation`**, **`isDisabled`**).
-
-### API
-
-#### ColorPicker.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `string \| Color` | — | No | Controlled color value |
-| defaultValue | `string \| Color` | — | No | Initial color when uncontrolled |
-| onChange | `(color: Color) => void` | — | No | Fires when any nested control changes the color |
-| children | `ReactNode \| (props: ColorPickerRenderProps) => ReactNode` | — | Yes | Pickers, triggers, and panels sharing state |
-| slot | `string \| null` | — | No | Slotted context name (RAC `SlotProps`) |
-| className | `string \| (values) => string` | — | No | Root element classes (RAC render props) |
-| …rest | RAC + DOM | — | No | Other **`ColorPickerRootProps`** / `AriaColorPickerProps` from react-aria-components |
-
-#### ColorPicker.FormatProvider
+`ColorPicker` has its own entry: it is the only part of the kit built on `react-aria-components`,
+an optional peer dependency — install it only when you use `ColorPicker`. Its styles are already
+in `prime-ui-kit/bundle.css`. `ColorPresets` stays in the main entry and needs no extra package.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `ReactNode` | — | Yes | Subtree that may use `FormatSelect` and `ChannelStrip` |
-| defaultFormat | `"hsl" \| "rgb" \| "hex"` | `"hsl"` | No | Initial format for the strip and format select |
-
-#### ColorPicker.FormatSelect
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Class on the wrapper around the kit [Select](../select/COMPONENT.md) |
-
-Renders `null` when not under `FormatProvider`.
-
-#### ColorPicker.ChannelStrip
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| pipetteIcon | `ReactNode` | — | Yes | Icon for the embedded eyedropper ([Button.Icon](../button/COMPONENT.md) + icon) |
-| className | `string` | — | No | Class on the strip container |
-
-#### ColorPicker.HexInput
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Passed to kit [Input](../input/COMPONENT.md) |
-| label | `ReactNode` | `"Hex"` | No | Field label |
-| className | `string` | — | No | Class on `Input.Root` |
-
-#### ColorPicker.TriggerSwatch
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Class on the preview square |
-
-#### ColorPicker.SliderMeta
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| label | `ReactNode` | — | Yes | Left label; current channel value on the right via `Output` |
-
-#### ColorPicker.EyeDropperButton
-
-Same props as **`Button.Root`** except **`variant`**, **`mode`**, and **`size`** are fixed (`neutral`, `stroke`, `m`). Forwarded ref: **`HTMLButtonElement`**. Children are usually **`Button.Icon`**.
-
-#### ColorPicker.Area, AreaThumb, Slider, SliderTrack, Thumb, Output, Field, SwatchPicker, SwatchPickerItem, Swatch
-
-Styled wrappers around matching **react-aria-components** primitives; use their RAC APIs. **`Swatch`** and **`SliderTrack`** add checkerboard layering for transparency in kit styles.
-
-#### `parseColor(value: string): Color`
+## Anatomy
+```
+ColorPicker.Root                 shared Color + value format (no DOM)
+├─ ColorPicker.HexInput          kit Input bound to the hex of the current color
+├─ ColorPicker.TriggerSwatch     square of the current color for a trigger button
+└─ ColorPicker.Panel             vertical stack, optional raised surface
+   ├─ ColorPicker.FormatSelect   kit Select: HSL / RGB / Hex
+   ├─ ColorPicker.Area           2D area (4:3)
+   │  └─ ColorPicker.AreaThumb
+   ├─ ColorPicker.Slider         one channel
+   │  ├─ ColorPicker.SliderMeta  label + value row
+   │  └─ ColorPicker.SliderTrack
+   │     └─ ColorPicker.Thumb
+   ├─ ColorPicker.ChannelStrip   eyedropper + channel fields of the current format
+   ├─ ColorPicker.EyeDropperButton
+   └─ ColorPicker.Swatches       kit ColorSwatches bound to the color
+
+ColorPresets.Root                value, open, presets (no DOM)
+├─ ColorPresets.Trigger          square swatch button (or `asChild` with ColorPresets.Swatch)
+└─ ColorPresets.Content          popover with the swatch grid (listbox)
+```
+Helpers: `parseColor(value)` (throws on invalid input; back to text with `color.toString("hex" | "hexa" | "css")`), `COLOR_PRESETS` (16 colors: step 500 and step 700 of eight hues), types `ColorPickerColorValue`, `ColorValueFormat`, `ColorPreset`.
 
-Parses a CSS color string into **`Color`**. **Throws** if parsing fails.
+## API
 
-Exported types: **`ColorPickerRootProps`**, **`ColorPickerHexInputProps`**, **`ColorPickerFormatProviderProps`**, **`ColorPickerTriggerSwatchProps`**, **`ColorValueFormat`**, **`ColorPickerRenderProps`**, **`ColorPickerColorValue`**.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-### Related
+### ColorPicker.Root
+No DOM. Holds the color (React Aria `ColorPicker`) and the value format for every part inside.
 
-- [Popover](../popover/COMPONENT.md)
-- [Button](../button/COMPONENT.md)
-- [Input](../input/COMPONENT.md)
-- [Select](../select/COMPONENT.md)
-- [Modal](../modal/COMPONENT.md)
-- [Drawer](../drawer/COMPONENT.md)
-- [Label](../label/COMPONENT.md)
-- [Typography](../typography/COMPONENT.md)
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string \| Color` | — | Controlled color: a CSS color string or a `Color` from `parseColor`. |
+| `defaultValue` | `string \| Color` | — | Initial color when uncontrolled. |
+| `onValueChange` | `(color: Color) => void` | — | Called with the new `Color` (`color.toString("hex")` for a string). |
+| `defaultFormat` | `"hsl" \| "rgb" \| "hex"` | `"hsl"` | Initial value format of `FormatSelect` and `ChannelStrip`. |
+| `labels` | `Partial<ColorPickerLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — (required) | The parts. |
 
-## LLM note
+### ColorPicker.Panel
+`ref` → `HTMLDivElement`. Vertical stack of the parts with the standard gap; native `<div>` props.
 
-- Always place **`FormatProvider`** above **`FormatSelect`**, **`ChannelStrip`**, or any code path that calls into strip format context—missing provider throws at runtime.
-- **`ChannelStrip`** requires **`pipetteIcon`**; use a real icon node or a minimal **`<span aria-hidden />`** only for docs/tests.
-- **`TriggerSwatch`** is **`aria-hidden`**; the trigger **Button** (or other control) must expose the purpose via visible text or **`aria-label`**.
-- Controlled integration: **`value`** can be **`string | Color`**; **`onChange`** always yields **`Color`**—serialize with **`toString(...)`** for APIs expecting strings.
-- **`parseColor`** throws on bad input; guard user paste if you cannot tolerate exceptions.
-- Dense UIs: mount the picker body in **[Popover](../popover/COMPONENT.md)** / **[Modal](../modal/COMPONENT.md)** / **[Drawer](../drawer/COMPONENT.md)**, not inline in toolbars.
-- Do not assume **`EyeDropper`** exists; provide sliders, hex, or swatches as primary input paths.
-- For copy-paste recipes, start from **`examples/minimal-popover.tsx`** or the **Minimal example** above; match **Scenarios (playground)** via the linked snippets or the **Package examples** table.
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `surface` | `"none" \| "raised"` | `"none"` | `none` — layout only (inside a Popover or Card). `raised` — a standalone floating panel: raised background, panel radius and padding, overlay shadow. |
+
+### ColorPicker.HexInput
+`ref` → `HTMLDivElement` (the field frame). The hex value as a kit Input field (label, hint, error); commits on blur / Enter and reverts invalid text.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Field label; defaults to `labels.hex`. |
+| `hint` | `ReactNode` | — | Help text under the field. Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; marks the field invalid. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Field tier. Without it the tier of its host (a panel, a popover), else `m`. |
+| `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring of the fields (`data-focus-ring="false"`); focus, keyboard and ARIA stay. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
+
+### ColorPicker.TriggerSwatch
+`ref` → `HTMLSpanElement`. A square of the current color for a trigger button (`aria-hidden`); follows the host icon size, e.g. inside `Button.Icon`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the `<span>`. |
+
+### ColorPicker.FormatSelect
+`ref` → `HTMLDivElement` (the wrapper). A kit Select of the value format (HSL · RGB · Hex), named by `labels.format`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the wrapper `<div>`. |
+
+### ColorPicker.ChannelStrip
+`ref` → `HTMLDivElement`. One row: the eyedropper, then a field per channel of the current format (or one hex field); each field commits on blur / Enter.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring of the fields (`data-focus-ring="false"`); focus, keyboard and ARIA stay. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the row `<div>`. |
+
+### ColorPicker.Area
+`ref` → `HTMLDivElement`. React Aria `ColorArea`: a two-channel square (e.g. saturation × lightness). Holds `ColorPicker.AreaThumb`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `disabled` | `boolean` | — | Shows the color but takes no input (grayscale). |
+| `…rest` | `ColorAreaProps (react-aria-components)` | — | The other props of the React Aria `ColorArea` (`channel`, `colorSpace`, `aria-label`…). |
+
+### ColorPicker.AreaThumb · ColorPicker.Thumb
+`ref` → `HTMLDivElement`. React Aria `ColorThumb` of the area / of a slider track: a thumb-colored ring with the overlay shadow and a focus ring.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `ColorThumbProps (react-aria-components)` | — | The other props of the React Aria `ColorThumb` (`channel`, `colorSpace`, `aria-label`…). |
+
+### ColorPicker.Slider
+`ref` → `HTMLDivElement`. React Aria `ColorSlider` of one channel (hue, alpha…). Holds `SliderMeta` and `SliderTrack`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `disabled` | `boolean` | — | Shows the color but takes no input (grayscale). |
+| `…rest` | `ColorSliderProps (react-aria-components)` | — | The other props of the React Aria `ColorSlider` (`channel`, `colorSpace`, `aria-label`…). |
+
+### ColorPicker.SliderMeta
+`ref` → `HTMLDivElement`. The slider heading: a label and the current channel value.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — (required) | Visible label of the slider. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the heading `<div>`. |
+
+### ColorPicker.SliderTrack
+`ref` → `HTMLDivElement`. React Aria `SliderTrack` with the channel gradient over a transparency checkerboard. Holds `ColorPicker.Thumb`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `SliderTrackProps (react-aria-components)` | — | The other props of the React Aria `SliderTrack` (`channel`, `colorSpace`, `aria-label`…). |
+
+### ColorPicker.Swatches
+`ref` → `HTMLDivElement` (the ColorSwatches field frame). The kit `ColorSwatches` bound to the picker color: a pick sets the color, editing the color moves the selection. Takes every ColorSwatches prop except the value ones, `allowEmpty` and `name`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `presets` | `readonly ColorPreset[]` | `COLOR_PRESETS` | Swatches `{ value, label }`; the label names the swatch. |
+| `…rest` | `Omit<ColorSwatchesProps, "value" \| "defaultValue" \| "onValueChange" \| "allowEmpty" \| "name">` | — | `label`, `size`, `aria-label`, `disabled`… |
+
+### ColorPicker.EyeDropperButton
+`ref` → `HTMLButtonElement`. A square soft kit Button that opens the native EyeDropper, named by `labels.eyeDropper`; without browser support it is disabled and hidden from assistive tech.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Custom content; default is the pipette icon. |
+| `…rest` | `Omit<ButtonRootProps, "variant" \| "tone" \| "size" \| "aria-label">` | — | The other Button props. |
+
+### ColorPresets.Root
+No DOM. A quick color from a fixed palette: a square trigger and a popover grid of presets (Popover overlay contract).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string \| null` | — | Controlled color; `null` — no color. |
+| `defaultValue` | `string \| null` | `null` | Initial color when uncontrolled. |
+| `onValueChange` | `(value: string \| null) => void` | — | Called with the preset `value` or `null`. |
+| `open` | `boolean` | — | Controlled open state of the panel. |
+| `defaultOpen` | `boolean` | `false` | Initial open state. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when the panel opens or closes. |
+| `presets` | `readonly ColorPreset[]` | `COLOR_PRESETS` | Swatches in panel order. |
+| `columns` | `number` | — | Grid columns; default one row for up to 8 presets (+ «no color»), else 8. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the trigger, the swatches and the panel. Without it the tier of its host, else `m`. |
+| `disabled` | `boolean` | `false` | The trigger does not open the panel. |
+| `allowEmpty` | `boolean` | `false` | Adds the «no color» swatch after the presets (value `null`). |
+| `closeOnSelect` | `boolean` | `true` | Close the panel after a pick (focus returns to the trigger). |
+| `labels` | `Partial<ColorPresetsLabels>` | — | Built-in strings, see Labels. |
+
+### ColorPresets.Trigger
+`ref` → `HTMLButtonElement`. The kit square swatch button of the root tier, named «`labels.trigger`: <color name>»; ArrowDown / ArrowUp open the panel.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Use the one child element (e.g. `Button.Root` with `ColorPresets.Swatch`) as the trigger. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" \| "disabled" \| "value">` | — | `aria-label`, `className` and the other button attributes. |
+
+### ColorPresets.Swatch
+`ref` → `HTMLSpanElement`. The current color as a small square for a custom trigger; follows the host icon size, `aria-hidden`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the `<span>`. |
+
+### ColorPresets.Content
+`ref` → `HTMLDivElement` (the panel). The floating panel with the swatch grid (`role="listbox"`); focus moves to the selected swatch.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Heading above the grid; also the list's accessible name (else `labels.list`). |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Side of the trigger. |
+| `align` | `"start" \| "center" \| "end"` | `"start"` | Alignment along the trigger. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role">` | — | `className` and the other attributes of the panel. |
+
+## Variants
+No `variant` / `tone` / `color`.
+
+### surface (ColorPicker.Panel)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `none` | parts stacked with a 12px gap, no own background | inside a Popover or a Card | yes |
+| `raised` | `bg-raised`, panel radius and padding, `shadow-overlay`; fields switch to `field-bg-surface` | a standalone panel on the page | |
+
+### defaultFormat (ColorPicker.Root)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `hsl` | hue °, saturation %, lightness %, alpha % fields | designers tuning a hue | yes |
+| `rgb` | red, green, blue (0–255), alpha % | developer-facing tools | |
+| `hex` | one hex field | brand colors copied from guidelines | |
+
+### size (HexInput, ColorPresets)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28px field / trigger, 16px preset swatches | dense tables | |
+| `s` | 32px, 20px swatches | rows inside popovers and lists | |
+| `m` | 36px, 24px swatches | regular forms | yes |
+| `l` | 40px, 28px swatches | spacious forms | |
+| `xl` | 48px, 32px swatches | touch-first screens | |
+
+**Sizes:** the ColorPresets trigger is a square of the control height, so it lines up with an Input of the same size; HexInput + a square soft `Button.Root` of the same `size` with `TriggerSwatch` inside `Button.Icon` match too. Area, sliders and the channel strip have no size axis (always tier `m`).
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `allowEmpty` (ColorPresets) | checkerboard «Без цвета» swatch at the end | the color is optional | `false` |
+| `closeOnSelect={false}` (ColorPresets) | panel stays open after a pick | trying several colors in a row | `true` |
+| `asChild` (ColorPresets.Trigger) | your element (e.g. a soft Button with the swatch as its icon) | the trigger needs text | `false` |
+| `disabled` (Area, Slider) | grayscale, no input | the part is locked | — |
+
+**Combinations**
+- `surface="raised"` inside a Popover → double surface; keep `none` there.
+- Several Roots with one controlled `value` → all parts edit the same color.
+- Prefer `ColorPresets` when a palette is enough; open the full `ColorPicker` only where any color is valid.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| disabled part | `disabled` on Area / Slider | React Aria `data-disabled`; muted, not interactive |
+| focus-visible | keyboard | React Aria `data-focus-visible`; `data-focus-ring="false"` on fields with `focusRing={false}` |
+| invalid hex | typing | reverts to the current color on blur / Enter |
+| hex error | `error` on HexInput | `aria-invalid`, danger ring, the error replaces the hint |
+| eyedropper unsupported | no `window.EyeDropper` | button `disabled`, `aria-hidden` |
+| selected swatch | the color | `data-state="checked"`; accent ring with a 2px offset and a contrasting check |
+| ColorPresets open | `open` / click / ArrowDown · ArrowUp on the trigger | popover `data-state`; focus on the selected swatch |
+| ColorPresets empty | value `null` | trigger `data-empty`; checkerboard fill |
+
+There is no `disabled` on `ColorPicker.Root` — disable parts individually. Controlled: `value` + `onValueChange` (both components), `open` + `onOpenChange` (ColorPresets). Uncontrolled: `defaultValue`, `defaultOpen`.
+
+## Layout & spacing
+- Panel width comes from the layout (e.g. `calc(var(--prime-panel-min-width) * 1.5)` fits the area and four channel fields).
+- Field + trigger row: gap `--prime-space-2`, `align-items: flex-end` so the trigger aligns with the field box under a label.
+- Panel parts gap: 12px (`--prime-space-3`) from `ColorPicker.Panel`.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `ArrowLeft` · `ArrowRight` · `ArrowUp` · `ArrowDown` | Move the area thumb or a slider; in the ColorPresets grid, move between swatches. |
+| `PageUp` · `PageDown` | Larger steps on the area and the sliders. |
+| `Home` · `End` | Slider ends; the first / last swatch in the ColorPresets grid. |
+| `Enter` · `Space` | Commit a field; pick the focused preset swatch and close. |
+| `Tab` | Moves through the parts; inside the ColorPresets grid returns to the trigger and closes. |
+| `Escape` | Closes the ColorPresets panel. |
+
+### ARIA
+- Area and sliders are React Aria primitives with their own `role="slider"` names.
+- `TriggerSwatch` and `ColorPresets.Swatch` are `aria-hidden` — give the trigger button an `aria-label` (ColorPresets.Trigger names itself «`labels.trigger`: <color name>»).
+- `ColorPicker.Swatches` is a `role="radiogroup"` (ColorSwatches): name it with `label` or `aria-label`.
+- The ColorPresets grid is `role="listbox"` with `role="option"` swatches (roving tabindex), named by the Content `label` or `labels.list`.
+- Channel fields are named by `labels` (`hue`, `red`…); HexInput by its label (`labels.hex` by default).
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `format` | `"Формат значений цвета"` | Name of `ColorPicker.FormatSelect`. |
+| `eyeDropper` | `"Пипетка"` | Name of `ColorPicker.EyeDropperButton`. |
+| `hex` | `"Hex"` | Hex field of `ChannelStrip` and the default `HexInput` label. |
+| `hue` | `"Оттенок, градусы"` | Hue channel field. |
+| `saturation` | `"Насыщенность, проценты"` | Saturation channel field. |
+| `lightness` | `"Яркость, проценты"` | Lightness channel field. |
+| `alpha` | `"Непрозрачность, проценты"` | Alpha channel field. |
+| `red` | `"Красный, 0–255"` | Red channel field. |
+| `green` | `"Зелёный, 0–255"` | Green channel field. |
+| `blue` | `"Синий, 0–255"` | Blue channel field. |
+| `trigger` | `"Цвет"` | ColorPresets trigger name prefix: «<trigger>: <color name>». |
+| `list` | `"Цвета"` | ColorPresets swatch list name when `Content` has no `label`. |
+| `empty` | `"Без цвета"` | ColorPresets «no color» swatch and the trigger name for an empty value. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A color field: a hex value and a swatch button that opens the picker panel — `ColorPicker.HexInput`, `ColorPicker.TriggerSwatch`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size of the hex field with a swatch button of the same tier — `size`. |
+| [states.tsx](examples/states.tsx) | A disabled area and hue slider keep showing the color but take no input — `disabled`. |
+| [validation.tsx](examples/validation.tsx) | A hint under the hex field and an error that replaces it; invalid text reverts on blur — `hint`, `error`. |
+| [panel.tsx](examples/panel.tsx) | The full raised panel and its part order: format, area, hue and alpha sliders, channels, brand swatches — `ColorPicker.Panel`, `surface`, `ColorPicker.Swatches`. |
+| [formats.tsx](examples/formats.tsx) | The channel strip in each value format; three pickers edit one color — `defaultFormat`, `ColorPicker.ChannelStrip`. |
+| [presets.tsx](examples/presets.tsx) | A quick color from the palette: a square trigger next to a field and a Button trigger; «no color» allowed — `ColorPresets`, `allowEmpty`, `asChild`. |
+| [presets-sizes.tsx](examples/presets-sizes.tsx) | The preset trigger in every size, a square of the control height next to an input of the same tier — `ColorPresets`, `size`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the color: brand swatches and the hex field edit it, a button resets it — `value`, `onValueChange`. |
+| [in-form.tsx](examples/in-form.tsx) | Theme settings: the color goes with the form and a too light color fails on save — `value`, `error`. |
+
+## Mistakes
+- Trigger in one `ColorPicker.Root` and panel in another → they will not share the color; wrap both in one Root.
+- `isDisabled` on Area / Slider → use `disabled`.
+- `onChange` on `ColorPicker.Root` → use `onValueChange`.
+- `parseColor` on raw user input without try/catch → it throws on invalid strings.
+- `surface="raised"` inside a Popover → use the default `none`.
+- Expecting `ColorPresets` to return a `Color` → it returns the preset string (or `null`).
+- `<ColorPresets.Trigger asChild onKeyDown={…}>` → the handler is dropped; put it on the child element.
+
+## Related
+- **Built from:** [Input](../input/COMPONENT.md) (`HexInput`), [Select](../select/COMPONENT.md) (`FormatSelect`), [Button](../button/COMPONENT.md) (`EyeDropperButton`), [ColorSwatches](../color-swatches/COMPONENT.md) (`Swatches`), [Popover](../popover/COMPONENT.md) (`ColorPresets.Content`), `Icon` (check, pipette)
+- **See also:** [ColorSwatches](../color-swatches/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md)

package/src/components/color-picker/examples/controlled.tsx

@@ -0,0 +1,37 @@
+/** The parent owns the color: brand swatches and the hex field edit it, a button resets it — `value`, `onValueChange`. */
+import { Button } from "prime-ui-kit";
+import { ColorPicker, parseColor } from "prime-ui-kit/color-picker";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const DEFAULT_COLOR = "#5b5bd6";
+const BRAND_COLORS = [
+  { value: "#5b5bd6", label: "Индиго" },
+  { value: "#0090ff", label: "Синий" },
+  { value: "#12a594", label: "Бирюзовый" },
+  { value: "#f76b15", label: "Оранжевый" },
+  { value: "#e5484d", label: "Красный" },
+];
+
+export default function ColorPickerControlledExample() {
+  const [color, setColor] = React.useState(() => parseColor(DEFAULT_COLOR));
+
+  return (
+    <div className={styles.panel}>
+      <ColorPicker.Root value={color} onValueChange={setColor}>
+        <ColorPicker.HexInput label="Цвет витрины" hint={`Сейчас: ${color.toString("hex")}`} />
+        <ColorPicker.Swatches aria-label="Цвета бренда" presets={BRAND_COLORS} />
+      </ColorPicker.Root>
+      <div>
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          onClick={() => setColor(parseColor(DEFAULT_COLOR))}
+        >
+          Сбросить
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/color-picker/examples/examples.module.css

@@ -0,0 +1,48 @@
+/* Layout of the ColorPicker and ColorPresets scenarios: semantic tokens only. */
+
+/* An inline or popover panel width: the area and four channel fields fit. */
+.panel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
+  width: calc(var(--prime-panel-min-width) * 1.5);
+  max-width: 100%;
+}
+
+/* Hex field + swatch button of the same tier, bottom-aligned with the field box. */
+.fieldRow {
+  display: flex;
+  align-items: flex-end;
+  gap: var(--prime-space-2);
+  width: calc(var(--prime-panel-min-width) * 1.5);
+  max-width: 100%;
+}
+
+/* presets-sizes.tsx: preset trigger + field of the same tier in one row. */
+.row {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-2);
+  width: calc(var(--prime-panel-min-width) * 1.5);
+  max-width: 100%;
+}
+
+.inlineRow {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-3);
+}
+
+/* in-form.tsx: field → field 20, group → actions 32. */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-5);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.actions {
+  display: flex;
+  margin-top: var(--prime-space-3);
+}

package/src/components/color-picker/examples/formats.tsx

@@ -0,0 +1,26 @@
+/** The channel strip in each value format; three pickers edit one color — `defaultFormat`, `ColorPicker.ChannelStrip`. */
+import { ColorPicker, type ColorValueFormat, parseColor } from "prime-ui-kit/color-picker";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const FORMATS: ColorValueFormat[] = ["hsl", "rgb", "hex"];
+
+export default function ColorPickerFormatsExample() {
+  const [color, setColor] = React.useState(() => parseColor("hsl(160, 60%, 42%)"));
+
+  return (
+    <div className={styles.panel}>
+      {FORMATS.map((format) => (
+        <ColorPicker.Root
+          key={format}
+          value={color}
+          onValueChange={setColor}
+          defaultFormat={format}
+        >
+          <ColorPicker.ChannelStrip />
+        </ColorPicker.Root>
+      ))}
+    </div>
+  );
+}