@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/components/overlays/command-palette.md

@@ -0,0 +1,147 @@
+---
+component: CommandPalette
+exports: [CommandPalette]
+category: overlays
+status: stable
+source: src/components/overlays/CommandPalette.tsx
+story: src/components/overlays/CommandPalette.stories.tsx
+---
+
+# CommandPalette
+
+## Кратко для AI
+
+`CommandPalette` — controlled modal search по действиям приложения. Передайте
+структурированные `sections` и обработайте выбранный `id` в `onSelect`; палитра
+сама ищет по `label` и `keywords`, закрывается после выбора и не регистрирует
+глобальную горячую клавишу открытия.
+
+Для находок сервера собственный поиск палитры выключается флагом
+`prefiltered: true` на разделе; запрос приходит в `onQueryChange`, а время
+ответа показывается через `loading`.
+
+## Когда использовать
+
+- Быстрый поиск среди действий, особенно когда команд уже много.
+- Оглавление доступных команд: при пустом запросе нужен полный список разделов.
+- Действия естественно группируются по `CommandSection`.
+
+## Когда не использовать
+
+- Для фильтрации списка на экране — `SearchControl`.
+- Для навигации по нескольким статичным страницам — обычные ссылки или вкладки.
+- Не ожидайте, что компонент сам слушает `⌘K`: этой горячей клавишей и `open`
+  владеет приложение.
+
+## Минимальный пример
+
+```tsx
+<CommandPalette
+  open={open}
+  onClose={() => setOpen(false)}
+  sections={[{ id: "files", label: "Файлы", items: [{ id: "upload", label: "Загрузить" }] }]}
+  onSelect={(id) => runCommand(id)}
+/>
+```
+
+## Public API
+
+Требуются `open`, `onClose`, `sections`, `onSelect`. Каждый section имеет `id`,
+`label`, `items` и опционально `prefiltered`; item требует `id`, `label` и
+опционально `shortcut`, `keywords`, `icon`. `placeholder`, `title` и
+`notFoundText` настраивают тексты. `emptyBehaviour="all"` (умолчание) показывает
+все разделы на пустом запросе; `"hint"` вместо них выводит `emptyHint` до
+первого символа.
+
+`onQueryChange(query)` отдаёт набранное наружу на каждое изменение поля —
+включая нажатие кнопки очистки и сброс при закрытии. Это уведомление, а не
+управление: значением поля владеет компонент. Дребезг запроса делает
+потребитель: сколько ждать, зависит от цены запроса, а её кит не знает.
+
+`loading` сообщает, что на стороне потребителя идёт поиск: на месте лупы появляется
+`Spinner`, а пустое состояние вместо `notFoundText` показывает `loadingText`
+(умолчание — «Загрузка»). Уже показанные результаты при этом не прячутся.
+
+**Слот под иконку фиксирован: его размер задаёт разметка.** Лупа — 16 пикселей,
+`Spinner` — 14, и пока слот занимала сама иконка, поле вместе с набранным текстом
+уезжало на эти два пикселя при каждом включении загрузки. Поиск в палитре ходит
+на сервер, запрос уходит на каждое изменение поля — текст дёргался в такт паузам в
+наборе и читался не как «идёт загрузка», а как «экран перезагружается». С
+3.26.0 слот фиксированный, и включать `loading` на каждую догрузку безопасно
+(замер потребителя; браузерный тест сторожит).
+
+## Поиск на сервере: `prefiltered`
+
+Палитра фильтрует переданные разделы сама. Для действий приложения это
+правильно: набор известен заранее и лежит в памяти целиком. Для находок
+сервера — разрушительно: они уже отобраны, причём по другим правилам, и второе
+просеивание подстрокой выбрасывает верные.
+
+Разберём на морфологии. Поиск по `tsvector` с русским словарём находит задачу
+«Подписать договор с подрядчиком» по запросу «договоры». Локальный `contains`
+такую пару не найдёт никогда — подстроки «договоры» в заголовке нет, — и
+человек видит «ничего не найдено» там, где сервер нашёл. Через `keywords` это не
+обходится в принципе: сколько слов туда ни клади, фильтр по подстроке не станет
+морфологическим.
+
+`prefiltered: true` на разделе выключает локальное просеивание именно для него.
+Порядок пунктов сохраняется как передан: ранжирование сделал тот, кто искал.
+Разделы обоих видов уживаются в одном списке, а клавиатура работает в
+`prefiltered`-разделе ровно так же — стрелки, `aria-activedescendant`, выбор по
+Enter.
+
+```tsx
+const [query, setQuery] = useState("");
+const found = useQuery({
+  queryKey: ["task-search", query],
+  queryFn: () => tasksApi.search(query),
+  enabled: query.trim().length >= 2,
+});
+
+<CommandPalette
+  open={open}
+  onClose={close}
+  onQueryChange={setQuery}
+  loading={found.isFetching}
+  sections={[
+    { id: "commands", label: "Команды", items: commands },
+    { id: "tasks", label: "Задачи", items: taskItems, prefiltered: true },
+  ]}
+  onSelect={run}
+/>;
+```
+
+## Доступность и клавиатура
+
+Компонент сочетает Radix Dialog и react-aria `Autocomplete`/`ListBox`. Поле получает
+autofocus, скрытый title даёт диалогу имя, а список получает то же имя. Поиск
+учитывает локаль, не различает регистр и диакритику; `keywords` расширяют
+`textValue`. Стрелки и выбор обрабатывает react-aria. После выбора пункта сначала
+вызывается `onSelect(id)`, затем `onClose`.
+
+Занятость объявляет сам `Spinner` — у него внутри `role="status"` со скрытой
+подписью. Отдельной живой области со счётом находок нет намеренно: она была бы
+вторым голосом про то же самое, а на локально фильтруемых командах срабатывала
+бы на каждый набранный символ.
+
+## Хорошие примеры
+
+- Пустой список действий через `emptyBehaviour="hint"`, если их сотни.
+- `prefiltered: true` на разделе с находками сервера — вместе с `loading`.
+- `keywords="similar поиск"` у пункта «Найти похожие»: английское название и русский синоним.
+- `shortcut={["⌘", "K"]}` для показа уже существующей команды приложения.
+
+## Антипаттерны
+
+- Хранить callback в `CommandItem` вместо устойчивого `id`.
+- Вводить разделы с дублирующими `id` пунктов.
+- Складывать результаты сервера в обычный раздел: локальный фильтр просеет их
+  второй раз и выбросит верные находки.
+- Ходить в сеть прямо в `onQueryChange`, без дребезга: запрос меняется на каждый
+  символ.
+- Оставлять палитру открытой после перехода к действию.
+
+## Связанные исходники и Storybook
+
+- `src/components/overlays/CommandPalette.tsx`
+- `src/components/overlays/CommandPalette.stories.tsx`

package/docs/components/overlays/confirm-dialog.en.md

@@ -0,0 +1,134 @@
+---
+component: ConfirmDialog
+exports: [ConfirmDialog]
+category: overlays
+status: stable
+source: src/components/overlays/ConfirmDialog.tsx
+story: src/components/overlays/ConfirmDialog.stories.tsx
+sourceHash: 5d89bff5031f
+---
+
+# ConfirmDialog
+
+## Summary for AI
+
+`ConfirmDialog` confirms a significant or irreversible action. It is already
+built on `Dialog` with `role="alertdialog"`, puts the initial focus on the
+confirm button, and you do not have to build modality or focus order by hand. For
+the most dangerous actions (deleting a workspace, a project, an account) it can
+ask for typed confirmation: with `typeToConfirm="Acme"` the confirm button stays
+disabled until the user has typed the name.
+
+## When to use
+
+- Deleting, unpublishing, sending immediately and other actions that the user
+  must confirm separately.
+- A short question in `title`, an explanation in `message` and explicit `onConfirm`/`onClose`.
+
+## When not to use
+
+- Use `Dialog` to collect input in several fields, to view something or to change a neutral setting.
+- For a non-critical operation that can be undone after it runs, use an action
+  plus a `toast`, not an extra confirmation.
+- Do not pick the button color by hand: `kind` sets the meaning.
+
+## Minimal example
+
+```tsx
+<ConfirmDialog
+  open={deleteOpen}
+  onClose={() => setDeleteOpen(false)}
+  onConfirm={removeUser}
+  title="Delete the user?"
+  message="This action cannot be undone."
+  confirmLabel="Delete"
+/>
+```
+
+## Typing the name to confirm
+
+```tsx
+<ConfirmDialog
+  open={deleteOpen}
+  onClose={() => setDeleteOpen(false)}
+  onConfirm={removeWorkspace}
+  title="Delete the workspace?"
+  message="Every project, file and member will be removed."
+  confirmLabel="Delete the workspace"
+  typeToConfirm={workspace.name}
+/>
+```
+
+`typeToConfirm` is the string to type. When it is set, the dialog shows a field
+labeled `Type “Acme” to confirm` with a hint under it. The initial focus goes
+to the field (not to the button), the confirm button stays disabled until the
+typed text matches, and pressing Enter in the field confirms only if the typed
+text matches.
+
+- **Case matters.** The point is that the user reads the name and
+  types exactly that: "acme" instead of "Acme" tells one workspace from another,
+  and the hint under the field says so outright.
+- **Spaces around the typed text are ignored**, because text pasted from the
+  clipboard often comes with extra spaces at the edges; spaces inside the name count. The
+  comparison runs in canonical Unicode form (NFC): "é" as one letter and "e"
+  with an accent are equal.
+- **An empty string is not a name.** `typeToConfirm=""` (or a string of spaces
+  only) does not enable the field: the dialog confirms as usual, without the lock field.
+- The typed text lives inside the dialog and is not kept after it closes;
+  `onConfirm` is called only after the match, so you do not need to check the match
+  yourself.
+- The label and the hint come from the message catalog
+  (`confirmDialog.typeToConfirm`, `confirmDialog.typeToConfirmHint`) with a
+  Russian translation and an English fallback. While `loading` is true, the field becomes read-only
+  (it keeps focus) and the buttons are blocked.
+
+The dialog stays an `alertdialog`: the field is a lock here, not data entry. If
+you need other fields, server-side validation or your own form markup, use
+`Dialog`.
+
+## Public API
+
+`open`, `onClose`, `onConfirm`, `title` and `message` are required. The button
+labels come from the message catalog (`confirmDialog.confirm`,
+`confirmDialog.cancel`): without a provider they are "Confirm" and "Cancel"; with
+the Russian locale they are "Подтвердить" and "Отменить". Props override them one by one.
+`kind` accepts `danger` (the default), `warning` or `info`: this is the semantics
+of the question, not an arbitrary palette. For `info` the confirm button uses
+the accent tone; for the other two it is an outline button in the `danger` tone.
+
+`typeToConfirm` is an optional typed-confirmation string, see the section above.
+
+`loading` blocks both buttons and is passed to the base `Dialog`, so the dialog
+cannot be closed with the close button, Escape or a click outside the dialog until the operation
+finishes.
+
+## Accessibility and keyboard
+
+The component creates an `alertdialog`, not a regular `dialog`, and focuses the
+confirm button through `initialFocusRef`; with `typeToConfirm` the focus goes to
+the input field instead. The hint under the field is tied to it through
+`aria-describedby`, and the question itself remains the dialog's description. Phrase `title` as a question and
+`confirmLabel` as a concrete action ("Delete", not "OK"). Do not call `onClose`
+from `onConfirm` while the async action is still running: manage `loading` on the
+consumer's side instead.
+
+## Good examples
+
+- `kind="danger"`, "Delete", for an irreversible operation.
+- `kind="warning"`, "Unpublish", for a noticeable but reversible change.
+- `kind="info"`, "Publish", for an explicit confirmation of an ordinary action.
+
+## Anti-patterns
+
+- Confirming every save or toggle.
+- Passing the single phrase "Are you sure?" as `message`, without saying what the consequence is.
+- Opening a second confirmation while the first one is `loading`.
+- Putting `typeToConfirm` on every deletion: the lock belongs where a mistake is
+  expensive, otherwise users learn to type without reading.
+- Building typed confirmation on `Dialog` with a hand-written comparison — that
+  is exactly what `typeToConfirm` does.
+
+## Related sources and Storybook
+
+- `src/components/overlays/ConfirmDialog.tsx`
+- `src/components/overlays/ConfirmDialog.stories.tsx`

package/docs/components/overlays/confirm-dialog.md

@@ -0,0 +1,127 @@
+---
+component: ConfirmDialog
+exports: [ConfirmDialog]
+category: overlays
+status: stable
+source: src/components/overlays/ConfirmDialog.tsx
+story: src/components/overlays/ConfirmDialog.stories.tsx
+---
+
+# ConfirmDialog
+
+## Кратко для AI
+
+`ConfirmDialog` подтверждает значимое или необратимое действие. Он уже собран на
+`Dialog` с `role="alertdialog"`, ставит начальный фокус на подтверждающую кнопку
+и не требует вручную строить модальность или порядок фокуса. Для самых опасных
+действий (удалить пространство, проект, аккаунт) умеет подтверждение вводом:
+`typeToConfirm="Acme"` — кнопка выключена, пока пользователь не набрал название.
+
+## Когда использовать
+
+- Удаление, снятие с публикации, немедленная отправка и другие действия, которые
+  пользователь должен подтвердить отдельно.
+- Короткий вопрос в `title`, пояснение в `message` и явные `onConfirm`/`onClose`.
+
+## Когда не использовать
+
+- Для ввода данных в несколько полей, просмотра или нейтральной настройки — `Dialog`.
+- Для некритичной операции, которую можно отменить после выполнения, — действие
+  плюс `toast`, не лишнее подтверждение.
+- Не выбирайте цвет кнопки вручную: смысл задаёт `kind`.
+
+## Минимальный пример
+
+```tsx
+<ConfirmDialog
+  open={deleteOpen}
+  onClose={() => setDeleteOpen(false)}
+  onConfirm={removeUser}
+  title="Удалить пользователя?"
+  message="Действие необратимо."
+  confirmLabel="Удалить"
+/>
+```
+
+## Подтверждение вводом имени
+
+```tsx
+<ConfirmDialog
+  open={deleteOpen}
+  onClose={() => setDeleteOpen(false)}
+  onConfirm={removeWorkspace}
+  title="Удалить пространство?"
+  message="Будут удалены все проекты, файлы и участники."
+  confirmLabel="Удалить пространство"
+  typeToConfirm={workspace.name}
+/>
+```
+
+`typeToConfirm` — строка, которую надо набрать. Когда она задана, в окне
+появляется поле с подписью `Введите «Acme», чтобы подтвердить` и пояснением под
+ним. Фокус при открытии встаёт в поле (а не на кнопку), кнопка подтверждения
+выключена, пока набранное не совпало. Enter в поле подтверждает только при
+совпадении.
+
+- **Регистр важен.** Смысл приёма в том, чтобы пользователь прочёл название и
+  набрал именно его: «acme» вместо «Acme» отличает одно пространство от другого,
+  и пояснение под полем говорит об этом прямо.
+- **Пробелы по краям набранного не считаются**, потому что вставка из буфера
+  часто приносит лишние пробелы по краям; пробелы внутри названия значимы. Сверка идёт в
+  канонической форме Unicode (NFC): «é» одной буквой и «e» с акцентом равны.
+- **Пустая строка — не название.** `typeToConfirm=""` (и строка из одних
+  пробелов) поля не включает: окно подтверждается как обычно, без поля-замка.
+- Набранный текст живёт внутри окна и после закрытия не сохраняется;
+  `onConfirm` вызывается уже после совпадения, проверять совпадение самостоятельно не нужно.
+- Подпись и пояснение — из каталога сообщений
+  (`confirmDialog.typeToConfirm`, `confirmDialog.typeToConfirmHint`) с русским
+  переводом и английским фолбэком. При `loading` поле
+  становится «только для чтения» (фокус остаётся в нём), кнопки блокируются.
+
+Окно остаётся `alertdialog`: поле здесь замок, а не ввод данных. Нужны другие
+поля, проверка на сервере или своя разметка формы — это `Dialog`.
+
+## Public API
+
+Обязательны `open`, `onClose`, `onConfirm`, `title` и `message`. Тексты кнопок
+берутся из каталога сообщений (`confirmDialog.confirm`,
+`confirmDialog.cancel`): без провайдера «Confirm» и «Cancel», с русской локалью —
+«Подтвердить» и «Отменить»; пропы переопределяют точечно. `kind` принимает `danger` (умолчание),
+`warning` или `info`: это семантика вопроса, а не произвольная палитра. Для
+`info` подтверждение акцентное; для двух остальных — контурная кнопка в тоне `danger`.
+
+`typeToConfirm` — необязательная строка подтверждения вводом, см. раздел выше.
+
+`loading` блокирует обе кнопки и передаётся в базовый `Dialog`, поэтому окно
+нельзя закрыть крестиком, Escape или щелчком вне окна до завершения операции.
+
+## Доступность и клавиатура
+
+Компонент создаёт `alertdialog`, а не обычный `dialog`, и фокусирует кнопку
+подтверждения через `initialFocusRef`; с `typeToConfirm` фокус встаёт в поле
+ввода. Пояснение под полем связано с ним через `aria-describedby`, а сам вопрос
+остаётся описанием диалога. Формулируйте `title` как вопрос, а
+`confirmLabel` как конкретное действие («Удалить», не «ОК»). Не вызывайте
+`onClose` из `onConfirm`, пока асинхронное действие ещё не завершено: вместо
+этого управляйте `loading` на стороне потребителя.
+
+## Хорошие примеры
+
+- `kind="danger"`, «Удалить», для безвозвратной операции.
+- `kind="warning"`, «Снять», для заметного, но обратимого изменения.
+- `kind="info"`, «Опубликовать», для явного подтверждения обычного действия.
+
+## Антипаттерны
+
+- Подтверждать каждое сохранение или переключатель.
+- Передавать в `message` единственную фразу «Вы уверены?», не назвав последствия.
+- Открывать второе подтверждение при `loading` первого.
+- Ставить `typeToConfirm` на каждое удаление: замок нужен там, где ошибка стоит
+  дорого, иначе пользователь привыкает набирать, не читая.
+- Собирать подтверждение вводом на `Dialog` с ручной сверкой — это и есть то,
+  что делает `typeToConfirm`.
+
+## Связанные исходники и Storybook
+
+- `src/components/overlays/ConfirmDialog.tsx`
+- `src/components/overlays/ConfirmDialog.stories.tsx`

package/docs/components/overlays/context-menu.en.md

@@ -0,0 +1,115 @@
+---
+component: ContextMenu
+exports:
+  [
+    ContextMenu,
+    ContextMenuCheckboxItem,
+    ContextMenuContent,
+    ContextMenuItem,
+    ContextMenuLabel,
+    ContextMenuRadioGroup,
+    ContextMenuRadioItem,
+    ContextMenuSeparator,
+    ContextMenuSub,
+    ContextMenuSubContent,
+    ContextMenuSubTrigger,
+    ContextMenuTrigger,
+  ]
+category: overlays
+status: stable
+source: src/components/overlays/ContextMenu.tsx
+story: src/components/overlays/ContextMenu.stories.tsx
+sourceHash: 8f5babfd80b2
+---
+
+# ContextMenu
+
+## Summary for AI
+
+`ContextMenu` is an action menu for a right click and the context menu key.
+It uses Radix but looks like `Menu`. For an ordinary click-trigger menu choose
+`Menu`; do not imitate a right click by hand.
+
+## When to use
+
+- Quick actions on a card, a table row, a canvas element or a file.
+- You need a nested submenu or an independent checkbox item.
+- The trigger has a clear target that the actions apply to.
+
+## When not to use
+
+- Use `Menu` or plain `Button` components for the main visible action bar.
+- Use `Select` or `Combobox` to pick a form value.
+- Do not open a context menu without a target element just for the sake of a visual menu.
+
+## Minimal example
+
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger>
+    <Card>File</Card>
+  </ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem onSelect={edit}>Rename</ContextMenuItem>
+    <ContextMenuItem tone="danger" onSelect={remove}>
+      Delete
+    </ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+## Public API
+
+`ContextMenu`, `ContextMenuTrigger` and `ContextMenuSub` re-export Radix `Root`,
+`Trigger` and `Sub`. `ContextMenuContent` creates a portal and accepts `children`/
+`className`. `ContextMenuItem` accepts `children`, `icon`, `shortcut`,
+`tone`, `disabled`, `onSelect`, `className`. `ContextMenuCheckboxItem` adds
+controlled `checked` and `onCheckedChange` right on the item — unlike `Menu`.
+
+`ContextMenuRadioGroup` and `ContextMenuRadioItem` implement single selection: the value
+is set on the group (`value`, `onValueChange`), the item carries only its own
+`value`. The selection lives on the group precisely because "exactly one is
+selected" is a property of the group: an item that does not know its group has no
+way to set `aria-checked="false"` on the other items. An item of this kind has no
+icon of its own: the check mark occupies the slot.
+
+`ContextMenuLabel` and `ContextMenuSeparator` give the menu its structure. For a submenu,
+wrap `ContextMenuSubTrigger` and `ContextMenuSubContent` in `ContextMenuSub`.
+The sub-trigger accepts `children`, `icon`, `className`; the sub-content accepts
+`children` and `className`.
+
+## Accessibility and keyboard
+
+Radix provides the role, focus management, checkbox selection and keyboard
+access to the context menu. Do not replace `ContextMenuCheckboxItem` with a plain
+item with a checkmark you render yourself: you would lose `menuitemcheckbox` and
+`aria-checked`.
+
+The same goes for single selection: a list with one marked item is a
+`ContextMenuRadioGroup`, not a set of plain items with a checkmark on the current
+one and not checkboxes. A checkbox also promises multiple selection, which is not
+available here.
+
+`shortcut` is only displayed; handling the command stays in the app. See [the ContextMenu source](../../../src/components/overlays/ContextMenu.tsx).
+
+## Good examples
+
+- A right click on a card with a `ContextMenuLabel`, actions and a separator.
+- A controlled checkbox "Dense grid" through `checked`/`onCheckedChange`.
+- A nested "Move to…" submenu built with `ContextMenuSub`.
+- Choosing one value from a list — a `ContextMenuRadioGroup` inside a submenu.
+
+## Anti-patterns
+
+- Mixing the `MenuSection` API with `ContextMenuCheckboxItem`.
+- Showing single selection with checkboxes or plain items with a checkmark.
+- Relying on `shortcut` as a real keybinding.
+- Hiding the only way to perform a key operation behind a right click.
+- Wrapping the content of a `VirtualGrid` cell in a `ContextMenu`: Shift+F10 does
+  not open the menu, and a click on an item selects the cell. Cells have the
+  `contextMenu` property ([VirtualGrid](../content/virtual-grid.md)).
+
+## Related sources and Storybook
+
+- `src/components/overlays/ContextMenu.tsx`, `src/lib/menu.ts`
+- `src/components/overlays/ContextMenu.stories.tsx`

package/docs/components/overlays/context-menu.md

@@ -0,0 +1,113 @@
+---
+component: ContextMenu
+exports:
+  [
+    ContextMenu,
+    ContextMenuCheckboxItem,
+    ContextMenuContent,
+    ContextMenuItem,
+    ContextMenuLabel,
+    ContextMenuRadioGroup,
+    ContextMenuRadioItem,
+    ContextMenuSeparator,
+    ContextMenuSub,
+    ContextMenuSubContent,
+    ContextMenuSubTrigger,
+    ContextMenuTrigger,
+  ]
+category: overlays
+status: stable
+source: src/components/overlays/ContextMenu.tsx
+story: src/components/overlays/ContextMenu.stories.tsx
+---
+
+# ContextMenu
+
+## Кратко для AI
+
+`ContextMenu` — меню действий для правого клика и клавиши контекстного меню.
+Оно использует Radix, но выглядит как `Menu`. Для обычного click-trigger меню
+выбирайте `Menu`; не имитируйте правый клик вручную.
+
+## Когда использовать
+
+- Быстрые действия над карточкой, строкой таблицы, canvas-элементом или файлом.
+- Нужно подменю либо независимый пункт-флажок.
+- У trigger есть понятная цель, над которой выполняются действия.
+
+## Когда не использовать
+
+- Для основной видимой панели действий — `Menu` или обычные `Button`.
+- Для выбора формы — `Select`/`Combobox`.
+- Не открывайте контекстное меню без цели действий только ради визуального меню.
+
+## Минимальный пример
+
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger>
+    <Card>Файл</Card>
+  </ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem onSelect={edit}>Переименовать</ContextMenuItem>
+    <ContextMenuItem tone="danger" onSelect={remove}>
+      Удалить
+    </ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+## Public API
+
+`ContextMenu`, `ContextMenuTrigger`, `ContextMenuSub` — реэкспорты Radix
+(`Root`, `Trigger`, `Sub`). `ContextMenuContent` создаёт portal и принимает `children`/
+`className`. `ContextMenuItem` принимает `children`, `icon`, `shortcut`,
+`tone`, `disabled`, `onSelect`, `className`. `ContextMenuCheckboxItem` добавляет
+controlled `checked` и `onCheckedChange` прямо на пункте — в отличие от `Menu`.
+
+`ContextMenuRadioGroup` и `ContextMenuRadioItem` — одиночный выбор: значение
+задано на группе (`value`, `onValueChange`), пункт несёт только свой `value`.
+Выбор живёт на группе именно потому, что «выбран ровно один» — свойство
+группы: пункт, который не знает группу, не может проставить
+`aria-checked="false"` остальным пунктам. Своей иконки у пункта выбора нет — слот занят отметкой.
+
+`ContextMenuLabel` и `ContextMenuSeparator` оформляют структуру. Для подменю
+оберните `ContextMenuSubTrigger` и `ContextMenuSubContent` в `ContextMenuSub`.
+Sub-trigger принимает `children`, `icon`, `className`; sub-content — `children`
+и `className`.
+
+## Доступность и клавиатура
+
+Radix предоставляет role, управление фокусом, выбор флажка и клавиатурный
+доступ к контекстному меню. Не подменяйте `ContextMenuCheckboxItem` обычным
+item с нарисованной галочкой: тогда потеряются `menuitemcheckbox` и
+`aria-checked`.
+
+То же и с одиночным выбором: список с одним отмеченным пунктом — это
+`ContextMenuRadioGroup`, а не набор обычных пунктов с галочкой у текущего и не
+флажки. Флажок вдобавок обещает множественный выбор, которого нет.
+
+`shortcut` только отображается; обработка команды остаётся в
+приложении. См. [исходник ContextMenu](../../../src/components/overlays/ContextMenu.tsx).
+
+## Хорошие примеры
+
+- Правый клик на карточке с `ContextMenuLabel`, действиями и separator.
+- Управляемый флажок «Плотная сетка» через `checked`/`onCheckedChange`.
+- Вложенное «Переместить в…» через `ContextMenuSub`.
+- Выбор одного значения из списка — `ContextMenuRadioGroup` внутри подменю.
+
+## Антипаттерны
+
+- Смешивать `MenuSection` API с `ContextMenuCheckboxItem`.
+- Показывать одиночный выбор флажками или обычными пунктами с галочкой.
+- Полагаться на `shortcut` как на настоящий keybinding.
+- Прятать единственный способ выполнить ключевую операцию в правом клике.
+- Оборачивать в `ContextMenu` содержимое ячейки `VirtualGrid`: Shift+F10 меню не
+  откроет, а клик по пункту выберет ячейку. Для ячеек есть поле `contextMenu`
+  ([VirtualGrid](../content/virtual-grid.md)).
+
+## Связанные исходники и Storybook
+
+- `src/components/overlays/ContextMenu.tsx`, `src/lib/menu.ts`
+- `src/components/overlays/ContextMenu.stories.tsx`