@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/actions/copy-and-truncate.en.md

@@ -0,0 +1,98 @@
+---
+component: CopyButton и Truncate
+exports: [CopyButton, Truncate]
+category: actions
+status: stable
+source: src/components/actions/CopyButton.tsx
+story: src/components/actions/CopyButton.stories.tsx
+sourceHash: fdbfbfaaa20a
+---
+
+# CopyButton and Truncate
+
+## Summary for AI
+
+Two small things that get rewritten in every project: copying a value to the
+clipboard with clear feedback, and truncating text with a tooltip showing the
+full value.
+
+## When to use
+
+- `CopyButton`: an identifier, a key, a link — something people copy rather than read.
+- `Truncate`: a long name in a table column, in a card, in a list.
+
+## When not to use
+
+- Do not use `CopyButton` to copy a selection from the page: that is the browser's job.
+- Do not use `Truncate` for text that can wrap: truncation loses content, wrapping
+  does not.
+- Do not wrap markup in `Truncate`: it takes a **string**, because it shows the
+  same value in the tooltip.
+
+## Minimal example
+
+```tsx
+import { CopyButton, Truncate } from "@olddevs/ui";
+
+<CopyButton value="ACME-4217" size="sm" variant="ghost" />;
+
+<Truncate>{file.name}</Truncate>;
+```
+
+## CopyButton
+
+| Prop         | Default | Purpose                                     |
+| ------------ | ------- | ------------------------------------------- |
+| `value`      | —       | What to copy.                               |
+| `children`   | —       | Label. Without it the button is icon-only.  |
+| `resetDelay` | `2000`  | How long to hold the "copied" state, in ms. |
+| `onCopy`     | —       | The outcome of the copy: `true` or `false`. |
+
+**The result is announced, not just shown as a different icon.** The checkmark
+is a signal for the eyes; a screen reader user who presses the button would
+otherwise not know whether it worked. A live region, always mounted, sits next
+to it, and the button's name changes along with the state.
+
+**A clipboard failure is an expected outcome.** `navigator.clipboard` is absent
+in an insecure context (a page served over `http`), and writing can be blocked by
+permission settings. When the copy fails, the button says so instead of crashing
+or pretending to succeed, and the value stays available for selecting by hand.
+
+## Truncate
+
+| Prop       | Default | Purpose                          |
+| ---------- | ------- | -------------------------------- |
+| `children` | —       | The text. A string, not markup.  |
+| `lines`    | `1`     | How many lines to show.          |
+| `side`     | `top`   | Which side the tooltip opens on. |
+
+**The tooltip appears only on text that is actually truncated.** A tooltip on
+text that is not truncated is noise: it repeats what is already visible and teaches
+people to ignore it.
+
+Truncation is **measured** (`scrollWidth > clientWidth`, and with `lines` above one also `scrollHeight > clientHeight`), not guessed from the
+string length: how many characters fit depends on the container width and the
+font. The measurement repeats when the size changes — a table column dragged
+with the mouse changes truncation without changing the text.
+
+**The full value is reachable from the keyboard:** truncated text gets
+`tabIndex={0}`, and the tooltip opens on focus the same way it does on hover.
+Without this the value would be available only to mouse users.
+
+A screen reader reads the whole text without our help: truncation is visual, and
+the full string is in the DOM.
+
+`Truncate` requires a `TooltipProvider` at the app root — like any `Tooltip`.
+
+## Anti-patterns
+
+- Changing only the button's icon without announcing the result.
+- Assuming that copying always succeeds.
+- Attaching a tooltip to all text, whether it is truncated or not.
+
+## Related sources and tests
+
+- Sources: `src/components/actions/CopyButton.tsx`, `src/components/actions/Truncate.tsx`
+- Tests: `tests/copy-button.test.tsx`, `tests/truncate.test.tsx`
+- Showcase: `src/components/actions/CopyButton.stories.tsx`,
+  `src/components/actions/Truncate.stories.tsx`

package/docs/components/actions/copy-and-truncate.md

@@ -0,0 +1,96 @@
+---
+component: CopyButton и Truncate
+exports: [CopyButton, Truncate]
+category: actions
+status: stable
+source: src/components/actions/CopyButton.tsx
+story: src/components/actions/CopyButton.stories.tsx
+---
+
+# CopyButton и Truncate
+
+## Кратко для AI
+
+Две мелочи, которые пишут заново в каждом проекте: копирование значения в буфер
+с внятным ответом и обрезка текста с подсказкой полного значения.
+
+## Когда использовать
+
+- `CopyButton`: идентификатор, ключ, ссылка — то, что копируют, а не читают.
+- `Truncate`: длинное имя в колонке таблицы, в карточке, в списке.
+
+## Когда не использовать
+
+- Не используйте `CopyButton` для копирования выделения со страницы: это работа браузера.
+- Не используйте `Truncate` для текста, который можно перенести: обрезка теряет
+  содержание, а перенос — нет.
+- Не оборачивайте в `Truncate` вёрстку: он принимает **строку**, потому что
+  показывает то же значение в подсказке.
+
+## Минимальный пример
+
+```tsx
+import { CopyButton, Truncate } from "@olddevs/ui";
+
+<CopyButton value="ACME-4217" size="sm" variant="ghost" />;
+
+<Truncate>{file.name}</Truncate>;
+```
+
+## CopyButton
+
+| Проп         | Умолчание | Назначение                                   |
+| ------------ | --------- | -------------------------------------------- |
+| `value`      | —         | Что скопировать.                             |
+| `children`   | —         | Подпись. Без неё кнопка иконочная.           |
+| `resetDelay` | `2000`    | Сколько держать состояние «скопировано», мс. |
+| `onCopy`     | —         | Чем кончилось: `true` или `false`.           |
+
+**Результат объявляется, а не только меняет иконку.** Галочка — сигнал для глаз;
+пользователь скринридера, нажав кнопку, иначе не узнает, сработала она или нет.
+Рядом стоит живая область, смонтированная всегда, и имя кнопки меняется вместе с
+состоянием.
+
+**Отказ буфера — законный исход.** `navigator.clipboard` отсутствует в
+небезопасном контексте (страница по `http`), а запись может быть заблокирована
+настройками разрешений. При отказе кнопка сообщает, что копирование не удалось, а
+значение остаётся доступным для выделения руками.
+
+## Truncate
+
+| Проп       | Умолчание | Назначение                   |
+| ---------- | --------- | ---------------------------- |
+| `children` | —         | Текст. Строка, а не вёрстка. |
+| `lines`    | `1`       | Сколько строк показывать.    |
+| `side`     | `top`     | С какой стороны подсказка.   |
+
+**Подсказка появляется только у обрезанного текста.** Подсказка на
+необрезанном — шум: она повторяет то, что и так видно, и приучает её
+игнорировать.
+
+Обрезанность **измеряется** (`scrollWidth > clientWidth`, при `lines` больше единицы ещё и `scrollHeight > clientHeight`), а не угадывается по
+длине строки: сколько символов влезло, зависит от ширины контейнера и шрифта.
+Замер повторяется при изменении размеров — колонка таблицы, потянутая мышью,
+меняет обрезанность, не меняя текста.
+
+**Полное значение доступно с клавиатуры:** обрезанный текст получает
+`tabIndex={0}`, и подсказка открывается по фокусу так же, как по наведению. Без
+этого значение было бы доступно только мышью.
+
+Скринридер читает текст целиком и без нашей помощи: обрезка визуальная, в DOM
+лежит вся строка.
+
+`Truncate` требует `TooltipProvider` у корня приложения — как и любой `Tooltip`.
+
+## Антипаттерны
+
+- Менять у кнопки только иконку, не объявляя результат.
+- Считать, что копирование всегда удаётся.
+- Вешать подсказку на весь текст подряд, обрезан он или нет.
+
+## Связанные исходники и проверка
+
+- Исходники: `src/components/actions/CopyButton.tsx`, `src/components/actions/Truncate.tsx`
+- Тесты: `tests/copy-button.test.tsx`, `tests/truncate.test.tsx`
+- Витрина: `src/components/actions/CopyButton.stories.tsx`,
+  `src/components/actions/Truncate.stories.tsx`

package/docs/components/actions/feedback.en.md

@@ -0,0 +1,69 @@
+---
+component: Feedback primitives
+exports: [Alert, Banner, Progress, Spinner, Toaster, toast, StatusBadge]
+category: actions
+status: stable
+source: src/components/actions/Alert.tsx
+story: src/components/actions/Alert.stories.tsx
+sourceHash: e80ab4275961
+---
+
+# Alert, Banner, Progress, Spinner, Toaster, toast and StatusBadge
+
+## Summary for AI
+
+Choose by the kind of information:
+
+- `Alert` is for a lasting state of a _place_;
+- `Banner` is for a state of the _app_;
+- `toast` is for a brief event that has finished;
+- `Progress` is for a known fraction of the work;
+- `Spinner` is for an unknown wait;
+- `StatusBadge` is for an object's status next to its name.
+
+## When to use
+
+- `Alert`: an important state on a page that must not disappear by itself.
+- `Banner`: service degradation, server maintenance, an expired subscription — anything that concerns the whole app and survives navigation.
+- `toast`: "saved", "failed to send"; a single `Toaster` goes at the app root.
+- `Progress`: the percentage/fraction is known; `value={null}` means indeterminate progress.
+- `Spinner`: neither the duration nor the future shape of the content is known.
+- `StatusBadge`: a compact domain status, such as a publication or a channel.
+
+## When not to use
+
+- Do not use a `toast` for a lasting error — that is an `Alert`.
+- Do not use `Banner` for a message about one block of the page — that is an `Alert`. The line is drawn by place and lifetime: `toast` reports an event, `Alert` describes the state of a place, and `Banner` describes the state of the app.
+- Do not show `Progress` at zero when the amount is unknown: pass `null`.
+- Do not replace a `Skeleton` with a `Spinner` when the shape of the result is known.
+- Do not use `StatusBadge` as a clickable filter — that is a `Chip`.
+
+## Minimal example
+
+```tsx
+<Alert tone="danger" title="Publishing is unavailable">Connect a channel.</Alert>
+<Progress label="Uploading files" value={64} showValue />
+<StatusBadge tone="success">Published</StatusBadge>
+
+// Next to the app root:
+<Toaster />
+// In a handler:
+toast.success("Saved");
+```
+
+## Public API
+
+- `Alert`: `tone`, `variant` (`soft`/`outline`), `title`, `icon`, `action`, `onDismiss`, `closeLabel`; `danger` gets `role="alert"` and the other tones get `role="status"`.
+- `Banner`: `tone`, `title`, `icon`, `action`, `onDismiss`, `closeLabel`. There is no `variant` — a banner is always a full-width strip with no rounded corners. The role follows the tone, as in `Alert`. A stack is just adjacent banners: the component has no queue.
+- `Progress`: required `label`, `value: number | null`, `showValue`; `null` does not set `aria-valuenow`.
+- `Spinner`: `size`, `tone`, `label` (from the message catalog: "Загрузка" with `@olddevs/ui/locales/ru`, "Loading" without a provider) and `role="status"`.
+- `Toaster`: `position`, `duration` (4000 ms by default), `theme`, `offsetVar`. `offsetVar` is the name of the variable holding the bottom bar height, `--bottombar-h` by default. At the bottom edge toasts sit above the `MobileTabBar` in the `bottomBar` slot of `AppShell` rather than under it; with no bar the offset is unchanged. `toast` has only `success`, `error`, `warning`, `info`, `promise`, `dismiss`.
+- **`toast` has four tones and nothing beyond them.** `toast.custom` and toasts with an arbitrary layout, which `sonner` has, are left out of the kit on purpose: a toast that can do everything stops being part of the system, and half a year later the app has five different toasts. The tone, look and layout belong to the kit rather than to the call site; the caller sets only the content: the message, `description` (the second line), `duration` and a single `action` with a label and a handler. If you need more, it is an `Alert` or a dialog. The kit does not parse server errors: the caller prepares the text for `description`, for example `toast.error("Couldn't save", { description: extractErrorMessage(error) })`.
+- `StatusBadge`: a non-interactive `span` with `tone`, `size` and an optional status dot; use a clear text label.
+
+## Accessibility and semantics
+
+- The `danger` tone on `Alert` and `Banner` interrupts the screen reader's speech; do not set it for ordinary success.
+- `Banner` is not sticky, and the header below it stays at `top: 0`: the `--topbar-h` contract (ADR-0016) is left untouched. The analysis is in ADR-0027.
+- `Progress` and `Spinner` must have a name, or a meaningful default.
+- Sources: `src/components/actions/Alert.tsx`, `src/components/actions/Progress.tsx`, `src/components/actions/Spinner.tsx`, `src/components/actions/Toaster.tsx`, `src/components/actions/StatusBadge.tsx`; the stories of the same components.

package/docs/components/actions/feedback.md

@@ -0,0 +1,68 @@
+---
+component: Feedback primitives
+exports: [Alert, Banner, Progress, Spinner, Toaster, toast, StatusBadge]
+category: actions
+status: stable
+source: src/components/actions/Alert.tsx
+story: src/components/actions/Alert.stories.tsx
+---
+
+# Alert, Banner, Progress, Spinner, Toaster, toast и StatusBadge
+
+## Кратко для AI
+
+Выбирайте по типу информации:
+
+- `Alert` — постоянное состояние **места**;
+- `Banner` — состояние **приложения**;
+- `toast` — краткое завершившееся событие;
+- `Progress` — известная доля работы;
+- `Spinner` — неизвестное ожидание;
+- `StatusBadge` — статус объекта рядом с его именем.
+
+## Когда использовать
+
+- `Alert`: важное состояние на странице, которое не должно исчезнуть само.
+- `Banner`: деградация сервиса, работы на сервере, истёкшая подписка — то, что касается всего приложения и переживает навигацию.
+- `toast`: «сохранено», «не удалось отправить»; один `Toaster` ставится у корня приложения.
+- `Progress`: известен процент/доля; `value={null}` означает неопределённый прогресс.
+- `Spinner`: неизвестны и длительность, и будущая форма контента.
+- `StatusBadge`: компактный доменный статус, например публикация или канал.
+
+## Когда не использовать
+
+- Не используйте `toast` для постоянной ошибки — это `Alert`.
+- Не используйте `Banner` для сообщения об одном блоке страницы — это `Alert`. Граница проходит по месту и времени жизни: `toast` сообщает о событии, `Alert` — о состоянии места, `Banner` — о состоянии приложения.
+- Не показывайте `Progress` с нулём, когда величина неизвестна: передайте `null`.
+- Не заменяйте `Skeleton` компонентом `Spinner`, когда форма результата известна.
+- Не используйте `StatusBadge` как кликабельный фильтр — это `Chip`.
+
+## Минимальный пример
+
+```tsx
+<Alert tone="danger" title="Публикация недоступна">Подключите канал.</Alert>
+<Progress label="Загрузка файлов" value={64} showValue />
+<StatusBadge tone="success">Опубликовано</StatusBadge>
+
+// Рядом с app root:
+<Toaster />
+// В обработчике:
+toast.success("Сохранено");
+```
+
+## Public API
+
+- `Alert`: `tone`, `variant` (`soft`/`outline`), `title`, `icon`, `action`, `onDismiss`, `closeLabel`; `danger` получает `role="alert"`, остальные тона — `role="status"`.
+- `Banner`: `tone`, `title`, `icon`, `action`, `onDismiss`, `closeLabel`. Вида (`variant`) нет — баннер всегда полоса во всю ширину без скруглений. Роль по тону та же, что у `Alert`. Стопка — это просто соседние баннеры: очереди у компонента нет.
+- `Progress`: обязательный `label`, `value: number | null`, `showValue`; `null` не выставляет `aria-valuenow`.
+- `Spinner`: `size`, `tone`, `label` (из каталога сообщений: «Загрузка» с `@olddevs/ui/locales/ru`, «Loading» без провайдера) и `role="status"`.
+- `Toaster`: `position`, `duration` (по умолчанию 4000 мс), `theme`, `offsetVar`. `offsetVar` — имя переменной с высотой нижней панели, по умолчанию `--bottombar-h`. У нижнего края тосты встают над `MobileTabBar` в слоте `bottomBar` у `AppShell`, а не под ним; если панели нет, отступ прежний. У `toast` только `success`, `error`, `warning`, `info`, `promise`, `dismiss`.
+- **У `toast` четыре тона, и сверх них ничего нет.** `toast.custom` и тост с произвольной раскладкой, которые есть у `sonner`, в кит не входят намеренно: тост, умеющий всё, перестаёт быть частью системы, и через полгода в приложении оказывается пять разных тостов. Тон, вид и раскладка принадлежат киту, а не месту вызова; вызывающий задаёт только содержимое — сообщение, `description` (вторая строка), `duration` и одно `action` с подписью и обработчиком. Нужно больше — это `Alert` или диалог. Разбор ошибки сервера кит не делает: текст для `description` готовит вызывающий, например `toast.error("Не удалось сохранить", { description: extractErrorMessage(error) })`.
+- `StatusBadge`: неинтерактивный `span` с `tone`, `size`, необязательной точкой статуса; используйте понятную текстовую подпись.
+
+## Доступность и семантика
+
+- Тон `danger` у `Alert` и `Banner` прерывает речь скринридера; не ставьте его для обычного успеха.
+- `Banner` не липкий, и шапка под ним остаётся на `top: 0`: контракт `--topbar-h` (ADR-0016) не трогается. Разбор — ADR-0027.
+- У `Progress` и `Spinner` имя обязательно или имеет осмысленное умолчание.
+- Источники: `src/components/actions/Alert.tsx`, `src/components/actions/Progress.tsx`, `src/components/actions/Spinner.tsx`, `src/components/actions/Toaster.tsx`, `src/components/actions/StatusBadge.tsx`; истории этих же компонентов.

package/docs/components/actions/split-button.en.md

@@ -0,0 +1,76 @@
+---
+component: SplitButton
+exports: [SplitButton]
+category: actions
+status: stable
+source: src/components/actions/SplitButton.tsx
+story: src/components/actions/SplitButton.stories.tsx
+sourceHash: 982b0da00a2f
+---
+
+# SplitButton
+
+## Summary for AI
+
+`SplitButton` is a primary action with a menu trigger for its variants next to it, as **two separate buttons**. The accessible name of the menu trigger is built from `label`, so `label` is a string, not a node. Menu items go in `children`.
+
+## When to use
+
+- The action has related variants: "Export" and next to it "to XLSX", "to JSON", "selected only".
+- One of the actions is clearly the primary one, and making people open a menu for it is an extra step.
+
+## When not to use
+
+- If all the variants are equal, use a `MenuButton` with a menu and no highlighted action.
+- If there are two variants and both are visible, use a `ButtonGroup` of two buttons.
+- If the variants are display modes, not actions, use `Segmented` or `ToggleGroup`.
+
+## Minimal example
+
+```tsx
+<SplitButton label="Export" onClick={exportAll} icon={<DownloadIcon aria-hidden />}>
+  <MenuItem onAction={exportXlsx}>Export to XLSX</MenuItem>
+  <MenuItem onAction={exportJson}>Export to JSON</MenuItem>
+  <MenuSeparator />
+  <MenuItem onAction={exportSelected}>Selected rows only</MenuItem>
+</SplitButton>
+```
+
+## Public API
+
+- `label` is a **string**: the label of the primary action and the source of the name of the menu trigger.
+- `icon` is the icon on the left of the primary action. If a button can enter `loading`, give it an icon from the start: otherwise the loading indicator adds a slot, and the label shifts.
+- `onClick` is called only by the primary action; the menu trigger does not call it.
+- `variant`, `tone`, `size` are the same axes as on `Button` and mean the same thing.
+- `disabled` and `loading` disable **both** buttons and close a menu that is already open — and **do not bring it back** when `disabled` or `loading` is lifted: otherwise the menu would open by itself once a submission ended.
+- `placement` is the side the panel opens to, `bottom end` by default. The side values of `Menu` are narrowed here: a panel that slides sideways lands on top of the primary action.
+- `children` is the menu content: `MenuItem`, `MenuSection`, `MenuSeparator`.
+- `className` is applied to the **group**; on `Button`, the prop of the same name goes on the button. There are two elements here, and "a class on the button" has no unambiguous target.
+- The remaining props are **not passed through** for the same reason: `id`, `type` or `data-*` have no unambiguous target. A button that has to submit a form needs a `Button` and a `MenuTrigger` side by side, assembled by hand.
+
+## Why two buttons, not one with the menu in its right part
+
+If the right part of a button opens a menu, the result is one element with two
+different outcomes and one accessible name. The second outcome cannot be reached
+from the keyboard at all, and a screen reader announces one action instead of
+two. These are two separate controls.
+
+## Why `label` is a string
+
+The name of the menu trigger is built from the label. A node would give a name
+that does not exist — or would require a second prop with the same label as a
+string. One label would live in two places and drift apart at the first edit.
+
+## Keyboard
+
+- **Two tab stops, not one.** Tab goes to the primary action, the next Tab to the menu trigger. The whole rationale of the component rests on this: a single button whose right part opens a menu would leave the second outcome unreachable from the keyboard.
+- The menu opens from the menu trigger with Enter, Space and Down Arrow — `MenuTrigger` does this.
+- Escape closes the menu and **returns focus to the menu trigger** instead of sending it to `<body>`.
+- Disabling the component while the menu is open closes the panel: otherwise it would look disabled while the items kept working.
+
+## Accessibility and semantics
+
+- The menu trigger's name comes from the message catalog: `splitButton.more({ action })` → "Другие действия: Экспорт" with `@olddevs/ui/locales/ru`, "More actions: Export" without a provider. Without the action's label, several menu triggers on a page are indistinguishable when read aloud by a screen reader.
+- The menu trigger carries `aria-haspopup` and `aria-expanded` — `MenuTrigger` sets them.
+- The group does not get `role="group"`: an unnamed group is an extra screen reader announcement, and a name would duplicate the button's label.
+- See `src/components/actions/SplitButton.tsx`, `src/components/actions/SplitButton.stories.tsx`, `tests/split-button.test.tsx`, [Menu](../overlays/menu.md).

package/docs/components/actions/split-button.md

@@ -0,0 +1,75 @@
+---
+component: SplitButton
+exports: [SplitButton]
+category: actions
+status: stable
+source: src/components/actions/SplitButton.tsx
+story: src/components/actions/SplitButton.stories.tsx
+---
+
+# SplitButton
+
+## Кратко для AI
+
+`SplitButton` — главное действие и раскрыватель его вариантов рядом, **двумя отдельными кнопками**. Доступное имя раскрывателя строится из `label`, поэтому `label` — строка, а не узел. Пункты меню передаются в `children`.
+
+## Когда использовать
+
+- У действия есть родня: «Экспорт» и рядом «в XLSX», «в JSON», «только выбранные».
+- Одно из действий заведомо главное, и заставлять открывать меню ради него — лишний шаг.
+
+## Когда не использовать
+
+- Если все варианты равнозначны, используйте `MenuButton` с меню, без выделенного действия.
+- Если вариантов два и оба видны, используйте `ButtonGroup` из двух кнопок.
+- Если варианты — режимы отображения, а не действия, используйте `Segmented` или `ToggleGroup`.
+
+## Минимальный пример
+
+```tsx
+<SplitButton label="Экспорт" onClick={exportAll} icon={<DownloadIcon aria-hidden />}>
+  <MenuItem onAction={exportXlsx}>Экспорт в XLSX</MenuItem>
+  <MenuItem onAction={exportJson}>Экспорт в JSON</MenuItem>
+  <MenuSeparator />
+  <MenuItem onAction={exportSelected}>Только выбранные строки</MenuItem>
+</SplitButton>
+```
+
+## Public API
+
+- `label` — **строка**, подпись главного действия и основа имени раскрывателя.
+- `icon` — иконка слева у главного действия. Кнопке, у которой бывает `loading`, иконку стоит дать сразу: иначе индикатор отправки добавляет слот, и подпись сдвигается.
+- `onClick` срабатывает только от главного действия; раскрыватель его не вызывает.
+- `variant`, `tone`, `size` — те же оси, что у `Button`, и значат то же самое.
+- `disabled` и `loading` отключают **обе** кнопки и закрывают уже открытое меню — и **не возвращают** его, когда `disabled` или `loading` снимут: иначе меню раскрывалось бы само после окончания отправки.
+- `placement` — сторона раскрытия панели, по умолчанию `bottom end`. Боковые значения `Menu` здесь сужены: панель, уезжающая вбок, встаёт поверх главного действия.
+- `children` — содержимое меню: `MenuItem`, `MenuSection`, `MenuSeparator`.
+- `className` ложится на **группу**; у одноимённого пропа `Button` он идёт на кнопку. Элементов здесь два, и у «класса на кнопку» нет однозначного адресата.
+- Остальные пропы наружу **не пробрасываются** по той же причине: у `id`, `type` или `data-*` нет однозначного адресата. Кнопке, которая обязана отправлять форму, нужны `Button` и `MenuTrigger` рядом, собранные вручную.
+
+## Почему две кнопки, а не одна с меню в правой части
+
+Если правая часть кнопки открывает меню, получается элемент с двумя разными
+исходами и одним доступным именем. С клавиатуры до второго исхода не добраться
+вовсе, а скринридер объявит одно действие вместо двух. Это два разных элемента
+управления.
+
+## Почему `label` — строка
+
+Из подписи строится имя раскрывателя. Узел дал бы имя, которого нет, — или
+потребовал бы второго пропа с той же подписью строкой. Одна подпись жила бы в
+двух местах и разошлась бы при первой правке.
+
+## Клавиатура
+
+- **Два табстопа, а не один.** Tab ведёт на главное действие, следующий Tab — на раскрыватель. На этом держится всё обоснование компонента: одна кнопка, правая часть которой открывает меню, оставила бы второй исход недостижимым с клавиатуры.
+- Меню открывается с раскрывателя по Enter, Space и стрелке вниз — это делает `MenuTrigger`.
+- Escape закрывает меню и **возвращает фокус раскрывателю**, а не уводит его на `<body>`.
+- Выключение компонента при открытом меню закрывает панель: иначе он выглядел бы выключенным, а пункты продолжали бы срабатывать.
+
+## Доступность и семантика
+
+- Имя раскрывателя приходит из каталога сообщений: `splitButton.more({ action })` → «Другие действия: Экспорт» с `@olddevs/ui/locales/ru`, «More actions: Export» без провайдера. Без подписи действия несколько раскрывателей на странице неразличимы на слух в скринридере.
+- Раскрыватель несёт `aria-haspopup` и `aria-expanded` — их проставляет `MenuTrigger`.
+- Группа не получает `role="group"`: безымянная группа — лишнее объявление скринридера, а имя дублировало бы подпись кнопки.
+- См. `src/components/actions/SplitButton.tsx`, `src/components/actions/SplitButton.stories.tsx`, `tests/split-button.test.tsx`, [Menu](../overlays/menu.md).

package/docs/components/actions/toggles.en.md

@@ -0,0 +1,139 @@
+---
+component: Toggle and selection controls
+exports: [Toggle, Segmented, ToggleGroup, ButtonGroup]
+category: actions
+status: stable
+source: src/components/actions/Toggle.tsx
+story: src/components/actions/Toggle.stories.tsx
+sourceHash: 84bb6aacceee
+---
+
+# Toggle, Segmented, ToggleGroup and ButtonGroup
+
+## Summary for AI
+
+Choose the component by what the state means:
+
+- `Toggle` is for one boolean property;
+- `Segmented` is for exactly one mode;
+- `ToggleGroup` is for zero or more independent choices;
+- `ButtonGroup` is only a visual group of ordinary actions.
+
+## When to use
+
+- `Toggle`: turn a setting on/off; `checked`, `onCheckedChange` and a name — `label` or visible text in `children` — are required.
+- `Segmented`: there is always exactly one mode, for example "list / grid".
+- `ToggleGroup`: filters or settings where an empty set is allowed; `value` is an array of keys.
+- `ButtonGroup`: join adjacent `Button` components without changing their semantics.
+
+## When not to use
+
+- Do not use `Segmented` for multiple selection or when users must be able to clear the last choice — use `ToggleGroup`.
+- Do not use `ToggleGroup` as a radio group with a mandatory answer — use `RadioGroup`.
+- Do not use `ButtonGroup` to represent a selection: it does not own selection state.
+
+## Minimal example
+
+```tsx
+<Toggle checked={digest} onCheckedChange={setDigest} description="A summary of activity every Monday">Weekly digest</Toggle>
+
+<Segmented value={view} onChange={setView} options={[{ value: "list", label: "List" }, { value: "grid", label: "Grid" }]} />
+
+<ToggleGroup value={statuses} onChange={setStatuses} aria-label="Statuses" options={[{ id: "new", label: "New" }]} />
+```
+
+## Public API
+
+- `Toggle` renders `button role="switch"`; `disabled` is supported. A name is required, and there is exactly one source: `label` — an accessible name with no visible text — or visible text in `children`. Both at once is not allowed: a screen reader would announce a different name than the one on screen. In development, a console warning flags this. The type does not forbid it, so that `extends ToggleProps` and `Omit<ToggleProps, …>` keep compiling for the consumer.
+- **Visible text and a description.** `<Toggle checked={…} onCheckedChange={…} description="A summary of activity every Monday">Weekly digest</Toggle>` renders a setting row: a title and an optional description on the left, the track on the right. The text is a real `<label for>` pointing at the button, so a click on the title or the description toggles (not when disabled), and the label becomes the accessible name (`aria-labelledby`). The description is linked to the switch through `aria-describedby` and is merged with the `FormField` description and any `aria-describedby` you pass, not replacing them. `description` without a label is not accepted — there is nothing to attach it to.
+- In the row form `className` applies to the whole row (width, margins), in the bare form — to the track. Other attributes (`id`, `data-*`, `ref`, `aria-*`) go to the button in both forms. The track sits on the right, the text on the left — a "switch on the left" layout has not been asked for yet, and you can still build it next to a bare `Toggle`.
+- The track of a `Toggle` that is on is outlined with an `accent-strong` border: the `accent` fill against the background falls short of 3:1 (WCAG 1.4.11), so the border provides the required contrast. A checked `Checkbox` uses the same technique.
+- A passed `onClick` is called _before_ the toggle and does not cancel it: a consumer's handler does not override the component's own behavior. To cancel the toggle deliberately, call `event.preventDefault()`. The role and `aria-checked` are not overridden by spread props.
+- `Segmented.options` holds `value`, `label`, `icon`, `tooltip`, `disabled`; for a segment without a label, `tooltip` is required as the accessible name.
+- `Segmented` wraps segments onto a second row when they do not fit the available width. There is no prop for this and there will not be — see the analysis below.
+- `Segmented.mobileIconOnly` hides the labels on screens narrower than 640 pixels, leaving the icons; the label stays the button's accessible name. See the analysis below.
+- `ToggleGroup.selectionMode` is `multiple` (the default) or `single`; in `single`, zero selected is allowed. An `option` with only an icon requires `aria-label`.
+- `ToggleGroup` inside a vertical `Toolbar` stacks into a column on its own: the axis comes from the toolbar through the react-aria context, and the component has no prop of its own.
+- `ButtonGroup.orientation` is `horizontal` or `vertical`; `aria-label` adds `role="group"`.
+
+## Wrapping segments
+
+A segment does not shrink: the button has `shrink-0` and `whitespace-nowrap`, and
+this is deliberate — a squeezed tab label reads worse than a wrapped one. So when
+the set does not fit the width, the container has exactly two outcomes: wrap the
+excess onto a second row or run off the edge; the kit wraps.
+
+It is not controlled by a boolean prop. A `Segmented` that does not fit and does
+not wrap is useless: running off the edge means horizontal scrolling, that is, a
+violation of WCAG 1.4.10, and we have not met a consumer who specifically needs
+the overflow. A prop here would read as "broken by default, fix it with a prop",
+and every later consumer would rediscover the defect — on a narrow screen and
+already in production.
+
+Wrapping depends on the available width, not on a breakpoint: a `Segmented` may
+also sit in a narrow column on a wide screen. It works inside any parent — block,
+`flex`, `grid`.
+
+The gap is set per axis: 2 pixels between segments, 4 between rows. A single
+`gap` for both axes would put the rows the same 2 pixels apart, and the two
+rows would read as a clumped grid instead of one control.
+
+The keyboard order when wrapping matches the visual one: left to right, then the
+second row. This is the second reason to prefer wrapping over scrolling — with
+scrolling, Tab moves focus to a button outside the visible part, and the browser
+scrolls it into view by itself, jerking the content sideways.
+
+## Icon only on a narrow screen (`mobileIconOnly`)
+
+On screens narrower than 640 pixels the segment label is hidden and the icon
+stays:
+
+```tsx
+<Segmented value={list} onChange={setList} mobileIconOnly options={lists} />
+```
+
+Height is the criterion: five segments with an icon and a label at a width of 375
+take two rows — 68 pixels instead of the 36 this mode needs. Segment wrapping (it
+came earlier and has not gone anywhere) removes horizontal scrolling but not
+height: over 500 pixels of content do not fit into 327 pixels of width, so a
+second row remains. In this mode there is one row.
+
+**The label is hidden, not removed.** The node stays in the accessibility tree
+and serves as the button's accessible name — `sr-only sm:not-sr-only sm:inline`, the
+same technique and the same _one_ node as in `Chip`. This is why the mode lives in
+the kit: hiding a label correctly takes one line of classes, but there are three
+ways to hide it incorrectly (`hidden`, `display: none`, dropped `children`), and
+each leaves a row of nameless buttons that only an audit will reveal.
+
+**`tooltip` is not needed in this mode.** The requirement "a segment without a
+label must have a tooltip" applies to a genuine absence of a label
+(`label: ""`); here the label exists, it just is not visible. A tooltip would not
+show on a touch device anyway. The kit used to refuse such a mode for exactly
+this reason: a tooltip would be invisible on touch. The refusal was lifted because
+it depended on an implementation that removed the label.
+
+**The mode is a property of the whole `Segmented`, not of a segment.** A row where
+some tabs have words and some do not would change width on switching, and the
+buttons would jump under the finger. The one exception is a segment _without_ an
+icon: its label stays visible, otherwise the button would be empty. This is a
+safeguard against a set where an icon was forgotten.
+
+**The threshold is not exposed.** It is the same 640 as `Chip.mobileIconOnly`;
+two consumers with different thresholds would diverge in behavior for no reason.
+The threshold is taken from the viewport width, not the parent's: a `Segmented` in a
+narrow column on a wide monitor keeps its labels.
+
+**The padding is reduced along with the label** — `px-2` instead of `px-3`. Around a
+single icon the button comes out 32 by 28 instead of 40 by 28: almost a square,
+like `Button iconOnly`. The height does not change, so the hit area keeps its
+height.
+
+The product objection — five bare icons read worse than five words — still
+stands, which is why the mode is a prop and not the default.
+
+## Accessibility and semantics
+
+- `Toggle` uses `aria-checked`, the other components use `aria-pressed` or React Aria behavior.
+- A bare `Toggle` with no visible text is named only through `label`; do not build the text next to it by hand (a `<span>` beside the button): it will not become the name and will not react to a click. `children` exists for that.
+- For a segment without a label, the `tooltip` sets the accessible name.
+- Sources: `src/components/actions/Toggle.tsx`, `src/components/actions/Segmented.tsx`, `src/components/actions/ToggleGroup.tsx`, `src/components/actions/ButtonGroup.tsx`; the stories `Toggle.stories.tsx`, `Segmented.stories.tsx`, `ToggleGroup.stories.tsx`, `ButtonGroup.stories.tsx`.