@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/overlays/hover-card.md

@@ -0,0 +1,175 @@
+---
+component: HoverCard
+exports: [HoverCard, HoverCardContent, HoverCardTrigger]
+category: overlays
+status: stable
+source: src/components/overlays/HoverCard.tsx
+story: src/components/overlays/HoverCard.stories.tsx
+---
+
+# HoverCard
+
+## Кратко для AI
+
+`HoverCard` — карточка-превью: при наведении на имя или ссылку, а также при
+фокусе на них с клавиатуры рядом всплывает панель с подробностями. Фокус от
+скринридера карточку **не** открывает (намеренно, см. «Доступность и клавиатура»). Триггер —
+ссылка или кнопка **со своим действием**; карточка его дополняет и ничего не
+заменяет. Содержимое — только дополнительное: всё, что в нём есть, должно быть
+доступно и без неё. Не кладите в карточку формы и обязательные действия.
+Собрана на китовом `Popover`, новой зависимости нет.
+
+## Когда использовать
+
+- Имя пользователя, ссылка на документ, тег, сущность в тексте: по наведению
+  нужно показать аватар, должность, первые строки — не уводя человека со
+  страницы.
+- Подробности вторичны: пользователь, не увидевший карточку, ничего не теряет
+  (ссылка ведёт на ту же информацию целиком).
+- **Экрана-заказчика при выпуске не было** (ADR-0048):
+  API взят по аналогам — `HoverCard` у Radix и shadcn/ui, hover-card у Chakra и
+  Mantine. Первый экран потребителя — первая проверка контракта; расхождение
+  между контрактом и экраном — повод менять API.
+
+## Когда не использовать
+
+- Короткая подпись или расшифровка термина — `Tooltip`: это одна строка текста,
+  без разметки, и открывается быстрее.
+- Поясняющий абзац, который надо успеть прочитать, лучше отдать `HelpTooltip`: это
+  поповер **по клику** на кнопку-вопросик, он не исчезает, когда курсор ушёл.
+- Содержимое с полями, кнопками действий, ссылками, до которых нужно добраться,
+  лучше отдать `Popover` (открывается по клику, забирает фокус, возвращает его)
+  или `Dialog`. Карточка закрывается, когда курсор или фокус уходят, и до неё не
+  доберёшься клавишей Tab.
+- Единственный способ узнать что-то важное. На телефоне она, как правило, не открывается.
+
+## Минимальный пример
+
+```tsx
+import { Avatar, HoverCard, HoverCardContent, HoverCardTrigger } from "@olddevs/ui";
+
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <a href="/people/ada">Ada Lovelace</a>
+  </HoverCardTrigger>
+  <HoverCardContent>
+    <div className="flex w-[280px] gap-3 p-3">
+      <Avatar name="Ada Lovelace" />
+      <p>Mathematician. Wrote the first published algorithm for a machine.</p>
+    </div>
+  </HoverCardContent>
+</HoverCard>;
+```
+
+## Public API
+
+**`HoverCard`** — корень, ничего не рисует.
+
+| Проп           | Значение по умолчанию | Смысл                                                                                       |
+| -------------- | --------------------- | ------------------------------------------------------------------------------------------- |
+| `openDelay`    | `700`                 | Мс, которые наведение или фокус должны продержаться, чтобы карточка открылась               |
+| `closeDelay`   | `300`                 | Мс после того, как курсор ушёл **и** с триггера, **и** с карточки                           |
+| `open`         | —                     | Управляемое состояние; задержки по-прежнему считает компонент и просит через `onOpenChange` |
+| `defaultOpen`  | `false`               | Начальное состояние без управления                                                          |
+| `onOpenChange` | —                     | Вызывается по таймеру, по Escape, по клику или фокусу вне карточки                          |
+
+**`HoverCardTrigger`** — слушает наведение и фокус. `asChild` включён по
+умолчанию: вид отдаётся единственному потомку — ссылке или кнопке. Собственные
+обработчики потомка сохраняются; по клику триггер **ничего не переключает**.
+Состояние для стилей — атрибут `data-state="open" | "closed"`. Почему на
+триггере нет `aria-haspopup` и `aria-expanded`, см. «Доступность и клавиатура».
+
+**`HoverCardContent`** — панель. Принимает пропы `PopoverContent` (`side`,
+`align`, `sideOffset`, `className`): вид, слой и анимации общие с ним. Ширину и
+отступы задаёт содержимое, как у поповера.
+
+Что отличает карточку от поповера:
+
+- **Открытие.** По `pointerenter` с задержкой `openDelay`. По фокусу — только
+  фокус, пришедший от навигационной клавиши (Tab, Shift+Tab, Option+Tab в Safari
+  на macOS, стрелки, Home, End, PageUp, PageDown): щелчок по ссылке ставит на неё
+  фокус, и открывать карточку, когда действие уже совершено, незачем. Фокус без
+  клавиши и без указателя
+  (свайп скринридера, программный `focus()`) карточку не открывает. Быстрый
+  пролёт курсора её не открывает.
+- **Закрытие.** Когда курсор ушёл и с триггера, и с карточки, через `closeDelay`.
+  Переход курсора с триггера на карточку её не закрывает; возврат на триггер до
+  конца задержки — тоже. Щелчок (в том числе по самому триггеру) и фокус на другом
+  элементе, а также Escape закрывают сразу; фокус на самом триггере карточку не
+  закрывает.
+- **Фокус.** При открытии остаётся на месте — в содержимое не уходит. При
+  закрытии не возвращается на триггер: закрытие от указателя не должно
+  перетаскивать фокус. Ловушки фокуса нет.
+- **Устройства без наведения.** При `(hover: none)` и для касаний карточка не
+  открывается по наведению; касание выполняет действие триггера (переход по
+  ссылке) и карточку не открывает. **Клавиатурный фокус открывает её и там:**
+  у планшета бывает аппаратная клавиатура, и Tab на триггере работает так же,
+  как на компьютере. Клавишу от касания отличает модальность ввода: клавиша
+  открывает, тап и щелчок мыши — нет. Управляемый `open` этим не блокируется.
+- **Роль.** У панели нет `role="dialog"`: диалог без перехода фокуса — обещание,
+  которого она не держит. Нужна роль или имя — передайте `role`, `aria-label`.
+
+## Доступность и клавиатура
+
+- Tab на триггер открывает карточку после `openDelay`; Tab дальше или Escape
+  закрывают. Клавиатурной считается навигационная клавиша: Tab, Shift+Tab,
+  стрелки, Home, End, PageUp, PageDown — и **Option+Tab**: в Safari на macOS это
+  единственный способ дойти клавишей до ссылок, пока в настройках не включён
+  обход всех элементов. Другие сочетания с Option, Ctrl и Cmd навигацией не
+  считаются (Ctrl+Tab переключает вкладки браузера, Cmd+Tab — приложения). Escape
+  слушает Radix, как у `Popover` и `Tooltip`; новых обработчиков Escape и своих
+  `z-index` у компонента нет — панель стоит на ступени
+  `OVERLAY_LAYER.popover` (ADR-0041),
+  выше окон, поэтому из `Dialog` она открывается видимой. Если карточка открыта
+  из окна, первое нажатие Escape закрывает её, второе — окно.
+- **Фокус от скринридера карточку не открывает — намеренно.** Свайп VoiceOver
+  и TalkBack, а на десктопе виртуальный курсор NVDA и JAWS (режим обзора) ставят
+  фокус, не присылая странице ни клавиши, ни указателя; `:focus-visible` в этом
+  случае истинен, поэтому кит различает источник фокуса сам (внутренний трекер
+  модальности ввода, без зависимостей). Карточка, всплывшая без объявления,
+  сбивает пользователя скринридера, а при экранной лупе закрывает соседний текст.
+  Содержимое по контракту дополнительное и доступно иначе — на странице, куда
+  ведёт триггер.
+- **Аппаратная клавиатура.** Tab и стрелки с неё открывают карточку и под
+  скринридером: это настоящая клавиша. Фокус, который браузер возвращает на
+  триггер, когда вкладка снова становится активной, и фокус, который код
+  страницы ставит сам (например, после закрытия окна), карточку не открывают.
+- **Ограничение: адресная строка.** Если первый Tab пришёл из адресной строки
+  или панели браузера, страница клавиши не видела — такой фокус неотличим от
+  фокуса скринридера, и карточка не откроется; следующий Tab или наведение
+  откроют её.
+- Триггер не должен быть единственным путём к содержимому для скринридера:
+  карточка дополняет, а не заменяет. Всё важное из неё должно быть и на
+  странице, на которую ведёт триггер.
+- **Триггер построен на `PopoverAnchor`, а не на `PopoverTrigger`.** Якорь только
+  задаёт, к чему крепится панель: ни переключения по клику, ни ARIA-атрибутов
+  поповера он не несёт, а открывает и закрывает карточку сам `HoverCard`
+  (Radix-поповер под ним управляемый). Поэтому на триггере нет `aria-haspopup` и
+  `aria-expanded`, и клик карточку не переключает: скринридер слышит обычную
+  ссылку или кнопку со своим действием, а не кнопку-поповер, обещающую панель по
+  нажатию.
+- Движение — по шкале движения (ADR-0047):
+  вход `popoverIn`, при `prefers-reduced-motion: reduce` остаётся одно
+  появление без смещения.
+
+## Хорошие примеры
+
+- Имя автора в списке комментариев → аватар, должность, число материалов.
+- Ссылка на документ в тексте → заголовок, автор, первые строки.
+- `openDelay={0}` для плотных таблиц, где человек и так ведёт курсор целенаправленно.
+
+## Антипаттерны
+
+- Триггер без своего действия (`span`, `div`, кнопка-пустышка): карточка — для
+  ссылок и кнопок, у которых есть куда нажать.
+- Форма, кнопка «Сохранить» или единственная ссылка на важное внутри
+  `HoverCardContent`.
+- Подпись в одну строку — для неё `Tooltip`.
+- Свой `z-index` или свой обработчик Escape на панели.
+- `@radix-ui/react-hover-card` рядом с китом: компонент собран на `Popover`.
+
+## Связанные исходники и Storybook
+
+- `src/components/overlays/HoverCard.tsx`
+- `src/components/overlays/HoverCard.stories.tsx`
+- `tests/hover-card.test.tsx`

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

@@ -0,0 +1,103 @@
+---
+component: Menu
+exports: [Menu, MenuButton, MenuItem, MenuSection, MenuSeparator, MenuTrigger, SubmenuTrigger]
+category: overlays
+status: stable
+source: src/components/overlays/Menu.tsx
+story: src/components/overlays/Menu.stories.tsx
+sourceHash: cedb4db63593
+---
+
+# Menu
+
+## Summary for AI
+
+`Menu` is a compound action menu opened by `MenuTrigger`. Inside `MenuTrigger`,
+use the dedicated `MenuButton`, not a regular `Button`: only it reads react-aria's
+`ButtonContext`. The menu suits heterogeneous commands, sections, selected modes
+and submenus; it is not for choosing a field value.
+
+## When to use
+
+- Contextual actions for an entity, an overflow button, a sort or view menu.
+- You need sections, a separator, a shortcut, a disabled/danger item or a submenu.
+- Several selected modes belong to one `MenuSection`.
+
+## When not to use
+
+- Use `Select` to choose a value in a form, and `Combobox` for user input with
+  a list of options.
+- Use `ContextMenu` for a right-click menu.
+- Do not use `Button` instead of `MenuButton`: the menu does not get the open/focus props.
+
+## Minimal example
+
+```tsx
+<MenuTrigger>
+  <MenuButton iconOnly aria-label="Actions" icon={<MoreIcon />} />
+  <Menu>
+    <MenuItem onAction={rename}>Rename</MenuItem>
+    <MenuSeparator />
+    <MenuItem tone="danger" onAction={remove}>
+      Delete
+    </MenuItem>
+  </Menu>
+</MenuTrigger>
+```
+
+## Public API
+
+`MenuTrigger` and `SubmenuTrigger` re-export react-aria. `MenuButton` accepts
+the props that set the button's look, `icon`, `children`, `disabled`, `aria-label`
+and `className`; `aria-label` is required if the button has no text, and with
+`iconOnly` it never does. `Menu` accepts the usual `AriaMenuProps`, plus `offset`,
+the gap between the panel and the button in pixels (default 6), and `placement`,
+the side where the panel opens (default `bottom start`; also `bottom end`,
+`top start`, `top end`, `right top` and `left top`).
+
+`MenuItem` accepts the `AriaMenuItem` props, `icon`, `shortcut`, `tone`,
+`disabled` and `className`; pass the action in `onAction`. `MenuSection` accepts
+`label` and the react-aria selection props. For toggles, set `selectionMode`,
+`selectedKeys` and `onSelectionChange` on the section, not `checked` on the item.
+`MenuSeparator` separates groups.
+
+react-aria sets the menu panel's height from the visible area. Items that do
+not fit scroll inside the panel (`overflow-y: auto`, the scroll does not leak to
+the page) instead of being rendered past its edge over the content. On iOS the panel
+overrides the height that react-aria computed with its own — 24rem or 60% of the
+dynamic screen height, whichever is smaller: in Safari on iOS 27 react-aria gave
+the panel a height of about zero. The same applies to `ContextMenu`: they share
+the look of the panel.
+
+On a touch screen without hover (`hover: none` and `pointer: coarse`) items do not
+show `shortcut`: there is no keyboard there. The shortcut cannot be turned off
+with a prop and does not need to be — on desktop and with a trackpad it is visible as
+before.
+
+## Accessibility and keyboard
+
+react-aria provides the menu roles, focus management and keyboard navigation.
+`Menu` is already wrapped in a `Popover`. A section item with `selectionMode` gets the correct
+role and `aria-checked` from the library. Inside a `Dialog` or a `Drawer`, the
+first Escape closes the menu and the next one closes the dialog; an item can be
+chosen with both mouse and keyboard, and a click on an item does not close the
+dialog. This cross-library contract is checked in Storybook and a browser test;
+a rule in `@olddevs/ui/styles.css` restores the panel's pointer events inside
+Radix's modal layer. See [the Menu source](../../../src/components/overlays/Menu.tsx).
+
+## Good examples
+
+- A "View" section with `selectionMode="multiple"`.
+- `SubmenuTrigger` with a `MenuItem` as the first child and a nested `Menu` as the second.
+- `shortcut` as a visual reminder, while handling the shortcut stays the app's job.
+
+## Anti-patterns
+
+- Managing the selected state on `MenuItem` by hand.
+- Using a menu as navigation between pages or tabs.
+- Putting interactive forms inside an ordinary menu item.
+
+## Related sources and Storybook
+
+- `src/components/overlays/Menu.tsx`, `src/lib/menu.ts`
+- `src/components/overlays/Menu.stories.tsx`

package/docs/components/overlays/menu.md

@@ -0,0 +1,100 @@
+---
+component: Menu
+exports: [Menu, MenuButton, MenuItem, MenuSection, MenuSeparator, MenuTrigger, SubmenuTrigger]
+category: overlays
+status: stable
+source: src/components/overlays/Menu.tsx
+story: src/components/overlays/Menu.stories.tsx
+---
+
+# Menu
+
+## Кратко для AI
+
+`Menu` — составное меню действий, открываемое `MenuTrigger`. Внутри `MenuTrigger`
+используйте специальный `MenuButton`, а не обычный `Button`: только он читает
+`ButtonContext` react-aria. Меню подходит для разнородных команд, разделов, выбранных режимов и
+подменю; не для выбора значения поля.
+
+## Когда использовать
+
+- Контекстные действия у сущности, overflow-кнопка, меню сортировки или вида.
+- Нужны разделы, separator, shortcut, disabled/опасный пункт или подменю.
+- Несколько выбранных режимов принадлежат одному `MenuSection`.
+
+## Когда не использовать
+
+- Для выбора значения в форме — `Select`, для пользовательского ввода со
+  списком вариантов — `Combobox`.
+- Для меню правой кнопкой — `ContextMenu`.
+- Не используйте `Button` вместо `MenuButton`: меню не получит open/focus props.
+
+## Минимальный пример
+
+```tsx
+<MenuTrigger>
+  <MenuButton iconOnly aria-label="Действия" icon={<MoreIcon />} />
+  <Menu>
+    <MenuItem onAction={rename}>Переименовать</MenuItem>
+    <MenuSeparator />
+    <MenuItem tone="danger" onAction={remove}>
+      Удалить
+    </MenuItem>
+  </Menu>
+</MenuTrigger>
+```
+
+## Public API
+
+`MenuTrigger` и `SubmenuTrigger` — реэкспорты react-aria. `MenuButton` принимает
+button look props, `icon`, `children`, `disabled`, `aria-label` и `className`;
+`aria-label` обязателен, если у кнопки нет подписи; с `iconOnly` её нет всегда.
+`Menu` принимает обычные `AriaMenuProps`, плюс `offset` — отступ панели от кнопки
+в пикселях (умолчание 6) и `placement` — сторона раскрытия (умолчание
+`bottom start`; ещё `bottom end`, `top start`, `top end`, `right top`,
+`left top`).
+
+`MenuItem` принимает props `AriaMenuItem`, `icon`, `shortcut`, `tone`, `disabled`
+и `className`; действие передавайте в `onAction`. `MenuSection` принимает
+`label` и props react-aria selection. Для переключателей задавайте
+`selectionMode`, `selectedKeys` и `onSelectionChange` на section, а не `checked`
+на item. `MenuSeparator` разделяет группы.
+
+Высоту панели меню задаёт react-aria по видимой области. Пункты, которые в неё
+не влезли, прокручиваются внутри панели (`overflow-y: auto`, прокрутка не
+уходит на страницу), а не рисуются за её краем поверх содержимого. На iOS
+высоту, посчитанную react-aria, панель перебивает своей — 24rem или 60%
+динамической высоты экрана, что меньше: в Safari на iOS 27 react-aria давал
+панели высоту около нуля. То же у `ContextMenu`: вид панели у них общий.
+
+На сенсорном экране без наведения (`hover: none` и `pointer: coarse`) пункты не
+показывают `shortcut`: клавиатуры там нет. Сочетание нельзя
+отключить пропом, и это не нужно — на десктопе и с трекпадом оно видно как раньше.
+
+## Доступность и клавиатура
+
+react-aria задаёт роли меню, управляет фокусом и клавиатурной навигацией. `Menu`
+уже оборачивается в `Popover`. Пункт раздела с `selectionMode` получает корректную роль
+и `aria-checked` от библиотеки. Внутри `Dialog` и `Drawer` первый Escape
+закрывает menu, а следующий — окно; пункт выбирается и мышью, и с клавиатуры, а
+окно от щелчка по пункту не закрывается. Этот межбиблиотечный контракт
+проверяется в Storybook и browser test; правило в `@olddevs/ui/styles.css`
+возвращает указатель панели внутри модального слоя Radix. См. [исходник Menu](../../../src/components/overlays/Menu.tsx).
+
+## Хорошие примеры
+
+- Раздел «Вид» с `selectionMode="multiple"`.
+- `SubmenuTrigger` с `MenuItem` первым и вложенным `Menu` вторым ребёнком.
+- `shortcut` как визуальное напоминание, при этом обработка сочетания остаётся
+  задачей приложения.
+
+## Антипаттерны
+
+- Управлять selected state на `MenuItem` вручную.
+- Использовать menu как навигацию между страницами или вкладками.
+- Помещать интерактивные формы внутрь обычного menu item.
+
+## Связанные исходники и Storybook
+
+- `src/components/overlays/Menu.tsx`, `src/lib/menu.ts`
+- `src/components/overlays/Menu.stories.tsx`

package/docs/components/overlays/popover.en.md

@@ -0,0 +1,78 @@
+---
+component: Popover
+exports: [Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger]
+category: overlays
+status: stable
+source: src/components/overlays/Popover.tsx
+story: src/components/overlays/Popover.stories.tsx
+sourceHash: 15a34733d106
+---
+
+# Popover
+
+## Summary for AI
+
+`Popover` is a compound primitive for a panel attached to an element. It does not
+know its content: the calling code sets the trigger, the content and, if needed,
+the anchor. Use it as the basis for a dropdown, a calendar or a compact panel,
+not as a standalone dialog.
+
+## When to use
+
+- The content must be positioned relative to a button or a separate anchor.
+- You need a portal, closing on Escape and correct positioning near the screen edge.
+- The content is arbitrary markup for which there is no ready `Select` or `Menu`.
+
+## When not to use
+
+- For a semantic list of actions, use `Menu`.
+- Use `Tooltip` for text on hover/focus, `HoverCard` for a preview with markup on
+  hover over a link or a name, and `Dialog` for a blocking dialog.
+- Do not use it for content that must always be present in the page's DOM as part
+  of the layout.
+
+## Minimal example
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button>Filters</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <FilterForm />
+  </PopoverContent>
+</Popover>
+```
+
+## Public API
+
+`Popover` is the Radix `Root` and accepts its controlled and uncontrolled props.
+`PopoverTrigger`, `PopoverAnchor` and `PopoverClose` are the matching Radix
+primitives; the trigger usually gets `asChild` to keep the `Button` semantics.
+Always render the content through `PopoverContent`, not the bare Radix `Content`:
+`PopoverContent` creates a portal, has `align="start"` and `sideOffset={4}` by default, and
+accepts the rest of the Radix props (`side`, `align`, `onOpenAutoFocus`, etc.).
+
+## Accessibility and keyboard
+
+Focus behavior, Escape and positioning are delegated to Radix. The content sits in
+a portal on a layer above modal dialogs, so do not add local `z-index` patches
+without a reason. The trigger must be an accessible interactive element; do
+not turn an arbitrary `div` into a trigger without a role, focus and a name.
+
+## Good examples
+
+- A filter button + a form in `PopoverContent`.
+- A separate `PopoverAnchor` when the panel is anchored to something other than the trigger.
+- `side="bottom" align="end"` for a panel at the right edge of the button.
+
+## Anti-patterns
+
+- `<PopoverContent>` without a `Popover`/trigger as a permanent layer.
+- Duplicating `Portal` or wrapping a `Popover` in `ModalOverlay`.
+- A list of commands with implicit navigation instead of `Menu`.
+
+## Related sources and Storybook
+
+- `src/components/overlays/Popover.tsx`
+- `src/components/overlays/Popover.stories.tsx`

package/docs/components/overlays/popover.md

@@ -0,0 +1,77 @@
+---
+component: Popover
+exports: [Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger]
+category: overlays
+status: stable
+source: src/components/overlays/Popover.tsx
+story: src/components/overlays/Popover.stories.tsx
+---
+
+# Popover
+
+## Кратко для AI
+
+`Popover` — составной примитив для панели, привязанной к элементу. Он не знает
+содержимого: вызывающий код задаёт trigger, контент и при необходимости anchor.
+Используйте его как основание dropdown, календаря или компактной панели, а не
+как самостоятельный диалог.
+
+## Когда использовать
+
+- Контент должен позиционироваться относительно кнопки или отдельного якоря.
+- Нужны portal, закрытие по Escape и корректное позиционирование у края экрана.
+- Внутри есть произвольная разметка, для которой нет готового `Select` или `Menu`.
+
+## Когда не использовать
+
+- Для семантического списка действий используйте `Menu`.
+- Для текста при hover/focus — `Tooltip`; для превью с разметкой по наведению
+  на ссылку или имя — `HoverCard`; для блокирующего окна — `Dialog`.
+- Не используйте для контента, который обязан постоянно присутствовать в DOM
+  страницы как часть layout.
+
+## Минимальный пример
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button>Фильтры</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <FilterForm />
+  </PopoverContent>
+</Popover>
+```
+
+## Public API
+
+`Popover` — Radix `Root`, принимает его controlled- и uncontrolled-пропсы.
+`PopoverTrigger`, `PopoverAnchor` и `PopoverClose` — одноимённые примитивы Radix;
+обычно trigger получает `asChild`, чтобы сохранить семантику `Button`. Контент
+обязательно рендерьте через `PopoverContent`, а не голый Radix `Content`:
+`PopoverContent` создаёт portal, имеет `align="start"` и `sideOffset={4}` по умолчанию, а также
+принимает остальные props Radix (`side`, `align`, `onOpenAutoFocus` и др.).
+
+## Доступность и клавиатура
+
+Поведение фокуса, Escape и позиционирование делегированы Radix. Контент находится
+в portal на слое выше модальных окон, поэтому не добавляйте локальные `z-index`
+патчи без причины. Trigger должен быть доступным интерактивным элементом;
+не превращайте произвольный `div` в trigger без роли, фокуса и имени.
+
+## Хорошие примеры
+
+- Кнопка фильтра + форма в `PopoverContent`.
+- Отдельный `PopoverAnchor`, когда панель крепится не к trigger.
+- `side="bottom" align="end"` для панели у правого края кнопки.
+
+## Антипаттерны
+
+- `<PopoverContent>` без `Popover`/триггера как постоянный слой.
+- Дублировать `Portal` или оборачивать `Popover` в `ModalOverlay`.
+- Список команд с неявной навигацией вместо `Menu`.
+
+## Связанные исходники и Storybook
+
+- `src/components/overlays/Popover.tsx`
+- `src/components/overlays/Popover.stories.tsx`