@sberbusiness/triplex-next-mcp-server 0.24.0-beta1

package/bundle/components/ButtonDropdown.md

@@ -0,0 +1,159 @@
+---
+component: ButtonDropdown
+category: Buttons
+figma-node: ""
+figma-file: ""
+related: [Button, ButtonDropdownExtended, Dropdown]
+tokens: []
+stories: stories/Buttons/ButtonDropdown.stories.tsx
+version: "1.0"
+---
+
+# ButtonDropdown
+
+## Назначение
+
+Кнопка-триггер с выпадающим списком действий.
+Поддерживает два визуальных режима: обычная кнопка (`EButtonTheme`) и dots-вариант (`EButtonDotsTheme`).
+
+Используй когда: нужно сгруппировать несколько действий под один триггер и дать выбор опции из списка.
+Не используй когда: нужна одиночная кнопка без списка - используй `Button`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Button/
+├── ButtonDropdown.tsx                  # Основной компонент (forwardRef, рендер button + dropdown)
+├── ButtonDropdownExtended.tsx          # Базовый контейнер с контролем opened/close и outside click
+├── styles/
+│   ├── ButtonDropdown.module.less      # Стили caret, active-состояния, block-режима
+│   └── ButtonDropdownExtended.module.less
+└── index.ts                            # Публичный экспорт ButtonDropdown
+```
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `theme` | `EButtonTheme.GENERAL \| EButtonTheme.SECONDARY \| EButtonTheme.SECONDARY_LIGHT \| EButtonTheme.DANGER \| EButtonDotsTheme` | Визуальная тема триггера |
+| `size` | `EComponentSize` | Размер кнопки (`SM` / `MD` / `LG`) |
+| `options` | `IButtonDropdownOption[]` | Опции выпадающего списка |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `children` | `React.ReactNode` | `undefined` | Текст/контент кнопки (используется также в mobile header) |
+| `selected` | `IButtonDropdownOption` | `undefined` | Предвыбранная опция для подсветки в списке |
+| `disabled` | `boolean` | `false` | Блокирует кнопку и открытие списка |
+| `buttonAttributes` | `React.ButtonHTMLAttributes<HTMLButtonElement>` | `undefined` | Дополнительные HTML-атрибуты нативной кнопки |
+| `block` | `boolean` | `false` | Доступен только для non-dots тем |
+| `className` | `string` | — | Дополнительный CSS-класс контейнера |
+| `...rest` | `React.HTMLAttributes<HTMLDivElement>` | — | Атрибуты корневого `div` компонента |
+
+### Ограничения по темам
+
+- Для `EButtonDotsTheme` prop `block` запрещен типизацией (`never`).
+- Dots-режим использует иконку `Dotshorizontal*` вместо текстового контента кнопки.
+
+### Структура опции (`IButtonDropdownOption`)
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `id` | `string` | Уникальный идентификатор опции |
+| `label` | `React.ReactNode` | Видимый контент пункта меню |
+| `onSelect` | `() => void` | Callback выбора опции |
+| `...rest` | `IDropdownListItemProps` (без ряда запрещенных полей) | Остальные настройки `DropdownList.Item` |
+
+---
+
+## Ключевые особенности реализации
+
+### Композиция через `ButtonDropdownExtended`
+
+- `ButtonDropdown` делегирует управление opened-state и close-on-outside в `ButtonDropdownExtended`.
+- Передает две render-функции: `renderButton` и `renderDropdown`.
+
+### Desktop + mobile dropdown
+
+- Desktop: рендерится `DropdownList` с `DropdownList.Item`.
+- Mobile: через `mobileViewProps` рендерится `DropdownMobileHeader` + `DropdownMobileList`.
+- После выбора любого пункта вызывается `option.onSelect?.()` и dropdown закрывается.
+
+### Управление клавиатурой
+
+- На кнопке перехватываются `Space`, `ArrowUp`, `ArrowDown` с `preventDefault`.
+- `ArrowUp/ArrowDown` открывают dropdown, если он закрыт.
+- В `ButtonDropdownExtended` dropdown закрывается по `Escape` и (из-за `closeOnTab`) по `Tab`.
+
+### ARIA-связка trigger/list
+
+- Кнопка получает `aria-haspopup="menu"`, `aria-expanded`, `aria-controls`.
+- `aria-controls` и `DropdownList` связываются через `instanceId` (`uniqueId()`).
+- `aria-activedescendant` синхронизируется через `DropdownListContext`.
+
+---
+
+## Accessibility
+
+- Триггер строится на `Button` (нативный `button`), базовая keyboard-навигация сохраняется.
+- Компонент не хардкодит aria-тексты: при необходимости `aria-label` нужно передавать через `buttonAttributes`.
+- На mobile-заголовке dropdown отображается `children` триггера; если в продукте нужен локализованный отдельный заголовок, его нужно задавать на уровне композиции (через `ButtonDropdownExtended`).
+- Для корректной доступности меню потребитель должен передавать понятные `label` для `options`.
+
+---
+
+## Дизайн-токены
+
+`ButtonDropdown` не использует собственных CSS color-токенов в `ButtonDropdown.module.less`.
+Визуальные токены берутся из `Button` и `Dropdown`, которые рендерятся внутри.
+
+---
+
+## Инварианты
+
+- `forwardRef` на `ButtonDropdown` обязателен: ref должен оставаться на `HTMLButtonElement` триггера.
+- `IButtonDropdownOption.id` должен оставаться обязательным и уникальным ключом для рендера списков.
+- `closeOnTab` в вызове `ButtonDropdownExtended` должен сохраняться (часть текущего UX-контракта закрытия).
+- Выбор опции должен закрывать dropdown и на desktop, и на mobile.
+- Публичный экспорт из `src/components/Button/index.ts` должен оставаться.
+
+---
+
+## Связанные компоненты
+
+- `Button` (`src/components/Button/Button.tsx`) - базовый триггер, на котором построен `ButtonDropdown`.
+- `ButtonDropdownExtended` (`src/components/Button/ButtonDropdownExtended.tsx`) - управляет открытием/закрытием dropdown.
+- `Dropdown` (`src/components/Dropdown`) - контейнер и пункты списка для desktop/mobile представления.
+
+---
+
+## Stories
+
+`stories/Buttons/ButtonDropdown.stories.tsx`
+Файлы примеров: `stories/Buttons/examples/ButtonDropdown/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `children`, `theme`, `size`, `block`, `disabled` |
+| `Default` | `DefaultExample.tsx` | Базовый сценарий открытия и выбора опций |
+| `Sizes` | `SizesExample.tsx` | Размеры `SM` / `MD` / `LG` |
+| `Themes` | `ThemesExample.tsx` | Разные темы (`EButtonTheme` + `EButtonDotsTheme`) |
+| `BlockMode` | `BlockModeExample.tsx` | Блочный режим non-dots кнопки |
+| `Disabled` | `DisabledExample.tsx` | Неактивное состояние |
+| `WithSelectedOption` | `WithSelectedOptionExample.tsx` | Предвыбранная опция через `selected` |
+| `VisualTests` | `VisualTestsExample.tsx` | Сценарий визуальной регрессии |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-15 | Создан документ AI-ready для `ButtonDropdown`. |

package/bundle/components/ButtonIcon.md

@@ -0,0 +1,122 @@
+---
+component: ButtonIcon
+category: Buttons
+figma-node: ""
+figma-file: ""
+related: [Button]
+tokens:
+  - --triplex-next-Button-Icon_Shadow_Focus
+stories: stories/Buttons/ButtonIcon.stories.tsx
+version: "1.0"
+---
+
+# ButtonIcon
+
+## Назначение
+
+Кнопка только с иконкой без текстового контента. Используется как компактный 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, базовые состояния
+```
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+Обязательных custom-props нет.
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `shape` | `EButtonIconShape` | `SQUIRCLE` | Форма кнопки: `SQUIRCLE` (радиус 4px) или `CIRCLE` (радиус 50%) |
+| `active` | `boolean` | `false` | Визуально активное состояние |
+| `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`.
+
+---
+
+## Дизайн-токены
+
+```
+--triplex-next-Button-Icon_Shadow_Focus
+```
+
+---
+
+## Инварианты
+
+- `forwardRef` обязателен: ref должен оставаться на `HTMLButtonElement`.
+- `type="button"` должен оставаться дефолтом, чтобы не триггерить submit в формах по умолчанию.
+- `shape` по умолчанию должен оставаться `EButtonIconShape.SQUIRCLE`.
+- Публичный экспорт `ButtonIcon` из `src/components/Button/index.ts` должен сохраняться.
+
+---
+
+## Связанные компоненты
+
+- `Button` (`src/components/Button/Button.tsx`) - текстовая/универсальная кнопка, используемая вместо `ButtonIcon` когда нужен label.
+- `ButtonDropdown` (`src/components/Button/ButtonDropdown.tsx`) - использует иконочный паттерн для dots-варианта trigger.
+
+---
+
+## Stories
+
+`stories/Buttons/ButtonIcon.stories.tsx`
+Файлы примеров: `stories/Buttons/examples/ButtonIcon/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `shape`, `active`, `disabled` |
+| `Default` | `DefaultExample.tsx` | Базовый сценарий использования |
+| `Sizes` | `SizesExample.tsx` | Разные размеры через размер иконки (16/20/24/32) |
+| `Disabled` | `DisabledExample.tsx` | Неактивное состояние |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-15 | Создан документ AI-ready для `ButtonIcon`. |