@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/components/inputs/search-control.en.md

@@ -0,0 +1,60 @@
+---
+component: SearchControl
+exports: [SearchControl]
+category: inputs
+status: stable
+source: src/components/inputs/SearchControl.tsx
+story: src/components/inputs/SearchControl.stories.tsx
+sourceHash: e172d7682498
+---
+
+# SearchControl
+
+## Summary for AI
+
+`SearchControl` is a controlled search field on top of `TextControl`: a magnifier, an accessible name, clearing and an optional on-screen keyboard. It does not debounce queries and does not intercept Escape.
+
+## When to use
+
+- Search over a list, a library or an API with a single visual contract.
+- You need a clear button that returns focus to the field.
+- On a wide screen (from `md`) you need the on-screen `Keyboard` through the `keyboard` prop.
+
+## When not to use
+
+- For plain text — `TextControl`.
+- For choosing from a list of options — `Combobox`; for filtering a closed list — a searchable `Select`.
+- Set a shared debounce policy in the consumer, not here.
+
+## Minimal example
+
+```tsx
+<SearchControl
+  label="Search collections"
+  value={query}
+  onChange={setQuery}
+  placeholder="Find a collection…"
+/>
+```
+
+## Public API
+
+- `value`, `onChange(string)`, `label` are required. A `placeholder` does not replace `label`.
+- `clearable` is true by default; `clearLabel`, `shellClassName` and native input props are available.
+- `keyboard` requires `layout` and `onLayoutChange`; `defaultOpen` affects only the initial opening; `onSubmit` is called by the on-screen keyboard.
+
+## Height step
+
+`size` is passed through to `TextControl`: `md` is 42 pixels (the default), `sm` is
+36, the same height as `Button size="md"` and of the `Select` pill in the same
+toolbar row.
+
+The step lives on `TextControl`, not here. Search is deliberately built on it, and a
+height of its own for search would mean a second way to compute it inside the
+package itself — exactly the divergence `SearchControl` was introduced to avoid.
+
+## Accessibility and keyboard
+
+- Escape deliberately passes through to the parent overlay; add an `onKeyDown` handler if you need to clear the query.
+- The on-screen keyboard button is hidden below `md`; a mouse click on the keyboard panel returns the caret to the field.
+- Source: `src/components/inputs/SearchControl.tsx`; checks — `tests/search-control.test.tsx`.

package/docs/components/inputs/search-control.md

@@ -0,0 +1,58 @@
+---
+component: SearchControl
+exports: [SearchControl]
+category: inputs
+status: stable
+source: src/components/inputs/SearchControl.tsx
+story: src/components/inputs/SearchControl.stories.tsx
+---
+
+# SearchControl
+
+## Кратко для AI
+
+`SearchControl` — управляемое поле поиска поверх `TextControl`: лупа, доступное имя, очистка и необязательная экранная клавиатура. Он не откладывает запросы (debounce) и не перехватывает Escape.
+
+## Когда использовать
+
+- Поиск по списку, библиотеке или API с единым визуальным контрактом.
+- Нужна кнопка очистки, возвращающая фокус в поле.
+- На широком экране (от `md`) нужна экранная клавиатура `Keyboard` через проп `keyboard`.
+
+## Когда не использовать
+
+- Для обычного текста — `TextControl`.
+- Для выбора из списка вариантов — `Combobox`; для фильтрации закрытого списка — searchable `Select`.
+- Общую debounce-политику задавайте в потребителе, а не здесь.
+
+## Минимальный пример
+
+```tsx
+<SearchControl
+  label="Поиск коллекций"
+  value={query}
+  onChange={setQuery}
+  placeholder="Найти коллекцию…"
+/>
+```
+
+## Public API
+
+- `value`, `onChange(string)`, `label` обязательны. `placeholder` не заменяет `label`.
+- `clearable` по умолчанию true; `clearLabel`, `shellClassName` и native input props доступны.
+- `keyboard` требует `layout` и `onLayoutChange`; `defaultOpen` действует только на первоначальное раскрытие, `onSubmit` вызывается экранной клавиатурой.
+
+## Ступень высоты
+
+`size` пробрасывается в `TextControl`: `md` — 42 пикселя (умолчание), `sm` — 36,
+как высота `Button size="md"` и пилюли `Select` в той же строке панели.
+
+Ступень живёт у `TextControl`, а не здесь. Поиск намеренно стоит на нём, и своя
+высота у поиска означала бы второй способ считать её внутри самого пакета —
+ровно то расхождение, ради которого `SearchControl` и заведён.
+
+## Доступность и клавиатура
+
+- Escape намеренно проходит к родительскому оверлею; добавьте свой `onKeyDown`, чтобы очищать запрос.
+- Кнопка экранной клавиатуры скрыта до `md`; щелчок мышью по панели клавиатуры возвращает каретку в поле.
+- Источник: `src/components/inputs/SearchControl.tsx`; проверки — `tests/search-control.test.tsx`.

package/docs/components/inputs/select.en.md

@@ -0,0 +1,68 @@
+---
+component: Select
+exports: [Select]
+category: inputs
+status: stable
+source: src/components/inputs/Select.tsx
+story: src/components/inputs/Select.stories.tsx
+sourceHash: cf9905bc2278
+---
+
+# Select
+
+## Summary for AI
+
+`Select` picks a value only from the closed list `items`. `searchable` filters that list but does not allow free input. `multiple` changes the shape of value and the callback to an array.
+
+## When to use
+
+- The values are known in advance: a category, a status, a collection, a set of filters.
+- You need search within a long but still closed list.
+- You need one or several selected items with a type-safe value shape.
+
+## When not to use
+
+- If the user may create a new value, use `Combobox`.
+- If you need checkboxes with complex markup that differs from one to the next, use `CheckboxGroup`.
+- If you need exactly one mode, always selected, use `Segmented`.
+
+## Minimal example
+
+```tsx
+<Select items={[{ id: "draft", label: "Draft" }]} value={status} onChange={setStatus} placeholder="Status" clearable />
+
+<Select multiple items={tags} value={tagIds} onChange={setTagIds} searchable countLabel={(n) => `Selected: ${n}`} />
+```
+
+## Public API
+
+- An item must have `id` and `label`; `keywords`, `meta`, `renderMedia` and domain fields are optional.
+- Without `multiple`: `value?: SelectId | null`, `onChange(id | null)`; with `multiple: true`: `value?: SelectId[]`, `onChange(ids)`. Clearing produces `null` or `[]` respectively.
+- `searchable` is false by default; `clearable`, `highlightSelected`, placeholders, `icon`, `triggerClassName`, `contentClassName` configure the presentation.
+- `disabled` disables the whole field: the trigger cannot be focused, the panel does not open (and an open one closes), the clear button disappears, the pill is dimmed. Behavior and look are as with `Button` and `TextControl`.
+- `aria-label` (or `aria-labelledby`, a reference to a label that is already rendered) sets the field's name. The name is **combined** with the trigger content and does not replace it: the field is announced as "Icon, Circle, button". If both are set, `aria-labelledby` wins.
+- `missingLabel` labels a value for which no item was found in `items`: this happens while the list is loading and when the record was deleted. By default the key itself is shown — it is more honest than a placeholder if it is human-readable; for machine identifiers (UUIDs) set the label yourself.
+- For a wide form the label limit can be lifted: `triggerClassName="[--select-label-max:none]"`.
+- **Anything you put in the trigger's text row must fit in 20 px.** The trigger row is a `leading-5` line box, and the control's height depends on it: a filter pill is 36 px (the same as a `Button` of size `md`), and a trigger in a form with `py-2.5` padding is 42 px (the same as `TextControl`, `NumberInput`, `SearchControl` and `DateRangePicker`). A taller child stretches the trigger and throws it out of line with the fields next to it. That is why `renderMedia(item, px)` receives the side of the square as a number, 20 in the trigger and 28 in the list, and you should draw exactly that. This does not apply to the `icon` and `trailing` slots of the input fields: they sit beside the field rather than in its text row.
+- A custom font size in `triggerClassName` keeps the height only if it is a step of the [type scale](../../theming.md#типографическая-шкала): every step sets its own line box. An arbitrary `text-[15px]` displaces the `text-[13px] leading-5` pair as a whole, and the height is again derived from the `1.5` multiplier.
+
+## Accessibility and keyboard
+
+- **The hint and error of `FormField` are announced together with the field.** The
+  description arrives through context, and `aria-describedby` is set on the trigger;
+  the value set by the consumer is not replaced but merged with it. Before version 3.0.0 the
+  components built on react-aria did not pick up the form description — it was on the screen
+  but did not reach the screen reader
+  (ADR-0031).
+- The trigger reports `aria-haspopup="listbox"` and the expanded state; clearing is a separate button.
+- **The field name in a form is set by `aria-label` or `aria-labelledby`, not by
+  the `FormField` label.** A composite control does not accept an `id`, so there is
+  nothing for `htmlFor` to bind to: without an explicit name the screen reader
+  announces only the trigger content — "No icon, button" — and two such fields side
+  by side cannot be told apart by ear. In a filter bar no name is needed: there the
+  placeholder is the name of the filter. The name from `aria-label` goes into a hidden node and is
+  read **together** with the value; a plain `aria-label` on the button would win over
+  the content, and the field would stop reporting what is selected in it (the same
+  technique is in `TreeSelect`).
+- In the list, the arrow keys, Home/End, Enter/Space and Escape work. In searchable mode the arrow keys move focus between the search and the list.
+- Sources: `src/components/inputs/Select.tsx`, `src/components/inputs/Select.stories.tsx`, `tests/select.test.tsx`.

package/docs/components/inputs/select.md

@@ -0,0 +1,65 @@
+---
+component: Select
+exports: [Select]
+category: inputs
+status: stable
+source: src/components/inputs/Select.tsx
+story: src/components/inputs/Select.stories.tsx
+---
+
+# Select
+
+## Кратко для AI
+
+`Select` выбирает значение только из закрытого списка `items`. `searchable` фильтрует этот список, но не разрешает свободный ввод. `multiple` меняет форму value и callback на массив.
+
+## Когда использовать
+
+- Значения заранее известны: категория, статус, коллекция, набор фильтров.
+- Нужен поиск среди длинного, но всё ещё закрытого списка.
+- Нужен один или несколько выбранных элементов с типобезопасной формой значения.
+
+## Когда не использовать
+
+- Если пользователь вправе создать новое значение, используйте `Combobox`.
+- Если нужны флажки со сложной разметкой, разной у каждого, используйте `CheckboxGroup`.
+- Если нужен ровно один режим, всегда выбранный, используйте `Segmented`.
+
+## Минимальный пример
+
+```tsx
+<Select items={[{ id: "draft", label: "Черновик" }]} value={status} onChange={setStatus} placeholder="Статус" clearable />
+
+<Select multiple items={tags} value={tagIds} onChange={setTagIds} searchable countLabel={(n) => `Выбрано: ${n}`} />
+```
+
+## Public API
+
+- Элемент обязан иметь `id` и `label`; опциональны `keywords`, `meta`, `renderMedia` и доменные поля.
+- Без `multiple`: `value?: SelectId | null`, `onChange(id | null)`; с `multiple: true`: `value?: SelectId[]`, `onChange(ids)`. Очистка отдаёт `null` или `[]` соответственно.
+- `searchable` по умолчанию false; `clearable`, `highlightSelected`, плейсхолдеры, `icon`, `triggerClassName`, `contentClassName` настраивают представление.
+- `disabled` выключает поле целиком: триггер не фокусируется, панель не открывается (а открытая закрывается), крестик очистки исчезает, пилюля гаснет. Поведение и вид — как у `Button` и `TextControl`.
+- `aria-label` (или `aria-labelledby` — ссылка на уже показанную подпись) даёт полю имя. Имя **складывается** с содержимым триггера, а не вытесняет его: поле объявляется «Иконка, Круг, кнопка». Заданы оба — побеждает `aria-labelledby`.
+- `missingLabel` подписывает значение, которому не нашлось элемента в `items`: так бывает, пока список грузится, и когда запись удалили. По умолчанию показывается сам ключ — он честнее плейсхолдера, если понятен человеку; для машинных идентификаторов (UUID) задайте подпись сами.
+- Для широкой формы можно снять ограничение подписи: `triggerClassName="[--select-label-max:none]"`.
+- **Всё, что кладётся в строку триггера, обязано умещаться в 20 px.** Строка триггера — строчный бокс `leading-5`, и от него зависит высота контрола: пилюля фильтра — 36 px (как `Button` размера `md`), триггер в форме с отступами `py-2.5` — 42 px (как `TextControl`, `NumberInput`, `SearchControl` и `DateRangePicker`). Более высокий потомок растягивает триггер и разводит его с соседними полями. Поэтому `renderMedia(item, px)` получает сторону квадрата числом — 20 в триггере и 28 в списке — и рисовать надо ровно её. К слотам `icon` и `trailing` полей ввода это не относится: они стоят рядом с полем, а не в его строке.
+- Свой размер шрифта в `triggerClassName` держит высоту, только если это ступень [типографической шкалы](../../theming.md#типографическая-шкала): у каждой ступени задан свой строчный бокс. Произвольный `text-[15px]` вытесняет пару `text-[13px] leading-5` целиком, и высота снова выводится из множителя `1.5`.
+
+## Доступность и клавиатура
+
+- **Пояснение и ошибка `FormField` объявляются вместе с полем.** Описание
+  приходит контекстом, `aria-describedby` ставится на триггер; значение, заданное
+  потребителем, не вытесняется, а дополняется. До версии 3.0.0 компоненты на react-aria
+  не забирали описание формы — на экране оно было, скринридеру не доставалось
+  (ADR-0031).
+- Триггер сообщает `aria-haspopup="listbox"` и `aria-expanded`; очистка — отдельная кнопка.
+- **Имя поля в форме задаётся `aria-label` или `aria-labelledby`, а не подписью
+  `FormField`.** Составной контрол не принимает `id`, и `htmlFor` связывать
+  нечего: без явного имени скринридер объявляет только содержимое триггера
+  («Без иконки, кнопка»), и два таких поля рядом на слух не различаются. В
+  панели фильтров имя не нужно: там плейсхолдер и есть название фильтра.
+  Имя из `aria-label` уходит в скрытый узел и читается **вместе** со значением; обычный
+  `aria-label` на кнопке победил бы содержимое, и поле перестало бы сообщать,
+  что в нём выбрано (тот же приём — в `TreeSelect`).
+- В списке работают стрелки, Home/End, Enter/Space, Escape. В searchable-режиме стрелки переводят фокус между поиском и списком.
+- Источники: `src/components/inputs/Select.tsx`, `src/components/inputs/Select.stories.tsx`, `tests/select.test.tsx`.

package/docs/components/inputs/slider.en.md

@@ -0,0 +1,60 @@
+---
+component: Slider controls
+exports: [Slider, RangeSlider]
+category: inputs
+status: stable
+source: src/components/inputs/Slider.tsx
+story: src/components/inputs/Slider.stories.tsx
+sourceHash: 6b20c8ce6cc4
+---
+
+# Slider and RangeSlider
+
+## Summary for AI
+
+`Slider` sets one number, `RangeSlider` sets the bounds `[min, max]`. These are controlled React Aria controls with keyboard support. `Slider` can be horizontal (the default) or vertical; `RangeSlider` only horizontal.
+
+## When to use
+
+- The value is naturally perceived as a position on a scale: volume, opacity, a numeric filter.
+- For a range you need two ends and, if necessary, a minimum gap `minGap`.
+- Use a vertical `Slider` when the value reads as a level: volume, gain, fill. Several such sliders side by side form a control panel.
+
+## When not to use
+
+- For precise input of a value without a visual scale, use `NumberInput`.
+- For one of several discrete text options, use `Select`/`RadioGroup`.
+- Do not put a vertical `Slider` in a form to save width: in a column of fields a horizontal one fits in with its neighbors, while a vertical one looks like a layout mistake.
+- There is no vertical `RangeSlider`; its `orientation` is rejected at the type level.
+
+## Minimal example
+
+```tsx
+<Slider label="Opacity" value={opacity} onChange={setOpacity} minValue={0} maxValue={100} />
+<RangeSlider label="Price" value={price} onChange={setPrice} minValue={0} maxValue={1000} minGap={50} />
+<Slider label="Level" orientation="vertical" value={level} onChange={setLevel} formatValue={(v) => `${v}%`} />
+```
+
+## Public API
+
+- The props inherit from React Aria Slider: `value`/`defaultValue`, `onChange`, `minValue`, `maxValue`, `step`, `isDisabled`.
+- `label` names the control; `valuePosition` is `side` (the default) or `none`; `formatValue` formats the value for screen readers.
+- `Slider.orientation` is `horizontal` (the default) or `vertical`. `RangeSlider` has no such prop.
+- `RangeSlider.minGap` prevents a range smaller than the specified gap. If the initial values already violate `minGap`, on the next change the component moves the end the user did not touch; the one under the finger stays in place.
+- **With `minGap`, keep `RangeSlider` controlled** (`value` + `onChange`). In an uncontrolled one the clamped pair goes only to `onChange`, while the internal react-aria state stays unclamped: on the screen the ends can end up closer than `minGap` even though the correct value was passed to `onChange`. The kit cannot fix this on its side — the library holds that state.
+
+## Vertical Slider
+
+- The fill grows from the bottom edge: "more" on a vertical scale is higher.
+- The height is set by the root: `h-48` by default; set a custom height through `className` (`className="h-64"`). Without a height a vertical track has nothing to stretch into.
+- The label and the value sit above the track, as on the horizontal one; `valuePosition` and `formatValue` work the same. The slider width follows the width of the header (the label and the value above the track), not the full width of the container.
+- Why `RangeSlider` has no vertical orientation: the fill geometry between two ends along the height is not implemented, and a prop that compiles and does nothing is worse than a missing one. If it is needed, it is a separate task.
+
+## Accessibility and keyboard
+
+- React Aria implements pointer/touch, arrow keys (one step at a time), Shift for a large step and Home/End for the bounds.
+- The mouse wheel and the touchpad over the slider move the value by a step: up increases, down decreases (on a horizontal one a sideways scroll to the right also increases). In `RangeSlider` the end nearest to the cursor moves, taking `minGap` into account. At the edge of the scale the wheel event goes to the page, so that scrolling does not "stick" on the slider; with `isDisabled` the slider ignores the wheel entirely.
+- On a vertical one the thumb announces `aria-orientation="vertical"`; Up Arrow increases the value, Down Arrow decreases it.
+- With `isDisabled` the slider is dimmed as a whole — label, value, track and thumb — like the other kit fields; it cannot be dragged or focused.
+- Do not hide the value unless there is another clear display next to it.
+- See `src/components/inputs/Slider.tsx`, `src/components/inputs/Slider.stories.tsx`, `tests/slider.test.tsx`.

package/docs/components/inputs/slider.md

@@ -0,0 +1,59 @@
+---
+component: Slider controls
+exports: [Slider, RangeSlider]
+category: inputs
+status: stable
+source: src/components/inputs/Slider.tsx
+story: src/components/inputs/Slider.stories.tsx
+---
+
+# Slider и RangeSlider
+
+## Кратко для AI
+
+`Slider` задаёт одно число, `RangeSlider` — границы `[min, max]`. Это управляемые контролы React Aria с поддержкой клавиатуры. `Slider` бывает горизонтальным (по умолчанию) и вертикальным, `RangeSlider` — только горизонтальным.
+
+## Когда использовать
+
+- Значение естественно воспринимается как место на шкале: громкость, прозрачность, числовой фильтр.
+- Для диапазона нужны два конца и, при необходимости, минимальный зазор `minGap`.
+- Вертикальный `Slider` — когда значение читается как уровень: громкость, усиление, заполненность. Несколько таких ползунков рядом складываются в пульт.
+
+## Когда не использовать
+
+- Для точного ввода значения без визуальной шкалы используйте `NumberInput`.
+- Для одного из дискретных текстовых вариантов используйте `Select`/`RadioGroup`.
+- Не ставьте вертикальный `Slider` в форму ради экономии ширины: в столбце полей горизонтальный встаёт в один ряд с соседями, а вертикальный выглядит ошибкой вёрстки.
+- Вертикального `RangeSlider` нет: `orientation` у него отклоняется на уровне типа.
+
+## Минимальный пример
+
+```tsx
+<Slider label="Прозрачность" value={opacity} onChange={setOpacity} minValue={0} maxValue={100} />
+<RangeSlider label="Цена" value={price} onChange={setPrice} minValue={0} maxValue={1000} minGap={50} />
+<Slider label="Уровень" orientation="vertical" value={level} onChange={setLevel} formatValue={(v) => `${v}%`} />
+```
+
+## Public API
+
+- Props наследуют React Aria Slider: `value`/`defaultValue`, `onChange`, `minValue`, `maxValue`, `step`, `isDisabled`.
+- `label` именует контрол; `valuePosition` — `side` (по умолчанию) либо `none`; `formatValue` форматирует значение для скринридера.
+- `Slider.orientation` — `horizontal` (по умолчанию) или `vertical`. У `RangeSlider` этого пропа нет.
+- `RangeSlider.minGap` предотвращает диапазон меньше указанного. Если начальные значения уже нарушают `minGap`, компонент сдвигает конец, которого пользователь не касался, при следующем изменении: тот, что под пальцем, остаётся на месте.
+- **С `minGap` держите `RangeSlider` управляемым** (`value` + `onChange`). У неуправляемого зажатая пара уходит только в `onChange`, а внутреннее состояние react-aria остаётся незажатым: на экране концы могут встать ближе, чем `minGap`, хотя в `onChange` ушло правильное значение. Кит выправить это у себя не может — состоянием там владеет библиотека.
+
+## Вертикальный Slider
+
+- Заливка растёт от нижнего края: «больше» на вертикальной шкале — выше.
+- Высоту задаёт корень: по умолчанию `h-48`, своя — через `className` (`className="h-64"`). Без высоты вертикальной дорожке не во что тянуться.
+- Подпись и значение стоят над дорожкой, как у горизонтального; `valuePosition` и `formatValue` работают так же. Ширина ползунка — по ширине шапки (подписи и значения над дорожкой), а не на всю ширину контейнера.
+- Почему вертикали нет у `RangeSlider`: геометрия заливки между двумя концами по высоте не сделана, а проп, который компилируется и ничего не делает, хуже отсутствующего. Понадобится — это отдельная задача.
+
+## Доступность и клавиатура
+
+- React Aria реализует pointer/touch, стрелки на шаг, Shift для крупного шага и Home/End для границ.
+- Колесо мыши и тачпад над ползунком двигают значение на шаг: вверх увеличивает, вниз уменьшает (на горизонтальном боковая прокрутка вправо тоже увеличивает). У `RangeSlider` двигается конец, ближайший к курсору, с учётом `minGap`. На границе шкалы колесо отдано странице, чтобы прокрутка не «залипала» на ползунке; при `isDisabled` колесо не работает.
+- У вертикального бегунок объявляет `aria-orientation="vertical"`; стрелка вверх увеличивает значение, вниз — уменьшает.
+- С `isDisabled` ползунок приглушается целиком, как прочие поля кита: подпись, значение, дорожка и бегунок; тянуть и фокусировать его нельзя.
+- Не скрывайте значение, если рядом нет другого понятного отображения.
+- См. `src/components/inputs/Slider.tsx`, `src/components/inputs/Slider.stories.tsx`, `tests/slider.test.tsx`.

package/docs/components/inputs/swatch-group.en.md

@@ -0,0 +1,181 @@
+---
+component: SwatchGroup
+exports: [SwatchGroup, SwatchOption]
+category: inputs
+status: stable
+source: src/components/inputs/SwatchGroup.tsx
+story: src/components/inputs/SwatchGroup.stories.tsx
+sourceHash: 3d34585fa1ae
+---
+
+# SwatchGroup
+
+## Summary for AI
+
+Picking one value from a closed set, where an option is shown as a **color
+swatch**, not as text. The fill comes as a hue of the label palette (`LabelHue`),
+the option name as a separate `name` field: the fill is for the eyes, the name
+for the ears.
+
+## When to use
+
+- A project color, a label hue, a calendar color — anywhere the value is a key
+  from a closed set and has to be shown as a color.
+- There are few options and they are compared by eye, laid out in a grid.
+
+## When not to use
+
+- If you need an **arbitrary** color, use `ColorPicker` (a separate entry point
+  `@olddevs/ui/color`). It deliberately produces a color outside the token system;
+  here it is the opposite — a key that the theme resolves to a color.
+- If the options are named in words, not by color, use `RadioGroup`.
+- To choose a mode rather than a value, use `Segmented`.
+- If there are dozens of values and people search them rather than compare, use `Select`.
+
+## Minimal example
+
+```tsx
+import { SwatchGroup, LABEL_HUES } from "@olddevs/ui";
+
+const [color, setColor] = useState<string>("teal");
+
+<SwatchGroup
+  label="Project color"
+  value={color}
+  onChange={setColor}
+  options={[
+    { value: "none", name: "No color" },
+    ...LABEL_HUES.map((hue) => ({ value: hue, hue, name: NAMES[hue] })),
+  ]}
+/>;
+```
+
+## Props
+
+| Prop       | Default | Purpose                                                                         |
+| ---------- | ------- | ------------------------------------------------------------------------------- |
+| `value`    | —       | The selected value. No `null`: the set is closed and non-empty by construction. |
+| `onChange` | —       | The new value. Applied at once — there is nothing in a set to confirm.          |
+| `label`    | —       | The question the set answers. **Required.**                                     |
+| `options`  | —       | The options: `value`, `hue`, `name`, `disabled`.                                |
+| `columns`  | `6`     | How many swatches in a row. Up Arrow and Down Arrow move by columns.            |
+| `tooltips` | —       | Show the option name as a tooltip on hover and focus.                           |
+| `disabled` | —       | Disables the whole set.                                                         |
+
+## The fill is a hue, not a class and not a color string
+
+`hue` is a name from the label palette (`LABEL_HUES`, eight hues, released in 3.12.0).
+The component does not accept a ready-made class from the consumer, and this is not
+strictness for its own sake:
+
+- a class would mean a color outside the tokens — it would not survive a theme
+  change, and one assembled at runtime (`` `bg-label-${hue}` ``) would not get into
+  the CSS at all: Tailwind scans the sources as text;
+- a color string would introduce a second palette next to the one already released.
+
+**If the hue is not set, the swatch is empty: an outline with no fill.** This is how
+the "no color" option is built: the absence of color is as much an answer to the
+set's question as any hue, and it needs no separate support.
+
+## Selection is a ring, not a second color
+
+The selected swatch gets a neutral ring inside (`fg-0`), not an accent one. The
+reason is practical: the accent is configured by the brand, and an accent ring
+around a swatch of the same hue would not read at all — this defect is why
+the component exists: in a consumer's app the selected option was highlighted in blue
+next to a teal swatch, and the two colors clashed.
+
+The ring changes the **shape** of the option, not only its color: telling "selected"
+from "not selected" by saturation alone is not possible.
+
+The focus ring is the accent one and sits outside the swatch, so the two indicators do
+not merge: on a selected option in focus both are visible.
+
+## The hue name as a tooltip (`tooltips`)
+
+By default the option name is audible but not visible: a label next to nine circles
+would turn the grid into a list. A sighted person then had no way to learn the name —
+not every eye tells "amber" from "red" in a 24-pixel circle. `tooltips` shows the same
+word as a tooltip: on hover and on keyboard focus.
+
+```tsx
+<TooltipProvider>
+  <SwatchGroup label="Project color" value={color} onChange={setColor} options={OPTIONS} tooltips />
+</TooltipProvider>
+```
+
+**The provider is required, and that is why the tooltip is not on by default.**
+`TooltipProvider` is placed once at the app root (it also sets the delay and the
+grouping of tooltips); without it Radix throws on the very first option. The set
+was released before the tooltip and is already in use in consumer apps without a provider —
+a default of "on" would have crashed them on a patch update.
+
+**The text is the same `name`; there is no second field for the tooltip.** Two
+sources of the name would diverge at the first translation.
+
+**A prop on the group, not on the option**: the set must behave uniformly, and a
+tooltip on three swatches of nine would look like a bug. On a disabled option
+the tooltip still appears: it does not explain "why not", but "what color is this" is a
+legitimate question about an unavailable option too.
+
+**For a screen reader, the option is still named once.** Radix sets `aria-describedby` on its
+trigger, and on the radio button itself that would duplicate the name, which is already
+the button's accessible name, and the screen reader would read "Amber Amber". So the trigger
+is a wrapper around the option: the description goes to it, and a description is
+not inherited from an ancestor. The same wrapper solves a second problem —
+`RadioButton` does not forward `onFocus` and `onBlur`, and a tooltip on it
+would work with the mouse only, which means it would be missing for the people who need
+it more.
+
+**There is no tooltip on touch.** That is a property of the gesture, not of this
+implementation: on a phone the hue name stays available to a screen reader only.
+
+## Keyboard
+
+| Key            | What it does                                                            |
+| -------------- | ----------------------------------------------------------------------- |
+| `Tab`          | Moves focus **to the selected** option; Tab also leaves the set         |
+| `←` / `→`      | Moves along the row; at the edge of a row, moves to the neighboring row |
+| `↑` / `↓`      | Moves along the column in steps of `columns`; the edges do not wrap     |
+| `Home` / `End` | Moves to the first and last **available** option                        |
+| `Space`        | Selects the option under focus                                          |
+| `Esc`          | Dismisses the tooltip shown by `tooltips`, without taking focus away    |
+
+The horizontal arrow keys are handled by the react-aria radio group itself — linearly,
+in markup order, and in a row that is exactly what is needed. The vertical ones are
+computed by the component: for linear navigation "down" would mean "next", that is,
+the neighboring column rather than the option below the current one. The handler runs
+in the capture phase and stops the event — react-aria listens lower in the tree
+and would have moved the selection first.
+
+**`columns` is a number, not `auto-fill`.** The arrow keys move along columns, so the
+component must know their count; with `auto-fill` it could learn it only by
+measuring, and the keyboard would silently change with the container width.
+
+## Accessibility
+
+- The set has the `radiogroup` role and an option has `radio`; the role itself
+  announces selection, so no live region is needed.
+- The set name is required (`label`); the option name is the required `name` field.
+  Without it nine identical circles cannot be told apart by ear at all, and the
+  fill is not a name: it cannot be read.
+- By default, only the screen reader announces the option name: to the eye, the swatch
+  itself names the option. With `tooltips` the name is also shown in a tooltip.
+- Color is not the only cue for the selection — see above.
+
+## Anti-patterns
+
+- Putting the same thing in `name` as in `hue`: the name is translated, the fill is not.
+- Building this choice on `RadioGroup` with a colored circle inside: an option ends
+  up with two circles in a row, and the grid reads as visual noise.
+- Pulling in `ColorPicker` to choose from nine options: it is about an arbitrary
+  color and, as a separate entry point, weighs as much as the whole rest of the kit.
+- Introducing an "empty value" with a prop: the "no color" option is an ordinary
+  option of the set.
+
+## Related sources and tests
+
+- Source: `src/components/inputs/SwatchGroup.tsx`
+- Hue palette: `LABEL_HUES`, `LABEL_BG_CLASS` — [`docs/palette.md`](../../palette.md)
+- Tests: `tests/swatch-group.test.tsx`; browser — `tests-visual/interactions.spec.ts`
+- Showcase: `src/components/inputs/SwatchGroup.stories.tsx`