@olddevs/ui 0.0.0-stage → 4.0.0

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

@@ -0,0 +1,120 @@
+---
+component: Dialog
+exports: [Dialog, ModalHeader, ModalOverlay]
+category: overlays
+status: stable
+source: src/components/overlays/Dialog.tsx
+story: src/components/overlays/Dialog.stories.tsx
+sourceHash: e0f979c39f29
+---
+
+# Dialog, ModalHeader and ModalOverlay
+
+## Summary for AI
+
+Use `Dialog` for a modal dialog with a known title: it provides modality, an
+accessible name, a focus trap, a portal and focus return. `ModalHeader` is only a
+ready-made header. `ModalOverlay` is only a dimmed scrim; it does not make its
+content a dialog and must not replace `Dialog` for forms or confirmations.
+
+## When to use
+
+- `Dialog` — a form, a view or another blocking dialog with `open` and `onClose`.
+- `ModalHeader` — a header for a non-standard overlay that already sets the role,
+  the name and focus management on its own.
+- `ModalOverlay` — a scrim for content that is not announced as a dialog and
+  handles its own accessibility; pass `onClose` and, if needed, `escape={false}`.
+
+## When not to use
+
+- For a question that needs an explicit decision, use `ConfirmDialog`, not a
+  `Dialog` with two hand-built buttons.
+- For a sliding panel, use `Drawer`.
+- Use `Popover` for a small panel anchored to a trigger and `Tooltip` for an explanation.
+- Do not wrap `Dialog` in `ModalOverlay` and do not add `useScrollLock`: Radix
+  already manages modality and scrolling.
+
+## Minimal example
+
+```tsx
+<Dialog
+  open={open}
+  onClose={() => setOpen(false)}
+  title="New collection"
+  className="w-full max-w-[420px]"
+>
+  <form>{/* fields and actions */}</form>
+</Dialog>
+```
+
+## Public API
+
+`Dialog` requires `open`, `onClose` and `title`. `title` can be a `ReactNode` and
+becomes the accessible name. `subtitle`, `icon`, `closeLabel` (the accessible name of the close button, "Close" by default), `className`, `overlayClassName`,
+`overlayStyle`, `contentStyle`, `zIndex` and `align` tune the presentation.
+`header={false}` leaves a hidden `Dialog.Title`, so `title` is still required.
+`role` accepts `dialog` (the default) or `alertdialog`.
+
+`describedBy` is the `id` of the node that serves as the dialog's description:
+the text a screen reader reads after the name. It is not `subtitle` — that one is
+visible on screen and lives in the header. For `role="alertdialog"` the ARIA
+Authoring Practices Guide (APG) requires a description: a confirmation that announces only a name and
+a button forces people to confirm blind. `ConfirmDialog` points to its own
+`message`.
+
+**An identifier, not text: a lesson from a defect analysis.** Before 3.7.0
+the prop was called `description`, accepted a `ReactNode` and rendered it as a
+hidden copy, so the text ended up in the document twice: a link inside it created
+an invisible extra tab stop, and a component with its own `id` created a duplicate
+ID. The description must point to the same node that is displayed on screen. If
+the text is only for screen readers, put it in `children` under `sr-only` and
+refer to it here.
+
+`loading` is one shared submitting state: the close button disappears, and Escape
+and a click outside the dialog do not close it. `initialFocusRef` sets the initial focus;
+use it, for example, for a safe form field, instead of calling `focus()` from an
+effect in your own code. `onEscapeKeyDown` is an additional handler for the dialog's
+internal state; it does not replace `onClose`.
+
+`ModalHeader` accepts `title`, optional `subtitle`, `icon`, `onClose`,
+`closeLabel`, `titleId`, `titleComponent` and `className`. The close button
+is rendered only when `onClose` is passed. `ModalOverlay` accepts `onClose`, `zIndex`, `align`,
+`backdrop`, `blur`, `escape`, `className` and `children`; it closes on a click on
+the scrim and, by default, on Escape.
+
+## Accessibility and keyboard
+
+`Dialog` is based on Radix: focus stays in the modal layer, returns to the
+element that opened it on close, and nested Radix dialogs close one at a time, one per press of
+Escape. While a react-aria menu or list is open, the first Escape press is handled
+by that menu or list and does not close the parent dialog. Such a menu or list inside the dialog
+also works with the mouse: Radix turns off pointer events on `<body>`, and the kit
+returns them to the react-aria overlay with a rule in `@olddevs/ui/styles.css`
+— before that an item could be chosen only with the keyboard. `ModalHeader`
+takes the accessible name of the close button from `closeLabel` (by default
+"Close").
+
+`ModalOverlay` does not provide `role="dialog"`, `aria-modal`, a focus trap or a
+scroll lock. If it is still used for an interactive dialog, the consumer must
+add these properties itself. See [the Dialog source](../../../src/components/overlays/Dialog.tsx),
+[ModalHeader](../../../src/components/overlays/ModalHeader.tsx) and
+[ModalOverlay](../../../src/components/overlays/ModalOverlay.tsx).
+
+## Good examples
+
+- A form dialog: `Dialog` with a `title`, a `FormField` and a footer in `children`.
+- Non-standard geometry: `Dialog header={false}` with its own content, but not
+  with a custom role.
+- A plain preview scrim: `ModalOverlay`, if the preview is not announced to
+  the user as a modal dialog.
+
+## Anti-patterns
+
+- `role="dialog"` on `ModalOverlay` without a name and a focus trap.
+- Three separate flags to disable the close button, Escape and click-away instead of `loading`.
+- Putting block markup such as a footer in `title`, or leaving the dialog without a meaningful name.
+
+## Related sources and Storybook
+
+- `src/components/overlays/Dialog.tsx`, `src/components/overlays/ModalHeader.tsx`, `src/components/overlays/ModalOverlay.tsx`
+- `src/components/overlays/Dialog.stories.tsx`

package/docs/components/overlays/dialog.md

@@ -0,0 +1,117 @@
+---
+component: Dialog
+exports: [Dialog, ModalHeader, ModalOverlay]
+category: overlays
+status: stable
+source: src/components/overlays/Dialog.tsx
+story: src/components/overlays/Dialog.stories.tsx
+---
+
+# Dialog, ModalHeader и ModalOverlay
+
+## Кратко для AI
+
+Используйте `Dialog` для модального окна с известным заголовком: он создаёт
+модальность, доступное имя, ловушку фокуса, портал и возврат фокуса. `ModalHeader`
+— только готовая шапка. `ModalOverlay` — только затемнённая подложка; он не делает
+содержимое диалогом и не должен быть заменой `Dialog` для форм или подтверждений.
+
+## Когда использовать
+
+- `Dialog` — форма, просмотр или другое блокирующее окно с `open` и `onClose`.
+- `ModalHeader` — шапка для нестандартного оверлея, который уже самостоятельно
+  задаёт роль, имя и управление фокусом.
+- `ModalOverlay` — подложка для содержимого, которое не объявляется диалогом и
+  само отвечает за доступность; передавайте `onClose` и при необходимости
+  `escape={false}`.
+
+## Когда не использовать
+
+- Для вопроса, требующего явного решения, используйте `ConfirmDialog`, а не
+  `Dialog` с двумя вручную собранными кнопками.
+- Для выезжающей панели используйте `Drawer`.
+- Для привязанной к триггеру небольшой панели — `Popover`; для пояснения — `Tooltip`.
+- Не оборачивайте `Dialog` в `ModalOverlay` и не добавляйте `useScrollLock`: Radix
+  уже управляет модальностью и прокруткой.
+
+## Минимальный пример
+
+```tsx
+<Dialog
+  open={open}
+  onClose={() => setOpen(false)}
+  title="Новая коллекция"
+  className="w-full max-w-[420px]"
+>
+  <form>{/* поля и действия */}</form>
+</Dialog>
+```
+
+## Public API
+
+`Dialog` требует `open`, `onClose` и `title`. `title` может быть `ReactNode` и
+становится доступным именем. `subtitle`, `icon`, `closeLabel` (доступное имя крестика, умолчание «Закрыть»), `className`, `overlayClassName`,
+`overlayStyle`, `contentStyle`, `zIndex` и `align` настраивают представление.
+`header={false}` оставляет скрытый `Dialog.Title`, поэтому `title` всё равно
+обязателен. `role` принимает `dialog` (умолчание) или `alertdialog`.
+
+`describedBy` — `id` узла, который служит окну описанием: текстом, который
+скринридер читает следом за именем. Это не `subtitle` — тот виден глазами и
+живёт в шапке. Для `role="alertdialog"` описание обязательно по ARIA Authoring Practices Guide (APG):
+подтверждение, объявившее только имя и кнопку, вынуждает подтверждать вслепую.
+`ConfirmDialog` ссылается на свой `message` сам.
+
+**Идентификатор, а не текст: так вышло после разбора дефекта.** До 3.7.0 проп
+назывался `description`, принимал `ReactNode` и рисовал его скрытой копией,
+поэтому текст оказывался в документе дважды: ссылка внутри него давала невидимый
+лишний табстоп, а компонент со своим `id` — дубль идентификатора. Описание
+обязано указывать на тот же узел, который видит глаз. Если текст нужен только
+для озвучки, положите его в `children` под `sr-only` и сошлитесь сюда.
+
+`loading` — единое состояние отправки: крестик исчезает, а Escape и клик вне
+окна его не закрывают. `initialFocusRef` задаёт начальный фокус; используйте его,
+например, для безопасного поля формы, не вызывая `focus()` эффектом снаружи.
+`onEscapeKeyDown` — дополнительная реакция для внутреннего состояния окна; она не
+заменяет `onClose`.
+
+`ModalHeader` принимает `title`, опциональные `subtitle`, `icon`, `onClose`,
+`closeLabel`, `titleId`, `titleComponent` и `className`. Кнопка закрытия существует
+только при `onClose`. `ModalOverlay` принимает `onClose`, `zIndex`, `align`,
+`backdrop`, `blur`, `escape`, `className` и `children`; он закрывается по клику на
+подложку и, по умолчанию, по Escape.
+
+## Доступность и клавиатура
+
+`Dialog` основан на Radix: фокус остаётся в модальном слое, при закрытии
+возвращается открывшему элементу, а вложенные окна Radix закрываются по одному
+на каждое нажатие Escape. При открытом меню или списке react-aria первое нажатие
+Escape обрабатывает это меню или список, а не родительское окно. Мышью такое меню
+или список внутри окна тоже работает: Radix отключает указатель у `<body>`, и кит возвращает его
+оверлею react-aria правилом в `@olddevs/ui/styles.css` — раньше пункт
+выбирался только с клавиатуры. `ModalHeader` получает доступное имя
+кнопки закрытия из `closeLabel` (по умолчанию «Закрыть»).
+
+`ModalOverlay` не даёт `role="dialog"`, `aria-modal`, focus trap или scroll lock.
+Если его всё же применяют для интерактивного окна, потребитель обязан добавить
+эти свойства сам. См. [исходник Dialog](../../../src/components/overlays/Dialog.tsx),
+[ModalHeader](../../../src/components/overlays/ModalHeader.tsx) и
+[ModalOverlay](../../../src/components/overlays/ModalOverlay.tsx).
+
+## Хорошие примеры
+
+- Окно формы: `Dialog` с `title`, `FormField` и footer в `children`.
+- Нестандартная геометрия: `Dialog header={false}` с собственным содержимым, но
+  не с самодельной ролью.
+- Обычная подложка предпросмотра: `ModalOverlay`, если preview не объявляется
+  пользователю модальным диалогом.
+
+## Антипаттерны
+
+- `role="dialog"` на `ModalOverlay` без имени и focus trap.
+- Три раздельных флага для запрета крестика, Escape и click-away вместо `loading`.
+- Класть в `title` блочную разметку вроде футера или оставлять окно без смыслового названия.
+
+## Связанные исходники и Storybook
+
+- `src/components/overlays/Dialog.tsx`, `src/components/overlays/ModalHeader.tsx`, `src/components/overlays/ModalOverlay.tsx`
+- `src/components/overlays/Dialog.stories.tsx`

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

@@ -0,0 +1,87 @@
+---
+component: Drawer
+exports: [Drawer]
+category: overlays
+status: stable
+source: src/components/overlays/Drawer.tsx
+story: src/components/overlays/Drawer.stories.tsx
+sourceHash: baed0ac7c97c
+---
+
+# Drawer
+
+## Summary for AI
+
+`Drawer` is a modal panel that slides in from the right, the left or the bottom.
+Choose it when the context of the main page should stay visible but the task
+needs more room than a popover. Modality, the portal, the focus trap and focus
+return are already implemented on Radix.
+
+## When to use
+
+- Viewing or editing an entity without a full navigation to a new page.
+- A panel with scrollable content and a pinned action `footer`.
+- A side panel on desktop: on a narrow screen it automatically becomes a bottom
+  one, so it does not clip the content.
+
+## When not to use
+
+- Use `ConfirmDialog` for a short question and `Dialog` for an ordinary compact form.
+- Use `Popover` for a dropdown anchored to a button, a calendar or a small list.
+- Do not use it as permanent, non-modal sidebar navigation.
+
+## Minimal example
+
+```tsx
+<Drawer open={open} onClose={close} title="Edit" footer={<Button onClick={save}>Save</Button>}>
+  <FormField label="Name">
+    <TextControl />
+  </FormField>
+</Drawer>
+```
+
+## Public API
+
+`open`, `onClose` and `title` are required. `subtitle` adds an explanation; `side`
+accepts `right` (the default), `left` or `bottom`; `size` accepts `sm`, `md` (the
+default) or `lg`. For the side variants the size means width; for the bottom one, height. `footer`
+always stays at the bottom, while `children` scroll separately. `closeLabel`,
+`className` and `zIndex` are available for tuning; a single `zIndex` applies to
+both the scrim and the panel.
+
+## Accessibility and keyboard
+
+The title is the dialog's name; `ModalHeader` creates the close button. Radix
+keeps focus inside the drawer, closes it on Escape, blocks the background and
+returns focus to the element that opened it. Do not add `useScrollLock`.
+See [the Drawer source](../../../src/components/overlays/Drawer.tsx).
+
+**Escape closes the topmost overlay (since 3.5.0).** When a menu, a dropdown list or a
+tooltip is open inside the drawer, the first Escape closes it rather than the
+drawer; before that, one press closed both — along with an unsaved form. The
+analysis is in
+ADR-0041.
+
+**Items of a react-aria menu and list inside a drawer can be chosen with the mouse.**
+Radix's modal layer turns off pointer events on `<body>`, while the `Menu` panel
+and the `Combobox` list sit in a portal beneath it; the kit gives pointer events
+back to such an overlay with a rule in `@olddevs/ui/styles.css`. Before this fix
+an item could be chosen only with the keyboard. A click on an item
+does not close the drawer.
+
+## Good examples
+
+- `side="right"` for editing a record, with a `footer` holding cancel and save.
+- `side="bottom"` for a panel that works well on a mobile screen.
+- `zIndex="z-100"` when the drawer must sit above the app's own layer.
+
+## Anti-patterns
+
+- Duplicating the footer inside `children`: it scrolls away.
+- Setting a fixed width on a side drawer through `className` without checking the mobile screen.
+- Using a drawer without a title or with an empty one.
+
+## Related sources and Storybook
+
+- `src/components/overlays/Drawer.tsx`
+- `src/components/overlays/Drawer.stories.tsx`

package/docs/components/overlays/drawer.md

@@ -0,0 +1,88 @@
+---
+component: Drawer
+exports: [Drawer]
+category: overlays
+status: stable
+source: src/components/overlays/Drawer.tsx
+story: src/components/overlays/Drawer.stories.tsx
+---
+
+# Drawer
+
+## Кратко для AI
+
+`Drawer` — модальная панель, выезжающая справа, слева или снизу. Выбирайте её,
+когда контекст основной страницы должен остаться виден, но задача требует
+пространства больше, чем у поповера. Модальность, portal, ловушка и возврат фокуса уже
+реализованы на Radix.
+
+## Когда использовать
+
+- Просмотр или редактирование сущности без полного перехода на новую страницу.
+- Панель с прокручиваемым содержимым и закреплённым `footer` действий.
+- Боковая панель на desktop: на узком экране она автоматически становится
+  нижней, чтобы не обрезать содержимое.
+
+## Когда не использовать
+
+- Для короткого вопроса — `ConfirmDialog`; для обычной компактной формы — `Dialog`.
+- Для выпадающего списка у кнопки, календаря или небольшого списка — `Popover`.
+- Не используйте как немодальную постоянную навигационную sidebar-панель.
+
+## Минимальный пример
+
+```tsx
+<Drawer
+  open={open}
+  onClose={close}
+  title="Редактирование"
+  footer={<Button onClick={save}>Сохранить</Button>}
+>
+  <FormField label="Название">
+    <TextControl />
+  </FormField>
+</Drawer>
+```
+
+## Public API
+
+Требуются `open`, `onClose`, `title`. `subtitle` добавляет пояснение; `side`:
+`right` (умолчание), `left` или `bottom`; `size`: `sm`, `md` (умолчание), `lg`.
+У боковых вариантов размер означает ширину, у нижнего — высоту. `footer` всегда
+остаётся внизу, а `children` прокручиваются отдельно. `closeLabel`, `className`
+и `zIndex` доступны для настройки; один `zIndex` применяется и к подложке, и к
+панели.
+
+## Доступность и клавиатура
+
+Заголовок — имя диалога; `ModalHeader` создаёт кнопку закрытия. Radix удерживает
+фокус в ящике, закрывает его Escape, блокирует фон и возвращает фокус к элементу,
+который открыл ящик. Не добавляйте `useScrollLock`. См.
+[исходник Drawer](../../../src/components/overlays/Drawer.tsx).
+
+**Escape закрывает верхний оверлей (с 3.5.0).** При открытом внутри ящика меню, выпадающем
+списке или подсказке первый Escape закрывает их, а не ящик; до этого одно нажатие
+закрывало и то, и другое — вместе с несохранённой формой. Разбор —
+ADR-0041.
+
+**Пункты меню и списка react-aria внутри ящика выбираются мышью.** Модальный слой Radix
+отключает указатель у `<body>`, а панель `Menu` и список `Combobox` лежат в
+портале под ним; кит возвращает такому оверлею указатель правилом в
+`@olddevs/ui/styles.css`. До этого исправления пункт выбирался только с клавиатуры. Ящик от щелчка по пункту не закрывается.
+
+## Хорошие примеры
+
+- `side="right"` для редактирования записи, `footer` с отменой и сохранением.
+- `side="bottom"` для панели, удобной на мобильном экране.
+- `zIndex="z-100"`, когда ящик должен быть выше собственного слоя приложения.
+
+## Антипаттерны
+
+- Дублировать footer внутри `children`: он уйдёт при прокрутке.
+- Задавать боковому ящику фиксированную ширину через `className`, не проверив мобильный экран.
+- Использовать ящик без заголовка или с пустым заголовком.
+
+## Связанные исходники и Storybook
+
+- `src/components/overlays/Drawer.tsx`
+- `src/components/overlays/Drawer.stories.tsx`

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

@@ -0,0 +1,179 @@
+---
+component: HoverCard
+exports: [HoverCard, HoverCardContent, HoverCardTrigger]
+category: overlays
+status: stable
+source: src/components/overlays/HoverCard.tsx
+story: src/components/overlays/HoverCard.stories.tsx
+sourceHash: daa346b258c2
+---
+
+# HoverCard
+
+## Summary for AI
+
+`HoverCard` is a preview card: when you hover over a name or a link, or focus it
+from the keyboard, a panel with details pops up next to it. Focus from a screen
+reader does **not** open the card (deliberately, see "Accessibility and keyboard"). The
+trigger is a link or a button **with its own action**; the card complements it
+and replaces nothing. The content is only supplementary: everything in it must
+also be available without the card. Do not put forms or required actions in the card.
+It is built on the kit's `Popover`, with no new dependency.
+
+## When to use
+
+- A user name, a link to a document, a tag, an entity in text: on hover you need
+  to show an avatar, a job title, the first lines — without navigating away from
+  the page.
+- The details are secondary: a user who did not see the card loses nothing (the
+  link leads to the same information in full).
+- **There was no requesting screen at release** (ADR-0048):
+  the API was modeled on similar components — `HoverCard` in Radix and shadcn/ui,
+  hover-card in Chakra and Mantine. The consumer's first screen is the first test
+  of the contract; a mismatch between the contract and the screen is a reason to
+  change the API.
+
+## When not to use
+
+- Use `Tooltip` for a short caption or the meaning of a term: it is one line of
+  text, without markup, and opens faster.
+- Use `HelpTooltip` for an explanatory paragraph that people need time to read: it
+  is a popover **on click** of a question-mark button, and it does not vanish when
+  the cursor moves away.
+- For content with fields, action buttons or links that must be reachable, use
+  `Popover` (opens on click, takes focus, returns it) or `Dialog`. The card
+  closes when the cursor or focus leaves, and you cannot reach it with the Tab key.
+- The only way to learn something important. On a phone it usually does not open.
+
+## Minimal example
+
+```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`** is the root and renders nothing.
+
+| Prop           | Default | Meaning                                                                                            |
+| -------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `openDelay`    | `700`   | Milliseconds that hover or focus must last for the card to open                                    |
+| `closeDelay`   | `300`   | Milliseconds after the cursor has left **both** the trigger **and** the card                       |
+| `open`         | —       | Controlled state; the component still times the delays and requests changes through `onOpenChange` |
+| `defaultOpen`  | `false` | Initial state when uncontrolled                                                                    |
+| `onOpenChange` | —       | Called when the timer fires, on Escape, or on a click or focus outside the card                    |
+
+**`HoverCardTrigger`** listens for hover and focus. `asChild` is on by default:
+the trigger renders as its single child — a link or a button. The child's own
+handlers are kept; a click on the trigger **toggles nothing**. The state for
+styles is the `data-state="open" | "closed"` attribute. For why the trigger has
+no `aria-haspopup` or `aria-expanded`, see "Accessibility and keyboard".
+
+**`HoverCardContent`** is the panel. It accepts the `PopoverContent` props
+(`side`, `align`, `sideOffset`, `className`): the look, the layer and the
+animations are shared with it. Width and padding are set by the content, as with
+a popover.
+
+What sets the card apart from a popover:
+
+- **Opening.** On `pointerenter`, after `openDelay`. On focus — only focus that
+  came from a navigation key (Tab, Shift+Tab, Option+Tab in Safari on macOS,
+  arrow keys, Home, End, PageUp, PageDown): a click on a link puts focus on it,
+  and there is no point in opening the card after the action has already been
+  taken. Focus with no key and no pointer (a screen reader swipe, a programmatic
+  `focus()`) does not open the card. A quick fly-by of the cursor does not open it.
+- **Closing.** When the cursor has left both the trigger and the card, after
+  `closeDelay`. Moving the cursor from the trigger to the card does not close it;
+  neither does returning to the trigger before the delay ends. A click (including
+  on the trigger itself), focus on another element, and Escape close it at once;
+  focus on the trigger itself does not close the card.
+- **Focus.** On open it stays where it is — it does not move into the content. On
+  close it does not return to the trigger: a close caused by the pointer must not
+  drag focus around. There is no focus trap.
+- **Devices without hover.** With `(hover: none)` and for touch input the card does
+  not open on hover; a touch performs the trigger's action (following the link)
+  and does not open the card. **Keyboard focus opens it there too:** a tablet may
+  have a hardware keyboard, and Tab on the trigger works just as it does on a
+  computer. Input modality tells a key from a touch: a key opens the card, a tap
+  and a mouse click do not. A controlled `open` is not blocked by this.
+- **Role.** The panel has no `role="dialog"`: a dialog that does not move focus is
+  a promise it does not keep. If you need a role or a name, pass `role` or `aria-label`.
+
+## Accessibility and keyboard
+
+- Tab onto the trigger opens the card after `openDelay`; Tab onward or Escape
+  closes it. A navigation key counts as keyboard: Tab, Shift+Tab, arrow keys, Home,
+  End, PageUp, PageDown — and **Option+Tab**: in Safari on macOS it is the only
+  way to reach links with the key until tabbing through all elements is turned on
+  in the settings. Other combinations with Option, Ctrl and Cmd do not count as
+  navigation (Ctrl+Tab switches browser tabs, Cmd+Tab switches applications).
+  Radix listens for Escape, as it does for `Popover` and `Tooltip`; the component
+  has no new Escape handlers and no `z-index` of its own — the panel sits on the
+  `OVERLAY_LAYER.popover` step (ADR-0041),
+  above dialogs, so it stays visible when opened from a `Dialog`. If the card is
+  opened from a dialog, the first Escape press closes the card and the second
+  closes the dialog.
+- **Focus from a screen reader does not open the card — deliberately.** A
+  VoiceOver or TalkBack swipe and, on desktop, the NVDA and JAWS virtual cursor
+  (browse mode) set focus without sending the page a key or a pointer;
+  `:focus-visible` matches in that case, so the kit works out the source of focus
+  on its own (an internal input modality tracker, with no dependencies). A card
+  that pops up without an announcement throws a screen reader user off, and with
+  a screen magnifier it covers the neighboring text. By contract the content is
+  supplementary and available another way — on the page the trigger leads to.
+- **Hardware keyboard.** Tab and the arrow keys on it open the card even with a
+  screen reader running: that is a real key. Focus that the browser returns to
+  the trigger when the tab becomes active again, and focus that the app sets
+  programmatically (for example, after a dialog closes), do not open the card
+  either.
+- **Limitation: the address bar.** If the first Tab came from the address bar or
+  the browser toolbar, the page did not see the key — such focus is
+  indistinguishable from screen reader focus, and the card does not open; the next
+  Tab or a hover opens it.
+- The trigger should not be the only path to the content for a screen reader: the
+  card complements, it does not replace. Everything important in it must also be
+  on the page the trigger leads to.
+- **The trigger is built on `PopoverAnchor`, not on `PopoverTrigger`.** An anchor
+  only defines what the panel attaches to: it carries neither click toggling nor
+  the popover's ARIA attributes, and `HoverCard` itself opens and closes the card
+  (the Radix popover under it is controlled). That is why the trigger has no
+  `aria-haspopup` or `aria-expanded`, and a click does not toggle the card: a
+  screen reader hears an ordinary link or a button with its own action, not a
+  popover button promising a panel on press.
+- Motion follows the kit's motion scale (ADR-0047):
+  the entrance is `popoverIn`, and under `prefers-reduced-motion: reduce` only the
+  appearance remains, with no shift.
+
+## Good examples
+
+- An author's name in a comment list → avatar, job title, number of materials.
+- A link to a document in text → title, author, first lines.
+- `openDelay={0}` for dense tables, where the person moves the cursor purposefully anyway.
+
+## Anti-patterns
+
+- A trigger without its own action (`span`, `div`, a dummy button): the card is
+  for links and buttons that have somewhere to go on click.
+- A form, a "Save" button or the only link to something important inside
+  `HoverCardContent`.
+- A one-line caption — `Tooltip` is for that.
+- Your own `z-index` or your own Escape handler on the panel.
+- `@radix-ui/react-hover-card` next to the kit: the component is built on `Popover`.
+
+## Related sources and Storybook
+
+- `src/components/overlays/HoverCard.tsx`
+- `src/components/overlays/HoverCard.stories.tsx`
+- `tests/hover-card.test.tsx`