@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 0.36.0-beta0

package/bundle/components/HelpBox.md

@@ -1,8 +1,6 @@
 ---
 component: HelpBox
 category: HelpBox
-figma-node: ""
-figma-file: ""
 related: [Tooltip, ButtonIcon, MobileView, FocusTrap]
 tokens: []
 stories: stories/HelpBox/HelpBox.stories.tsx
@@ -13,25 +11,10 @@ version: "1.0"
 
 ## Назначение
 
-Иконка "?" (`QuestioncircleFilledSrvIcon16`) с всплывающей подсказкой (Tooltip).
-Объединяет ButtonIcon-триггер, Tooltip и FocusTrap в одном компоненте.
+Иконка «?» (`QuestioncircleFilledSrvIcon16`) с всплывающей подсказкой (`Tooltip`). Объединяет `ButtonIcon`-триггер, `Tooltip` и `FocusTrap` в одном компоненте.
 
 Используй когда: нужна контекстная подсказка рядом с элементом интерфейса.
-Не используй когда: нужен полноценный попап с формой или сложным контентом — используй Dropdown или Modal.
-
----
-
-## Файловая структура
-
-```text
-src/components/HelpBox/
-├── HelpBox.tsx                   # Основной компонент
-├── index.ts                      # Barrel export
-├── styles/
-│   └── HelpBox.module.less       # Минимальные стили (position, vertical-align)
-└── __tests__/
-    └── HelpBox.test.tsx          # Unit-тесты
-```
+Не используй когда: нужен полноценный попап с формой или сложным контентом — используй `Dropdown` или `Modal`.
 
 ---
 
@@ -48,7 +31,7 @@ src/components/HelpBox/
 
 | Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `isOpen` | `boolean` | `undefined` | Управляемое состояние открытия тултипа |
+| `isOpen` | `boolean` | — | Управляемое состояние открытия тултипа |
 | `toggle` | `(open: boolean) => void` | — | Callback при открытии/закрытии |
 | `onShow` | `(node: HTMLDivElement) => void` | — | Callback при появлении тултипа в DOM |
 | `preferPlace` | `ETooltipPreferPlace` | — | Предпочтительное расположение: `ABOVE`, `BELOW`, `LEFT`, `RIGHT` |
@@ -61,46 +44,11 @@ src/components/HelpBox/
 | `className` | `string` | — | CSS-класс, пробрасывается на кнопку-триггер |
 | `...rest` | `React.HTMLAttributes<HTMLButtonElement>` | — | Все стандартные атрибуты `<button>`, включая `aria-label`, пробрасываются на кнопку-триггер |
 
-### Controlled / Uncontrolled
+### Ограничения использования
 
-- **Uncontrolled** (по умолчанию): `isOpen` не передан — компонент сам управляет `openState`.
-- **Controlled**: передай `isOpen` + `toggle` — компонент не меняет внутреннее состояние.
-
----
-
-## Ключевые особенности реализации
-
-### Композиция внутренних компонентов
-
-HelpBox — обёртка над несколькими внутренними компонентами:
-- `ButtonIcon` (shape=CIRCLE) — кнопка-триггер с иконкой `QuestioncircleFilledSrvIcon16`
-- `Tooltip` (toggleType="hover", role="dialog") — всплывающая подсказка
-- `FocusTrap` (только desktop, через `MobileView`) — ловушка фокуса при открытом тултипе
-- `TooltipMobileHeader` — заголовок мобильной версии (рендерится только при наличии `mobileHeaderContent`)
-
-### FocusTrap
-
-Ловушка фокуса активируется только на desktop (через `MobileView` fallback). При открытии:
-- `initialFocus` — элемент Tooltip (по ID)
-- `clickOutsideDeactivates: true` — клик за пределами закрывает
-- `preventScroll: true`
-
-Потребитель может расширить настройки через `focusTrapProps.focusTrapOptions`.
-
-### Ref forwarding
-
-`forwardRef` пробрасывает ref на внутренний `ButtonIcon` (кнопку-триггер). Внутренний `buttonRef` используется для позиционирования Tooltip через `targetRef`.
-
----
-
-## Accessibility
-
-- Кнопка-триггер — нативный `<button>` через `ButtonIcon`, shape `CIRCLE`.
-- **`aria-label` триггера** — не захардкожен. Потребитель **обязан** передать `aria-label` через `...rest` (например, `aria-label="Подсказка"`). Библиотека мультиязычная, текст не хардкодится.
-- **`aria-label` кнопки закрытия** — передаётся через `tooltipXButtonProps={{ "aria-label": "Закрыть" }}`. Потребитель **обязан** указать значение на своём языке.
-- Tooltip открывается с `role="dialog"`, `tabIndex={-1}`.
-- FocusTrap удерживает фокус внутри открытого тултипа на desktop.
-- `tooltipAriaAttributes` позволяет добавить aria-атрибуты к контейнеру Tooltip.
+- **Controlled / Uncontrolled**: если `isOpen` не передан — компонент сам управляет `openState`. При передаче `isOpen` обязательно передавать `toggle`, иначе компонент не сможет переключать состояние.
+- `forwardRef` пробрасывает `ref` на внутренний `ButtonIcon` (кнопку-триггер). Внутренний `buttonRef` используется для позиционирования Tooltip через `targetRef`.
+- HelpBox — обёртка над несколькими внутренними компонентами: `ButtonIcon` (`shape=CIRCLE`), `Tooltip` (`toggleType="hover"`, `role="dialog"`), `FocusTrap` (только desktop) и опциональный `TooltipMobileHeader` (рендерится только при наличии `mobileHeaderContent`).
 
 ---
 
@@ -120,30 +68,41 @@ HelpBox — обёртка над несколькими внутренними
 
 ---
 
+## Accessibility
+
+- Кнопка-триггер — нативный `<button>` через `ButtonIcon`, `shape=CIRCLE`.
+- **`aria-label` триггера** — не захардкожен. Потребитель **обязан** передать `aria-label` через `...rest` (например, `aria-label="Подсказка"`). Библиотека мультиязычная, текст не хардкодится.
+- **`aria-label` кнопки закрытия** — передаётся через `tooltipXButtonProps={{ "aria-label": "Закрыть" }}`. Потребитель **обязан** указать значение на своём языке.
+- Tooltip открывается с `role="dialog"`, `tabIndex={-1}`.
+- FocusTrap удерживает фокус внутри открытого тултипа на desktop. При активации: `initialFocus` — элемент Tooltip (по ID), `clickOutsideDeactivates: true` — клик за пределами закрывает, `preventScroll: true`. Потребитель может расширить настройки через `focusTrapProps.focusTrapOptions`.
+- `tooltipAriaAttributes` позволяет добавить aria-атрибуты к контейнеру Tooltip.
+
+---
+
 ## Связанные компоненты
 
-- `Tooltip` (`src/components/Tooltip/`) — всплывающая подсказка, основной визуальный элемент
-- `ButtonIcon` (`src/components/Button/ButtonIcon.tsx`) — кнопка-триггер
-- `MobileView` (`src/components/MobileView/`) — переключение desktop/mobile поведения
-- `FocusTrap` (npm: `focus-trap-react`) — ловушка фокуса для desktop
+- `Tooltip` (`src/components/Tooltip/`) — всплывающая подсказка, основной визуальный элемент.
+- `ButtonIcon` (`src/components/Button/ButtonIcon.tsx`) — кнопка-триггер.
+- `MobileView` (`src/components/MobileView/`) — переключение desktop/mobile поведения.
+- `FocusTrap` (npm: `focus-trap-react`) — ловушка фокуса для desktop.
 
 ---
 
 ## Stories
 
-`stories/HelpBox/HelpBox.stories.tsx`
+Основные истории: `stories/HelpBox/HelpBox.stories.tsx`
 Файлы примеров: `stories/HelpBox/examples/`
 
 | Story | Example file | Что демонстрирует |
 |---|---|---|
-| `Playground` | — | Интерактивный контроль всех props (inline в `*.stories.tsx`) |
-| `Default` | `DefaultExample.tsx` | Минимальное использование |
-| `Sizes` | `SizesExample.tsx` | Размеры тултипа SM / LG |
-| `Placement` | `PlacementExample.tsx` | Расположение: above, below, left, right |
-| `WithMobileHeader` | `WithMobileHeaderExample.tsx` | Мобильный заголовок |
-| `Controlled` | `ControlledExample.tsx` | Управляемое состояние (isOpen + toggle) |
-| `ChangeIconProps` | `ChangeIconPropsExample.tsx` | Кастомизация иконки через iconProps |
-| `VisualTests` | — | Скриншот-тест с открытым тултипом (inline в `*.stories.tsx`) |
+| `Playground` | — | Интерактивный контроль всех props |
+| `Default` | `Default.tsx` | Минимальное использование |
+| `Sizes` | `Sizes.tsx` | Размеры тултипа `SM` / `LG` |
+| `Placement` | `Placement.tsx` | Расположение: above, below, left, right |
+| `WithMobileHeader` | `WithMobileHeader.tsx` | Мобильный заголовок |
+| `Controlled` | `Controlled.tsx` | Управляемое состояние (`isOpen` + `toggle`) |
+| `ChangeIconProps` | `ChangeIconProps.tsx` | Кастомизация иконки через `iconProps` |
+| `VisualTests` | — | Скриншот-тест с открытым тултипом |
 
 ---
 
@@ -152,6 +111,8 @@ HelpBox — обёртка над несколькими внутренними
 | Дата | Изменение |
 |---|---|
 | 2026-04-08 | Создан документ. Добавлен `forwardRef`. |
+| 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убраны секции «Файловая структура» и «Ключевые особенности реализации», их содержимое перенесено в `Ограничения использования` и `Accessibility`, переставлены секции, добавлена колонка `Example file`. |
+| 2026-07-08 | Актуализирована колонка `Example file`: имена файлов примеров приведены к фактическим (без постфикса `Example`). |
 
 ---
 
@@ -159,13 +120,13 @@ HelpBox — обёртка над несколькими внутренними
 
 ### Default
 
-`stories/HelpBox/examples/DefaultExample.tsx`
+`stories/HelpBox/examples/Default.tsx`
 
 ```tsx
 import React from "react";
 import { HelpBox, ETooltipSize } from "@sberbusiness/triplex-next";
 
-export const DefaultExample = () => (
+export const Default = () => (
     <div style={{ padding: 50 }}>
         <HelpBox tooltipSize={ETooltipSize.SM} aria-label="Подсказка" tooltipXButtonProps={{ "aria-label": "Закрыть" }}>
             Подсказка по элементу интерфейса
@@ -176,13 +137,13 @@ export const DefaultExample = () => (
 
 ### Sizes
 
-`stories/HelpBox/examples/SizesExample.tsx`
+`stories/HelpBox/examples/Sizes.tsx`
 
 ```tsx
 import React from "react";
 import { HelpBox, ETooltipSize, ETooltipPreferPlace } from "@sberbusiness/triplex-next";
 
-export const SizesExample = () => (
+export const Sizes = () => (
     <div style={{ padding: 50, display: "flex", gap: 100 }}>
         <div>
             <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>SM</div>
@@ -212,13 +173,13 @@ export const SizesExample = () => (
 
 ### Placement
 
-`stories/HelpBox/examples/PlacementExample.tsx`
+`stories/HelpBox/examples/Placement.tsx`
 
 ```tsx
 import React from "react";
 import { HelpBox, ETooltipSize, ETooltipPreferPlace } from "@sberbusiness/triplex-next";
 
-export const PlacementExample = () => (
+export const Placement = () => (
     <div style={{ padding: 50, display: "grid", gridTemplateColumns: "repeat(2, minmax(120px, 1fr))", gap: 32 }}>
         <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
             <span style={{ width: 150 }}>above</span>
@@ -270,13 +231,13 @@ export const PlacementExample = () => (
 
 ### WithMobileHeader
 
-`stories/HelpBox/examples/WithMobileHeaderExample.tsx`
+`stories/HelpBox/examples/WithMobileHeader.tsx`
 
 ```tsx
 import React from "react";
 import { HelpBox, ETooltipSize } from "@sberbusiness/triplex-next";
 
-export const WithMobileHeaderExample = () => (
+export const WithMobileHeader = () => (
     <div style={{ padding: 50 }}>
         <HelpBox
             tooltipSize={ETooltipSize.SM}
@@ -292,13 +253,13 @@ export const WithMobileHeaderExample = () => (
 
 ### Controlled
 
-`stories/HelpBox/examples/ControlledExample.tsx`
+`stories/HelpBox/examples/Controlled.tsx`
 
 ```tsx
 import React, { useState } from "react";
 import { HelpBox, ETooltipSize, ETooltipPreferPlace } from "@sberbusiness/triplex-next";
 
-export const ControlledExample = () => {
+export const Controlled = () => {
     const [open, setOpen] = useState(false);
 
     const handleToggle = (nextOpen: boolean) => setOpen(nextOpen);
@@ -330,13 +291,13 @@ export const ControlledExample = () => {
 
 ### ChangeIconProps
 
-`stories/HelpBox/examples/ChangeIconPropsExample.tsx`
+`stories/HelpBox/examples/ChangeIconProps.tsx`
 
 ```tsx
 import React from "react";
 import { HelpBox, ETooltipSize } from "@sberbusiness/triplex-next";
 
-export const ChangeIconPropsExample = () => (
+export const ChangeIconProps = () => (
     <div style={{ padding: 50 }}>
         <HelpBox
             tooltipSize={ETooltipSize.SM}