@sberbusiness/triplex-next-mcp-server 0.36.0-beta0 → 1.41.0-beta

package/bundle/components/AlertContext.md

@@ -0,0 +1,268 @@
+---
+component: AlertContext
+category: Alert
+related: [AlertProcess]
+tokens:
+    - --triplex-next-AlertContext-Info_Color
+    - --triplex-next-AlertContext-Warning_Color
+    - --triplex-next-AlertContext-Error_Color
+    - --triplex-next-AlertContext-System_Color
+stories: stories/Alerts/AlertContext.stories.tsx
+version: "1.0"
+---
+
+# AlertContext
+
+## Назначение
+
+Инлайновое контекстное предупреждение: строка «иконка + короткий текст», которая
+поясняет или уточняет соседний элемент интерфейса. Рендерится в `<span>` с
+`role="alert"`, иконка выбирается автоматически по `type`, текст оборачивается в
+`Text` с размером `ETextSize.B4`.
+
+Используй когда: нужно дать пояснение, предупреждение или сообщение об ошибке
+рядом с полем, кнопкой или блоком контента — без рамки, фона и кнопки закрытия.
+
+Не используй когда: нужен полноценный блок-уведомление с фоном, скруглением,
+ссылками, спойлером и кнопкой закрытия — это `AlertProcess`. Для всплывающих
+уведомлений поверх интерфейса — `Notification`.
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+| Prop   | Тип                                       | Описание                                                                                                     |
+| ------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `type` | `Exclude<EAlertType, EAlertType.FEATURE>` | Тип предупреждения: `INFO` / `WARNING` / `ERROR` / `SYSTEM`. Определяет и иконку по умолчанию, и цвет текста |
+
+### Опциональные props
+
+| Prop                           | Тип               | По умолчанию     | Описание                                                                   |
+| ------------------------------ | ----------------- | ---------------- | -------------------------------------------------------------------------- |
+| `renderIcon`                   | `React.ReactNode` | иконка по `type` | Полностью заменяет иконку по умолчанию                                     |
+| `children`                     | `React.ReactNode` | —                | Текст предупреждения. Всегда оборачивается в `Text`, наружу не «протекает» |
+| `...HTMLSpanElementAttributes` | —                 | —                | Все стандартные атрибуты `<span>`                                          |
+
+### Ограничения по типам
+
+- `EAlertType.FEATURE` **не поддерживается** и исключён на уровне типа
+  (`Exclude<EAlertType, EAlertType.FEATURE>`). Класса `.alertTypeFeature` в
+  `AlertContext.module.less` нет — общий `ALERT_TYPE_TO_CLASS_NAME_MAP` содержит
+  ветку `FEATURE` только ради `AlertProcess`. Если обойти типизацию (`as`) и
+  передать `FEATURE`, компонент отрендерится без иконки и без цветового класса.
+- Иконки по умолчанию фиксированы: `InfoStrokeStsIcon16` (`paletteIndex={3}`),
+  `WarningStrokeStsIcon16` (`2`), `ErrorStrokeStsIcon16` (`1`),
+  `SystemStrokeStsIcon16` (`4`). Менять `paletteIndex` нельзя — они согласованы
+  с цветовыми токенами.
+
+---
+
+## Дизайн-токены
+
+```text
+--triplex-next-AlertContext-Info_Color     // цвет текста для type=INFO
+--triplex-next-AlertContext-Warning_Color  // цвет текста для type=WARNING
+--triplex-next-AlertContext-Error_Color    // цвет текста для type=ERROR
+--triplex-next-AlertContext-System_Color   // цвет текста для type=SYSTEM
+```
+
+Значения — в `src/components/DesignTokens/components/AlertContext.ts`. Обрати
+внимание: `Info_Color`, `Warning_Color` и `System_Color` ссылаются на один и тот
+же нейтральный цвет (`ColorDarkNeutralAlpha.0` / `ColorNeutralAlpha.0`),
+выделен цветом только `Error_Color`. Типы различаются прежде всего иконкой, а не
+цветом текста.
+
+Размеры шрифта токенами не задаются — типографику целиком определяет `Text`
+с `ETextSize.B4` (класс `.b4` в `Typography/styles/Text.module.less`).
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, target — `HTMLSpanElement`. Не убирать.
+- **Корневой элемент `<span>` с `role="alert"`** — не менять ни тег, ни роль.
+  Тег `<span>` выбран ради валидности вложения в инлайновый контекст, но
+  `display: flex` делает элемент **блочным** flex-контейнером: из текстового
+  потока он выпадает. Не рассчитывай на инлайновое обтекание.
+- **`type` исключает `EAlertType.FEATURE`** — сужение типа публичное, расширять
+  без добавления стилей и иконки нельзя.
+- **`renderIcon` переопределяет иконку через `||`, а не `??`** — намеренно:
+  falsy-значение (`false`, `null`) означает «показать иконку по умолчанию». Замена
+  на `??` изменит поведение для `renderIcon={false}`.
+- **CSS-классы `alertContext`, `alertContextText`, `alertTypeInfo`,
+  `alertTypeWarning`, `alertTypeError`, `alertTypeSystem`** — проверяются в
+  unit-тестах, не переименовывать.
+- **`Text` получает только `size` и `className`** — никакого `type`. Цвет —
+  зона ответственности `AlertContext`, см. «Подводные камни». Тест
+  `does not set the mapped Typography font type class on text` охраняет это
+  правило. В DOM класс `primary` при этом присутствует: `Text` подставляет
+  `EFontType.PRIMARY` по умолчанию — на цвет он не влияет, его перекрывает
+  локальное правило.
+- **`ALERT_TYPE_TO_CLASS_NAME_MAP`** (`AlertTypeUtils.tsx`) — общий с
+  `AlertProcess` и экспортируется из barrel. Его форма (`Record<EAlertType,
+(styles) => string>`) — часть публичного API, менять нельзя без breaking change.
+
+---
+
+## Подводные камни
+
+- **Цвет текста задаётся локальным правилом, а `type` у `Text` намеренно не
+  передаётся.** Цвет берётся из `.alertContext.alertTypeX .alertContextText`
+  (токены `AlertContext-*`). Раньше компонент дополнительно передавал в `Text`
+  вычисленный `EFontType`, но это было мёртвым кодом: локальное правило имеет
+  специфичность (0,3,0) и всегда перекрывает `.typography.info` (0,2,0) из
+  `Typography.module.less`. Хуже того, значения расходились — см. таблицу ниже.
+  Не возвращай `type` у `Text`: цвет от этого не изменится, но код начнёт
+  документировать неверное намерение. Обратное тоже неверно — не убирай
+  LESS-правила «раз цвет и так задаёт `Text`»: тогда текст станет `primary`.
+
+  | `type` | `AlertContext-*` (действует) | `Typography-*` (не действует) |
+  |---|---|---|
+  | `INFO` | нейтральный `rgba(31,31,34,1)` / `rgba(255,255,255,1)` | синий `#0E57CC` / `#1297FE` |
+  | `WARNING` | нейтральный, те же значения | оранжевый `#EF4C01` / `#FF7A17` |
+  | `ERROR` | `#D10032` / `#F80C45` | `#D10032` / `#F80C45` — совпадает |
+  | `SYSTEM` | нейтральный, альфа `1` | `SECONDARY`: альфа `.65` / `.55` |
+
+- **Из `.alertContext` удалены `font-size: 12px` / `line-height: 16px`**
+  (2026-07-27) как мёртвые правила: типографику текста задаёт `Text` через
+  класс `.b4` на самом текстовом элементе, а собственное объявление потомка
+  всегда бьёт наследуемое от родителя. На иконки влияния не было — они
+  рендерятся как `<svg width="16" height="16">` с px-атрибутами.
+  **Остаточный риск:** если потребитель передаёт в `renderIcon` не-svg элемент
+  с текстом, его типографика после удаления изменится — раньше он наследовал от
+  `.alertContext` 12px/16px, теперь наследует размер шрифта родителя страницы.
+  Штатный сценарий (`renderIcon` = иконка из `@sberbusiness/icons-next`) не
+  затронут.
+- **`role="alert"` присутствует в DOM с момента монтирования.** Live-region,
+  добавленный в дерево вместе со своим содержимым, скринридеры часто не
+  анонсируют. Если нужно гарантированное озвучивание при динамическом появлении
+  сообщения — держи `AlertContext` смонтированным и меняй `children`, а не
+  монтируй компонент целиком.
+
+---
+
+## Accessibility
+
+- Корневой `<span>` имеет `role="alert"` — это `aria-live="assertive"` region:
+  изменение содержимого прерывает текущую речь скринридера.
+- Иконка декоративная и не имеет текстовой альтернативы — весь смысл должен
+  быть в `children`. Не полагайся на цвет и иконку как на единственный носитель
+  информации о серьёзности сообщения.
+- Компонент неинтерактивен: не получает фокус, не обрабатывает клавиатуру,
+  собственных `aria-*` атрибутов сверх `role` не выставляет. Любые `aria-label`
+  / `aria-describedby` пробрасываются через `...rest`.
+- При связывании с полем формы передавай `id` и ссылайся на него из поля через
+  `aria-describedby`.
+
+---
+
+## Связанные компоненты
+
+- `AlertProcess` — блочное уведомление того же семейства: фон, скругление,
+  кнопка закрытия, спойлер, ссылки. Поддерживает `EAlertType.FEATURE`.
+- `EAlertType` — общий enum типов для всего семейства. `AlertContext`
+  использует его подмножество.
+- `ALERT_TYPE_TO_CLASS_NAME_MAP` (`AlertTypeUtils.tsx`) — общий маппинг типа в
+  CSS-класс, разделяемый с `AlertProcess`. Собственного AI.md не имеет.
+- `Text` — рендерит текст предупреждения (`ETextSize.B4`). Цвет им не
+  управляется: prop `type` намеренно не передаётся.
+- `Notification` — всплывающее уведомление поверх интерфейса, а не инлайновое.
+
+---
+
+## Stories
+
+Основные истории: `stories/Alerts/AlertContext.stories.tsx`
+Файлы примеров: `stories/Alerts/examples/AlertContext/`
+
+| Story            | Example file         | Что демонстрирует                                                |
+| ---------------- | -------------------- | ---------------------------------------------------------------- |
+| `Playground`     | `Playground.tsx`     | Интерактивный контроль `type` и `children`                       |
+| `Default`        | `Default.tsx`        | Базовое предупреждение с типом `INFO`                            |
+| `Types`          | `Types.tsx`          | Все поддерживаемые типы: `INFO` / `WARNING` / `ERROR` / `SYSTEM` |
+| `WithCustomIcon` | `WithCustomIcon.tsx` | Замена иконки через `renderIcon`                                 |
+
+Скриншот-тесты: baseline лежат в `__screenshots__/` как
+`alerts-alertcontext--{default,types,with-custom-icon}--{xs,xl}.png`.
+`Playground` исключён из скриншот-тестов через `testRunner: { skip: true }`
+(по `docs/ai/stories-guide.md` — всегда), его визуальная регрессия не покрыта.
+Устаревшие `alerts-alertcontext--playground--{xs,xl}.png` удалены: скрипт
+`scripts/checkOrphanScreenshots.ts` такие файлы не ловит — `parameters` нет в
+`storybook-static/index.json`, поэтому skip-стори считаются ожидаемыми.
+Отдельная `VisualTests` story не создавалась — у компонента нет состояний,
+требующих взаимодействия (hover / focus / disabled / loading отсутствуют).
+Непокрытый визуальный кейс — перенос текста на несколько строк.
+
+---
+
+## История изменений
+
+| Дата       | Изменение                                                                                                                                                                                                                                                                                                                         |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 2026-07-27 | Создан документ. AI-рефакторинг: switch иконок заменён на `TYPE_TO_DEFAULT_ICON_MAP`, в `IAlertContextProps` добавлен явный `children`, из `.alertContext` удалены мёртвые `font-size` / `line-height`, из `Text` убран prop `type` вместе с маппингом `EFontType` (перекрывался специфичностью и расходился по значениям с токенами `AlertContext-*`). Unit-тесты расширены с 6 до 25 кейсов. Файлы примеров в `stories/Alerts/examples/AlertContext/` переименованы под modern pattern — без суффикса `Example`. Публичный API не менялся. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Alerts/examples/AlertContext/Default.tsx`
+
+```tsx
+import React from "react";
+import { AlertContext, EAlertType } from "@sberbusiness/triplex-next";
+
+export const Default = () => (
+    <div style={{ maxWidth: "750px" }}>
+        <AlertContext type={EAlertType.INFO}>
+            This message provides context or highlights important information to note.
+        </AlertContext>
+    </div>
+);
+```
+
+### Types
+
+`stories/Alerts/examples/AlertContext/Types.tsx`
+
+```tsx
+import React from "react";
+import { AlertContext, EAlertType } from "@sberbusiness/triplex-next";
+
+const TYPES = Object.values(EAlertType).filter((type) => type !== EAlertType.FEATURE);
+
+export const Types = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "750px" }}>
+        {TYPES.map((type) => (
+            <div key={type}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{type.toUpperCase()}</div>
+                <AlertContext type={type}>
+                    This message provides context or highlights important information to note.
+                </AlertContext>
+            </div>
+        ))}
+    </div>
+);
+```
+
+### WithCustomIcon
+
+`stories/Alerts/examples/AlertContext/WithCustomIcon.tsx`
+
+```tsx
+import React from "react";
+import { AlertContext, EAlertType } from "@sberbusiness/triplex-next";
+import { WaitStrokeStsIcon16 } from "@sberbusiness/icons-next";
+
+export const WithCustomIcon = () => (
+    <div style={{ maxWidth: "750px" }}>
+        <AlertContext type={EAlertType.INFO} renderIcon={<WaitStrokeStsIcon16 paletteIndex={4} />}>
+            This message provides context or highlights important information to note.
+        </AlertContext>
+    </div>
+);
+```
+

package/bundle/components/Button.md

@@ -87,12 +87,12 @@ version: "1.0"
 | Prop | Тип | Описание |
 |---|---|---|
 | `theme` | `EButtonTheme` | Визуальный стиль |
-| `size` | `EComponentSize` | Размер |
 
 ### Опциональные props (`Button`)
 
 | Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
+| `size` | `EComponentSize` | `MD` | Размер |
 | `block` | `boolean` | `false` | Полноширинный режим |
 | `loading` | `boolean` | `false` | Состояние загрузки: скрывает контент через `visibility: hidden`, показывает спиннер, ставит `tabIndex={-1}` |
 | `icon` | `React.ReactElement` | — | Иконка слева от текста; если без `children` — кнопка становится квадратной (icon-only) |
@@ -145,7 +145,7 @@ version: "1.0"
 - Нативный `<button>` — полная поддержка клавиатуры (Tab, Enter, Space) без дополнительных атрибутов.
 - **`ButtonIcon`**: иконочная кнопка без видимого текста — потребитель **обязан** передать `aria-label` через `...rest`. Библиотека мультиязычная, текст не хардкодится.
 - **`loading`**: устанавливает `tabIndex={-1}` — кнопка исключается из tab-порядка. Если нужна доступность состояния загрузки для скринридеров, потребитель добавляет `aria-busy="true"` через props.
-- **`aria-expanded`**: управляет визуальным состоянием «раскрыто» (добавляет CSS-классы `.expanded`, `.active`). Передаётся потребителем при использовании кнопки как триггера dropdown. Отдельного prop `expanded` нет — используй стандартный HTML-атрибут.
+- **`aria-expanded`**: управляет визуальным состоянием «раскрыто» (добавляет CSS-классы `.expanded`, `.active`). Раскрытым считается только значение `true` или `"true"` — строковое `"false"` трактуется как закрытое состояние (тип атрибута `Booleanish`). Передаётся потребителем при использовании кнопки как триггера dropdown. Отдельного prop `expanded` нет — используй стандартный HTML-атрибут.
 - Фокус-стиль через `:focus-visible` — виден только при клавиатурной навигации.
 
 ---
@@ -185,6 +185,9 @@ version: "1.0"
 |---|---|
 | 2026-03-31 | Создан документ (пилот AI-Ready) |
 | 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убраны секции «Файловая структура» и «Ключевые особенности реализации», переструктурированы props, добавлена колонка `Example file` в таблице Stories |
+| 2026-07-15 | Добавлен `vertical-align: middle` корневому классу `.button` — icon-only кнопка (`icon` без `children`) смещалась по вертикали относительно соседней текстовой кнопки из-за baseline-выравнивания inline-элементов; `middle` также центрирует кнопку относительно строки инлайн-текста |
+| 2026-07-28 | AI-рефакторинг (TRI-13): codestyle-чистка `Button.tsx` (JSDoc компонента, поясняющие комментарии, эквивалентные упрощения в `clsx`), unit-тесты расширены с 10 до 24 кейсов; публичный API и поведение не изменены |
+| 2026-07-28 | Правки по ревью PR #481 (TRI-13): исправлена трактовка строкового `aria-expanded="false"` (больше не считается раскрытым состоянием); `size` стал опциональным с default `EComponentSize.MD` (типы приведены в соответствие с реализацией); `ButtonBase` убран из barrel-экспорта `index.ts` — импорт только по прямому пути `components/Button/ButtonBase` |
 
 ---
 

package/bundle/components/ButtonDropdown.md

@@ -36,7 +36,10 @@ version: "1.0"
 | `selected` | `IButtonDropdownOption` | — | Предвыбранная опция для подсветки в списке |
 | `disabled` | `boolean` | `false` | Блокирует кнопку и открытие списка |
 | `buttonAttributes` | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | Дополнительные HTML-атрибуты нативной кнопки (включая `aria-label`) |
+| `dropdownAttributes` | `React.HTMLAttributes<HTMLDivElement> & DataAttributes` | — | HTML-атрибуты выпадающего блока, включая `data-*`; `className` мержится с внутренними классами; применяется в desktop-отображении |
 | `block` | `boolean` | `false` | Полноширинный режим (только для non-dots тем) |
+| `opened` | `boolean` | — | Управляемое состояние открытости dropdown (controlled-режим); задаётся в паре с `setOpened`, без него состояние зафиксировано |
+| `setOpened` | `(opened: boolean) => void` | — | Обработчик изменения состояния открытости (пара к `opened`) |
 | `className` | `string` | — | Дополнительный CSS-класс контейнера |
 | `...rest` | `React.HTMLAttributes<HTMLDivElement>` | — | Атрибуты корневого `<div>` компонента |
 
@@ -77,7 +80,7 @@ version: "1.0"
 
 - Триггер строится на `Button` (нативный `<button>`), базовая keyboard-навигация сохраняется.
 - Кнопка получает `aria-haspopup="menu"`, `aria-expanded`, `aria-controls`. Связка trigger/list осуществляется через `instanceId` (`uniqueId()`); `aria-activedescendant` синхронизируется через `DropdownListContext`.
-- На кнопке перехватываются `Space`, `ArrowUp`, `ArrowDown` с `preventDefault`. `ArrowUp` / `ArrowDown` открывают dropdown, если он закрыт. Dropdown закрывается по `Escape` и (из-за `closeOnTab`) по `Tab`.
+- На кнопке перехватываются `Space`, `ArrowUp`, `ArrowDown` с `preventDefault` (сравнение по `event.code`, как в `ButtonDropdownExtended`). `Space` явно переключает dropdown (нативная click-активация отменена `preventDefault`), `ArrowUp` / `ArrowDown` открывают его, если закрыт. Dropdown закрывается по `Escape` и (из-за `closeOnTab`) по `Tab`.
 - Компонент **не хардкодит** aria-тексты: при необходимости `aria-label` нужно передавать через `buttonAttributes`. Для корректной доступности меню потребитель должен передавать понятные `label` для `options`.
 - На mobile-заголовке dropdown отображается `children` триггера; если в продукте нужен локализованный отдельный заголовок, его нужно задавать на уровне композиции (через `ButtonDropdownExtended`).
 
@@ -115,6 +118,11 @@ version: "1.0"
 |---|---|
 | 2026-04-15 | Создан документ AI-ready для `ButtonDropdown`. |
 | 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убраны секции «Файловая структура» и «Ключевые особенности реализации», их содержимое перенесено в `Ограничения по темам` и `Accessibility`, добавлена колонка `Example file`. |
+| 2026-07-09 | Добавлено свойство `dropdownAttributes` — HTML-атрибуты выпадающего блока (в том числе возможность поднять `z-index` через `style`). |
+| 2026-07-15 | В `ButtonDropdownExtended` `vertical-align: top` заменён на `middle` (синхронно с `Button`) — общая опорная точка для кнопок разной высоты и центрирование относительно строки инлайн-текста. |
+| 2026-07-28 | AI-рефакторинг: dots- и обычный триггер объединены в один `renderButton` (общая a11y-обвязка), тема кнопки и палитра каретки выведены через мапы вместо `as`-каста и `switch`, удалено обращение к несуществующему CSS-классу `buttonDropdownMenu` (в LESS его не было, в сборке значение было `undefined`). Публичный API и разметка не изменились. Unit-тесты расширены до 32 кейсов. |
+| 2026-07-29 | Правки по ревью PR #482: типы триггера и props-интерфейсы вариантов теперь экспортируются (`TButtonDropdownButtonTheme`, `TButtonDropdownTheme`, `IButtonDropdownBaseProps`, `IButtonDotsProps`) — по конвенции все типы barrel-компонентов публичны; поведение не изменилось. |
+| 2026-07-29 | Отработка находок AI-рефакторинга: починен перехват пробела на триггере (сравнение по `event.code`; `Space` явно переключает dropdown), `label` опции больше не утекает в DOM-атрибут элемента списка, легализован controlled-режим — публичные props `opened` / `setOpened` (ранее `opened` работал только через нетипизированный spread). |
 
 ---