prime-ui-kit 0.9.3 → 0.11.0

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

@@ -6,11 +6,12 @@
 > Color selection: a full picker (hex field, area, channel sliders and fields, eyedropper, swatches) and `ColorPresets` for a quick color from a fixed palette.
 
 ## 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.
+- `ColorPicker` — any color is allowed and the picker parts are laid out by hand: an inline panel, a design tool, a hex field with a custom trigger.
 - `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`.
 
 ## When not to use
+- Any color as one field of a form (swatch + hex, the panel in a popover) → use [ColorField](../color-field/COMPONENT.md).
 - 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.
@@ -44,7 +45,8 @@ ColorPicker.Root                 shared Color + value format (no DOM)
    └─ 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.Trigger          slot around one element
+│  └─ ColorPresets.SwatchButton  square swatch button (or your Button 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`.
@@ -174,18 +176,24 @@ No DOM. A quick color from a fixed palette: a square trigger and a popover grid
 | `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. |
+| `disabled` | `boolean` | `false` | The trigger is disabled and does not open the panel. A disabled `Fieldset` around it sets it too. |
 | `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.
+No DOM: clones the single child into the panel's trigger, merges `ref` and `onClick` (toggles), names it «`labels.trigger`: <color name>», sets `disabled` from the root and opens the panel on ArrowDown / ArrowUp. The child's own `aria-label`, `disabled` and handlers win.
 
 | 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. |
+| `children` | `ReactElement` | — (required) | One element: `ColorPresets.SwatchButton`, or e.g. `Button.Root` with `ColorPresets.Swatch`. |
+
+### ColorPresets.SwatchButton
+`ref` → `HTMLButtonElement`. The kit square swatch button of the root tier: a square of the control height filled with the current color. Put it in `ColorPresets.Trigger`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" \| "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`.
@@ -201,7 +209,7 @@ No DOM. A quick color from a fixed palette: a square trigger and a popover grid
 |---|---|---|---|
 | `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. |
+| `align` | `"auto" \| "start" \| "center" \| "end"` | `"auto"` | Alignment along the trigger. `auto` lines the panel up with the trigger edge that has more room beyond it; `start`, `center` or `end` fix it. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role">` | — | `className` and the other attributes of the panel. |
 
 ## Variants
@@ -229,14 +237,13 @@ No `variant` / `tone` / `color`.
 | `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`).
+**Sizes:** `ColorPresets.SwatchButton` 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**
@@ -252,9 +259,9 @@ No `variant` / `tone` / `color`.
 | 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 |
+| selected swatch | the color | `data-state="checked"`; a check mark that contrasts with the color draws in — no ring, the check is the selection |
 | 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 |
+| ColorPresets empty | value `null` | the trigger shows the checkerboard fill and is named «`labels.trigger`: `labels.empty`» |
 
 There is no `disabled` on `ColorPicker.Root` — disable parts individually. Controlled: `value` + `onValueChange` (both components), `open` + `onOpenChange` (ColorPresets). Uncontrolled: `defaultValue`, `defaultOpen`.
 
@@ -262,6 +269,8 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 - 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`.
+- ColorPresets.Content `align="auto"`: a trigger near the end of the screen lines up the panel's end edge and the panel grows toward the start, and the other way near the start; a fixed `align` still flips at the screen edge.
+- ColorPresets grid: one row for up to 8 presets (+ «no color»), else rows of 8 (`columns` overrides); below 480px viewport width the `l` / `xl` grids wrap to half the columns.
 
 ## Accessibility
 
@@ -277,7 +286,7 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 
 ### 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>»).
+- `TriggerSwatch` and `ColorPresets.Swatch` are `aria-hidden` — give the trigger button an `aria-label` (ColorPresets.Trigger names its element «`labels.trigger`: <color name>» unless the element has its own `aria-label`).
 - `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).
@@ -307,13 +316,13 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 | [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`. |
+| [validation.tsx](examples/validation.tsx) | A button color checked live: a too light color shakes in an error that leaves once the color is darker; a hint under the other field, 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.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`, `ColorPresets.Trigger`. |
 | [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`. |
+| [in-form.tsx](examples/in-form.tsx) | Theme settings: the color goes with the form, a too light color shakes in an error on save that leaves once the color changes — `value`, `error`. |
 
 ## Mistakes
 - Trigger in one `ColorPicker.Root` and panel in another → they will not share the color; wrap both in one Root.
@@ -322,8 +331,9 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 - `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.
+- `<ColorPresets.Trigger onKeyDown={…}>` or `className` on the Trigger → it is a slot with no props of its own; put them on the child element.
+- `<ColorPresets.Trigger />` with no child → put `ColorPresets.SwatchButton` (or your Button) inside it.
 
 ## 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)
+- **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.Root`, `ColorPresets.Content`), `Icon` (pipette)
+- **See also:** [ColorField](../color-field/COMPONENT.md), [ColorSwatches](../color-swatches/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md)

package/src/components/color-picker/examples/in-form.tsx

@@ -1,5 +1,5 @@
-/** Theme settings: the color goes with the form and a too light color fails on save — `value`, `error`. */
-import { Button, Input } from "prime-ui-kit";
+/** Theme settings: the color goes with the form, a too light color shakes in an error on save that leaves once the color changes — `value`, `error`. */
+import { Button, Input, Typography } from "prime-ui-kit";
 import { ColorPicker, parseColor } from "prime-ui-kit/color-picker";
 import * as React from "react";
 
@@ -10,13 +10,15 @@ const MAX_LIGHTNESS = 80;
 export default function ColorPickerInFormExample() {
   const [color, setColor] = React.useState(() => parseColor("#f2f2f2"));
   const [error, setError] = React.useState<string>();
+  const [saved, setSaved] = React.useState(false);
 
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
     const lightness = color.toFormat("hsl").getChannelValue("lightness");
-    setError(
-      lightness > MAX_LIGHTNESS ? "Слишком светлый: белый текст на нём не читается" : undefined,
-    );
+    const next =
+      lightness > MAX_LIGHTNESS ? "Слишком светлый: белый текст на нём не читается" : undefined;
+    setError(next);
+    setSaved(next === undefined);
   };
 
   return (
@@ -31,11 +33,17 @@ export default function ColorPickerInFormExample() {
         onValueChange={(next) => {
           setColor(next);
           setError(undefined);
+          setSaved(false);
         }}
       >
         <ColorPicker.HexInput label="Цвет кнопок" error={error} />
       </ColorPicker.Root>
       <input type="hidden" name="buttonColor" value={color.toString("hex")} />
+      {saved ? (
+        <Typography as="p" variant="body-s" tone="secondary" role="status">
+          Тема сохранена.
+        </Typography>
+      ) : null}
       <div className={styles.actions}>
         <Button.Root type="submit">Сохранить тему</Button.Root>
       </div>

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

@@ -17,7 +17,7 @@ export default function ColorPickerOverviewExample() {
               </Button.Icon>
             </Button.Root>
           </Popover.Trigger>
-          <Popover.Content align="end">
+          <Popover.Content>
             <ColorPicker.Panel className={styles.panel}>
               <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness">
                 <ColorPicker.AreaThumb />

package/src/components/color-picker/examples/presets-sizes.tsx

@@ -11,7 +11,9 @@ export default function ColorPickerPresetsSizesExample() {
       {SIZES.map((size) => (
         <div key={size} className={styles.row}>
           <ColorPresets.Root size={size} defaultValue="#f97316" labels={{ trigger: "Цвет метки" }}>
-            <ColorPresets.Trigger />
+            <ColorPresets.Trigger>
+              <ColorPresets.SwatchButton />
+            </ColorPresets.Trigger>
             <ColorPresets.Content />
           </ColorPresets.Root>
           <Input.Root size={size}>

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

@@ -1,4 +1,4 @@
-/** A quick color from the palette: a square trigger next to a field and a Button trigger; «no color» allowed — `ColorPresets`, `allowEmpty`, `asChild`. */
+/** A quick color from the palette: a square trigger next to a field and a Button trigger; «no color» allowed — `ColorPresets`, `allowEmpty`, `ColorPresets.Trigger`. */
 import { Button, COLOR_PRESETS, ColorPresets } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -14,11 +14,13 @@ export default function ColorPickerPresetsExample() {
         defaultValue="#5068f5"
         labels={{ trigger: "Цвет метки" }}
       >
-        <ColorPresets.Trigger />
+        <ColorPresets.Trigger>
+          <ColorPresets.SwatchButton />
+        </ColorPresets.Trigger>
         <ColorPresets.Content />
       </ColorPresets.Root>
       <ColorPresets.Root defaultValue="#22c55e">
-        <ColorPresets.Trigger asChild>
+        <ColorPresets.Trigger>
           <Button.Root variant="soft" tone="neutral">
             <Button.Icon>
               <ColorPresets.Swatch />

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

@@ -1,16 +1,22 @@
-/** A hint under the hex field and an error that replaces it; invalid text reverts on blur — `hint`, `error`. */
-import { ColorPicker } from "prime-ui-kit/color-picker";
+/** A button color checked live: a too light color shakes in an error that leaves once the color is darker; a hint under the other field, invalid text reverts on blur — `hint`, `error`. */
+import { ColorPicker, parseColor } from "prime-ui-kit/color-picker";
+import * as React from "react";
+
+const MAX_LIGHTNESS = 80;
 
 export default function ColorPickerValidationExample() {
+  const [color, setColor] = React.useState(() => parseColor("#f5f5f5"));
+  const tooLight = color.toFormat("hsl").getChannelValue("lightness") > MAX_LIGHTNESS;
+
   return (
     <>
       <ColorPicker.Root defaultValue="#0090ff">
         <ColorPicker.HexInput label="Цвет ссылок" hint="Формат #RRGGBB или #RRGGBBAA" />
       </ColorPicker.Root>
-      <ColorPicker.Root defaultValue="#f5f5f5">
+      <ColorPicker.Root value={color} onValueChange={setColor}>
         <ColorPicker.HexInput
           label="Цвет кнопок"
-          error="Слишком светлый: белый текст на нём не читается"
+          error={tooLight ? "Слишком светлый: белый текст на нём не читается" : undefined}
         />
       </ColorPicker.Root>
     </>

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

@@ -3,7 +3,7 @@
 **Category:** selection
 **Kind:** control
 
-> An inline color choice: preset swatches that wrap inside a form, without a popover.
+> An inline color choice: preset swatches that fill the width of a form or panel and wrap, without a popover.
 
 ## When to use
 - Picking a color for an entity in a form or dialog (pipeline stage, tag, project, calendar).
@@ -12,7 +12,7 @@
 
 ## When not to use
 - A compact color next to a field or in a dense list row (one trigger per row) → use [ColorPresets](../color-picker/COMPONENT.md) (trigger + popover palette).
-- A free color (any hex, eyedropper, channels) → use [ColorPicker](../color-picker/COMPONENT.md).
+- A free color (any hex, eyedropper, channels) → use [ColorField](../color-field/COMPONENT.md) in a form, [ColorPicker](../color-picker/COMPONENT.md) for a panel of its own.
 - Choosing a mode or a value that is not a color → use [SegmentedControl](../segmented-control/COMPONENT.md) or [Radio](../radio/COMPONENT.md).
 
 ## Import
@@ -23,7 +23,7 @@ import { COLOR_PRESETS, ColorSwatches } from "prime-ui-kit";
 ## Anatomy
 ```
 ColorSwatches                 field frame: label → swatches → hint | error
-└─ radiogroup                 wrapping row of swatches
+└─ radiogroup                 swatches sharing the width, wrapping into rows
    ├─ radio × presets         swatch button (color fill, faint inner ring, check when selected)
    ├─ radio «Без цвета»       checkerboard swatch (`allowEmpty`)
    └─ input[type=hidden]      submits the value (`name`)
@@ -42,7 +42,7 @@ ColorSwatches                 field frame: label → swatches → hint | error
 | `defaultValue` | `string \| null` | `null` | Initial color when uncontrolled. |
 | `onValueChange` | `(value: string \| null) => void` | — | Called with the preset `value` (as written in `presets`) or `null`. |
 | `presets` | `readonly ColorPreset[]` | `COLOR_PRESETS` | Swatches in order: `{ value, label }`; the label is the swatch's accessible name and tooltip. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier: swatch = control height − 8 (20 · 24 · 28 · 32 · 40), gap = the tier gap; label and hint follow it. Without it the tier of its host, else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the swatches (height 20 · 24 · 28 · 32 · 40); the label and hint keep the host tier. Without it the swatches take the host tier too. |
 | `label` | `ReactNode` | — | Label above the swatches; names the radiogroup (`aria-labelledby`). |
 | `required` | `boolean` | — | Red `*` after the label and `aria-required` on the group. |
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
@@ -70,7 +70,7 @@ ColorSwatches                 field frame: label → swatches → hint | error
 | `l` | Swatch 32, gap 8, radius 8 | Spacious settings pages | |
 | `xl` | Swatch 40, gap 12, radius 8 | Touch-first layouts | |
 
-**Sizes:** match the size of the form around it: an `m` form uses `m` swatches (28), which sit on the same 4px rhythm as `m` fields.
+**Sizes:** `size` sets the swatches only; the label and the hint keep the tier of the form around (else `m`), so larger swatches never enlarge the label. Without `size` the swatches take the host tier: an `m` form gets `m` swatches (28) on the same 4px rhythm as `m` fields.
 
 ### Flags
 | Value | Looks like | Use when | Default |
@@ -87,16 +87,16 @@ ColorSwatches                 field frame: label → swatches → hint | error
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| selected | `value` / `defaultValue` | `aria-checked="true"`, `data-state="checked"` on the radio; the check mark (light or dark by color contrast) scales in from half size (`base` · emphasized) and leaves faster (`fast` · exit); no ring — the check is the selection |
+| selected | `value` / `defaultValue` | `aria-checked="true"`, `data-state="checked"` on the radio; the check mark (light or dark by color contrast) draws in and grows from 0.6 (`base` · emphasized) and retracts faster (`fast` · exit); no ring — the check is the selection |
 | hover | pointer | the swatch scales to 1.08 (fine pointers only) |
 | focus-visible | keyboard | focus ring outside the swatch |
-| invalid | `invalid` / `error` | `aria-invalid`, `data-invalid` on the group; the inner edge of every swatch turns `danger-border` |
-| disabled | `disabled` | native `disabled` on every radio, `aria-disabled` and `data-disabled` on the group |
+| invalid | `invalid` / `error` | `aria-invalid`, `data-invalid` on the group; the inner edge of every swatch turns `danger-border`; the control shakes once when an error arrives (`data-shake` on the frame) |
+| disabled | `disabled` | native `disabled` on every radio, `data-disabled` on the group; the arrow keys do nothing |
 
 Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`.
 
 ## Layout & spacing
-- The swatches take the container width and wrap to new rows by themselves; no column count to set. In a content-sized container they stay in one row.
+- The swatches take the container width in equal columns: each one stretches across its column (the height stays the tier's). A row wraps only when they no longer fit, and then the swatches split evenly over the rows (16 → 8 + 8, never 14 + 2); no column count to set. In a content-sized container they stand in one row at the tier size.
 - The keyboard focus ring sits outside the swatches; kit hosts (Modal / Drawer body, panels, cards) already keep `--prime-focus-space` padding, so the ring is never clipped. In your own `overflow` container, keep that padding.
 - Label → swatches and swatches → hint use the tier `label-gap` / `hint-gap`; field → field 20.
 
@@ -128,18 +128,19 @@ Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`.
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | The kit palette inline under a field label, one color chosen — `label`, `defaultValue`. |
-| [sizes.tsx](examples/sizes.tsx) | Every size, swatch 20 to 40 px with the tier gap — `size`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size: the swatch height 20 to 40 px with the tier gap, the label stays the form's — `size`. |
 | [states.tsx](examples/states.tsx) | A default palette next to an invalid and a disabled one — `invalid`, `disabled`. |
-| [wrapping.tsx](examples/wrapping.tsx) | In a narrow column the swatches wrap by themselves and the arrows move by the visual rows. |
+| [wrapping.tsx](examples/wrapping.tsx) | In a narrow column the swatches wrap by themselves into even rows and the arrows move by the visual rows. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the color, «no color» included, and names it in the hint — `value`, `onValueChange`, `allowEmpty`. |
-| [in-form.tsx](examples/in-form.tsx) | A calendar event form: the color is submitted by `name` and required on save — `name`, `required`, `error`. |
+| [in-form.tsx](examples/in-form.tsx) | A calendar event form: the color is submitted by `name` and required on save: submitting an empty title or no color shakes the field, picking or typing clears the error — `name`, `required`, `error`. |
 
 ## Mistakes
 - `<ColorSwatches.Root>` → the component is a single export: `<ColorSwatches />`.
 - A visible heading next to the swatches made by hand → pass `label`.
 - Presets without names → every preset needs a `label`; it is the swatch's accessible name.
+- A larger `size` to make the swatches fill a wide field → they already fill it; `size` changes only their height.
 - Dozens of presets → use ColorPicker.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), `Icon` (check mark)
-- **See also:** [ColorPicker](../color-picker/COMPONENT.md) (`ColorPresets`, `ColorPicker.Swatches`), [Radio](../radio/COMPONENT.md)
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **See also:** [ColorField](../color-field/COMPONENT.md), [ColorPicker](../color-picker/COMPONENT.md) (`ColorPresets`, `ColorPicker.Swatches`), [Radio](../radio/COMPONENT.md)

package/src/components/color-swatches/examples/in-form.tsx

@@ -1,23 +1,29 @@
-/** A calendar event form: the color is submitted by `name` and required on save — `name`, `required`, `error`. */
+/** A calendar event form: the color is submitted by `name` and required on save: submitting an empty title or no color shakes the field, picking or typing clears the error — `name`, `required`, `error`. */
 import { Button, ColorSwatches, Input } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 export default function ColorSwatchesInFormExample() {
+  const [titleError, setTitleError] = React.useState<string>();
   const [error, setError] = React.useState<string>();
 
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
-    const color = new FormData(event.currentTarget).get("color");
-    setError(color ? undefined : "Выберите цвет события");
+    const data = new FormData(event.currentTarget);
+    setTitleError(String(data.get("title") ?? "").trim() ? undefined : "Введите название события");
+    setError(data.get("color") ? undefined : "Выберите цвет события");
   };
 
   return (
     <form className={styles.form} noValidate onSubmit={submit}>
-      <Input.Root label="Название события" required>
+      <Input.Root label="Название события" required error={titleError} reserveSupportRow>
         <Input.Wrapper>
-          <Input.Field name="title" defaultValue="Встреча с поставщиком" />
+          <Input.Field
+            name="title"
+            defaultValue="Встреча с поставщиком"
+            onValueChange={() => setTitleError(undefined)}
+          />
         </Input.Wrapper>
       </Input.Root>
       <ColorSwatches

package/src/components/color-swatches/examples/sizes.tsx

@@ -1,4 +1,4 @@
-/** Every size, swatch 20 to 40 px with the tier gap — `size`. */
+/** Every size: the swatch height 20 to 40 px with the tier gap, the label stays the form's — `size`. */
 import { COLOR_PRESETS, ColorSwatches } from "prime-ui-kit";
 
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;

package/src/components/color-swatches/examples/wrapping.tsx

@@ -1,4 +1,4 @@
-/** In a narrow column the swatches wrap by themselves and the arrows move by the visual rows. */
+/** In a narrow column the swatches wrap by themselves into even rows and the arrows move by the visual rows. */
 import { ColorSwatches } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/src/components/command-menu/COMPONENT.md

@@ -9,6 +9,7 @@
 - Global search of an app opened with ⌘K / Ctrl+K: pages, records, settings.
 - Quick actions (create, invite, switch workspace) for keyboard users.
 - Picking one entry from a long list by typing, when a Select would be too small.
+- Searching records on the server (orders, clients, invoices): `search` / `onSearchChange`, `filter={false}`, `loading`, `hasMore` + `onLoadMore`, `loadError` + `onRetry`.
 
 ## When not to use
 - A few actions next to a button → use [Dropdown](../dropdown/COMPONENT.md).
@@ -22,17 +23,18 @@ import { CommandMenu } from "prime-ui-kit";
 
 ## Anatomy
 ```
-CommandMenu.Root                 Modal + top-aligned palette panel, query state
+CommandMenu.Root                 Modal + top-aligned palette panel, query and load state
 ├── CommandMenu.Title            optional <h2>, names the dialog
 ├── CommandMenu.Description      optional <p>
 ├── CommandMenu.Input            search icon + role="combobox" field, faint hairline below
-├── CommandMenu.List             role="listbox", scrolls
-│   ├── CommandMenu.Empty        compact EmptyPage while nothing matches
+├── CommandMenu.List             role="listbox", scrolls; skeleton rows while loading / loading more
+│   ├── CommandMenu.Empty        compact EmptyPage while nothing matches; may hold a CommandMenu.Item
 │   └── CommandMenu.Group        role="group", named by `label`
 │       └── CommandMenu.Item     <button role="option">
 │           ├── CommandMenu.ItemIcon
 │           ├── CommandMenu.ItemText       title + description line
 │           └── CommandMenu.ItemShortcut   Kbd at the end
+├── load error                   after the List: compact EmptyPage, role="alert", retry Button
 └── CommandMenu.Footer           key hints, hairline above
     └── CommandMenu.FooterHint   Kbd per key + label
 ```
@@ -42,16 +44,23 @@ CommandMenu.Root                 Modal + top-aligned palette panel, query state
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### CommandMenu.Root
-`ref` → `HTMLDivElement` (the dialog panel). A Modal with a top-aligned palette panel; owns the query (cleared on close) and the active item (a new opening starts empty, focus in the search field).
+`ref` → `HTMLDivElement` (the dialog panel). A Modal with a top-aligned palette panel; owns the query (cleared on close), the active item (a new opening starts empty, focus in the search field) and the load state of server results.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
 | `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
 | `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: Escape, scrim click, code. |
-| `value` | `string` | — | Controlled query; the list filters by it. Together with `onValueChange`. |
-| `defaultValue` | `string` | `""` | Initial query, uncontrolled. |
-| `onValueChange` | `(value: string) => void` | — | Called with the new query: typing, and `""` when the palette closes. |
+| `search` | `string` | — | Controlled query; the list filters by it. Together with `onSearchChange`. |
+| `defaultSearch` | `string` | `""` | Initial query, uncontrolled. |
+| `onSearchChange` | `(search: string) => void` | — | Called with the new query: typing, and `""` when the palette closes. Load the matching results here for a server search. |
+| `filter` | `boolean` | `true` | The palette filters its items by the query. `false` when the results come from a server: every item shows, the query is still marked in the labels. |
+| `loading` | `boolean` | `false` | Results are loading: skeleton rows in the list while no item matches (items already on screen stay), `aria-busy`. |
+| `loadingMore` | `boolean` | `false` | More results are loading at the end: skeleton rows after the items. |
+| `hasMore` | `boolean` | `false` | More results exist: reaching the end of the list calls `onLoadMore`. |
+| `onLoadMore` | `() => void \| Promise<void>` | — | Called once per round with `hasMore` when the end of the list scrolls into view or the arrows reach the last item; set `loadingMore` while it runs. |
+| `loadError` | `ReactNode` | — | The results failed to load: the message replaces the list in `role="alert"`. |
+| `onRetry` | `() => void \| Promise<void>` | — | A retry button (`labels.retry`) under `loadError`; Enter in the search field runs it too. Return the request's promise to keep the button loading until it settles. |
 | `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim closes the palette; focus returns to the opener. |
 | `closeOnEscape` | `boolean` | `true` | Escape closes the palette. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the rows and the search row: item height, text, icon. |
@@ -64,14 +73,14 @@ CommandMenu.Root                 Modal + top-aligned palette panel, query state
 `ref` → `HTMLHeadingElement` / `HTMLParagraphElement`. `<h2>` / `<p>` above the search row; they name and describe the dialog. + native props except `id`.
 
 ### CommandMenu.Input
-`ref` → `HTMLInputElement`. The search row: a search icon and `<input role="combobox">` controlling the list; shows `CommandMenu.Root` `value`; takes focus on open; no focus ring (the caret is the indicator). + native input props except `value` / `defaultValue`.
+`ref` → `HTMLInputElement`. The search row: a search icon and `<input role="combobox">` controlling the list, showing `CommandMenu.Root` `search`; takes focus on open. + native input props except `value` / `defaultValue`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `placeholder` | `string` | `labels.search` | Placeholder; also the default accessible name comes from `labels.search`. |
 
 ### CommandMenu.List
-`ref` → `HTMLElement`. The scrolling `role="listbox"` (a ScrollContainer) under the search row. + native props.
+`ref` → `HTMLElement`. The scrolling `role="listbox"` under the search row; draws the load states of Root: skeleton rows, more rows loading at the end, the error with a retry. + native props.
 
 ### CommandMenu.Group
 `ref` → `HTMLDivElement`. `<div role="group">` named by its `label`; hidden while none of its items match. + native `<div>` props.
@@ -91,7 +100,7 @@ CommandMenu.Root                 Modal + top-aligned palette panel, query state
 | `disabled` | `boolean` | `false` | Unavailable right now: shown muted with `aria-disabled`, skipped by the arrows, does not run. |
 
 ### CommandMenu.ItemIcon · CommandMenu.ItemShortcut
-`ref` → `HTMLSpanElement` / `HTMLElement` (the `<kbd>`). An `aria-hidden` `<span>` holding the leading glyph at the tier icon size / a `Kbd` one tier below, pushed to the end of the item — a hint, not a handler. + native props.
+`ref` → `HTMLSpanElement` / `HTMLElement` (the `<kbd>`). The `aria-hidden` leading glyph / a `Kbd` key hint at the end of the item — a hint, not a handler. + native props.
 
 ### CommandMenu.ItemText
 `ref` → `HTMLSpanElement`. A `<span>` column: the title with an ellipsis and an optional description line. + native `<span>` props.
@@ -101,7 +110,7 @@ CommandMenu.Root                 Modal + top-aligned palette panel, query state
 | `description` | `ReactNode` | — | Second line (path, details): caption, muted. |
 
 ### CommandMenu.Empty
-`ref` → `HTMLDivElement`. A compact EmptyPage with `role="status"`, shown only while nothing matches: `labels.empty`, `labels.emptyHint`, and `children` as an action under them.
+`ref` → `HTMLDivElement`. A compact EmptyPage (`role="status"`) shown while nothing matches and nothing loads: `labels.empty`, `labels.emptyHint`, and `children` as an action — a button or a `CommandMenu.Item`.
 
 ### CommandMenu.Footer · CommandMenu.FooterHint
 `ref` → `HTMLDivElement` / `HTMLSpanElement`. A bottom row of hints with a hairline above / one hint: every entry of `keys` in its own `Kbd`, then the label (`children`). + native props.
@@ -126,10 +135,13 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `disabled` (Item) | muted row, `aria-disabled`, skipped by the arrows | The command is unavailable right now | `false` |
+| `filter={false}` | every item shows whatever the query; the query is still marked in the labels | The owner searches on the server (`search`, `onSearchChange`) | `true` |
+| `loading` | skeleton rows in the item geometry while no item is on screen; items on screen stay | Results load asynchronously | `false` |
+| `loadingMore` | skeleton rows after the items | The next page is loading (`hasMore` + `onLoadMore`) | `false` |
 | `closeOnOutsideClick={false}` | the scrim does not close it | A required pick | |
 | `closeOnEscape={false}` | Escape does nothing | A required pick that must not be skipped | |
 
-**Combinations** — one palette per app; open it with ⌘K / Ctrl+K and a visible button. Add a Footer with key hints when keyboard use is not obvious.
+**Combinations** — one palette per app; open it with ⌘K / Ctrl+K and a visible button. Add a Footer with key hints when keyboard use is not obvious. A server search: `search` / `onSearchChange` + `filter={false}` + `loading`; paging adds `hasMore`, `loadingMore`, `onLoadMore`; a failed request `loadError` + `onRetry`. A «create from the query» action is a `CommandMenu.Item` inside `CommandMenu.Empty`: it shows only while nothing matches, the arrows and Enter reach it, and it never counts as a match.
 
 ## States
 | State | Driven by | DOM |
@@ -138,14 +150,20 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 | active item | arrows, Home, End, pointer move | `aria-selected="true"`, `data-highlighted="true"`: a fill only, no movement |
 | filtered out | the query | `hidden` on items and on groups without matches |
 | matched text | the query | the first match in the item's text children and in `ItemText` is wrapped in a `<mark>` in `accent-text`, no fill (same as SmartFilter) |
-| nothing found | the query | `CommandMenu.Empty` with `role="status"` |
-| query | `value` / `defaultValue` / `onValueChange` on Root | the search field's value; cleared when the palette closes |
+| nothing found | the query | `CommandMenu.Empty` with `role="status"`; hidden while loading or after a load error. A `CommandMenu.Item` inside it (create from the query) is reached by the arrows and Enter and never counts as a match |
+| query | `search` / `defaultSearch` / `onSearchChange` on Root | the search field's value; cleared when the palette closes |
+| loading | `loading` | `aria-busy` on the list and the field; with no item on screen, `aria-hidden` skeleton rows (`data-skeleton`); `labels.loading` in a polite live region |
+| loading more | `loadingMore` | skeleton rows after the items; the end of the list is watched while `hasMore` (`onLoadMore` once per batch) |
+| load error | `loadError` | the list is `hidden`; a compact EmptyPage with `role="alert"` and a retry Button (`onRetry`) |
+| retrying | `onRetry` returned a pending promise | the retry Button is `loading` (`aria-busy`); a press or Enter does not retry again until it settles; on resolve clear `loadError` and the results swap in; on reject the error stays and the button is ready again |
+| state swap | loading ↔ items ↔ load error | the new content fades in (`swapMotion`), the first render stays still |
 | disabled item | `disabled` on Item | `aria-disabled="true"`, `data-disabled`; never active, not runnable |
 | size | `size` | `data-size` on the tier wrapper |
 
 ## Layout & spacing
 - Width `--prime-modal-width-l`, max height 1.5 × `--prime-panel-max-height`; only the list scrolls.
 - One content column: title, search icon, group labels and item icons start 16 from the edge.
+- `CommandMenu.ItemIcon` holds the glyph at the tier icon size; `CommandMenu.ItemShortcut` is a `Kbd` one tier below, pushed to the end of the item.
 - Search row and footer are separated from the list by hairlines; the search row hairline is faint.
 
 ## Accessibility
@@ -155,13 +173,17 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 |---|---|
 | `ArrowDown` · `ArrowUp` | Move the active item, wrapping; focus stays in the search field. |
 | `Home` · `End` | First / last matching item. |
-| `Enter` | Runs the active item. |
+| `Enter` | Runs the active item; with a load error, retries (`onRetry`). |
+| `Tab` | With a load error, moves focus to the retry button. |
 | `Escape` | Closes the palette (`closeOnEscape`); focus returns to the opener. |
 
 ### ARIA
 - The palette is `role="dialog"` with `aria-modal`, named by `CommandMenu.Title` or `aria-label`.
+- The search field takes focus on open and has no focus ring: the caret is the indicator. Its `onChange`, `onKeyDown`, `onFocus` and `onBlur` reach the input.
 - The field is `role="combobox"` with `aria-controls` on the list and `aria-activedescendant` on the active item; items are `role="option"`, the active one `aria-selected`.
 - `CommandMenu.Group` is `role="group"` named by its `label`; the empty result is `role="status"`.
+- While loading the list and the field are `aria-busy` and `labels.loading` is announced politely; skeleton rows are hidden from screen readers; a load error is `role="alert"`.
+- The arrows reaching the last item ask for the next batch the same way scrolling does.
 - The page behind is inert; after closing, focus returns to the opener.
 
 ### Labels
@@ -172,6 +194,8 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 | `search` | `"Поиск"` | Default placeholder and accessible name of `CommandMenu.Input`. |
 | `empty` | `"Ничего не найдено"` | `CommandMenu.Empty`: nothing matches the query. |
 | `emptyHint` | `"Попробуйте изменить запрос"` | Second line of `CommandMenu.Empty`; `""` hides it. |
+| `loading` | `"Загрузка…"` | Announced while `loading` or `loadingMore`. |
+| `retry` | `"Повторить"` | The retry button under `loadError` (`onRetry`). |
 
 ## Examples
 | Example | Shows |
@@ -180,8 +204,10 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 | [structure.tsx](examples/structure.tsx) | Optional parts: a visible title and description, a description line and a key hint in items, and a footer with key hints — `CommandMenu.Title`, `CommandMenu.ItemText`, `CommandMenu.ItemShortcut`, `CommandMenu.Footer`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier: rows, text, icons and the search row follow it; match the density of the app — `size`. |
 | [states.tsx](examples/states.tsx) | A disabled item stays visible but muted and is skipped by the arrows, and an empty result speaks in the words of the task — `disabled`, `labels`. |
+| [server-search.tsx](examples/server-search.tsx) | Orders searched on the server: the parent loads results for the query and the next page at the end of the list; with nothing found the palette offers to create an order — `search`, `onSearchChange`, `filter`, `loading`, `hasMore`, `loadingMore`, `onLoadMore`, `CommandMenu.Empty`. |
+| [load-error.tsx](examples/load-error.tsx) | The results failed to load: the palette says so instead of the list, and a retry asks again with the button loading until the server answers; the first retry fails too, the second brings the results — `loadError`, `onRetry`. |
 | [dismiss.tsx](examples/dismiss.tsx) | A required pick during an import: a stray click on the scrim does not close the palette, only Escape or a choice — `closeOnOutsideClick`, `closeOnEscape`. |
-| [controlled.tsx](examples/controlled.tsx) | The parent owns the query: it shows the text outside and a command resets it; the palette clears it on close — `value`, `onValueChange`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the query: it shows the text outside and a command resets it; the palette clears it on close — `search`, `onSearchChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the open state: a button opens the palette and a command closes it — `open`, `onOpenChange`. |
 
 ## Mistakes
@@ -190,7 +216,10 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 - `CommandMenu.Group` with a separate heading element → pass the heading as `label`.
 - Items that differ only by an icon → give them distinct `value` texts; the query matches text, not icons.
 - No name for the dialog → add `CommandMenu.Title` (visually hidden if needed) or `aria-label`.
+- Server results squeezed through `keywords` so the kit filter keeps them → set `filter={false}`.
+- A hand-drawn spinner or «Загрузка…» item → set `loading` (skeleton rows) and `loadingMore`.
+- A «Создать …» action placed beside the results with a hand-made visibility check → put it in `CommandMenu.Empty` as a `CommandMenu.Item`.
 
 ## Related
-- **Built from:** [Modal](../modal/COMPONENT.md) (dialog, scrim, focus, Title / Description), [ScrollContainer](../scroll-container/COMPONENT.md) (`List`), [EmptyPage](../empty-page/COMPONENT.md) (`Empty`), [Kbd](../kbd/COMPONENT.md) (`ItemShortcut`, `FooterHint`)
+- **Built from:** [Modal](../modal/COMPONENT.md) (dialog, scrim, focus, Title / Description), [ScrollContainer](../scroll-container/COMPONENT.md) (`List`), [EmptyPage](../empty-page/COMPONENT.md) (`Empty`, load error), [Skeleton](../skeleton/COMPONENT.md) (loading rows), [Button](../button/COMPONENT.md) (retry), [Kbd](../kbd/COMPONENT.md) (`ItemShortcut`, `FooterHint`), `Icon` (search glyph, retry)
 - **See also:** [Dropdown](../dropdown/COMPONENT.md), [Select](../select/COMPONENT.md), [Modal](../modal/COMPONENT.md)

package/src/components/command-menu/examples/controlled.tsx

@@ -1,4 +1,4 @@
-/** The parent owns the query: it shows the text outside and a command resets it; the palette clears it on close — `value`, `onValueChange`. */
+/** The parent owns the query: it shows the text outside and a command resets it; the palette clears it on close — `search`, `onSearchChange`. */
 import { Button, CommandMenu, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -17,8 +17,8 @@ export default function CommandMenuControlledExample() {
       <CommandMenu.Root
         open={open}
         onOpenChange={setOpen}
-        value={query}
-        onValueChange={setQuery}
+        search={query}
+        onSearchChange={setQuery}
         aria-label="Поиск по отчётам"
       >
         <CommandMenu.Input placeholder="Название отчёта" />