@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/api/utilities.md

@@ -0,0 +1,252 @@
+---
+category: api
+status: stable
+source: src/index.ts
+---
+
+# Общий API: утилиты, токены, константы и типы
+
+## Кратко для AI
+
+`@olddevs/ui` экспортирует несколько программных API помимо компонентов. Они
+предназначены для интеграции с компонентами и общим визуальным словарём; не
+импортируйте внутренние `src/lib/*` напрямую. Все публичные component exports
+и их prop-типы документируются на страницах самих компонентов, а
+`@olddevs/ui/icons` — в [icons.md](../icons.md).
+
+## Когда использовать
+
+- `cn` — для объединения классов Tailwind, особенно если вместе встречаются
+  `text-caption` и цвет текста из шкалы кита.
+- `useScrollLock` — для собственной контролируемой overlay-композиции, когда
+  именно она владеет открытым состоянием и должна блокировать прокрутку `body`.
+- `useMediaQuery` — когда от ширины окна зависит состав или поведение (что
+  смонтировать, сколько месяцев показать, свернуть ли `SplitPanel`), а не
+  только вид: показать или спрятать блок по ширине — класс Tailwind. Подробности —
+  в [SplitPanel](../components/app-shell/split-panel.md).
+- `Size`, `Tone`, `Variant`, `TONE_TOKENS` и `variantClasses` — при создании
+  нового примитива дизайн-системы с теми же семантическими осями.
+- helpers периодов — для относительного периода в URL и его преобразования в
+  даты; helpers времени — для ввода `HH:MM` в контролах даты и времени.
+- реестр тем — для переключателя оформления и раннего применения сохранённой
+  темы; списки осей берите оттуда, а не переписывайте константами у себя.
+
+## Когда не использовать
+
+- Не создавайте второй счётчик блокировки прокрутки `body` в приложении. Несвязанные счётчики
+  ломают вложенные overlays; используйте один `useScrollLock` из пакета.
+- Не собирайте классы Tailwind динамически, например `text-${tone}`. Используйте
+  буквальные токены или `variantClasses`: имена классов, собранные на лету, не
+  попадут в сборку CSS.
+- Не передавайте невалидную строку из URL сразу в `resolvePeriod`: сначала
+  сузьте её `isRelativePeriod`.
+- Не используйте `maskTime` как финальную валидацию: маска работает во время
+  ввода, а нормализация — после него.
+
+## Общие варианты
+
+Источник общих экспортов — `src/index.ts`; их реализация находится в
+`src/lib/cn.ts`, `src/hooks/useScrollLock.ts`, `src/hooks/useMediaQuery.ts`, `src/lib/variants.ts`,
+`src/lib/period.ts` и `src/lib/time.ts`.
+
+| Export                               | Назначение                                                                                                                                                |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cn(...inputs)`                      | `clsx` + настроенный Tailwind merge; последний конфликтующий класс побеждает, а `text-caption` не конфликтует с `text-fg-*`.                              |
+| `useScrollLock(isLocked)`            | Блокирует прокрутку `body`, компенсирует ширину scrollbar и считает вложенные замки на уровне модуля. Снимает замок при размонтировании.                  |
+| `useMediaQuery(query, serverValue?)` | Возвращает, выполняется ли медиазапрос сейчас, и перерисовывает компонент при изменении. До гидратации и без `matchMedia` отдаёт `serverValue` (`false`). |
+| `Size`                               | Общая шкала `sm \| md \| lg`; конкретный компонент может поддерживать её подмножество.                                                                    |
+| `Tone`                               | Семантический цвет `neutral \| accent \| success \| warning \| danger`, не имя оттенка.                                                                   |
+| `Variant`                            | Визуальная трактовка `solid \| soft \| outline \| ghost`.                                                                                                 |
+| `Numeric`                            | Начертание цифр: `tabular` — равной ширины. Ось компонентов `Text` и `Heading`, не отдельная утилита.                                                     |
+| `ToneAtoms`                          | Тип набора готовых Tailwind-классов для одного `Tone`.                                                                                                    |
+| `TONE_TOKENS`                        | Карта `Tone → ToneAtoms`; используйте вместо копирования строк токенов.                                                                                   |
+| `variantClasses(variant, tone)`      | Готовые классы пары variant/tone для собственного примитива.                                                                                              |
+| `INVALID_BORDER_CLASS`               | Готовый класс границы invalid-поля.                                                                                                                       |
+
+## Периоды
+
+| Export                                     | Назначение и ограничения                                                                                                                                             |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RELATIVE_PERIODS`, `RelativePeriod`       | Допустимые относительные значения: `7d`, `30d`, `90d`, `180d`, `365d`, `thisMonth`, `lastMonth`, `thisYear`.                                                         |
+| `isRelativePeriod(value)`                  | Runtime type guard для внешней строки, в том числе из URL.                                                                                                           |
+| `resolvePeriod(period, timeZone?, now?)`   | Возвращает включительные ISO-границы `DateRange`; по умолчанию использует локальную timezone. `now` нужен главным образом для детерминированных тестов.              |
+| `DateRange`                                | Пара `{ start, end }` в ISO `YYYY-MM-DD`, обе границы включительны.                                                                                                  |
+| `periodLength(range)`                      | Число дней включительно, вычисленное в UTC; диапазон, перевёрнутый вручную, даёт не меньше одного дня. Неразбираемая граница даёт `0` — «считать нечего».            |
+| `formatPeriodLength(range, messages?)`     | Подпись длины периода из каталога сообщений: `14 дней` или `14 days`; без `messages` — английский фолбэк. При неразбираемой границе — пустая строка, а не «0 дней».  |
+| `PeriodPreset`, `periodPresets(messages?)` | Тип и функция, которая собирает короткий набор стандартных пресетов для UI с подписями из каталога сообщений; без `messages` — английские подписи.                   |
+| `DEFAULT_PERIOD_PRESETS`                   | `@deprecated` с 2.0.0: неизменяемый набор пресетов с английскими подписями, локаль он не знает. Используйте `periodPresets(messages)`; удаляется в следующем мажоре. |
+
+```ts
+const rawPeriod = searchParams.get("period");
+const period = rawPeriod && isRelativePeriod(rawPeriod) ? rawPeriod : "30d";
+const range = resolvePeriod(period, "Europe/Moscow");
+```
+
+## Время
+
+| Export                            | Назначение                                                                                                                                                         |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `maskTime(value)`                 | Оставляет до четырёх цифр и добавляет `:` после первых двух: `2130 → 21:30`. Применяйте при каждом вводе.                                                          |
+| `normalizeTime(value, fallback?)` | Получает частичный ввод и возвращает значение `HH:MM` в допустимых границах; пустой ввод отдаёт `fallback`, по умолчанию `00:00`. Применяйте при завершении ввода. |
+| `formatDate(isoDate, locale?)`    | Форматирует ISO-день из `DatePicker` для отображения; документирован вместе с [DatePicker](../components/date-time/date-picker.md).                                |
+| `upcomingSlots(step, now)`        | Строит ближайшие слоты времени; документирован вместе с [TimePicker](../components/date-time/time-picker.md).                                                      |
+
+## Маски ввода
+
+Чистые функции движка маски. Экспортируются отдельно от компонента, потому что
+подготовить значение перед отправкой или проверить заполненность бывает нужно
+без поля на экране.
+
+| Export                  | Назначение                                                                 |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `formatMask(raw, mask)` | Раскладывает сырое значение по маске. Хвост маски не показывается заранее. |
+| `unmask(display, mask)` | Достаёт сырое значение позиционно — литерал-цифра маски в него не утекает. |
+| `maskCapacity(mask)`    | Сколько символов значения вмещает маска: `+7 (999) 999-99-99` → 10.        |
+
+Токены маски: `9` — цифра, `a` — буква, `*` — цифра или буква; остальное —
+литерал. Экранирования нет; подробности — в [MaskedInput](../components/inputs/masked-input.md).
+
+## Темы
+
+Реестр осей оформления и контракт их применения. Компонента переключателя в
+ките **нет**: `Segmented` уже даёт нужную форму, а кнопка завязана на хранилище
+и вёрстку конкретного приложения. Обоснование —
+ADR-0020; готовый код
+двух вариантов переключателя — [рецепт в theming.md](../theming.md#переключатель-темы).
+
+| Export                                                | Назначение                                                                                                      |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `UI_THEMES`, `UI_ACCENTS`, `UI_BRANDS`                | Три оси оформления списками. Сверяются со `styles.css` тестом — разойтись молча не могут.                       |
+| `normalizeTheme`, `normalizeAccent`, `normalizeBrand` | Приводят произвольное значение к допустимому. Принимают `unknown`: типичный источник — хранилище.               |
+| `applyTheme(root, prefs)`                             | Выставляет все три оси на элементе. Если ось не передана, она возвращается к умолчанию, а не сохраняет прежнее. |
+| `themeInitScript({ storageKey })`                     | **Строка** JS для раннего применения темы до первой отрисовки.                                                  |
+| `DEFAULT_THEME_PREFS`                                 | Состояние, в котором ни один оверлей не задан: `dark` / `blue` / `base`.                                        |
+
+`base` **снимает** `data-brand`, а не пишет `data-brand="base"`: блока с таким
+именем в CSS нет, и оставленный атрибут выглядел бы работающим оверлеем.
+
+### Раннее применение темы
+
+Без раннего применения темы пользователь видит вспышку не той темы между отрисовкой и гидратацией.
+Кит отдаёт **строку**, а не выполняет код: куда её вставить, знает фреймворк
+потребителя, а не дизайн-система.
+
+```jsx
+import Script from "next/script";
+import { themeInitScript } from "@olddevs/ui";
+
+<Script
+  id="theme-init"
+  strategy="beforeInteractive"
+  dangerouslySetInnerHTML={{ __html: themeInitScript({ storageKey: "ui-prefs" }) }}
+/>;
+```
+
+Формат хранения — JSON-объект `{ theme, accent, brand }` по этому ключу. Пишет
+его потребитель (`applyTheme` сохранением не занимается), читает скрипт; любое
+поле может отсутствовать или врать: нормализация отработает, а битый JSON
+страницу не уронит.
+
+## Состояние таблицы
+
+`useTableState` описывает форму состояния таблицы `DataTable` и связи между его
+частями. Хук **ничего не хранит вне React** и ни на что не подписывается: кит
+даёт форму, а владеет ею потребитель
+(ADR-0023).
+
+| Export          | Назначение                                                                              |
+| --------------- | --------------------------------------------------------------------------------------- |
+| `useTableState` | `{ state, set, reset }`. Одна функция обновления вместо десяти обработчиков — см. ниже. |
+| `TableState`    | Сортировка, страница и её размер, выделение, раскрытие, фильтры, колонки, плотность.    |
+| `TableFilter`   | Применённый фильтр: `id`, `field`, `value`, необязательные `label` и `to`.              |
+
+### Инварианты, ради которых хук существует
+
+- смена **фильтров, сортировки или размера страницы сбрасывает страницу** на первую. Иначе
+  пользователь смотрит на четвёртую страницу выборки из десяти строк и читает
+  пустоту как «ничего не найдено»;
+- **выделение при этом не сбрасывается.** Обратное выглядит аккуратнее и срывает
+  массовое действие ровно тогда, когда оно нужнее всего;
+- плотность и видимость колонок страницу **не трогают**: выборку сужает фильтр,
+  а не оформление;
+- явная `page` в том же вызове сброс отменяет — так восстанавливается состояние
+  из адреса, целиком и за один раз.
+
+Обновление идёт через одну функцию, потому что инварианты обязаны срабатывать
+независимо от того, что именно поменяли; разложенные по отдельным обработчикам,
+они разъехались бы.
+
+### Перенос в URL
+
+| Export                 | Назначение                                                   |
+| ---------------------- | ------------------------------------------------------------ |
+| `tableStateToParams`   | Состояние → `URLSearchParams`. Умолчания не пишутся.         |
+| `tableStateFromParams` | `URLSearchParams` → часть состояния. Мусор не роняет разбор. |
+| `DEFAULT_TABLE_STATE`  | Умолчания, кроме плотности: её даёт провайдер.               |
+
+Функции **чистые и без `"use client"`**: разбор URL нужен и на сервере, ведь в
+Next.js состояние восстанавливается из `searchParams` до отрисовки. Применять
+их к URL — дело приложения: у разных маршрутизаторов разные правила записи
+параметров (`replace` или `push`, кодирование массивов, `basePath`), и кит,
+взявшийся их угадывать, ошибётся молча.
+
+```tsx
+const { state, set } = useTableState(tableStateFromParams(searchParams));
+
+// после изменения — записать обратно тем способом, каким умеет ваш роутер
+router.replace(`?${tableStateToParams(state)}`);
+```
+
+**Выделение и раскрытие в URL не идут**, хотя в исходной спецификации выделение
+входило в состояние таблицы. Причины две: список ключей ничем не ограничен по длине, и ссылка с
+выделением, открытая назавтра, отмечает записи, которых уже нет. Выделение —
+состояние сеанса, а не URL.
+
+**Восстановление кладётся в хук целиком**, одним вызовом `set`: инвариант
+«сужение выборки сбрасывает страницу» отменяется явной страницей в том же вызове, иначе
+ссылка всегда открывала бы первую.
+
+### У токена фильтра свой `id`
+
+У фильтра свой `id`, а не пара «поле + значение» и не подпись. Два фильтра по
+одному полю дают одинаковые на вид токены, и по ним не понять, какой из двух
+снимать; подпись же локализуется и обрезается.
+
+Операторов в модели нет намеренно: без `to` токен означает равенство, с `to` —
+диапазон `value…to`, любая граница которого может быть пустой строкой («от 50»,
+«до 100»). Различие несёт само наличие ключа `to`, поэтому проверять его надо
+через `!== undefined`
+(ADR-0063). `contains`
+и `in` можно добавить, когда они понадобятся. В URL `to` едет пятой частью
+токена; ссылки из трёх и четырёх частей читаются как раньше. Как собрать
+диапазон в интерфейсе — [FilterBar](../components/table/filter-bar.md).
+
+## Константы, классы и публичные типы: где они описаны
+
+Это публичные exports, но не самостоятельные компоненты. Их описывает страница
+семейства, которому они принадлежат, чтобы AI не воспринимал класс как
+универсальный API:
+
+| Exports                                                                                                                                       | Документация                                                  |
+| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `MENU_PANEL_CLASS`, `MENU_ITEM_CLASS`, `MENU_ITEM_ICON_CLASS`, `MENU_ITEM_SHORTCUT_CLASS`, `MENU_SECTION_LABEL_CLASS`, `MENU_SEPARATOR_CLASS` | [Menu](../components/overlays/menu.md)                        |
+| `NAV_BUTTON_CLASS`, `WEEKDAY_CELL_CLASS`                                                                                                      | [Calendar](../components/date-time/calendar.md)               |
+| `pageRange`                                                                                                                                   | [Pagination](../components/navigation/pagination.md)          |
+| `maskTime`, `normalizeTime`                                                                                                                   | [DateTimePicker](../components/date-time/date-time-picker.md) |
+| `formatDate`                                                                                                                                  | [DatePicker](../components/date-time/date-picker.md)          |
+| `upcomingSlots`                                                                                                                               | [TimePicker](../components/date-time/time-picker.md)          |
+
+Каждый `*Props` и предметный тип, экспортированный с компонентом (например
+`TableProps`, `CommandItem`, `SelectItem`, `KeyboardSelection` или `DrawerSide`),
+остаётся частью его public API и описывается на странице этого семейства.
+[Каталог компонентов](../components/index.md) связывает public exports со
+страницами семейств; `src/index.ts` — окончательный источник всех экспортов.
+
+## Связанные исходники и проверка
+
+- Публичная поверхность: `src/index.ts`.
+- Реализации: `src/lib/cn.ts`, `src/hooks/useScrollLock.ts`,
+  `src/hooks/useMediaQuery.ts`, `src/lib/variants.ts`, `src/lib/period.ts`, `src/lib/time.ts`,
+  `src/lib/themes.ts`, `src/lib/table-state.ts`, `src/hooks/useTableState.ts`.
+- `maskTime` и `normalizeTime` также используются в
+  `src/components/date-time/DateTimePicker.tsx`.

package/docs/component-selection.en.md

@@ -0,0 +1,48 @@
+---
+sourceHash: 93cc57b25c0e
+---
+
+# How to choose a component
+
+Choose by the meaning of the action and by the state, not by the shape that is easier to build.
+If the rule below does not fit, open the component catalog and the page of the closest candidate
+before writing JSX.
+
+| Task                                                    | Use                                   | Do not use instead                                             | Reason                                                                                                                                                      |
+| ------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Pick a value from a known finite set                    | `Select`                              | `Combobox`                                                     | `Select` does not allow a new value; search only filters the set.                                                                                           |
+| Enter a value with a list of options or allow a new one | `Combobox`                            | `Select`                                                       | `Combobox` supports free input when the contract allows it.                                                                                                 |
+| Pick exactly one mode                                   | `Segmented`                           | `ToggleGroup`                                                  | A mode always has a value; an empty state is not allowed.                                                                                                   |
+| Turn on zero, one or several independent conditions     | `ToggleGroup`                         | `Segmented`                                                    | An empty set is legitimate for filters and settings.                                                                                                        |
+| Confirm a deletion or another dangerous action          | `ConfirmDialog`                       | `Dialog`                                                       | `alertdialog`, an explicit destructive action and a safe initial focus point.                                                                               |
+| Show ordinary modal content or a form                   | `Dialog`                              | `ConfirmDialog`                                                | An ordinary dialog must not pretend to be a critical confirmation.                                                                                          |
+| Show a screen's shortcut reference                      | `ShortcutsHelp`                       | `Dialog` with `Kbd` / `Keyboard` elements scattered through it | Named groups and the spoken form of a shortcut ("Ctrl plus K") are already in the component; `Keyboard` is an on-screen keyboard for input, not a shortcut. |
+| Show a short result of a completed operation            | `toast` + `Toaster`                   | `Alert`                                                        | A toast is temporary and does not take permanent space on the page.                                                                                         |
+| Show a persistent important message in context          | `Alert`                               | `toast`                                                        | The user must see the message for as long as it is relevant.                                                                                                |
+| Show an entity's status                                 | `StatusBadge`                         | `Badge`                                                        | Status is a closed semantic set; its tone conveys the meaning.                                                                                              |
+| Show a count                                            | `Badge`                               | `StatusBadge`                                                  | A counter says "how many", not the entity's lifecycle.                                                                                                      |
+| Navigate to a URL                                       | `Link` or `Button asChild` with `<a>` | `Button onClick`                                               | A real link lets users open it in a new tab and copy its URL, and keeps the correct role.                                                                   |
+| Give an additional short explanation                    | `Tooltip` / `HelpTooltip`             | hidden text without a name                                     | A tooltip does not replace a label and the main content.                                                                                                    |
+| Show an entity preview on hover over a link or name     | `HoverCard`                           | `Tooltip` / `Popover`                                          | A card with rich content opens on hover and keyboard focus; it is absent on touch devices, so everything important must be available without it.            |
+| Report the state of the whole app                       | `Banner`                              | `Alert`                                                        | `Alert` describes the state of one area of the page; a banner survives navigation.                                                                          |
+| Show what happened to the selected files                | `UploadQueue`                         | `FileDropzone`                                                 | The dropzone provides files, the queue shows what became of them.                                                                                           |
+| Show a feed of events that occurred                     | `NotificationList`                    | `Timeline`                                                     | In a feed, time sets the order and there are actions; in `Timeline`, the order is set by the process.                                                       |
+| Show a tile with a preview and actions                  | `MediaCard`                           | `Card`                                                         | For a tile the main things are a proportionally scaled preview, an overlay and selection.                                                                   |
+| Let the user set the order                              | `SortableList`                        | `Table` with sorting                                           | In a table the order is computed; here it is assigned by a person.                                                                                          |
+| Show hundreds of previews                               | `VirtualGrid`                         | a plain CSS grid                                               | Only the visible cells live in the DOM; the consumer sets the container height.                                                                             |
+| Copy a value to the clipboard                           | `CopyButton`                          | a hand-built button with an icon                               | The result is announced, and a clipboard failure is shown rather than swallowed.                                                                            |
+| Truncate long text                                      | `Truncate`                            | `text-overflow` by hand                                        | The tooltip appears only when the text is actually truncated and is keyboard-accessible.                                                                    |
+
+## The minimal component rule
+
+Do not create a new local primitive while the semantics you need already exist in
+`@olddevs/ui`. But do not move domain data into the package: for example, the status vocabulary,
+the texts of a specific product and the page layout belong to the consumer.
+
+## If there is no component
+
+1. Check the [component catalog](components/index.md) and the public icon exports.
+2. Build a domain composition from existing primitives if it is only
+   the layout or text of a specific screen.
+3. Propose a new primitive only when the semantics, API and
+   accessibility requirements repeat, not just because one CSS combination does.

package/docs/component-selection.md

@@ -0,0 +1,44 @@
+# Как выбрать компонент
+
+Выбирайте по смыслу действия и состоянию, а не по форме, которую проще собрать.
+Если правило ниже не подходит, откройте каталог компонентов и страницу ближайшего кандидата
+до написания JSX.
+
+| Задача                                                   | Используйте                         | Не используйте вместо этого            | Причина                                                                                                                                  |
+| -------------------------------------------------------- | ----------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Выбрать значение из известного конечного набора          | `Select`                            | `Combobox`                             | `Select` не допускает нового значения; поиск только фильтрует набор.                                                                     |
+| Ввести значение со списком вариантов или разрешить новое | `Combobox`                          | `Select`                               | `Combobox` поддерживает свободный ввод, когда это разрешено контрактом.                                                                  |
+| Выбрать ровно один режим                                 | `Segmented`                         | `ToggleGroup`                          | У режима всегда есть значение; пустое состояние недопустимо.                                                                             |
+| Включить ноль, одно или несколько независимых условий    | `ToggleGroup`                       | `Segmented`                            | Нулевой набор для фильтров и настроек законен.                                                                                           |
+| Подтвердить удаление или другое опасное действие         | `ConfirmDialog`                     | `Dialog`                               | `alertdialog`, явный destructive action и безопасная начальная точка фокуса.                                                             |
+| Показать обычное модальное содержимое или форму          | `Dialog`                            | `ConfirmDialog`                        | Обычное окно не должно изображать критическое подтверждение.                                                                             |
+| Показать свод горячих клавиш экрана                      | `ShortcutsHelp`                     | `Dialog` с россыпью `Kbd` / `Keyboard` | Группы с именами и озвучка сочетания («Ctrl плюс K») уже в компоненте; `Keyboard` — экранная клавиатура для ввода, а не сочетание.       |
+| Показать краткий результат завершённой операции          | `toast` + `Toaster`                 | `Alert`                                | Тост временный и не занимает постоянное место на странице.                                                                               |
+| Показать постоянное важное сообщение в контексте         | `Alert`                             | `toast`                                | Пользователь должен видеть сообщение, пока оно актуально.                                                                                |
+| Показать состояние сущности                              | `StatusBadge`                       | `Badge`                                | Статус — закрытый семантический набор, его тон сообщает значение.                                                                        |
+| Показать количество                                      | `Badge`                             | `StatusBadge`                          | Счётчик сообщает «сколько», но не жизненный цикл сущности.                                                                               |
+| Перейти по URL                                           | `Link` или `Button asChild` с `<a>` | `Button onClick`                       | Настоящая ссылка сохраняет открытие в новой вкладке, копирование адреса и корректную роль.                                               |
+| Дать дополнительное краткое пояснение                    | `Tooltip` / `HelpTooltip`           | скрытый текст без имени                | Подсказка не заменяет подпись и основной контент.                                                                                        |
+| Показать превью сущности по наведению на ссылку или имя  | `HoverCard`                         | `Tooltip` / `Popover`                  | Карточка с разметкой открывается наведением и клавиатурным фокусом; на тач-устройствах её нет, поэтому всё важное должно быть и без неё. |
+| Сообщить о состоянии всего приложения                    | `Banner`                            | `Alert`                                | `Alert` описывает состояние места на странице; баннер переживает навигацию.                                                              |
+| Показать судьбу выбранных файлов                         | `UploadQueue`                       | `FileDropzone`                         | Область даёт файлы, очередь показывает, что с ними стало.                                                                                |
+| Показать ленту произошедших событий                      | `NotificationList`                  | `Timeline`                             | У ленты порядок задаёт время, и есть действия; у `Timeline` порядок задаёт процесс.                                                      |
+| Показать плитку с превью и действиями                    | `MediaCard`                         | `Card`                                 | У плитки главное — превью с сохранением пропорций, оверлей и выбор.                                                                      |
+| Дать пользователю задать порядок                         | `SortableList`                      | `Table` с сортировкой                  | В таблице порядок вычисляется, здесь — назначается человеком.                                                                            |
+| Показать сотни превью                                    | `VirtualGrid`                       | обычный CSS-грид                       | В DOM живут только видимые ячейки; высоту контейнера задаёт потребитель.                                                                 |
+| Скопировать значение в буфер                             | `CopyButton`                        | самодельная кнопка с иконкой           | Результат объявляется, а отказ буфера виден, а не проглатывается.                                                                        |
+| Обрезать длинный текст                                   | `Truncate`                          | `text-overflow` руками                 | Подсказка появляется только у текста, который действительно обрезан, и доступна с клавиатуры.                                            |
+
+## Правило минимального компонента
+
+Не создавайте новый локальный примитив, пока нужная семантика уже есть в
+`@olddevs/ui`. Но не переносите доменные данные в пакет: например, словарь статусов,
+тексты конкретного продукта и раскладка страницы принадлежат потребителю.
+
+## Если компонента нет
+
+1. Проверьте [каталог компонентов](components/index.md) и публичные icon exports.
+2. Соберите доменную композицию из существующих примитивов, если это лишь
+   раскладка или текст конкретного экрана.
+3. Предлагайте новый примитив, только когда повторяются семантика, API и
+   требования доступности, а не одна CSS-комбинация.

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

@@ -0,0 +1,59 @@
+---
+component: Button
+exports: [Button]
+category: actions
+status: stable
+source: src/components/actions/Button.tsx
+story: src/components/actions/Button.stories.tsx
+sourceHash: 5a0614985d7b
+---
+
+# Button
+
+## Summary for AI
+
+`Button` runs an action. For navigation, use a real link through `asChild`, not `onClick` with routing. It defaults to `type="button"`, so inside a form it never submits the form by accident.
+
+## When to use
+
+- The user has to perform an action: save, open a dialog, delete, retry a request.
+- You need the shared set of `variant`, `tone`, `size`, `disabled` and focus indication.
+- The action is navigation: pass a single link as `children` together with `asChild`.
+
+## When not to use
+
+- To pick one mode, use `Segmented`; for an independent set of filters, use `ToggleGroup`.
+- To toggle a boolean state with the switch role, use `Toggle`.
+- For a link that does not need to look like a button, use `Link`.
+
+## Minimal example
+
+```tsx
+<Button tone="accent" variant="solid" onClick={save}>
+  Save
+</Button>
+
+<Button asChild variant="soft">
+  <a href="/campaigns">To campaigns</a>
+</Button>
+```
+
+## Public API
+
+- `variant`, `tone`, `size` set the look; the defaults are `soft`, `neutral`, `md`.
+- There are four size steps: `xs`, `sm`, `md`, `lg`. `xs` is 20 pixels and
+  exists for an icon button in a list row: `sm` is 30 with 20 for the
+  content, and a 32 row stretches to 42. `xs` is not meant to have a label, so
+  use it with `iconOnly`. The hit area of `xs` is still 24×24: a pseudo-element
+  extends it, because 20×20 fails WCAG 2.5.8, and enlarging the button itself
+  would bring the stretched row back.
+- `icon` adds an icon; with `iconOnly` the label is not rendered. An icon-only button must have an accessible name through `aria-label` or `title`. The icon itself is not a hit target (`pointer-events: none`): otherwise the `event.target` of a click on the icon is the `<svg>`, not the button, and anyone who inspects the click target gets it wrong. A real-world example is an `EditableList` row with an action: react-aria checks the target without walking up the ancestors, and a click on the icon triggered both the button and the row action.
+- `selected` sets `aria-pressed`; it is only for a pressed **button**, and a link (`asChild`) does not get it.
+- `loading` means a submission is in progress: an indicator takes the icon slot, the button cannot be pressed, and the state is announced through `aria-busy`. There is no need to add `disabled`: it is applied automatically. A button without an icon gets the slot for the duration of the submission, and the label shifts; if a button can enter `loading`, give it an icon from the start. The indicator is decorative and is not part of the button's accessible name.
+- `asChild` passes the styles, props and ref to the single child element. For a link, `disabled` becomes `aria-disabled`, turns off pointer events and takes the child out of the tab order (`tabIndex={-1}`) — even if the child set `tabIndex` itself: the component decides this itself, because otherwise a disabled link remained reachable from the keyboard. `selected` is not passed on, because `aria-pressed` is not allowed on a link.
+
+## Accessibility and semantics
+
+- A regular button is activated with Space and Enter; a link rendered through `asChild` is activated with Enter, as a link should be.
+- Do not nest interactive elements in `children`.
+- Source of the contract: `src/components/actions/Button.tsx`; scenarios — `src/components/actions/Button.stories.tsx` and `tests/button-aschild.test.tsx`.

package/docs/components/actions/button.md

@@ -0,0 +1,58 @@
+---
+component: Button
+exports: [Button]
+category: actions
+status: stable
+source: src/components/actions/Button.tsx
+story: src/components/actions/Button.stories.tsx
+---
+
+# Button
+
+## Кратко для AI
+
+`Button` запускает действие. Для перехода используйте настоящую ссылку через `asChild`, а не `onClick` с маршрутизацией. По умолчанию это `type="button"`, поэтому внутри формы он не отправляет её случайно.
+
+## Когда использовать
+
+- Пользователь должен выполнить действие: сохранить, открыть диалог, удалить, повторить запрос.
+- Нужен общий набор `variant`, `tone`, `size`, `disabled` и фокусной индикации.
+- Действие — навигация: передайте одну ссылку как `children` вместе с `asChild`.
+
+## Когда не использовать
+
+- Для выбора одного режима используйте `Segmented`; для независимого набора фильтров — `ToggleGroup`.
+- Для переключения булевого состояния с ролью switch используйте `Toggle`.
+- Для ссылки, которой не нужен вид кнопки, используйте `Link`.
+
+## Минимальный пример
+
+```tsx
+<Button tone="accent" variant="solid" onClick={save}>
+  Сохранить
+</Button>
+
+<Button asChild variant="soft">
+  <a href="/campaigns">К кампаниям</a>
+</Button>
+```
+
+## Public API
+
+- `variant`, `tone`, `size` определяют внешний вид; умолчания — `soft`, `neutral`, `md`.
+- Ступеней размера четыре: `xs`, `sm`, `md`, `lg`. `xs` — 20 пикселей, и
+  заведена она под кнопку-иконку в строке списка: `sm` даёт 30 при 20 под
+  содержимое, и строка на 32 растягивается до 42. Подпись в `xs` не
+  предполагается — берите вместе с `iconOnly`. Зона нажатия у `xs` всё равно
+  24×24: её расширяет псевдоэлемент, потому что 20×20 не проходит
+  WCAG 2.5.8, а увеличить саму кнопку — значит вернуть растянутую строку.
+- `icon` добавляет иконку; с `iconOnly` подпись не рисуется. У icon-only кнопки доступное имя обязательно: `aria-label` или `title`. Сама иконка целью попадания не является (`pointer-events: none`): иначе `event.target` у щелчка в рисунок — `<svg>`, а не кнопка, и всякий, кто разбирает цель щелчка, ошибается. Живой случай — строка `EditableList` с действием: react-aria проверяет цель, не обходя предков, и щелчок по иконке запускал и кнопку, и действие строки.
+- `selected` ставит `aria-pressed`; он нужен только нажатой **кнопке**, у ссылки (`asChild`) его нет.
+- `loading` — идёт отправка: индикатор занимает слот иконки, кнопка не нажимается, состояние объявляется через `aria-busy`. Отдельный `disabled` не пишите: он включается сам. У кнопки без иконки слот появляется на время отправки, и подпись сдвигается; если у кнопки бывает `loading`, дайте ей иконку сразу. Индикатор декоративен и в доступное имя кнопки не входит.
+- `asChild` передаёт стиль, props и ref единственному дочернему элементу. Для ссылки `disabled` становится `aria-disabled`, отключает pointer-события и исключает потомка из обхода табуляции (`tabIndex={-1}`) — в том числе если тот задал `tabIndex` сам: решает компонент, иначе выключенная ссылка оставалась достижимой с клавиатуры. `selected` не переносится, поскольку `aria-pressed` недопустим для link.
+
+## Доступность и семантика
+
+- Обычная кнопка активируется Space и Enter; ссылка при `asChild` — Enter, как и положено ссылке.
+- Не вкладывайте интерактивные элементы в `children`.
+- Источник контракта: `src/components/actions/Button.tsx`; сценарии — `src/components/actions/Button.stories.tsx` и `tests/button-aschild.test.tsx`.

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

@@ -0,0 +1,47 @@
+---
+component: Chip
+exports: [Chip]
+category: actions
+status: stable
+source: src/components/actions/Chip.tsx
+story: src/components/actions/Chip.stories.tsx
+sourceHash: 6687a73b593c
+---
+
+# Chip
+
+## Summary for AI
+
+`Chip` is a compact filter button. Its `selected` is controlled state and is announced through `aria-pressed`; the component does not store the selection itself.
+
+## When to use
+
+- You need a short filter, an action tag or a toggleable category.
+- You need an optional counter next to a short label.
+
+## When not to use
+
+- For an entity's status, use `StatusBadge`; for a plain numeric marker, use `Badge`.
+- For several related options, use `ToggleGroup` or `Segmented`.
+- Do not use `Chip` for a decorative tag with no action: it is a button.
+
+## Minimal example
+
+```tsx
+<Chip selected={filters.includes("ready")} onClick={() => toggleFilter("ready")} count={12}>
+  Ready
+</Chip>
+```
+
+## Public API
+
+- `selected` defaults to `false`; `tone` colors only the selected chip.
+- `size`: `sm` or `md`; `count={0}` is shown, `null` and `undefined` are not.
+- `iconOnly` hides the visible label but keeps it for the screen reader; `mobileIconOnly` hides the label only on screens narrower than 640 pixels (the `sm` breakpoint).
+- `type="button"` by default; native `button` attributes are passed to the element.
+
+## Accessibility and semantics
+
+- Always pass `children` for the icon-only and mobile-only variants: it is the button's name.
+- Do not use color as the only signal — the state is conveyed by `aria-pressed`.
+- See `src/components/actions/Chip.tsx`, `src/components/actions/Chip.stories.tsx`.

package/docs/components/actions/chip.md

@@ -0,0 +1,46 @@
+---
+component: Chip
+exports: [Chip]
+category: actions
+status: stable
+source: src/components/actions/Chip.tsx
+story: src/components/actions/Chip.stories.tsx
+---
+
+# Chip
+
+## Кратко для AI
+
+`Chip` — компактная кнопка-фильтр. Его `selected` — управляемое состояние, оно объявляется через `aria-pressed`; компонент не хранит выбор сам.
+
+## Когда использовать
+
+- Нужен короткий фильтр, тег действия или переключаемая категория.
+- Нужен необязательный счётчик рядом с короткой подписью.
+
+## Когда не использовать
+
+- Для статуса сущности используйте `StatusBadge`; для простого числового маркера — `Badge`.
+- Для нескольких согласованных вариантов используйте `ToggleGroup` или `Segmented`.
+- Для декоративного тега без действия не используйте `Chip`: это кнопка.
+
+## Минимальный пример
+
+```tsx
+<Chip selected={filters.includes("ready")} onClick={() => toggleFilter("ready")} count={12}>
+  Готово
+</Chip>
+```
+
+## Public API
+
+- `selected` по умолчанию `false`; `tone` окрашивает только выбранный chip.
+- `size`: `sm` или `md`; `count={0}` показывается, `null` и `undefined` — нет.
+- `iconOnly` скрывает видимую подпись, но оставляет её для скринридера; `mobileIconOnly` скрывает подпись только на экранах меньше 640 пикселей (брейкпоинт `sm`).
+- По умолчанию `type="button"`; нативные атрибуты `button` передаются элементу.
+
+## Доступность и семантика
+
+- Всегда передавайте `children` для icon-only и mobile-only вариантов: это имя кнопки.
+- Не используйте цвет как единственный сигнал — состояние сообщается `aria-pressed`.
+- См. `src/components/actions/Chip.tsx`, `src/components/actions/Chip.stories.tsx`.