@olddevs/ui 0.0.0-stage → 4.0.0

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

@@ -0,0 +1,177 @@
+---
+component: SwatchGroup
+exports: [SwatchGroup, SwatchOption]
+category: inputs
+status: stable
+source: src/components/inputs/SwatchGroup.tsx
+story: src/components/inputs/SwatchGroup.stories.tsx
+---
+
+# SwatchGroup
+
+## Кратко для AI
+
+Выбор одного значения из закрытого набора, где вариант показан **образцом
+цвета**, а не текстом. Закраска приходит оттенком палитры меток (`LabelHue`),
+имя варианта — отдельным полем `name`: закраска нужна глазам, имя — слуху.
+
+## Когда использовать
+
+- Цвет проекта, оттенок метки, цвет календаря — всё, где значение — это ключ из
+  закрытого набора, а показывать его нужно цветом.
+- Вариантов немного, и их сравнивают глазами, выкладывая сеткой.
+
+## Когда не использовать
+
+- Если нужен **произвольный** цвет, используйте `ColorPicker` (отдельный вход
+  `@olddevs/ui/color`). Он намеренно выдаёт цвет мимо системы токенов; здесь
+  наоборот — ключ, который тема превращает в цвет.
+- Если варианты называются словами, а не цветом, используйте `RadioGroup`.
+- Для выбора режима, а не значения используйте `Segmented`.
+- Если значений десятки и их ищут, а не сравнивают, используйте `Select`.
+
+## Минимальный пример
+
+```tsx
+import { SwatchGroup, LABEL_HUES } from "@olddevs/ui";
+
+const [color, setColor] = useState<string>("teal");
+
+<SwatchGroup
+  label="Цвет проекта"
+  value={color}
+  onChange={setColor}
+  options={[
+    { value: "none", name: "Без цвета" },
+    ...LABEL_HUES.map((hue) => ({ value: hue, hue, name: NAMES[hue] })),
+  ]}
+/>;
+```
+
+## Пропы
+
+| Проп       | Умолчание | Назначение                                                               |
+| ---------- | --------- | ------------------------------------------------------------------------ |
+| `value`    | —         | Выбранное значение. Без `null`: набор закрытый и непустой по построению. |
+| `onChange` | —         | Новое значение. Применяется сразу — подтверждать в наборе нечего.        |
+| `label`    | —         | Вопрос, на который отвечает набор. **Обязателен.**                       |
+| `options`  | —         | Варианты: `value`, `hue`, `name`, `disabled`.                            |
+| `columns`  | `6`       | Сколько образцов в ряду. По столбцам ходят вертикальные стрелки.         |
+| `tooltips` | —         | Показывать имя варианта подсказкой при наведении и фокусе.               |
+| `disabled` | —         | Выключает весь набор.                                                    |
+
+## Закраска — оттенок, а не класс и не строка цвета
+
+`hue` — имя из палитры меток (`LABEL_HUES`, восемь оттенков, выпущены в 3.12.0).
+Готовый класс от потребителя компонент не принимает, и это не строгость ради строгости:
+
+- класс означал бы цвет мимо токенов — он не пережил бы смену темы, а собранный
+  в рантайме (`` `bg-label-${hue}` ``) не попал бы в CSS вовсе: Tailwind
+  сканирует исходники текстом;
+- строка цвета завела бы вторую палитру рядом с уже выпущенной.
+
+**Оттенок не задан — образец пустой: контур без заливки.** Так и собирается
+вариант «без цвета»: отсутствие цвета — это такой же ответ на вопрос набора, как
+и любой оттенок, и отдельной поддержки ему не нужно.
+
+## Выбранность — кольцо, а не второй цвет
+
+Выбранный образец получает нейтральное кольцо внутрь (`fg-0`), а не акцентное.
+Причина прикладная: акцент настраивается брендом, и акцентное кольцо вокруг
+образца того же оттенка не читалось бы вовсе. Этот дефект и породил компонент:
+у потребителя выбранный вариант подсвечивался синим рядом с бирюзовым образцом,
+и два цвета спорили.
+
+Кольцо меняет **форму** варианта, а не только его цвет: различать «выбран» и
+«не выбран» по одной насыщенности нельзя.
+
+Кольцо фокуса — акцентное и снаружи образца, поэтому два индикатора не сливаются:
+на выбранном варианте в фокусе видно оба.
+
+## Имя оттенка подсказкой (`tooltips`)
+
+Имя варианта по умолчанию слышно, но не видно: подпись рядом с девятью кругами
+превратила бы сетку в список. Зрячему человеку при этом узнать название было
+нечем — «янтарный» от «красного» в кружке 24 пикселя отличает не каждый глаз.
+`tooltips` показывает то же самое слово подсказкой: при наведении и при фокусе
+с клавиатуры.
+
+```tsx
+<TooltipProvider>
+  <SwatchGroup label="Цвет проекта" value={color} onChange={setColor} options={OPTIONS} tooltips />
+</TooltipProvider>
+```
+
+**Провайдер обязателен, и поэтому подсказка не включена по умолчанию.**
+`TooltipProvider` ставится один на корень приложения (он же задаёт задержку и
+группировку подсказок); без него Radix бросает исключение на первом же варианте. Набор
+выпущен раньше подсказки и уже используется потребителями без провайдера — умолчание
+«включено» сломало бы их при обновлении на патч.
+
+**Текст — тот же `name`, второго поля под подсказку нет.** Два источника имени
+разошлись бы при первом же переводе.
+
+**Проп на группе, а не на варианте**: набор обязан вести себя одинаково, и
+подсказка у трёх образцов из девяти читалась бы как поломка. На выключенном
+варианте подсказка работает: «почему нельзя» она не объясняет, но «что это за
+цвет» — вопрос законный и к недоступному варианту.
+
+**Для скринридера вариант по-прежнему называется один раз.** Radix вешает на свой триггер
+`aria-describedby`, и на самой радиокнопке это удвоило бы имя — оно уже её
+доступное имя, и скринридер прочитал бы «Янтарный Янтарный». Поэтому триггером
+служит обёртка вокруг варианта: описание достаётся ей, а от предка описание не
+наследуется. Той же обёрткой решается и вторая задача — `RadioButton` не
+пробрасывает `onFocus` и `onBlur`, и подсказка на нём работала бы только
+мышью, то есть отсутствовала бы у тех, кому она нужнее.
+
+**На касании подсказки нет.** Так устроен жест, а не эта реализация: на телефоне
+имя оттенка остаётся доступным только скринридеру.
+
+## Клавиатура
+
+| Клавиша        | Что делает                                                          |
+| -------------- | ------------------------------------------------------------------- |
+| `Tab`          | Приводит фокус **на выбранный** вариант; выход из набора — тоже Tab |
+| `←` / `→`      | По ряду; на краю ряда переход к соседнему                           |
+| `↑` / `↓`      | По столбцу, шагом в `columns`; края не зацикливаются                |
+| `Home` / `End` | Первый и последний **доступный** вариант                            |
+| `Пробел`       | Выбирает вариант под фокусом                                        |
+| `Esc`          | Убирает подсказку `tooltips`, не забирая фокус                      |
+
+Горизонтальные стрелки разбирает сама радиогруппа react-aria — линейно, по
+порядку разметки, и в ряду это именно то, что нужно. Вертикальные считает
+компонент: для линейной навигации «вниз» означало бы «следующий», то есть
+соседний столбец, а не вариант под текущим. Обработчик стоит на погружении и
+гасит событие — react-aria слушает ниже по дереву и успела бы увести выбор
+раньше.
+
+**`columns` — число, а не `auto-fill`.** По столбцам ходят стрелки, то есть
+компонент обязан знать их количество; при `auto-fill` он узнавал бы его только
+замером, и клавиатура молча менялась бы от ширины контейнера.
+
+## Доступность
+
+- Роль набора — `radiogroup`, у варианта — `radio`; выбранность объявляет сама
+  роль, живой области не нужно.
+- Имя набора обязательно (`label`), имя варианта — обязательное поле `name`.
+  Без него девять одинаковых кругов не различаются на слух никак, а закраска
+  именем не является: её не прочитать.
+- Имя варианта по умолчанию слышно только скринридеру: глазами вариант называет сам образец. С `tooltips` имя ещё и показывается подсказкой.
+- Цвет не единственный носитель выбранности — см. выше.
+
+## Антипаттерны
+
+- Класть в `name` то же, что в `hue`: имя переводится, закраска нет.
+- Собирать этот выбор на `RadioGroup` с цветным кружком внутри: у варианта
+  получаются два круга подряд, и сетка читается рябью.
+- Тащить `ColorPicker` ради выбора из девяти вариантов: он про произвольный
+  цвет и весит отдельным входом столько же, сколько весь остальной кит.
+- Заводить «пустое значение» пропом: вариант «без цвета» — обычный вариант
+  набора.
+
+## Связанные исходники и проверка
+
+- Исходник: `src/components/inputs/SwatchGroup.tsx`
+- Палитра оттенков: `LABEL_HUES`, `LABEL_BG_CLASS` — [`docs/palette.md`](../../palette.md)
+- Тесты: `tests/swatch-group.test.tsx`; браузер — `tests-visual/interactions.spec.ts`
+- Витрина: `src/components/inputs/SwatchGroup.stories.tsx`

package/docs/components/inputs/tag-input.en.md

@@ -0,0 +1,50 @@
+---
+component: TagInput
+exports: [TagInput]
+category: inputs
+status: stable
+source: src/components/inputs/TagInput.tsx
+story: src/components/inputs/TagInput.stories.tsx
+sourceHash: 7c9521708c37
+---
+
+# TagInput
+
+## Summary for AI
+
+`TagInput` is a controlled set of strings. Enter or a comma turns the draft into a tag; duplicate tags are ignored, and Backspace in an empty field removes the last one.
+
+## When to use
+
+- The user enters several arbitrary tags, including ones made of several words.
+- You need each tag to be removable in an accessible way, and the `max` limit.
+
+## When not to use
+
+- If the set is predefined, use `Select multiple`, `CheckboxGroup` or `ToggleGroup`.
+- If you need only a single free-form text value, use `TextControl` or `Combobox`.
+
+## Minimal example
+
+```tsx
+<TagInput label="Tags" value={tags} onChange={setTags} placeholder="Enter a tag" max={8} />
+```
+
+## Public API
+
+- `value` and `onChange` are required; they are the only source of the set of tags.
+- `label` or `aria-label` names the group; the input automatically gets a separate name "…: add".
+- `max` disables input when the limit is reached. `disabled` blocks the input; `placeholder` disappears when the set is full.
+- A pasted string is split at commas; spaces inside tags are kept; adding on blur happens only when focus leaves the component entirely.
+
+## 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 input,
+  not on the group of tags; 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).
+- Enter on an empty input deliberately does not submit the form.
+- The remove button has a name that includes the specific tag; do not replace it with a custom button.
+- See `src/components/inputs/TagInput.tsx`, `src/components/inputs/TagInput.stories.tsx`, `tests/tag-input.test.tsx`.

package/docs/components/inputs/tag-input.md

@@ -0,0 +1,48 @@
+---
+component: TagInput
+exports: [TagInput]
+category: inputs
+status: stable
+source: src/components/inputs/TagInput.tsx
+story: src/components/inputs/TagInput.stories.tsx
+---
+
+# TagInput
+
+## Кратко для AI
+
+`TagInput` — управляемый набор строк. Enter или запятая превращают черновик в тег; повторные теги игнорируются, Backspace в пустом поле удаляет последний.
+
+## Когда использовать
+
+- Пользователь вводит несколько произвольных тегов, в том числе состоящих из нескольких слов.
+- Нужно удаление каждого тега, доступное с клавиатуры и скринридеру, и ограничение `max`.
+
+## Когда не использовать
+
+- Если набор предопределён, используйте `Select multiple`, `CheckboxGroup` или `ToggleGroup`.
+- Если нужен только один свободный текст, используйте `TextControl` или `Combobox`.
+
+## Минимальный пример
+
+```tsx
+<TagInput label="Теги" value={tags} onChange={setTags} placeholder="Введите тег" max={8} />
+```
+
+## Public API
+
+- `value` и `onChange` обязательны; это единственный источник набора тегов.
+- `label` или `aria-label` задаёт имя группе; input автоматически получает отдельное имя «…: добавить».
+- `max` отключает ввод по достижении лимита. `disabled` блокирует input; `placeholder` пропадает при полном наборе.
+- Вставленная строка делится по запятым, пробелы внутри тегов сохраняются; добавление на blur происходит только при уходе фокуса за пределы компонента.
+
+## Доступность и клавиатура
+
+- **Пояснение и ошибка `FormField` объявляются вместе с полем.** Описание
+  приходит контекстом, `aria-describedby` ставится на поле ввода, а не на группу тегов; значение,
+  заданное потребителем, не вытесняется, а дополняется. До версии 3.0.0 компоненты на react-aria
+  не забирали описание формы — на экране оно было, скринридеру не доставалось
+  (ADR-0031).
+- Enter на пустом вводе намеренно не отправляет форму.
+- В имени кнопки удаления назван конкретный тег; не заменяйте её другой кнопкой.
+- См. `src/components/inputs/TagInput.tsx`, `src/components/inputs/TagInput.stories.tsx`, `tests/tag-input.test.tsx`.

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

@@ -0,0 +1,76 @@
+---
+component: TextControl
+exports: [TextControl]
+category: inputs
+status: stable
+source: src/components/inputs/TextControl.tsx
+story: src/components/inputs/TextControl.stories.tsx
+sourceHash: 458eb37b5e80
+---
+
+# TextControl
+
+## Summary for AI
+
+`TextControl` is a base text field or textarea with a shared form shell. Whoever owns the state uses either the regular React `value`/`onChange` contract or `defaultValue`; the component does not convert the value into a domain string.
+
+## When to use
+
+- Single-line text, a multi-line description, a password or another native input.
+- You need the `icon` and `trailing` slots, a shared border and focus with other fields.
+- For a textarea you need `as="textarea"`; for growing text — `autosize` and, if needed, `maxRows`.
+
+## When not to use
+
+- For search with a built-in magnifier and clearing, use `SearchControl`.
+- For numbers, a step and local formatting, use `NumberInput`.
+- For a closed set, use `Select`; for a free value with a list of options, use `Combobox`.
+
+## Minimal example
+
+```tsx
+<TextControl id="title" value={title} onChange={(e) => setTitle(e.target.value)} placeholder="Title" />
+<TextControl as="textarea" rows={3} autosize maxRows={6} showCount maxLength={500} />
+```
+
+## Public API
+
+- Accepts the native input props. `as` is `input` (the default) or `textarea`; `rows` applies only to a textarea.
+- `shellClassName` styles the shell, `className` the control itself; do not mix them if you change the width/border.
+- `icon` and `trailing` sit inside the shared shell. For a textarea the counter from `showCount` is shown at the bottom; for an input — on the right.
+- `autosize` works only with a textarea: `rows` becomes the minimum, `maxRows` limits the growth.
+- `underlay` renders a layer **under** the value, in the same line: a mask guide, a format sample. It is not a slot next to the field but a layer under it — hence not `icon`/`trailing`. Alignment is held by a shared field class and a shared grid cell, not by pixel fitting. The component itself sets `aria-hidden` on the layer and turns off pointer events and text selection on it: there is nothing to read there, and if it intercepted clicks, clicking the field's own text would no longer focus the field. The layer is for a single-line field only: it has no effect together with `autosize`.
+
+## Height step
+
+| `size` | Height | When                                                                |
+| ------ | ------ | ------------------------------------------------------------------- |
+| `md`   | 42 px  | The default. A form: the field sits among labels and other fields   |
+| `sm`   | 36 px  | A control panel: the field sits in a row with a button and `Select` |
+
+Thirty-six is not an invented number: it is the height of `Button size="md"` and of
+the `Select` pill trigger, that is, the height the kit itself has already chosen twice.
+Before the step, this field was the only one that fell out of this row.
+
+**Only the vertical padding** changes: the border, corner radius, shadow, font and
+line box are the same. The hit area stays above the threshold — 36 is one and a
+half times the minimum WCAG 2.5.8 target.
+
+**The step does not apply to `as="textarea"`.** There the height is governed by
+`rows` and `autosize`, and a third system competing with them for the same number
+would give a field that collapses after every keystroke.
+
+**`shellClassName` and `className` are still there.** Corner radius, width and
+background genuinely differ between products, and the step does not replace them: it
+covers only the height — the one dimension that two products had already worked out separately,
+arriving at different numbers.
+
+The compact field of an `EditableList` row is not this step but 32 px of the row
+height itself: there the number comes from the list row, not from a scale.
+
+## Accessibility and forms
+
+- Pass `id` and tie it to `FormField htmlFor`; a placeholder does not replace a label.
+- The `FormField` hint and error are announced automatically: the field takes their `id` values from context and adds them to `aria-describedby`. A description passed as a prop is not replaced: the ids are added to it — the attribute holds a list (ADR-0026).
+- `disabled` also makes the shell inactive; `readOnly` keeps the value readable.
+- See `src/components/inputs/TextControl.tsx`, `src/components/inputs/TextControl.stories.tsx`.

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

@@ -0,0 +1,74 @@
+---
+component: TextControl
+exports: [TextControl]
+category: inputs
+status: stable
+source: src/components/inputs/TextControl.tsx
+story: src/components/inputs/TextControl.stories.tsx
+---
+
+# TextControl
+
+## Кратко для AI
+
+`TextControl` — базовое текстовое поле или textarea с общей оболочкой формы. Владелец состояния выбирает обычный React-контракт `value`/`onChange` либо `defaultValue`; компонент не преобразует значение в строку домена.
+
+## Когда использовать
+
+- Однострочный текст, многострочное описание, пароль или иной нативный input.
+- Нужны слоты `icon` и `trailing`, единая рамка и фокус с другими полями.
+- Для textarea нужен `as="textarea"`; при растущем тексте — `autosize` и при необходимости `maxRows`.
+
+## Когда не использовать
+
+- Для поиска со встроенной лупой и очисткой используйте `SearchControl`.
+- Для чисел, шага и локального форматирования используйте `NumberInput`.
+- Для закрытого набора используйте `Select`; для свободного значения со списком вариантов — `Combobox`.
+
+## Минимальный пример
+
+```tsx
+<TextControl id="title" value={title} onChange={(e) => setTitle(e.target.value)} placeholder="Название" />
+<TextControl as="textarea" rows={3} autosize maxRows={6} showCount maxLength={500} />
+```
+
+## Public API
+
+- Принимает нативные input-props. `as` — `input` (по умолчанию) либо `textarea`; `rows` относится только к textarea.
+- `shellClassName` стилизует оболочку, `className` — сам контрол; не смешивайте их, если меняете ширину/рамку.
+- `icon` и `trailing` размещаются внутри общей оболочки. У textarea счётчик из `showCount` показывается снизу; у input — справа.
+- `autosize` действует только с textarea: `rows` становится минимумом, `maxRows` ограничивает рост.
+- `underlay` кладёт слой **под** значение, в ту же строку: трафарет маски, образец формата. Не слот рядом с полем, а слой под ним — поэтому и не `icon`/`trailing`. Выравнивание держится общим классом поля и общей ячейкой сетки, а не подгонкой в пикселях. Компонент сам вешает на слой `aria-hidden` и отключает на нём события указателя и выделение текста: читать там нечего, а перехватывай он клики — поле перестало бы фокусироваться щелчком по собственному тексту. Слой только для однострочного поля: вместе с `autosize` он не действует.
+
+## Ступень высоты
+
+| `size` | Высота | Когда                                                      |
+| ------ | ------ | ---------------------------------------------------------- |
+| `md`   | 42 px  | Умолчание. Форма: поле стоит среди подписей и других полей |
+| `sm`   | 36 px  | Панель управления: поле стоит в ряду с кнопкой и `Select`  |
+
+Тридцать шесть — не выдуманное число: это рост `Button size="md"` и
+пилюли-триггера `Select`, то есть то, что кит уже дважды выбрал сам. До ступени
+поле выпадало из этого ряда в одиночку.
+
+Меняется **только вертикальный отступ**: рамка, скругление, тень, шрифт и
+строчный бокс те же. Зона нажатия остаётся выше порога — 36 в полтора раза
+больше минимальной цели WCAG 2.5.8.
+
+**Ступень не действует на `as="textarea"`.** Там высотой распоряжаются `rows` и
+`autosize`, и третья система, спорящая с ними за то же число, дала бы поле,
+которое схлопывается после каждого нажатия.
+
+**`shellClassName` и `className` никуда не делись.** Скругление, ширина и фон у
+продуктов разные, и ступень их не заменяет: она закрывает только высоту —
+ту величину, которую два продукта уже вывели порознь и разными числами.
+
+Компактное поле строки `EditableList` — не эта ступень, а 32 px высоты
+самой строки: там число берётся из ряда списка, а не из шкалы.
+
+## Доступность и форма
+
+- Передавайте `id` и связывайте с `FormField htmlFor`; плейсхолдер не заменяет label.
+- Пояснение и ошибка `FormField` объявляются автоматически: поле забирает их `id` из контекста и подставляет в `aria-describedby`. Описание, переданное пропом, при этом не вытесняется, а дополняется — атрибут хранит список (ADR-0026).
+- `disabled` делает неактивной и оболочку, `readOnly` сохраняет читаемое значение.
+- См. `src/components/inputs/TextControl.tsx`, `src/components/inputs/TextControl.stories.tsx`.

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

@@ -0,0 +1,118 @@
+---
+component: Transfer
+exports: [Transfer, TransferItem]
+category: inputs
+status: stable
+source: src/components/inputs/Transfer.tsx
+story: src/components/inputs/Transfer.stories.tsx
+sourceHash: a447ca595caa
+---
+
+# Transfer
+
+## Summary for AI
+
+`Transfer` is a pair of columns with items moved between them: what can be chosen on the left, what is selected on the right. Controlled: `items` is all the items at once, `value` is the keys of those that ended up on the right. The order of `value` matters and is preserved.
+
+## When to use
+
+- Assigning permissions, roles, members, territories — anywhere "what exists" and "what is granted" must be seen side by side.
+- There are many selected items and the order of assignment matters.
+- The user needs to see what remains unselected, not only what is selected.
+
+## When not to use
+
+- If one value or several are picked from a short list, use `Select` with `multiple`.
+- If values are typed as free input, use `TagInput`.
+- If the choice follows a hierarchy, use `TreeSelect`.
+
+## Minimal example
+
+```tsx
+<Transfer
+  items={allPermissions}
+  value={granted}
+  onChange={setGranted}
+  sourceLabel="All permissions"
+  targetLabel="Granted to the role"
+  searchable
+/>
+```
+
+## Public API
+
+- `items` is **all** the items at once, regardless of column. One list, not two: two would drift apart at the first edit, and an item forgotten in both or missing from both would show no sign of it. `id` must be unique: the react-aria collection collapses duplicates, and one of the items silently disappears from the screen.
+- `value` and `onChange` work with the keys of the right column. The order matters: it is the order of assignment. The kit does not show or count a key that is not in `items`, and does **not drop** it either — it survives the moves untouched. Dropping it would mean silently editing the consumer's value.
+- `sourceLabel` / `targetLabel` are the column labels; without them they come from the message catalog.
+- `searchable` adds a search field above each list. The button moves **only what is visible**, that is, what the user sees; a selection hidden by the filter does not move.
+- `disabled` dims the whole control: both columns and both buttons. It differs from `TransferItem.disabled`, which applies to a single item that is shown but cannot be moved.
+- `aria-label` gives the pair of columns a name, and then it is announced as a group. Without a name the group is not announced: an unnamed group is an extra announcement in the screen reader output that is followed by nothing. The same rule applies to `ButtonGroup`.
+- `TransferItem.disabled` — the item is shown but can be neither moved nor selected.
+
+## Size ceiling
+
+There is no virtualization: every item gets a DOM node. The measured delay of one
+keystroke in the search field is about 16 ms for 200 items, about 56 ms for 1000,
+about 187 ms for 3000. Up to a few hundred items the component is comfortable to use; beyond that
+you start to notice lag when typing.
+
+Memoization does not help here and was deliberately not added: the render body costs
+about a millisecond even at 20,000 items, and everything is spent in
+React and in rebuilding the collection. If you need thousands, that is not a prop but
+a decision about virtualization.
+
+## Selection and value are different things
+
+The highlight inside a column lives in the component and does not survive a move.
+The value — what is in which column — is passed in and out through props. The component
+does not mix them: otherwise "highlighted" and "granted" would become one state, and
+removing the highlight would be impossible without taking the permission away.
+
+## The counter counts the column, not the filter
+
+The number in the header is the count of everything in the column, regardless of the
+search: it answers the question "how many permissions are available in total", and
+the filter is only a view of them. It is also part of the list's accessible name —
+otherwise the number is on the screen but not in the screen reader output.
+
+## Select all
+
+`Ctrl` / `Cmd` + `A` inside a column is a standard react-aria shortcut, and it yields the
+special value "all", not a set of keys. The kit expands it into the keys of its own
+column: otherwise the most common scenario — select all and move — would disable
+both buttons. Disabled items are not moved: select all does not mean bypassing
+the restriction.
+
+## Focus after a move
+
+This is the only decision the component makes itself. After a move the selected items vanish
+from the list — together with the one that had focus. react-aria has no handling for
+this case: the collection changed, and focus goes to `body`, that is, to the start
+of the document.
+
+**The rule: focus follows the items.** It lands on the first moved item, and
+all the moved ones become the selection there — so they can be moved back without
+selecting again.
+
+Focus is set one frame after the commit, and this is not an optimization: `ListBox`
+builds its collection in a separate pass, and right after the commit it does not yet
+contain the moved item — but it does contain the one that was in the column
+before. Setting focus synchronously landed on exactly that item.
+
+The alternative "leave focus on the button" breaks on the very first full move: the
+button dims because there is nothing left to move, and focus is lost anyway.
+
+## A disabled item
+
+It is shown but not moved. Hiding it would misrepresent which permissions exist —
+the user would not see that the permission exists at all; moving it would bypass
+the restriction. The move button stays disabled if only disabled items are
+selected.
+
+## Accessibility and semantics
+
+- Each column is a `listbox` whose name is made of the label and the counter; the items have the `option` role, with multiple selection. The keyboard, typeahead and roles come from the react-aria `ListBox`.
+- The move buttons are named by direction ("Move to selected"), not by an arrow: "right" says nothing about the meaning.
+- The name of the search field is parameterized by the column label: there are two fields, and "Search" on both does not tell them apart at all.
+- An empty column says "Empty", an empty search result — "Nothing found"; both strings are from `common`, the component adds no keys of its own for them.
+- See `src/components/inputs/Transfer.tsx`, `src/components/inputs/Transfer.stories.tsx`, `tests/transfer.test.tsx`.