@sberbusiness/triplex-next-mcp-server 1.40.0-beta → 1.41.0-beta

package/bundle/components/Tooltip.md

@@ -1,10 +1,18 @@
 ---
 component: Tooltip
-category: Overlay
-figma-node: ""
-figma-file: ""
-related: [Dropdown, MobileView, MediaWidth]
-tokens: []
+category: Tooltip
+related: [HelpBox, SMSField, Dropdown, DropdownMobile, Portal, MobileView, ThemeProvider, ButtonIcon]
+tokens:
+  - --triplex-next-Tooltip-Background
+  - --triplex-next-Tooltip-Color
+  - --triplex-next-Tooltip-Link_Desktop_Color_Default
+  - --triplex-next-Tooltip-Link_Desktop_Color_Hover
+  - --triplex-next-Tooltip-Link_Desktop_Color_Active
+  - --triplex-next-Tooltip-Link_Desktop_Shadow_Focus
+  - --triplex-next-Tooltip-Link_Mobile_Color_Default
+  - --triplex-next-Tooltip-Link_Mobile_Color_Hover
+  - --triplex-next-Tooltip-Link_Mobile_Color_Active
+  - --triplex-next-Tooltip-Link_Mobile_Shadow_Focus
 stories: stories/Tooltip/Tooltip.stories.tsx
 version: "1.0"
 ---
@@ -13,242 +21,474 @@ version: "1.0"
 
 ## Назначение
 
-Всплывающая подсказка с автоматическим позиционированием
-(`above`/`below`/`right`/`left`) и адаптивным переключением desktop/mobile.
-Контент компонуется через слоты: `Target` (триггер) + `Body` (контент) +
-опционально `Link`, `XButton` (закрыть), `MobileHeader`. Управление —
-hover или click.
+Всплывающая подсказка, привязанная к целевому элементу. Рендерится через `Portal` — по умолчанию в `document.body`, либо в контейнер из `renderContainer` — и позиционируется относительно `targetRef`. На мобильной ширине экрана (<768px) вместо всплывающей подсказки открывается полноэкранный оверлей снизу на базе `DropdownMobile`.
 
-Используй когда: нужна подсказка возле элемента (label-описание, ошибка,
-информация). Для модальных диалогов — `Modal`. Для меню действий — `Dropdown`.
+Используй когда: нужно пояснить элемент интерфейса коротким текстом, при необходимости со ссылкой на подробное описание.
+Не используй когда:
+
+- нужна готовая иконка-вопрос с подсказкой и мобильным заголовком — используй `HelpBox` (обёртка над `Tooltip`);
+- нужно выпадающее меню или произвольный интерактивный блок — используй `Dropdown` / `ButtonDropdownExtended`;
+- содержимое подсказки требует фокусируемых элементов кроме `Tooltip.Link`: компонент не перехватывает фокус и не строит focus trap.
 
 ---
 
-## Файловая структура
+## Состав (compound-компонент)
 
-```text
-src/components/Tooltip/
-├── Tooltip.tsx                         # FC + Composition; MobileView switcher; Provider
-├── TootlipContext.ts                   # ITooltipContext (опечатка имени файла зафиксирована)
-├── enums.ts                            # ETooltipSize, ETooltipPreferPlace, ETooltipAlign + внутренние enum'ы позиционирования
-├── types.ts                            # все интерфейсы
-├── components/
-│   ├── common/
-│   │   ├── TooltipTarget.tsx           # клонирование child'а с onClick/onKeyDown
-│   │   ├── TooltipBody.tsx             # forwardRef<HTMLDivElement>; MobileView для Text-обёртки
-│   │   ├── TooltipLink.tsx
-│   │   └── TooltipXButton.tsx          # children: never
-│   ├── desktop/
-│   │   ├── TooltipDesktop.tsx
-│   │   └── components/                 # позиционирование, портал
-│   └── mobile/
-│       ├── TooltipMobile.tsx
-│       └── components/TooltipMobileHeader.tsx
-├── utils/
-│   ├── Positioning.ts                  # геометрия для desktop размещения
-│   └── useTooltipTheme.ts              # инжект темы в renderContainer
-├── styles/
-└── index.ts
-```
+Состав задаётся субкомпонентами внутри `children`. Компонент разбирает `children` **по типу элемента**, поэтому порядок в разметке не важен, а произвольные узлы (текст, `<div>`, фрагменты) просто игнорируются.
+
+| Субкомпонент | Обязателен | Что делает |
+|---|---|---|
+| `Tooltip.Target` | Да | Клонирует единственный дочерний элемент, навешивая обработчики открытия. Собственной разметки не рендерит |
+| `Tooltip.Body` | Практически всегда | Текст подсказки. На десктопе — `<div>`, в мобильной версии — `Text` (`ETextSize.B3`) |
+| `Tooltip.Link` | Нет | Гиперссылка под текстом. При `target="_blank"` сам подставляет `rel="noopener"` |
+| `Tooltip.XButton` | Нет | Кнопка закрытия. Её наличие добавляет корню класс `closable` (отступ справа у контента). В адаптивном режиме кнопка закрытия есть всегда, независимо от `Tooltip.XButton`, — он лишь передаёт ей свои props (в том числе `aria-label`) |
+| `Tooltip.MobileHeader` | Нет | Заголовок мобильной версии. На десктопе не рендерится |
 
 ---
 
-## Композиция
+## Варианты и props
 
-```tsx
-<Tooltip
-    targetRef={btnRef}
-    size={ETooltipSize.LG}
-    toggleType="hover"
-    preferPlace={ETooltipPreferPlace.ABOVE}
-    isOpen={open}
-    toggle={setOpen}
->
-    <Tooltip.Target>
-        <button ref={btnRef}>?</button>
-    </Tooltip.Target>
-    <Tooltip.Body>Подсказка</Tooltip.Body>
-    <Tooltip.Link href="/help">Подробнее</Tooltip.Link>
-    <Tooltip.XButton aria-label="Закрыть" />
-    <Tooltip.MobileHeader>Заголовок</Tooltip.MobileHeader>
-</Tooltip>
-```
+`ITooltipProps` расширяет `React.HTMLAttributes<HTMLDivElement>`. Неизвестные компоненту атрибуты уходят на корневой `<div>` десктопной подсказки (и на контейнер мобильного оверлея в адаптивном режиме). Исключение — `onKeyDown`: см. «Ограничения».
 
-Все слоты — статические свойства `Tooltip.X = X`. Дети распознаются по
-типу через `React.Children.map` (см. `getChildrenElements`); порядок
-расположения в JSX неважен.
+### Обязательные props
 
----
+| Prop | Тип | Описание |
+|---|---|---|
+| `size` | `ETooltipSize` | Ширина тела подсказки в десктопной версии: `SM` — 192px, `LG` — 384px. В мобильной версии не влияет ни на что |
+| `targetRef` | `React.MutableRefObject<HTMLElement \| null>` | Ссылка на целевой элемент. От его `getBoundingClientRect()` считается положение подсказки и на него вешаются hover-обработчики. Тот же ref нужно передать и в сам элемент внутри `Tooltip.Target` |
 
-## Публичный API
+### Опциональные props
 
-### `ITooltipProps`
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `toggleType` | `"hover" \| "click"` | — | Способ открытия. Без значения подсказка сама не открывается — состоянием управляет потребитель через `isOpen` |
+| `preferPlace` | `ETooltipPreferPlace` | — | Предпочитаемое место. Если подсказка туда не помещается, выбирается зона, где помещается. Без значения зона выбирается автоматически |
+| `alignTip` | `ETooltipAlign` | — | Принудительное выравнивание указателя (стрелочки): `START` / `END`. Без значения указатель центрируется по целевому элементу |
+| `isOpen` | `boolean` | — | Управляемый режим. Пока prop задан (в том числе `false`), внутреннее состояние открытости игнорируется |
+| `toggle` | `(open: boolean) => void` | — | Запрос на смену состояния. Вызывается всегда — и в управляемом, и в неуправляемом режиме |
+| `onShow` | `(node: HTMLDivElement) => void` | — | Вызывается при открытии, аргумент — DOM-нода подсказки (десктоп) или контентная нода оверлея (мобильная версия) |
+| `renderContainer` | `Element` | `document.body` | Контейнер портала для десктопной версии. Мобильная версия всегда рендерится в `document.body` |
+| `disableAdaptiveMode` | `boolean` | `false` | Отключает мобильную версию: подсказка остаётся всплывающей на любой ширине экрана |
+| `className` | `string` | — | Дополнительный класс на корневом элементе подсказки |
+
+### Ограничения
+
+- **`Tooltip` — не `forwardRef`-компонент.** Это провайдер контекста без собственной разметки: ссылка на подсказку отдаётся через `onShow`, ссылка на целевой элемент — это `targetRef` потребителя. `forwardRef` есть у `Tooltip.Body`, `Tooltip.Link` и внутреннего `TooltipDesktopTip`.
+- `Tooltip.Target` принимает **ровно один** React-элемент, который умеет принимать `onClick` / `onKeyDown`.
+- `Tooltip.XButton` не принимает `children` (`children?: never`) — иконка крестика внутри фиксированная.
+- `size`, `preferPlace`, `alignTip` и `renderContainer` действуют только в десктопной версии.
+- `onKeyDown`, переданный в `Tooltip`, на десктопе до корневого элемента подсказки не доходит: `TooltipDesktopBase` вырезает его из props и никуда не прокидывает. В адаптивном режиме он, наоборот, попадает на контейнер оверлея — поведение одного и того же prop в двух режимах различается. Клавиатурный обработчик вешай на элемент внутри `Tooltip.Target`.
+- `Tooltip.MobileHeader` подставляет кнопку закрытия сам, но слот `controlButtons` при этом остаётся открытым: переданное потребителем значение спредится **после** значения по умолчанию и молча заменяет кнопку закрытия. Сузить тип нельзя без breaking change — на это рассчитывать не стоит.
+- Компонент не хардкодит текст: `aria-label` для целевого элемента и для `Tooltip.XButton` передаёт потребитель (библиотека мультиязычная).
 
-```ts
-extends HTMLAttributes<HTMLDivElement>
-```
+---
 
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `size` | `ETooltipSize` (`SM` \| `LG`) | — | **Обязателен**. |
-| `targetRef` | `MutableRefObject<HTMLElement \| null>` | — | **Обязателен**. Ref на якорный элемент (используется для расчёта позиции). |
-| `toggleType?` | `"click" \| "hover"` | — | Способ открытия. Если не передан — Tooltip управляется только программно через `isOpen`/`toggle`. |
-| `preferPlace?` | `ETooltipPreferPlace` (`ABOVE`/`BELOW`/`LEFT`/`RIGHT`) | — | Предпочтительная сторона. Если не помещается — flip автоматически. |
-| `alignTip?` | `ETooltipAlign` (`START`/`CENTER`/`END`) | — | Выравнивание указателя относительно target'а. |
-| `renderContainer?` | `Element` | `document.body` | Контейнер для портала. На mobile с включённой адаптивностью — игнорируется (всегда `document.body`). |
-| `disableAdaptiveMode?` | `boolean` | `false` | Отключить переключение на mobile-вариант. |
-| `isOpen?` | `boolean` | — | Контролируемое открытие. Если не передан — внутренний `openState`. |
-| `toggle?` | `(open: boolean) => void` | — | Колбэк изменения. |
-| `onShow?` | `(node: HTMLDivElement) => void` | — | После появления tooltip-DOM. |
-| `children` | `ReactNode` | — | Слоты `Tooltip.*`. |
-
-### Слоты
-
-#### `Tooltip.Target`
-
-```ts
-{ children: ReactElement }   // ровно один React-элемент
+## Дизайн-токены
+
+```text
+--triplex-next-Tooltip-Background
+--triplex-next-Tooltip-Color
+--triplex-next-Tooltip-Link_Desktop_Color_Default
+--triplex-next-Tooltip-Link_Desktop_Color_Hover
+--triplex-next-Tooltip-Link_Desktop_Color_Active
+--triplex-next-Tooltip-Link_Desktop_Shadow_Focus
+--triplex-next-Tooltip-Link_Mobile_Color_Default
+--triplex-next-Tooltip-Link_Mobile_Color_Hover
+--triplex-next-Tooltip-Link_Mobile_Color_Active
+--triplex-next-Tooltip-Link_Mobile_Shadow_Focus
 ```
 
-Клонирует child через `React.cloneElement`, добавляя `onClick` и `onKeyDown`:
-- `onClick` (если `toggleType === "click"` или `hover` + не висим в hovered-состоянии): `setTooltipOpen(!tooltipOpen)`.
-- `onKeyDown TAB` при открытом — закрывает.
-- Существующие хендлеры на child'е сохраняются (вызываются после).
+Мобильная версия дополнительно наследует токены `DropdownMobile` (`--triplex-next-DropdownMobile-*`), так как построена на его субкомпонентах.
 
-#### `Tooltip.Body`
+---
 
-```ts
-extends HTMLAttributes<HTMLDivElement>
-```
+## Инварианты
+
+- Публичный barrel `src/components/Tooltip/index.ts` реэкспортирует `Tooltip`, `enums` и `types` целиком. Компонент используется внутри `HelpBox`, `SMSField.Tooltip` и косвенно (через типы) в `Dropdown`, поэтому удаление любого экспорта ломает библиотеку изнутри.
+- `IDropdownMobileHeaderProps` объявлен **в `src/components/Tooltip/types.ts`**, но используется `DropdownMobileHeader` из семейства `Dropdown`. Переносить тип нельзя без синхронной правки `Dropdown` (и это breaking change для deep-импортов).
+- Файл контекста называется `TootlipContext.ts` — опечатка в имени зафиксирована в публикуемых путях подпакета; переименование ломает deep-импорты потребителей.
+- `Tooltip` — `React.FC` со статическими субкомпонентами (`Tooltip.Target` и т.д.). Набор статических свойств — часть публичного API.
+- Разбор `children` по типу элемента (`child.type === TooltipTarget`) означает, что обёртка субкомпонента в собственный компонент-прокси **не сработает** — узел просто не попадёт ни в один слот. Это осознанное ограничение, на нём построен весь состав.
+- Десктопная версия отслеживает положение целевого элемента опросом с интервалом 200мс (`REFRESH_INTERVAL_MS`) плюс слушатели `scroll` / `resize`. Отписка в `componentWillUnmount` и при закрытии обязательна.
+- Анимации появления/исчезновения длятся 500мс (`ENTER_EXIT_TRANSITION_DURATION_MS`). На это же время завязано снятие класса темы в `useTooltipTheme` — значения нужно менять синхронно.
+- `useTooltipTheme` вешает класс темы на контейнер рендера и считает количество открытых подсказок в data-атрибуте `data-tooltip-theme-{scopeClassName}-counter`. Счётчик нужен, чтобы одна закрывшаяся подсказка не сняла тему у остальных.
+- `TooltipDesktop` и `TooltipDesktopBase` — классовые компоненты. Это исключение из правила «только функциональные компоненты» в `docs/ai/codestyle.md`: перевод на хуки затрагивает всю логику позиционирования и анимаций и требует отдельной задачи с визуальной регрессией.
+- Внутренние утилиты (`utils/Positioning.ts`, `utils/useTooltipTheme.ts`) через barrel не экспортируются.
 
-`forwardRef<HTMLDivElement>`. На desktop — `<div>`, на mobile — `<Text tag="div" size=B3 line=NORMAL>` (через `MobileView`).
+---
 
-#### `Tooltip.Link`
+## Accessibility
 
-```ts
-extends AnchorHTMLAttributes<HTMLAnchorElement>
-```
+- Собственных ARIA-ролей и атрибутов компонент **не выставляет** — ни `role="tooltip"`, ни `aria-describedby`. Связать целевой элемент с текстом подсказки должен потребитель (пример такой связки — `SMSField.Tooltip`, который прокидывает `id` подсказки в поле).
+- Целевой элемент отвечает за собственную доступность: он должен быть фокусируемым (`ButtonIcon` в примерах) и иметь `aria-label`, так как иконка-триггер не содержит текста.
+- Клавиатура: `Escape` закрывает подсказку (обработчик на `document`, пока она открыта), `Tab` с целевого элемента закрывает открытую подсказку. Собственных обработчиков `Enter` / `Space` у `Tooltip.Target` нет — открытие с клавиатуры работает через нативный клик кнопки.
+- Закрытие также срабатывает по `mousedown` вне подсказки и вне целевого элемента.
+- Открытие по наведению: подсказка закрывается не сразу после ухода курсора, а через 500мс — за это время курсор можно довести до самой подсказки (её нода тоже слушает `mouseenter`/`mouseleave`).
+- Фокус компонент не перехватывает и не возвращает: при открытии фокус остаётся на целевом элементе. Поэтому интерактивное содержимое сложнее `Tooltip.Link` в подсказку класть не стоит.
+- Мобильная версия — оверлей `DropdownMobile`; кнопке закрытия `aria-label` задаёт потребитель через props `Tooltip.XButton`. Кнопка там рендерится всегда, поэтому без `Tooltip.XButton` она остаётся без доступного имени — в адаптивном сценарии `Tooltip.XButton` с `aria-label` стоит передавать, даже если на десктопе крестик не нужен.
 
-Ссылка внутри tooltip'а.
+---
 
-#### `Tooltip.XButton`
+## Связанные компоненты
 
-```ts
-extends ButtonHTMLAttributes<HTMLButtonElement>
-{ children: never }
-```
+Отдельного AI.md нет ни у одного субкомпонента семейства — они описаны здесь.
+Это область задачи TRI-98 («Scope: только Tooltip»), а не вывод по критериям
+`docs/ai/CONTEXT.md` → «Когда создавать `{ComponentName}-ai.md`». По этим критериям
+собственного AI.md заслуживают разве что `HelpBox` (отдельная строка в ROADMAP),
+остальные части семейства — внутренние и через barrel не экспортируются.
 
-Кнопка закрытия (без своего content'а — рендерится X-иконка).
+**Части составного компонента (`components/common/`, `components/mobile/`):**
 
-#### `Tooltip.MobileHeader`
+- `TooltipTarget` — целевой элемент: `cloneElement` с обработчиками клика и `Tab`.
+- `TooltipBody` — тело подсказки; на мобильной ширине рендерится через `Text`.
+- `TooltipLink` — ссылка; защита от reverse tabnabbing через `getSafeRel`.
+- `TooltipXButton` — кнопка закрытия десктопной версии (обёртка над `ButtonIcon`).
+- `TooltipMobileHeader` — шапка мобильной версии; кнопку закрытия подставляет сам, наследуя props у `Tooltip.XButton`.
+- `TooltipMobileCloseButton` — кнопка закрытия мобильной версии (обёртка над `DropdownMobileClose`).
 
-```ts
-extends Omit<IDropdownMobileHeaderProps, "closeButton">
-{ controlButtons?: ReactNode }
-```
+**Десктопная версия (`components/desktop/`):**
 
-Заголовок мобильного полноэкранного варианта.
+- `TooltipDesktop` — подписки на события документа и целевого элемента (клик вне, Escape, hover).
+- `TooltipDesktopBase` — портал, расчёт положения, анимации.
+- `TooltipDesktopTip` — указатель (стрелочка) подсказки.
 
-### Enums
+**Инфраструктура:**
 
-- `ETooltipSize`: `SM` | `LG`
-- `ETooltipPreferPlace`: `ABOVE` | `BELOW` | `RIGHT` | `LEFT`
-- `ETooltipAlign`: `START` | `CENTER` | `END`
-- `ETooltipDirection`: `UP` | `DOWN` | `LEFT` | `RIGHT` (для указателя)
+- `TooltipContext` (`TootlipContext.ts`) — разобранные слоты, состояние открытости и сеттер между частями.
+- `utils/Positioning.ts` — чистые функции выбора зоны и расчёта координат.
+- `utils/useTooltipTheme.ts` — класс темы на контейнере портала со счётчиком использования.
+- `Portal`, `MobileView`, `DropdownMobile` — инфраструктура рендера.
 
-Внутренние enum'ы (`ETooltipAxesType`, `ETooltipFlowTypes`, `ETooltipStartCoordinates`, `ETooltipEndCoordinates`, `ETooltipSizeParameter`, `ETooltipTypeName`) — экспортированы, но используются в основном `Positioning.ts`.
+**Потребители внутри библиотеки:**
+
+- `HelpBox` — готовая иконка-подсказка поверх `Tooltip`.
+- `SMSField.Tooltip` — подсказка об ошибке у поля СМС-кода.
 
 ---
 
-## Контекст (`TooltipContext`)
+## Stories
 
-```ts
-{
-    elements: ITooltipElements;     // распознанные слоты
-    tooltipOpen: boolean;
-    setTooltipOpen(open): void;
-    targetHoveredRef: MutableRefObject<boolean>;
-    toggleType?: TTooltipToggleType;
-}
-```
+Основные истории: `stories/Tooltip/Tooltip.stories.tsx`
+Файлы примеров: `stories/Tooltip/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `size`, `toggleType`, `preferPlace`, `alignTip`, адаптивного режима и состава |
+| `Default` | `Default.tsx` | Минимальный состав: целевой элемент и текст, открытие по наведению |
+| `Sizes` | `Sizes.tsx` | Размеры SM (192px) и LG (384px) |
+| `DifferentPlaces` | `DifferentPlaces.tsx` | Все варианты `preferPlace` |
+| `WithLink` | `WithLink.tsx` | Ссылка `Tooltip.Link` под текстом |
+| `WithCloseButton` | `WithCloseButton.tsx` | Кнопка закрытия `Tooltip.XButton` |
+| `MobileHeader` | `MobileHeader.tsx` | Заголовок адаптивной версии (виден на узком экране) |
+| `RenderContainer` | `RenderContainer.tsx` | Рендер подсказки в заданный DOM-элемент |
+| `VisualTests` | `VisualTests.tsx` | `alignTip: start`, `alignTip: end`, широкая подсказка с длинным текстом, ссылкой и кнопкой закрытия |
+
+---
+
+## История изменений
 
-`elements.body/link/closeButton/mobileHeader/target` — `null` или `ReactElement`.
-`getChildrenElements` распознаёт child'ов по `child.type === TooltipTarget` и т.п.
+| Дата | Изменение |
+|---|---|
+| 2026-08-03 | Создан документ AI-ready для `Tooltip` (TRI-98). |
+| 2026-08-03 | AI-рефакторинг: разбор `children` вынесен в чистую функцию и мемоизирован, значение контекста стабилизировано, дедуплицирована разметка `TooltipLink`, `switch` в `TooltipDesktopTip` заменён на маппинг, из `calcRelPos` убрано двойное приведение типов, в `useTooltipTheme` вынесен хелпер имени счётчика и добавлен guard на unmount, `displayName` `TooltipDesktopBase` приведён к имени класса, JSDoc на props и приватных методах. Исправлено: подсказка, смонтированная сразу открытой (`isOpen` в управляемом режиме), не закрывалась по действию мышью вне неё — при монтировании вешался слушатель `click`, а снимался `mousedown`. Публичный API не изменён. Добавлены unit-тесты и stories по modern pattern. |
+| 2026-08-03 | Правки по ревью PR #496. Исправлено: класс темы не снимается с контейнера, если в течение задержки закрытия подсказку открыли снова или контейнер занял другой `Tooltip` (в `useTooltipTheme` появились учёт собственного инкремента и перепроверка счётчика). Исправлено: в адаптивном режиме `size` и `alignTip` больше не уходят в DOM (React предупреждал о нераспознанном атрибуте `alignTip`). Исправлено: при размонтировании открытой подсказки с `toggleType="hover"` обработчики наведения снимаются и с самой подсказки. В `collectTooltipElements` приведения через `as` заменены на typed-guard'ы. Публичный API не изменён. |
+| 2026-08-03 | Правки по второму ревью PR #496 (документация и stories, кода не касаются): в «Ограничения» добавлено, что `onKeyDown` на десктопе не доходит до корневого элемента подсказки, а в адаптивном режиме доходит; уточнено, что в адаптивном режиме кнопка закрытия рендерится всегда и без `Tooltip.XButton` остаётся без `aria-label`; в `VisualTests` добавлен блок с `alignTip: end` — раньше это значение enum не было покрыто ни примером, ни тестом. |
+| 2026-08-03 | Правки по третьему ревью PR #496. Исправлено: при смене `toggleType` на лету hover-обработчики синхронизируются и на самой подсказке, а не только на целевом элементе (`setTooltipRef` повторно не вызывается, поэтому раньше на ноде подсказки оставались устаревшие слушатели). Тесты: `Tooltip.Link` в десктопном хелпере вынесен в прямые дети `Tooltip` — раньше слот `elements.link` не исполнялся ни в одном десктопном кейсе; добавлены кейсы на ветку `disableAdaptiveMode`. Публичный API не изменён. |
 
 ---
 
-## Поведение
+## Примеры использования
 
-### Адаптивность
+### Default
 
-- `useMatchMedia(max-width: SM_MAX)` — определяет mobile.
-- `disableAdaptiveMode === true` → всегда desktop.
-- Иначе — `<MobileView fallback={Desktop}>{Mobile}</MobileView>`.
+`stories/Tooltip/examples/Default.tsx`
 
-### Контролируемое vs неконтролируемое
+```tsx
+import React, { useRef } from "react";
+import { QuestioncircleFilledSrvIcon16 } from "@sberbusiness/icons-next";
+import { ButtonIcon, ETooltipPreferPlace, ETooltipSize, Tooltip } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const targetRef = useRef<HTMLButtonElement | null>(null);
+
+    return (
+        <div style={{ display: "flex", justifyContent: "center", padding: "80px 0" }}>
+            <Tooltip
+                size={ETooltipSize.SM}
+                toggleType="hover"
+                preferPlace={ETooltipPreferPlace.BELOW}
+                targetRef={targetRef}
+            >
+                <Tooltip.Target>
+                    <ButtonIcon aria-label="Показать подсказку" ref={targetRef}>
+                        <QuestioncircleFilledSrvIcon16 paletteIndex={5} />
+                    </ButtonIcon>
+                </Tooltip.Target>
+                <Tooltip.Body>Текст подсказки</Tooltip.Body>
+            </Tooltip>
+        </div>
+    );
+};
+```
 
-- `isOpen` передан → контролируемое (внешний state). `setTooltipOpen` только зовёт `toggle?.(nextOpen)`, не пишет в `openState`.
-- `isOpen` не передан → внутренний `openState`.
-- Сброс `targetHoveredRef.current = false` при `openProp === false` (через `useEffect`) — чтобы повторный hover после программного закрытия снова открывал tooltip.
+### Sizes
 
-### `useTooltipTheme(open, container)`
+`stories/Tooltip/examples/Sizes.tsx`
 
-Инжектит тему (CSS-переменные) в `renderContainer` (или `document.body`),
-чтобы tooltip-портал имел тот же стиль, что и текущий `ThemeProvider`.
+```tsx
+import React, { useRef } from "react";
+import { QuestioncircleFilledSrvIcon16 } from "@sberbusiness/icons-next";
+import { ButtonIcon, ETooltipPreferPlace, ETooltipSize, Tooltip } from "@sberbusiness/triplex-next";
 
-### Targeting
+const TEXT_BY_SIZE: Record<ETooltipSize, string> = {
+    [ETooltipSize.SM]: "Узкая подсказка шириной 192 пикселя.",
+    [ETooltipSize.LG]: "Широкая подсказка шириной 384 пикселя. Подходит для текста в несколько строк.",
+};
 
-- `targetRef` обязателен — без него desktop-позиционирование не сработает.
-- `toggleType: "hover"` — открывает на hover target'а; `"click"` — на клик.
-- Без `toggleType` — tooltip управляется только через `isOpen`/`toggle` (полностью контролируемый сценарий).
+interface ISizeItemProps {
+    size: ETooltipSize;
+}
 
----
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const targetRef = useRef<HTMLButtonElement | null>(null);
+
+    return (
+        <div style={{ display: "flex", alignItems: "center", gap: "16px", padding: "64px 0" }}>
+            <div style={{ fontSize: "16px", fontWeight: "700", width: "40px" }}>{size.toUpperCase()}</div>
+            <Tooltip
+                size={size}
+                toggleType="hover"
+                preferPlace={ETooltipPreferPlace.BELOW}
+                // Подсказка открыта постоянно, чтобы в примере были видны оба размера сразу.
+                isOpen
+                // Размер влияет только на десктопную версию: в адаптиве подсказка занимает всю ширину экрана.
+                disableAdaptiveMode
+                targetRef={targetRef}
+            >
+                <Tooltip.Target>
+                    <ButtonIcon aria-label={`Подсказка размера ${size}`} ref={targetRef}>
+                        <QuestioncircleFilledSrvIcon16 paletteIndex={5} />
+                    </ButtonIcon>
+                </Tooltip.Target>
+                <Tooltip.Body>{TEXT_BY_SIZE[size]}</Tooltip.Body>
+            </Tooltip>
+        </div>
+    );
+};
+
+const SIZES = Object.values(ETooltipSize);
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
+```
 
-## Инварианты
+### DifferentPlaces
 
-- **`Tooltip` — `FC` + composition** (`Tooltip.Target = TooltipTarget` и т.д.).
-- **`TooltipTarget` — `FC`**, ожидает **ровно одного** child'а (`React.Children.only`); должен быть `ReactElement` (не string/number).
-- **`TooltipBody` — `forwardRef<HTMLDivElement>`** — не убирать.
-- **Слоты распознаются по типу** (`child.type === TooltipTarget`) — нельзя оборачивать слоты в Fragment'ы или HOC'и (потеряется тип).
-- **`size` и `targetRef` обязательны** — проверять при использовании.
-- **Файл контекста назван `TootlipContext.ts`** (опечатка) — менять имя считается breaking change для импортов.
-- **`renderContainer` игнорируется в mobile + adaptiveMode** — всегда `document.body` (для полноэкранного листа).
-- **`toggleType === "hover"` использует `targetHoveredRef`**, чтобы не дёргать toggle при движении внутри target'а; при `isOpen=false` извне ref сбрасывается.
-- **На desktop body — `<div>`, на mobile — `<Text tag="div" size=B3>`** (через MobileView). Стили совпадают по className, но обёртка разная.
-- **`XButton.children: never`** — иконка X встроена, не передавать content.
-- **Все enum'ы экспортируются** — часть публичного API.
+`stories/Tooltip/examples/DifferentPlaces.tsx`
 
----
+```tsx
+import React, { useRef } from "react";
+import { QuestioncircleFilledSrvIcon16 } from "@sberbusiness/icons-next";
+import { ButtonIcon, ETooltipPreferPlace, ETooltipSize, Tooltip } from "@sberbusiness/triplex-next";
 
-## Accessibility
+interface IPlaceItemProps {
+    place: ETooltipPreferPlace;
+}
+
+const PlaceItem = ({ place }: IPlaceItemProps) => {
+    const targetRef = useRef<HTMLButtonElement | null>(null);
+
+    return (
+        <div style={{ display: "flex", alignItems: "center", gap: "16px", padding: "64px 0" }}>
+            <div style={{ fontSize: "16px", fontWeight: "700", width: "56px" }}>{place}</div>
+            <Tooltip
+                size={ETooltipSize.SM}
+                toggleType="hover"
+                preferPlace={place}
+                // Подсказки открыты постоянно, чтобы в примере были видны все варианты расположения сразу.
+                isOpen
+                // preferPlace влияет только на десктопную версию: в адаптиве подсказка открывается снизу экрана.
+                disableAdaptiveMode
+                targetRef={targetRef}
+            >
+                <Tooltip.Target>
+                    <ButtonIcon aria-label={`Подсказка ${place}`} ref={targetRef}>
+                        <QuestioncircleFilledSrvIcon16 paletteIndex={5} />
+                    </ButtonIcon>
+                </Tooltip.Target>
+                <Tooltip.Body>Расположение {place}</Tooltip.Body>
+            </Tooltip>
+        </div>
+    );
+};
+
+const PLACES = Object.values(ETooltipPreferPlace);
+
+export const DifferentPlaces = () => (
+    <div style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
+        {PLACES.map((place) => (
+            <PlaceItem key={place} place={place} />
+        ))}
+    </div>
+);
+```
 
-- `Tooltip.Target` — потребитель сам ставит `aria-describedby`/`aria-haspopup` на child-элементе (компонент это не делает автоматически — TODO).
-- TAB на target при открытом tooltip — закрывает (clean-up для tab-навигации).
-- `XButton` — `<button>`, `aria-label` ставит потребитель (через `aria-label="Закрыть"`).
-- Mobile-вариант — полноэкранный лист (управляется фокусом через `MobileHeader`/`closeButton`).
-- На hover-tooltip'ах screen-reader пользователи не видят содержимое — для критичной информации использовать `role="status"` или дублировать в `aria-describedby`.
+### WithLink
 
----
+`stories/Tooltip/examples/WithLink.tsx`
 
-## Связанные компоненты
+```tsx
+import React, { useRef } from "react";
+import { QuestioncircleFilledSrvIcon16 } from "@sberbusiness/icons-next";
+import { ButtonIcon, ETooltipPreferPlace, ETooltipSize, Tooltip } from "@sberbusiness/triplex-next";
+
+export const WithLink = () => {
+    const targetRef = useRef<HTMLButtonElement | null>(null);
+
+    return (
+        <div style={{ display: "flex", justifyContent: "center", paddingBottom: "160px" }}>
+            <Tooltip
+                size={ETooltipSize.LG}
+                toggleType="click"
+                preferPlace={ETooltipPreferPlace.BELOW}
+                // Подсказка открыта постоянно, чтобы в примере была видна ссылка.
+                isOpen
+                disableAdaptiveMode
+                targetRef={targetRef}
+            >
+                <Tooltip.Target>
+                    <ButtonIcon aria-label="Показать подсказку" ref={targetRef}>
+                        <QuestioncircleFilledSrvIcon16 paletteIndex={5} />
+                    </ButtonIcon>
+                </Tooltip.Target>
+                <Tooltip.Body>Ссылка ведёт на страницу с подробным описанием.</Tooltip.Body>
+                <Tooltip.Link href="https://triplex-design.ru" target="_blank">
+                    Подробнее
+                </Tooltip.Link>
+            </Tooltip>
+        </div>
+    );
+};
+```
 
-- `MobileView` / `useMatchMedia` — переключение desktop/mobile.
-- `Dropdown` — для меню/списков (другая UX-семантика).
-- `Typography.Text` — обёртка body на mobile.
-- `ThemeProvider` (через `useTooltipTheme`) — наследование темы в портал.
-- `IDropdownMobileHeaderProps` — родитель для `ITooltipMobileHeaderProps`.
+### WithCloseButton
 
----
+`stories/Tooltip/examples/WithCloseButton.tsx`
 
-## Stories
+```tsx
+import React, { useRef, useState } from "react";
+import { QuestioncircleFilledSrvIcon16 } from "@sberbusiness/icons-next";
+import { ButtonIcon, ETooltipPreferPlace, ETooltipSize, Tooltip } from "@sberbusiness/triplex-next";
+
+export const WithCloseButton = () => {
+    const targetRef = useRef<HTMLButtonElement | null>(null);
+    const [opened, setOpened] = useState(true);
+
+    return (
+        <div style={{ display: "flex", justifyContent: "center", paddingBottom: "160px" }}>
+            <Tooltip
+                size={ETooltipSize.LG}
+                toggleType="click"
+                preferPlace={ETooltipPreferPlace.BELOW}
+                isOpen={opened}
+                toggle={setOpened}
+                disableAdaptiveMode
+                targetRef={targetRef}
+            >
+                <Tooltip.Target>
+                    <ButtonIcon aria-label="Показать подсказку" ref={targetRef}>
+                        <QuestioncircleFilledSrvIcon16 paletteIndex={5} />
+                    </ButtonIcon>
+                </Tooltip.Target>
+                <Tooltip.Body>
+                    Подсказку с кнопкой закрытия пользователь закрывает сам — по клику на крестик, по Escape или по
+                    клику вне подсказки.
+                </Tooltip.Body>
+                <Tooltip.XButton aria-label="Закрыть подсказку" />
+            </Tooltip>
+        </div>
+    );
+};
+```
 
-Основные истории: `stories/Tooltip/Tooltip.stories.tsx`
-Примеры: `stories/Tooltip/examples/`
+### MobileHeader
 
----
+`stories/Tooltip/examples/MobileHeader.tsx`
 
-## История изменений
+```tsx
+import React, { useRef } from "react";
+import { QuestioncircleFilledSrvIcon16 } from "@sberbusiness/icons-next";
+import { ButtonIcon, ETooltipPreferPlace, ETooltipSize, Tooltip } from "@sberbusiness/triplex-next";
+
+export const MobileHeader = () => {
+    const targetRef = useRef<HTMLButtonElement | null>(null);
+
+    return (
+        <div style={{ display: "flex", justifyContent: "center", padding: "80px 0" }}>
+            <Tooltip
+                size={ETooltipSize.SM}
+                toggleType="hover"
+                preferPlace={ETooltipPreferPlace.BELOW}
+                targetRef={targetRef}
+            >
+                <Tooltip.Target>
+                    <ButtonIcon aria-label="Показать подсказку" ref={targetRef}>
+                        <QuestioncircleFilledSrvIcon16 paletteIndex={5} />
+                    </ButtonIcon>
+                </Tooltip.Target>
+                <Tooltip.Body>Текст подсказки</Tooltip.Body>
+                <Tooltip.XButton aria-label="Закрыть подсказку" />
+                <Tooltip.MobileHeader>Заголовок для адаптивного режима</Tooltip.MobileHeader>
+            </Tooltip>
+        </div>
+    );
+};
+```
+
+### RenderContainer
+
+`stories/Tooltip/examples/RenderContainer.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import { QuestioncircleFilledSrvIcon16 } from "@sberbusiness/icons-next";
+import { ButtonIcon, ETooltipPreferPlace, ETooltipSize, Tooltip } from "@sberbusiness/triplex-next";
+
+export const RenderContainer = () => {
+    const targetRef = useRef<HTMLButtonElement | null>(null);
+    // Callback-ref вместо useEffect: контейнер попадает в state сразу после монтирования.
+    const [container, setContainer] = useState<HTMLElement | null>(null);
+
+    return (
+        <div style={{ display: "flex", justifyContent: "center", paddingBottom: "160px" }}>
+            <div ref={setContainer} />
+
+            {container ? (
+                <Tooltip
+                    size={ETooltipSize.SM}
+                    toggleType="click"
+                    preferPlace={ETooltipPreferPlace.BELOW}
+                    renderContainer={container}
+                    // Подсказка открыта постоянно, чтобы её было видно в примере.
+                    isOpen
+                    disableAdaptiveMode
+                    targetRef={targetRef}
+                >
+                    <Tooltip.Target>
+                        <ButtonIcon aria-label="Показать подсказку" ref={targetRef}>
+                            <QuestioncircleFilledSrvIcon16 paletteIndex={5} />
+                        </ButtonIcon>
+                    </Tooltip.Target>
+                    <Tooltip.Body>Подсказка отрендерена в заданный контейнер.</Tooltip.Body>
+                </Tooltip>
+            ) : null}
+        </div>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |