@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/components/overlays/shortcuts-help.en.md

@@ -0,0 +1,190 @@
+---
+component: ShortcutsHelp
+exports: [ShortcutsHelp, ShortcutGroup, ShortcutItem, ShortcutsHelpProps]
+category: overlays
+status: stable
+source: src/components/overlays/ShortcutsHelp.tsx
+story: src/components/overlays/ShortcutsHelp.stories.tsx
+sourceHash: ab935ac387f6
+---
+
+# ShortcutsHelp
+
+## Summary for AI
+
+A modal dialog with a list of keyboard shortcuts, built on `Dialog`. Props: `open`,
+`onOpenChange`, `title` (by default "Keyboard shortcuts" from the message catalog)
+and `groups` — an array of groups `{ id, label, items }`, where an item is
+`{ keys, description }`. Each key is rendered with its own `Kbd`. A group is
+announced as a named group (`role="group"`), not as a heading. The kit **does not
+register global shortcuts**: which key opens the list and which shortcuts exist at
+all is up to the app.
+
+## When to use
+
+- A screen with keyboard navigation: the user must find out what to press without
+  reading the docs. The model is the "Keyboard shortcuts" dialog at GitHub,
+  Linear and Atlassian.
+- There are more than a few shortcuts, and it is convenient to lay them out in sections.
+
+## When not to use
+
+- A shortcut next to a single menu item is a `Kbd` inside the item; in
+  `CommandPalette` the shortcut lives in the `shortcut` property. A whole dialog for
+  one key is excessive.
+- Editing shortcuts, binding shortcuts and searching the list are not the
+  component's job: it only shows a list. That is a separate settings screen.
+- Do not confuse it with `Keyboard`: that is the name of the **on-screen
+  keyboard** for entering text ([`Keyboard` page](../content/keyboard.md)), not a way to render
+  "Ctrl+K". A shortcut is assembled from `Kbd`.
+- A list that must not cover the page is a help panel in a `Drawer` or a separate
+  page; `ShortcutsHelp` is modal and covers the background.
+
+## Minimal example
+
+```tsx
+import { Button, ShortcutsHelp, type ShortcutGroup } from "@olddevs/ui";
+
+const groups: ShortcutGroup[] = [
+  {
+    id: "navigation",
+    label: "Navigation",
+    items: [
+      { keys: ["Ctrl", "K"], description: "Open search" },
+      { keys: ["G", "H"], description: "Go to home" },
+    ],
+  },
+  {
+    id: "general",
+    label: "General",
+    items: [{ keys: ["Esc"], description: "Close the dialog" }],
+  },
+];
+
+const [open, setOpen] = useState(false);
+
+<>
+  <Button onClick={() => setOpen(true)}>Keyboard shortcuts</Button>
+  <ShortcutsHelp open={open} onOpenChange={setOpen} groups={groups} />
+</>;
+```
+
+## Opening with "?": a consumer recipe
+
+The kit installs no global handlers, and that is a decision, not an omission: the
+key that opens the list fires in input fields and over other dialogs, and only
+the app knows what to do in those cases. The handler is yours to write; three
+things in it are required (see the `OpenWithQuestionMark` story for working code):
+
+```tsx
+useEffect(() => {
+  const onKeyDown = (event: KeyboardEvent) => {
+    // The character, not the position: "?" sits on different keys (Shift+/ on a
+    // Latin layout, Shift+7 on a Russian one), and the user presses the character itself.
+    if (event.key !== "?" || event.isComposing || event.repeat) return;
+    if (event.ctrlKey || event.altKey || event.metaKey) return;
+    const target = event.target;
+    if (
+      target instanceof HTMLElement &&
+      (target.isContentEditable || /^(input|textarea|select)$/i.test(target.tagName))
+    ) {
+      return; // in an input field a question mark is just a character
+    }
+    event.preventDefault();
+    setOpen(true);
+  };
+  document.addEventListener("keydown", onKeyDown);
+  return () => document.removeEventListener("keydown", onKeyDown);
+}, []);
+```
+
+1. **Check the character for "?" and the position for letters.** The user looks for
+   the question mark on the keyboard, and on a Russian layout it sits on Shift+7 —
+   `event.key` returns "?" on both layouts. Check letter shortcuts ("G, H") by
+   `event.code` (`KeyG`): if you compare characters, they stop working on another
+   layout.
+2. **Do nothing in input fields**, otherwise a question mark cannot be typed.
+3. **Do not react to** shortcuts with `Ctrl`, `Alt` and `Meta`, auto-repeat and
+   input through an IME (input method editor, `isComposing`).
+
+If the list must also open over an already open dialog, that is also the app's
+decision: the kit's `Dialog` keeps an Escape stack, and Escape closes the top one.
+
+## Public API
+
+### `ShortcutsHelp`
+
+| Prop           | Default                                         | Meaning                                                                                                            |
+| -------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `open`         | —                                               | Whether the dialog is shown. The consumer owns the state.                                                          |
+| `onOpenChange` | —                                               | Called when the dialog requests a state change: the close button, Escape and a click outside call it with `false`. |
+| `title`        | "Keyboard shortcuts" (from the message catalog) | The dialog's title and its accessible name. `ReactNode`.                                                           |
+| `groups`       | —                                               | Groups of shortcuts. A group with no items is not rendered or announced.                                           |
+
+### `ShortcutGroup` and `ShortcutItem`
+
+| Property           | Meaning                                                                                                                |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `group.id`         | A stable React list key; it does not reach the markup as an `id` (for `aria-labelledby` the kit uses the group index). |
+| `group.label`      | The group's label, `ReactNode`.                                                                                        |
+| `group.items`      | The group's items.                                                                                                     |
+| `item.keys`        | Keys in order: `["Ctrl", "K"]`. Each one is its own `Kbd`; a merged "Ctrl+K" is not parsed.                            |
+| `item.description` | What the shortcut does, `ReactNode`.                                                                                   |
+
+The default strings are `shortcutsHelp.title`, `shortcutsHelp.list` (the name of
+the scroll area) and `shortcutsHelp.keySeparator` (the word read aloud between
+keys) in the `ru` and `en` message catalogs.
+Other strings — `title`, `label` and `description` — come in as props: the kit does
+not know the shortcuts and their names.
+
+## Behavior and accessibility
+
+- The dialog is `role="dialog"` named by its title; the focus trap, Escape, a
+  click outside and focus return to the element that opened it come from
+  `Dialog`. After closing, focus returns to the button that opened the list; if
+  the list was opened by a keyboard shortcut, to the element that was focused.
+- **A group is a named group, not a heading.** `role="group"` with
+  `aria-labelledby` pointing at the label — as in `NotificationList`. The heading
+  level depends on where the dialog ends up, and the kit cannot know it; the
+  only heading in the dialog is its name.
+- **An item is a list item** (`ul`/`li`): "description, then the shortcut". A
+  list was chosen over `dl`: "term — definition" pairs are announced
+  inconsistently (some screen readers name neither the number of pairs nor their
+  boundaries), while a list is read everywhere — "list, 3 items".
+- **The word "plus" is read between the keys.** Each key is a `<kbd>`, and the visible "+"
+  between them is removed from the accessibility tree (`aria-hidden`), with a word
+  from the message catalog read in its place: "Ctrl plus K". The "+" sign is voiced
+  according to the user's settings (NVDA skips it at the default punctuation
+  level), and without the word "plus", "Ctrl K" would sound like two keys in a row. A
+  single key gets no separator.
+- In `CommandPalette` an item's shortcut is entirely `aria-hidden` — it is a reminder
+  next to an item that can be chosen anyway. Here the shortcut is the dialog's
+  only content, and hiding it would hand a screen reader an empty cheat sheet.
+- **Scrolling inside the dialog.** The list sits in a `ScrollArea` no taller than
+  70% of the screen height and no taller than 32rem: the header with the close
+  button stays in place. The area is a Tab stop with a separate name ("Shortcuts" /
+  "Сочетания клавиш", key `shortcutsHelp.list`), and it is scrolled with the arrow
+  keys and `PageDown`.
+- Key names are text that you pass. A word ("Ctrl", "Shift") is read everywhere;
+  screen readers voice a glyph ("⌘", "⇧") differently, and if your app shows a shortcut only as a glyph, label it with a word in
+  `description`.
+
+## Anti-patterns
+
+- Expecting the component to open itself on "?" or another shortcut: it does not
+  listen to the keyboard.
+- Passing a shortcut as one string: `keys: ["Ctrl+K"]`. That is one `Kbd` with
+  long text and no word to read aloud.
+- Putting interactive elements in `description`: the list is a reference, not a menu.
+- Storing domain shortcuts and their names in the kit — they belong to the app.
+- Adding `h3` headings inside groups by hand: the groups already have a name.
+
+## Related sources and Storybook
+
+- Source: `src/components/overlays/ShortcutsHelp.tsx`; the key is `src/components/content/Kbd.tsx`,
+  the dialog is `src/components/overlays/Dialog.tsx`.
+- Tests: `tests/shortcuts-help.test.tsx`.
+- Showcase: `src/components/overlays/ShortcutsHelp.stories.tsx` (`Playground`,
+  `OpenWithQuestionMark`, `LongList`, `CustomTitle`). Level: periphery
+  (ADR-0014): no snapshots. Opening, Escape, focus return and scrolling were
+  checked by hand on the built showcase.

package/docs/components/overlays/shortcuts-help.md

@@ -0,0 +1,186 @@
+---
+component: ShortcutsHelp
+exports: [ShortcutsHelp, ShortcutGroup, ShortcutItem, ShortcutsHelpProps]
+category: overlays
+status: stable
+source: src/components/overlays/ShortcutsHelp.tsx
+story: src/components/overlays/ShortcutsHelp.stories.tsx
+---
+
+# ShortcutsHelp
+
+## Кратко для AI
+
+Это модальное окно со сводом сочетаний клавиш на `Dialog`. Пропы: `open`,
+`onOpenChange`, `title` (по умолчанию «Горячие клавиши» из каталога сообщений) и
+`groups` — массив групп `{ id, label, items }`, где пункт — `{ keys, description }`.
+Каждая клавиша рисуется своей `Kbd`. Группа объявляется группой с именем
+(`role="group"`), а не заголовком. Кит **не вешает глобальных клавиш**: по какой
+клавише свод открывается и какие сочетания вообще есть — решает приложение.
+
+## Когда использовать
+
+- Экран с клавиатурной навигацией: пользователь должен узнать, что нажимается, не
+  читая справку. Образец — окно «Keyboard shortcuts» у GitHub, Linear, Atlassian.
+- Сочетаний больше нескольких, и их удобно разложить по разделам.
+
+## Когда не использовать
+
+- Сочетание рядом с одним пунктом меню — это `Kbd` внутри пункта; у
+  `CommandPalette` сочетание лежит в поле `shortcut`. Целое окно ради одной
+  клавиши — лишнее.
+- Редактирование сочетаний, привязка клавиш и поиск по своду — не задача
+  компонента: он только показывает список. Это отдельный экран настроек.
+- Не путайте с `Keyboard`: так называется **экранная клавиатура** для ввода
+  текста ([страница `Keyboard`](../content/keyboard.md)), а не способ нарисовать «Ctrl+K».
+  Сочетание собирается из `Kbd`.
+- Список, который не должен перекрывать страницу, — это справка в `Drawer` или
+  отдельная страница; `ShortcutsHelp` модален и закрывает фон.
+
+## Минимальный пример
+
+```tsx
+import { Button, ShortcutsHelp, type ShortcutGroup } from "@olddevs/ui";
+
+const groups: ShortcutGroup[] = [
+  {
+    id: "navigation",
+    label: "Навигация",
+    items: [
+      { keys: ["Ctrl", "K"], description: "Открыть поиск" },
+      { keys: ["G", "H"], description: "Перейти на главную" },
+    ],
+  },
+  {
+    id: "general",
+    label: "Общие",
+    items: [{ keys: ["Esc"], description: "Закрыть окно" }],
+  },
+];
+
+const [open, setOpen] = useState(false);
+
+<>
+  <Button onClick={() => setOpen(true)}>Горячие клавиши</Button>
+  <ShortcutsHelp open={open} onOpenChange={setOpen} groups={groups} />
+</>;
+```
+
+## Открытие по «?»: рецепт потребителя
+
+Кит глобальных обработчиков не ставит, и это решение, а не недоделка: клавиша,
+по которой открывается свод, срабатывает в полях ввода и поверх чужих окон, а что
+делать в этих случаях, знает только приложение. Обработчик живёт у вас; в нём обязательны
+три вещи (рабочий код — история `OpenWithQuestionMark`):
+
+```tsx
+useEffect(() => {
+  const onKeyDown = (event: KeyboardEvent) => {
+    // Знак, а не положение: «?» стоит на разных клавишах (Shift+/ на латинской
+    // раскладке, Shift+7 на русской), и пользователь нажимает именно знак.
+    if (event.key !== "?" || event.isComposing || event.repeat) return;
+    if (event.ctrlKey || event.altKey || event.metaKey) return;
+    const target = event.target;
+    if (
+      target instanceof HTMLElement &&
+      (target.isContentEditable || /^(input|textarea|select)$/i.test(target.tagName))
+    ) {
+      return; // в поле ввода знак вопроса — просто знак
+    }
+    event.preventDefault();
+    setOpen(true);
+  };
+  document.addEventListener("keydown", onKeyDown);
+  return () => document.removeEventListener("keydown", onKeyDown);
+}, []);
+```
+
+1. **Сверять знак для «?» и положение для букв.** Знак вопроса пользователь ищет
+   глазами, и на русской раскладке он стоит на Shift+7 — `event.key` вернёт «?» на
+   обеих раскладках. Буквенные сочетания («G, H») сверяйте по `event.code`
+   (`KeyG`): если сверять по символу, на другой раскладке они перестанут
+   срабатывать.
+2. **Ничего не делать в полях ввода**, иначе вопросительный знак нельзя напечатать.
+3. **Не реагировать** на сочетания с `Ctrl`, `Alt` и `Meta`, автоповтор и ввод
+   через IME (редактор метода ввода, `isComposing`).
+
+Если свод должен открываться и поверх уже открытого окна, это тоже решение
+приложения: `Dialog` кита ведёт стек Escape, Escape закроет верхний.
+
+## Public API
+
+### `ShortcutsHelp`
+
+| Проп           | По умолчанию                    | Значение                                                                           |
+| -------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
+| `open`         | —                               | Показано ли окно. Состояние хранит потребитель.                                    |
+| `onOpenChange` | —                               | Окно просит сменить состояние: крестик, Escape и клик мимо вызывают его с `false`. |
+| `title`        | «Горячие клавиши» (из каталога) | Заголовок окна и его доступное имя. `ReactNode`.                                   |
+| `groups`       | —                               | Группы сочетаний. Группа без пунктов не рисуется и не объявляется.                 |
+
+### `ShortcutGroup` и `ShortcutItem`
+
+| Поле               | Значение                                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `group.id`         | Стабильный ключ списка React; в разметку как `id` не попадает (для `aria-labelledby` кит берёт номер группы). |
+| `group.label`      | Подпись группы, `ReactNode`.                                                                                  |
+| `group.items`      | Пункты группы.                                                                                                |
+| `item.keys`        | Клавиши по порядку: `["Ctrl", "K"]`. Каждая — своя `Kbd`; слитное «Ctrl+K» не разбирается.                    |
+| `item.description` | Что делает сочетание, `ReactNode`.                                                                            |
+
+Строки по умолчанию — `shortcutsHelp.title`, `shortcutsHelp.list` (имя области
+прокрутки) и `shortcutsHelp.keySeparator` (слово между клавишами для слуха) в
+каталоге сообщений `ru` и `en`.
+Другие тексты — `title`, `label` и `description` — приходят пропами: сочетания
+и их названия кит не знает.
+
+## Поведение и доступность
+
+- Окно — `role="dialog"` с именем из заголовка; ловушка фокуса, Escape, клик
+  мимо и возврат фокуса на открывший элемент — от `Dialog`. После закрытия
+  фокус возвращается на кнопку, открывшую свод; если свод открыт сочетанием
+  клавиш, то на элемент, который был в фокусе.
+- **Группа — именованная группа, а не заголовок.** `role="group"` с
+  `aria-labelledby` на подпись — как у `NotificationList`. Уровень заголовка
+  зависит от места, куда окно встало, и кит его не знает; единственный заголовок
+  в окне — его имя.
+- **Пункт — элемент списка** `ul`/`li`: «описание, затем сочетание». Выбран список,
+  а не `dl`: пары «термин — определение» озвучиваются непоследовательно (часть
+  скринридеров не называет ни числа пар, ни их границы), а список читают
+  везде — «список, 3 элемента».
+- **Между клавишами читается слово «плюс».** Каждая клавиша — `<kbd>`, между ними
+  видимый «+» убран из дерева доступности (`aria-hidden`), а вместо него
+  читается слово из каталога: «Ctrl плюс K». Знак «+» озвучивается по настройкам
+  пользователя (NVDA на умолчательном уровне пунктуации его пропускает), и без
+  слова «плюс» сочетание «Ctrl K» звучало бы как две клавиши подряд. Одиночная клавиша разделителя
+  не получает.
+- У `CommandPalette` сочетание пункта целиком `aria-hidden` — это напоминание рядом
+  с пунктом, который и так выбирается. Здесь сочетание — единственное
+  содержимое окна, и скрыть его значило бы дать скринридеру пустую шпаргалку.
+- **Прокрутка внутри окна.** Список лежит в `ScrollArea` с высотой не больше
+  70% высоты экрана и не больше 32rem: шапка с крестиком остаётся на месте. Область — остановка
+  табуляции с отдельным именем («Shortcuts» / «Сочетания клавиш», ключ
+  `shortcutsHelp.list`), её прокручивают стрелками и `PageDown`.
+- Названия клавиш — текст, который вы передаёте. Слово («Ctrl», «Shift») читается
+  везде; глиф («⌘», «⇧») скринридеры озвучивают по-разному, и если в вашем
+  приложении сочетание обозначено только глифом, подпишите его словом в `description`.
+
+## Антипаттерны
+
+- Ждать, что компонент сам откроется по «?» или другому сочетанию: он не
+  слушает клавиатуру.
+- Передавать сочетание одной строкой: `keys: ["Ctrl+K"]`. Это одна `Kbd` с
+  длинным текстом и без слова для слуха.
+- Класть в `description` интерактивные элементы: свод — справка, а не меню.
+- Хранить в ките доменные сочетания и их названия — они принадлежат приложению.
+- Заводить заголовки `h3` внутри групп вручную: у групп уже есть имя.
+
+## Связанные исходники и Storybook
+
+- Исходник: `src/components/overlays/ShortcutsHelp.tsx`; клавиша — `src/components/content/Kbd.tsx`,
+  окно — `src/components/overlays/Dialog.tsx`.
+- Тесты: `tests/shortcuts-help.test.tsx`.
+- Витрина: `src/components/overlays/ShortcutsHelp.stories.tsx` (`Playground`,
+  `OpenWithQuestionMark`, `LongList`, `CustomTitle`). Уровень — периферия
+  (ADR-0014): снимков нет. Открытие, Escape, возврат фокуса и прокрутка
+  проверены вручную на собранной витрине.

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

@@ -0,0 +1,78 @@
+---
+component: Tooltip
+exports: [Tooltip, TooltipContent, TooltipProvider, TooltipRoot, TooltipTrigger, HelpTooltip]
+category: overlays
+status: stable
+source: src/components/overlays/Tooltip.tsx
+story: src/components/overlays/Tooltip.stories.tsx
+sourceHash: a44d75c75a7f
+---
+
+# Tooltip and HelpTooltip
+
+## Summary for AI
+
+`Tooltip` adds a short explanation to a single element on hover and focus. It
+does not replace a visible label, an instruction or a confirmation.
+`TooltipProvider` is placed once at the app root. For the ordinary case, use the
+`Tooltip` wrapper; the primitives `TooltipRoot`, `TooltipTrigger` and
+`TooltipContent` are needed when you want Radix's compound markup. `HelpTooltip`
+is a ready-made popover opened by a click on a help icon.
+
+## When to use
+
+- To label an icon-only button or to explain an unfamiliar term.
+- To give a short optional clarification that is not needed to complete the task.
+- `HelpTooltip` — for a standard help icon next to a field or a setting.
+
+## When not to use
+
+- Do not hide a required instruction, an error or the only name of an action:
+  they must be visible or programmatically tied to the control.
+- Use `Popover` for complex interactive content and `Alert` for a status message.
+  Use `HoverCard` for a preview with markup (an avatar, a title, a couple of
+  lines) on hover over a link or a name.
+- Do not create a `TooltipProvider` for every button.
+
+## Minimal example
+
+```tsx
+<Tooltip content="Delete the selection">
+  <Button iconOnly aria-label="Delete" icon={<DeleteIcon />} />
+</Tooltip>
+```
+
+## Public API
+
+`Tooltip` accepts `content`, a single `children: ReactElement`, `side`, `align`
+and `delayDuration`. An empty `content` returns the child without a
+wrapper. The child must accept a `ref`, because it becomes the trigger.
+`TooltipContent` accepts the Radix `Content` props; its `sideOffset` is 6 by
+default. `TooltipProvider`, `TooltipRoot` and `TooltipTrigger` export the Radix
+primitives for the compound API.
+
+## Accessibility and keyboard
+
+The tooltip opens on focus too, not only on hover. An icon-only trigger must still
+have its own `aria-label`: a tooltip is not a reliable accessible name for a
+button. Put one provider at the root so that the shared delay and the transition
+between tooltips work consistently. See
+[the Tooltip source](../../../src/components/overlays/Tooltip.tsx) and
+[HelpTooltip](../../../src/components/overlays/HelpTooltip.tsx).
+
+## Good examples
+
+- A delete icon with an `aria-label` and a clarifying tooltip.
+- `content={condition ? text : undefined}` without branching the DOM by hand.
+- `HelpTooltip` next to an unclear parameter, but not instead of its `label`.
+
+## Anti-patterns
+
+- A tooltip on a non-focusable `span` as the only way to read the action.
+- Multi-paragraph text, buttons or a form inside a tooltip.
+- A nested provider in a library component.
+
+## Related sources and Storybook
+
+- `src/components/overlays/Tooltip.tsx`, `src/components/overlays/HelpTooltip.tsx`
+- `src/components/overlays/Tooltip.stories.tsx`

package/docs/components/overlays/tooltip.md

@@ -0,0 +1,77 @@
+---
+component: Tooltip
+exports: [Tooltip, TooltipContent, TooltipProvider, TooltipRoot, TooltipTrigger, HelpTooltip]
+category: overlays
+status: stable
+source: src/components/overlays/Tooltip.tsx
+story: src/components/overlays/Tooltip.stories.tsx
+---
+
+# Tooltip и HelpTooltip
+
+## Кратко для AI
+
+`Tooltip` добавляет краткое пояснение к одному элементу при hover и focus.
+Он не заменяет видимую подпись, инструкцию или подтверждение. `TooltipProvider`
+ставится один раз у корня приложения. Для обычного случая берите wrapper
+`Tooltip`; primitives `TooltipRoot`, `TooltipTrigger`, `TooltipContent` нужны,
+когда требуется составная разметка Radix. `HelpTooltip` — готовый поповер по клику на
+иконку помощи.
+
+## Когда использовать
+
+- Подписать кнопку только с иконкой или расшифровать незнакомый термин.
+- Дать короткое необязательное уточнение, которое не нужно для завершения задачи.
+- `HelpTooltip` — для стандартной help-иконки рядом с полем или настройкой.
+
+## Когда не использовать
+
+- Не прячьте обязательную инструкцию, ошибку или единственное название действия:
+  они должны быть видимы или программно связаны с контролом.
+- Для сложного интерактивного содержимого — `Popover`; для сообщения о состоянии
+  — `Alert`. Для превью с разметкой (аватар, заголовок, пара строк) по наведению
+  на ссылку или имя — `HoverCard`.
+- Не создавайте `TooltipProvider` у каждой кнопки.
+
+## Минимальный пример
+
+```tsx
+<Tooltip content="Удалить выбранное">
+  <Button iconOnly aria-label="Удалить" icon={<DeleteIcon />} />
+</Tooltip>
+```
+
+## Public API
+
+`Tooltip` принимает `content`, единственный `children: ReactElement`, а также
+`side`, `align` и `delayDuration`. Пустой `content` возвращает ребёнка без
+обёртки. Ребёнок обязан принимать `ref`, потому что он становится trigger.
+`TooltipContent` принимает props Radix `Content`; его `sideOffset` по умолчанию
+равен 6. `TooltipProvider`, `TooltipRoot` и `TooltipTrigger` экспортируют
+примитивы Radix для составного API.
+
+## Доступность и клавиатура
+
+Подсказка открывается и при фокусе, а не только при наведении. У icon-only
+trigger всё равно должен быть собственный `aria-label`: подсказка не является
+надёжным доступным именем кнопки. Поставьте один provider на root, чтобы общая
+задержка и переход между подсказками работали согласованно. См.
+[исходник Tooltip](../../../src/components/overlays/Tooltip.tsx) и
+[HelpTooltip](../../../src/components/overlays/HelpTooltip.tsx).
+
+## Хорошие примеры
+
+- Иконка удаления с `aria-label` и уточняющей подсказкой.
+- `content={condition ? text : undefined}` без ручного ветвления DOM.
+- `HelpTooltip` рядом с непонятным параметром, но не вместо его `label`.
+
+## Антипаттерны
+
+- Подсказка на нефокусируемом `span` как единственный способ прочитать действие.
+- Многоабзацный текст, кнопки или форма внутри подсказки.
+- Вложенный provider в библиотечном компоненте.
+
+## Связанные исходники и Storybook
+
+- `src/components/overlays/Tooltip.tsx`, `src/components/overlays/HelpTooltip.tsx`
+- `src/components/overlays/Tooltip.stories.tsx`