@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 1.40.0-beta

package/bundle/components/ButtonDropdownExtended.md

@@ -0,0 +1,422 @@
+---
+component: ButtonDropdownExtended
+category: Buttons
+related: [ButtonDropdown, Button, Dropdown, DropdownList]
+tokens: []
+stories: stories/Buttons/ButtonDropdownExtended.stories.tsx
+version: "1.0"
+---
+
+# ButtonDropdownExtended
+
+## Назначение
+
+Низкоуровневый контейнер «кнопка + выпадающий блок». Сам ничего не рисует: кнопку и содержимое выпадающего блока задаёт потребитель через render-функции `renderButton` и `renderDropdown`. Компонент берёт на себя только состояние открытости и закрытие блока по Escape, по Tab (при `closeOnTab`) и по клику/тапу вне кнопки и вне блока.
+
+Используй когда: нужен собственный триггер и/или произвольное содержимое выпадающего блока (форма, фильтр, кастомный список), а логику открытия/закрытия переиспользовать.
+Не используй когда: нужен готовый список действий — используй `ButtonDropdown`, он построен поверх этого компонента.
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `renderButton` | `(props: IButtonDropdownExtendedButtonProvideProps) => React.ReactNode` | Отрисовка кнопки-триггера. Получает `opened` и `setOpened` |
+| `renderDropdown` | `(props: IButtonDropdownExtendedDropdownProvideProps) => React.ReactNode` | Отрисовка выпадающего блока. Дополнительно получает `className` внутреннего позиционирующего класса |
+| `dropdownRef` | `React.RefObject<HTMLElement>` | Ссылка на DOM-элемент выпадающего блока. Нужна для click-outside: клик внутри этого элемента не закрывает блок |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `opened` | `boolean` | — | Внешнее состояние открытости. Включает контролируемый режим |
+| `setOpened` | `(opened: boolean) => void` | — | Запрос на смену состояния. Вызывается **только** в контролируемом режиме |
+| `closeOnTab` | `boolean` | `false` | Закрывать блок по Tab (в дополнение к Escape и клику снаружи) |
+| `className` | `string` | — | Дополнительный CSS-класс корневого `<div>` |
+| `...rest` | `React.HTMLAttributes<HTMLDivElement>` | — | Атрибуты корневого `<div>` |
+
+### Контролируемый и неконтролируемый режим
+
+- Режим **фиксируется на монтировании**: если `opened !== undefined` на первом рендере — компонент контролируемый на всё время жизни, иначе неконтролируемый. Появление или исчезновение `opened` после маунта режим не меняет.
+- В контролируемом режиме внутреннее состояние не используется: `setOpened` вызывается, а фактическое значение приходит из prop `opened`. Без `setOpened` блок в этом режиме не сможет закрыться.
+- В неконтролируемом режиме `setOpened` не вызывается — состояние живёт внутри компонента.
+- `renderButton` и `renderDropdown` в обоих режимах получают одно и то же актуальное значение `opened` и один и тот же обработчик `setOpened`.
+
+### Статические субкомпоненты
+
+`ButtonDropdownExtended.Dropdown` и `ButtonDropdownExtended.DropdownList` — реэкспорты `Dropdown` и `DropdownList`, чтобы собирать выпадающий блок без дополнительных импортов. Это те же самые компоненты, а не обёртки.
+
+---
+
+## Дизайн-токены
+
+Собственных CSS-переменных нет. `ButtonDropdownExtended.module.less` задаёт только раскладку корневого контейнера: `display: inline-block`, `position: relative`, `vertical-align: middle` (общая опорная точка с `Button`), `line-height: 0`. Цвета и размеры приходят из вложенных `Button` и `Dropdown`.
+
+Правила класса выпадающего блока (`padding: 4px`, `margin-top: 4px`, `right: 0`) объявлены **вложенным** селектором внутри `.buttonDropdownExtended`, то есть компилируются в потомковый. При штатном использовании они не применяются: `ButtonDropdownExtended.Dropdown` рендерится через `<Portal container={document.body}>`, и узел с этим классом не является потомком корневого `<div>`. Позиционирование блока в этом случае обеспечивает сам `Dropdown` по `targetRef`. Учитывай это, если правишь отступы: менять их нужно не здесь.
+
+---
+
+## Инварианты
+
+- Компонент объявлен как `IButtonDropdownExtendedComponent extends React.FC<IButtonDropdownExtendedProps>`, `forwardRef` **не используется**: ref на корневой `<div>` не пробрасывается. Добавление `forwardRef` меняет базовый тип экспортируемого интерфейса — это breaking change, требует отдельного решения.
+- Публичные имена `ButtonDropdownExtended`, `IButtonDropdownExtendedProps`, `IButtonDropdownExtendedButtonProvideProps`, `IButtonDropdownExtendedDropdownProvideProps`, `IButtonDropdownExtendedComponent` экспортируются из `src/components/Button/index.ts` — сохранять.
+- Статические свойства `Dropdown` и `DropdownList` — часть публичного API.
+- Фиксация режима управления на монтировании — наблюдаемое поведение, на него опираются потребители. Менять только осознанно.
+- `renderDropdown` обязан применить переданный `className` к выпадающему блоку. Но не считай, что на нём держится раскладка: стили этого класса объявлены вложенным селектором внутри `.buttonDropdownExtended` и при рендере блока в портале (штатный путь через `ButtonDropdownExtended.Dropdown`) не применяются — см. раздел «Дизайн-токены».
+- Корневой DOM-элемент — `<div>` с классом `buttonDropdownExtended`; на нём же живёт `containerRef`, по которому определяется «клик внутри триггера».
+- Слушатели `keydown` / `mousedown` / `touchstart` вешаются на `document` только пока блок открыт.
+
+---
+
+## Accessibility
+
+- Компонент не рендерит собственной разметки кроме контейнера `<div>` и **не выставляет ARIA-атрибутов**. Роли и связки — зона ответственности `renderButton` / `renderDropdown`.
+- Потребитель обязан сам проставить на триггере `aria-haspopup`, `aria-expanded={opened}` и при необходимости `aria-controls` (см. `ButtonDropdown` как эталонную реализацию).
+- Клавиатура, обрабатываемая самим компонентом: `Escape` закрывает блок всегда, `Tab` — только при `closeOnTab`. Обработчик висит на `document`, поэтому срабатывает независимо от того, где находится фокус.
+- Фокус компонент не перемещает: при открытии фокус не уходит в блок, при закрытии не возвращается на триггер. Если продукту нужен focus trap или возврат фокуса — реализуй это в render-функциях.
+- Текстовых строк компонент не содержит, хардкода языка нет.
+
+---
+
+## Связанные компоненты
+
+- `ButtonDropdown` (`src/components/Button/ButtonDropdown.tsx`) — готовая кнопка со списком действий, построена поверх `ButtonDropdownExtended`.
+- `Button` (`src/components/Button/Button.tsx`) — обычный триггер для `renderButton`.
+- `Dropdown` (`src/components/Dropdown`) — выпадающий блок, доступен как `ButtonDropdownExtended.Dropdown`; рендерится в портале, позиционируется по `targetRef`.
+- `DropdownList` (`src/components/Dropdown/desktop/DropdownList.tsx`) — список с клавиатурной навигацией, доступен как `ButtonDropdownExtended.DropdownList`.
+- Внутренние потребители в библиотеке: `ListItemControlsButtonDropdown`, `TableBasicSettings` — при изменении поведения проверяй их.
+
+---
+
+## Stories
+
+Основные истории: `stories/Buttons/ButtonDropdownExtended.stories.tsx`
+Файлы примеров: `stories/Buttons/examples/ButtonDropdownExtended/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `closeOnTab` |
+| `Default` | `Default.tsx` | Неконтролируемый режим: кнопка `Button` + `Dropdown` со списком действий |
+| `Controlled` | `Controlled.tsx` | Контролируемый режим через `opened` / `setOpened` |
+| `CloseOnTab` | `CloseOnTab.tsx` | Закрытие блока по Tab |
+| `WithCustomContent` | `WithCustomContent.tsx` | Произвольное содержимое блока вместо списка действий |
+| `VisualTests` | `VisualTests.tsx` | Раскрытые блоки: список действий (`MIN_TARGET` + `RIGHT`, раскрывается `play`-функцией) и произвольный контент (`CONTENT` + `LEFT`, форсированно раскрыт в контролируемом режиме) |
+
+Документационные стори намеренно рендерятся в закрытом состоянии: раскрытый `Dropdown` блокирует скролл страницы (`wheel`-обработчик в `DropdownDesktop`), что ломает навигацию по autodocs. Раскрытые состояния покрыты `VisualTests`.
+
+Скриншот-тесты: `Playground` пропускается всегда; `Controlled` и `CloseOnTab` пропускаются как визуально идентичные `Default`.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-07-29 | Создан документ AI-ready для `ButtonDropdownExtended`. AI-рефакторинг без изменения публичного API: режим управления переведён с ref на `useState` (устранены ошибки `react-hooks/refs`), убраны вырожденный тернарник в `useState` и мёртвые проверки `opened` внутри обработчиков, `setOpened && setOpened(...)` заменён на опциональный вызов, добавлены JSDoc. Добавлены unit-тесты и stories по modern pattern. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Buttons/examples/ButtonDropdownExtended/Default.tsx`
+
+```tsx
+import React, { useRef } from "react";
+import {
+    Button,
+    ButtonDropdownExtended,
+    EButtonTheme,
+    EComponentSize,
+    EDropdownAlignment,
+    EDropdownWidth,
+    IButtonDropdownExtendedButtonProvideProps,
+    IButtonDropdownExtendedDropdownProvideProps,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS = [
+    { id: "opt-1", label: "Действие 1" },
+    { id: "opt-2", label: "Действие 2" },
+    { id: "opt-3", label: "Действие 3" },
+];
+
+export const Default = () => {
+    const buttonRef = useRef<HTMLButtonElement>(null);
+    const dropdownRef = useRef<HTMLDivElement>(null);
+
+    const renderButton = ({ opened, setOpened }: IButtonDropdownExtendedButtonProvideProps) => (
+        <Button
+            theme={EButtonTheme.GENERAL}
+            size={EComponentSize.MD}
+            aria-haspopup="menu"
+            aria-expanded={opened}
+            onClick={() => setOpened(!opened)}
+            ref={buttonRef}
+        >
+            Действия
+        </Button>
+    );
+
+    const renderDropdown = ({ opened, setOpened, className }: IButtonDropdownExtendedDropdownProvideProps) => (
+        <ButtonDropdownExtended.Dropdown
+            className={className}
+            size={EComponentSize.MD}
+            width={EDropdownWidth.MIN_TARGET}
+            alignment={EDropdownAlignment.LEFT}
+            opened={opened}
+            setOpened={setOpened}
+            targetRef={buttonRef}
+            ref={dropdownRef}
+        >
+            <ButtonDropdownExtended.DropdownList dropdownOpened={opened} size={EComponentSize.MD}>
+                {OPTIONS.map((option) => (
+                    <ButtonDropdownExtended.DropdownList.Item
+                        key={option.id}
+                        id={option.id}
+                        onSelect={() => setOpened(false)}
+                    >
+                        {option.label}
+                    </ButtonDropdownExtended.DropdownList.Item>
+                ))}
+            </ButtonDropdownExtended.DropdownList>
+        </ButtonDropdownExtended.Dropdown>
+    );
+
+    return (
+        <ButtonDropdownExtended renderButton={renderButton} renderDropdown={renderDropdown} dropdownRef={dropdownRef} />
+    );
+};
+```
+
+### Controlled
+
+`stories/Buttons/examples/ButtonDropdownExtended/Controlled.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import {
+    Button,
+    ButtonDropdownExtended,
+    EButtonTheme,
+    EComponentSize,
+    EDropdownAlignment,
+    EDropdownWidth,
+    IButtonDropdownExtendedButtonProvideProps,
+    IButtonDropdownExtendedDropdownProvideProps,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS = [
+    { id: "opt-1", label: "Действие 1" },
+    { id: "opt-2", label: "Действие 2" },
+    { id: "opt-3", label: "Действие 3" },
+];
+
+export const Controlled = () => {
+    const buttonRef = useRef<HTMLButtonElement>(null);
+    const dropdownRef = useRef<HTMLDivElement>(null);
+    // opened должен быть определён уже на первом рендере — режим управления фиксируется на монтировании.
+    const [opened, setOpened] = useState(false);
+
+    // В контролируемом режиме render-функции получают то же значение opened и тот же обработчик,
+    // что и в неконтролируемом, — контракт render-props одинаков в обоих режимах.
+    const renderButton = ({ opened, setOpened }: IButtonDropdownExtendedButtonProvideProps) => (
+        <Button
+            theme={EButtonTheme.GENERAL}
+            size={EComponentSize.MD}
+            aria-haspopup="menu"
+            aria-expanded={opened}
+            onClick={() => setOpened(!opened)}
+            ref={buttonRef}
+        >
+            Действия
+        </Button>
+    );
+
+    const renderDropdown = ({ className, opened, setOpened }: IButtonDropdownExtendedDropdownProvideProps) => (
+        <ButtonDropdownExtended.Dropdown
+            className={className}
+            size={EComponentSize.MD}
+            width={EDropdownWidth.MIN_TARGET}
+            alignment={EDropdownAlignment.LEFT}
+            opened={opened}
+            setOpened={setOpened}
+            targetRef={buttonRef}
+            ref={dropdownRef}
+        >
+            <ButtonDropdownExtended.DropdownList dropdownOpened={opened} size={EComponentSize.MD}>
+                {OPTIONS.map((option) => (
+                    <ButtonDropdownExtended.DropdownList.Item
+                        key={option.id}
+                        id={option.id}
+                        onSelect={() => setOpened(false)}
+                    >
+                        {option.label}
+                    </ButtonDropdownExtended.DropdownList.Item>
+                ))}
+            </ButtonDropdownExtended.DropdownList>
+        </ButtonDropdownExtended.Dropdown>
+    );
+
+    return (
+        <ButtonDropdownExtended
+            opened={opened}
+            setOpened={setOpened}
+            renderButton={renderButton}
+            renderDropdown={renderDropdown}
+            dropdownRef={dropdownRef}
+        />
+    );
+};
+```
+
+### CloseOnTab
+
+`stories/Buttons/examples/ButtonDropdownExtended/CloseOnTab.tsx`
+
+```tsx
+import React, { useRef } from "react";
+import {
+    Button,
+    ButtonDropdownExtended,
+    EButtonTheme,
+    EComponentSize,
+    EDropdownAlignment,
+    EDropdownWidth,
+    IButtonDropdownExtendedButtonProvideProps,
+    IButtonDropdownExtendedDropdownProvideProps,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS = [
+    { id: "opt-1", label: "Действие 1" },
+    { id: "opt-2", label: "Действие 2" },
+    { id: "opt-3", label: "Действие 3" },
+];
+
+export const CloseOnTab = () => {
+    const buttonRef = useRef<HTMLButtonElement>(null);
+    const dropdownRef = useRef<HTMLDivElement>(null);
+
+    const renderButton = ({ opened, setOpened }: IButtonDropdownExtendedButtonProvideProps) => (
+        <Button
+            theme={EButtonTheme.GENERAL}
+            size={EComponentSize.MD}
+            aria-haspopup="menu"
+            aria-expanded={opened}
+            onClick={() => setOpened(!opened)}
+            ref={buttonRef}
+        >
+            Действия
+        </Button>
+    );
+
+    const renderDropdown = ({ opened, setOpened, className }: IButtonDropdownExtendedDropdownProvideProps) => (
+        <ButtonDropdownExtended.Dropdown
+            className={className}
+            size={EComponentSize.MD}
+            width={EDropdownWidth.MIN_TARGET}
+            alignment={EDropdownAlignment.LEFT}
+            opened={opened}
+            setOpened={setOpened}
+            targetRef={buttonRef}
+            ref={dropdownRef}
+        >
+            <ButtonDropdownExtended.DropdownList dropdownOpened={opened} size={EComponentSize.MD}>
+                {OPTIONS.map((option) => (
+                    <ButtonDropdownExtended.DropdownList.Item
+                        key={option.id}
+                        id={option.id}
+                        onSelect={() => setOpened(false)}
+                    >
+                        {option.label}
+                    </ButtonDropdownExtended.DropdownList.Item>
+                ))}
+            </ButtonDropdownExtended.DropdownList>
+        </ButtonDropdownExtended.Dropdown>
+    );
+
+    return (
+        <ButtonDropdownExtended
+            closeOnTab
+            renderButton={renderButton}
+            renderDropdown={renderDropdown}
+            dropdownRef={dropdownRef}
+        />
+    );
+};
+```
+
+### WithCustomContent
+
+`stories/Buttons/examples/ButtonDropdownExtended/WithCustomContent.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import {
+    Button,
+    ButtonDropdownExtended,
+    EButtonTheme,
+    EComponentSize,
+    EDropdownAlignment,
+    ETextSize,
+    EDropdownWidth,
+    IButtonDropdownExtendedButtonProvideProps,
+    IButtonDropdownExtendedDropdownProvideProps,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+export const WithCustomContent = () => {
+    const buttonRef = useRef<HTMLButtonElement>(null);
+    const dropdownRef = useRef<HTMLDivElement>(null);
+    const [opened, setOpened] = useState(false);
+
+    const renderButton = ({ opened, setOpened }: IButtonDropdownExtendedButtonProvideProps) => (
+        <Button
+            theme={EButtonTheme.SECONDARY}
+            size={EComponentSize.MD}
+            aria-haspopup="dialog"
+            aria-expanded={opened}
+            onClick={() => setOpened(!opened)}
+            ref={buttonRef}
+        >
+            Фильтр
+        </Button>
+    );
+
+    const renderDropdown = ({ className, opened, setOpened }: IButtonDropdownExtendedDropdownProvideProps) => (
+        <ButtonDropdownExtended.Dropdown
+            className={className}
+            size={EComponentSize.MD}
+            width={EDropdownWidth.CONTENT}
+            alignment={EDropdownAlignment.LEFT}
+            opened={opened}
+            setOpened={setOpened}
+            targetRef={buttonRef}
+            ref={dropdownRef}
+        >
+            <div style={{ display: "flex", flexDirection: "column", gap: 12, padding: 8, width: 220 }}>
+                <Text tag="div" size={ETextSize.B3}>
+                    Здесь может быть любой контент: форма, фильтр или подсказка.
+                </Text>
+                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.SM} onClick={() => setOpened(false)}>
+                    Применить
+                </Button>
+            </div>
+        </ButtonDropdownExtended.Dropdown>
+    );
+
+    return (
+        <ButtonDropdownExtended
+            opened={opened}
+            setOpened={setOpened}
+            renderButton={renderButton}
+            renderDropdown={renderDropdown}
+            dropdownRef={dropdownRef}
+        />
+    );
+};
+```
+

package/bundle/components/ButtonIcon.md

@@ -1,8 +1,6 @@
 ---
 component: ButtonIcon
 category: Buttons
-figma-node: ""
-figma-file: ""
 related: [Button]
 tokens:
   - --triplex-next-Button-Icon_Shadow_Focus
@@ -17,19 +15,7 @@ version: "1.0"
 Кнопка только с иконкой без текстового контента. Используется как компактный trigger для локальных действий (например, открыть меню, удалить, закрыть).
 
 Используй когда: действие можно однозначно распознать по иконке и есть корректный `aria-label`.
-Не используй когда: нужен текстовый CTA или несколько визуальных тем с размерами как у `Button` - используй `Button`.
-
----
-
-## Файловая структура
-
-```text
-src/components/Button/
-├── ButtonIcon.tsx                     # Компонент (forwardRef, native button)
-├── enums.ts                           # EButtonIconShape (SQUIRCLE / CIRCLE)
-└── styles/
-    └── ButtonIcon.module.less         # Геометрия, focus-visible, базовые состояния
-```
+Не используй когда: нужен текстовый CTA или несколько визуальных тем с размерами как у `Button` — используй `Button`.
 
 ---
 
@@ -45,35 +31,16 @@ src/components/Button/
 |---|---|---|---|
 | `shape` | `EButtonIconShape` | `SQUIRCLE` | Форма кнопки: `SQUIRCLE` (радиус 4px) или `CIRCLE` (радиус 50%) |
 | `active` | `boolean` | `false` | Визуально активное состояние |
+| `children` | `React.ReactNode` | — | Содержимое кнопки, обычно иконка из `@sberbusiness/icons-next` |
 | `className` | `string` | — | Дополнительный CSS-класс |
 | `...rest` | `React.ButtonHTMLAttributes<HTMLButtonElement> & DataAttributes` | — | Нативные атрибуты `<button>`, включая `disabled`, `aria-*`, `data-*` |
 
 ### Ограничения использования
 
 - Размер `ButtonIcon` задаётся размером переданной иконки; у компонента нет собственного prop `size`.
-- Корневой DOM-элемент всегда `button`, `type` по умолчанию принудительно установлен в `button`.
-
----
-
-## Ключевые особенности реализации
-
-### Маппинг формы через enum
-
-- `shape` маппится в CSS-класс через `Record<EButtonIconShape, string>`.
-- При расширении `EButtonIconShape` нужно добавить класс в маппинг и в `ButtonIcon.module.less`.
-
-### Визуальные состояния
-
-- `active` и `disabled` добавляются как глобальные CSS-классы (`active`, `disabled`) для совместимости с иконками.
-- Дополнительно всегда добавляется класс `hoverable`.
-
----
-
-## Accessibility
-
-- Компонент рендерит нативный `<button>`, поэтому базовая keyboard-навигация доступна из коробки.
-- Компонент **не хардкодит** `aria-label` (библиотека мультиязычная). Для иконки без текста потребитель обязан передать `aria-label` через `...rest`.
-- Фокусное состояние реализовано через `:focus-visible` и токен `--triplex-next-Button-Icon_Shadow_Focus`.
+- Внешний DOM-узел — не `<button>`: компонент рендерит `IconWrapper` (`<span>` с классами `hoverable` и `displayContents`, то есть `display: contents`), а внутри него — `<button>`. Ref-target и получатель `className` / `...rest` — всегда `<button>`; классы состояний `active` и `disabled` выставляются на span-обёртке. Это важно для `>`-селекторов и логики на `parentElement`.
+- `type="button"` выставляется компонентом (чтобы кнопка не триггерила submit формы), но может быть переопределён через `...rest`.
+- При расширении `EButtonIconShape` необходимо добавить класс в маппинг `Record<EButtonIconShape, string>` и в `ButtonIcon.module.less`.
 
 ---
 
@@ -94,16 +61,24 @@ src/components/Button/
 
 ---
 
+## Accessibility
+
+- Компонент рендерит нативный `<button>`, поэтому базовая keyboard-навигация доступна из коробки.
+- Компонент **не хардкодит** `aria-label` (библиотека мультиязычная). Для иконки без текста потребитель **обязан** передать `aria-label` через `...rest`.
+- Фокусное состояние реализовано через `:focus-visible` и токен `--triplex-next-Button-Icon_Shadow_Focus`.
+
+---
+
 ## Связанные компоненты
 
-- `Button` (`src/components/Button/Button.tsx`) - текстовая/универсальная кнопка, используемая вместо `ButtonIcon` когда нужен label.
-- `ButtonDropdown` (`src/components/Button/ButtonDropdown.tsx`) - использует иконочный паттерн для dots-варианта trigger.
+- `Button` (`src/components/Button/Button.tsx`) — текстовая/универсальная кнопка, используемая вместо `ButtonIcon` когда нужен label.
+- `ButtonDropdown` (`src/components/Button/ButtonDropdown.tsx`) — использует иконочный паттерн для dots-варианта trigger.
 
 ---
 
 ## Stories
 
-`stories/Buttons/ButtonIcon.stories.tsx`
+Основные истории: `stories/Buttons/ButtonIcon.stories.tsx`
 Файлы примеров: `stories/Buttons/examples/ButtonIcon/`
 
 | Story | Example file | Что демонстрирует |
@@ -111,7 +86,9 @@ src/components/Button/
 | `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `shape`, `active`, `disabled` |
 | `Default` | `DefaultExample.tsx` | Базовый сценарий использования |
 | `Sizes` | `SizesExample.tsx` | Разные размеры через размер иконки (16/20/24/32) |
-| `Disabled` | `DisabledExample.tsx` | Неактивное состояние |
+| `States` | `StatesExample.tsx` | Состояния `active` и `disabled` |
+| `VisualTestsSquircle` | `VisualTestsExample.tsx` | Скриншот-регрессия: `:focus-visible` на squircle-кнопке |
+| `VisualTestsCircle` | `VisualTestsExample.tsx` | Скриншот-регрессия: `:focus-visible` на circle-кнопке |
 
 ---
 
@@ -120,6 +97,10 @@ src/components/Button/
 | Дата | Изменение |
 |---|---|
 | 2026-04-15 | Создан документ AI-ready для `ButtonIcon`. |
+| 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убрана секция «Файловая структура», содержимое «Ключевых особенностей реализации» перенесено в `Ограничения использования`, добавлена колонка `Example file`. |
+| 2026-07-08 | Актуализирована таблица Stories: story `Disabled` заменена на `States` (`StatesExample.tsx`). |
+| 2026-07-15 | `vertical-align: top` заменён на `middle` (синхронно с `Button`) — общая опорная точка для кнопок разной высоты и центрирование относительно строки инлайн-текста. |
+| 2026-07-30 | AI-рефакторинг: внутренние импорты переведены на относительные, `children` объявлен и задокументирован явно, JSDoc уточнён дефолтами; добавлены unit-тесты `__tests__/ButtonIcon.test.tsx`; в таблицу Stories добавлены отсутствовавшие `VisualTestsSquircle` и `VisualTestsCircle`. Публичный API не изменён. |
 
 ---
 
@@ -173,19 +154,31 @@ export const SizesExample = () => (
 );
 ```
 
-### Disabled
+### States
 
-`stories/Buttons/examples/ButtonIcon/DisabledExample.tsx`
+`stories/Buttons/examples/ButtonIcon/StatesExample.tsx`
 
 ```tsx
 import React from "react";
 import { DefaulticonStrokePrdIcon32 } from "@sberbusiness/icons-next";
 import { ButtonIcon, EButtonIconShape } from "@sberbusiness/triplex-next";
 
-export const DisabledExample = () => (
-    <ButtonIcon shape={EButtonIconShape.SQUIRCLE} disabled>
-        <DefaulticonStrokePrdIcon32 paletteIndex={5} />
-    </ButtonIcon>
+export const StatesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        <div style={{ display: "flex", flexDirection: "column", alignItems: "start", gap: "8px" }}>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Active</div>
+            <ButtonIcon shape={EButtonIconShape.SQUIRCLE} active>
+                <DefaulticonStrokePrdIcon32 paletteIndex={5} />
+            </ButtonIcon>
+        </div>
+
+        <div style={{ display: "flex", flexDirection: "column", alignItems: "start", gap: "8px" }}>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Disabled</div>
+            <ButtonIcon shape={EButtonIconShape.SQUIRCLE} disabled>
+                <DefaulticonStrokePrdIcon32 paletteIndex={5} />
+            </ButtonIcon>
+        </div>
+    </div>
 );
 ```