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

package/bundle/components/IconWrapper.md

@@ -1,9 +1,7 @@
 ---
 component: IconWrapper
 category: Icons
-figma-node: ""
-figma-file: ""
-related: [ButtonIcon, Button, Link]
+related: [ButtonIcon, Button, Link, Chip, ListItemControlsButton]
 tokens: []
 stories: stories/Icons/IconWrapper/IconWrapper.stories.tsx
 version: "1.0"
@@ -13,128 +11,129 @@ version: "1.0"
 
 ## Назначение
 
-Минимальный `<span>`-обёртка для иконок из `@sberbusiness/icons-next`,
-которая проставляет **глобальный CSS-класс `hoverable`** + опционально `active`/`disabled`.
-Эти имена используются CSS-правилами из `icons-next/styles/icons.css` для
-смены `fill` у палитры иконок при hover/active/disabled.
+Обёртка-`<span>` для иконок из `@sberbusiness/icons-next`. Сама ничего не рисует: выставляет
+на корневом элементе глобальные классы `hoverable` / `active` / `disabled`, по которым стили
+пакета иконок подбирают цвет вложенной иконки в обычном, наведённом, активном и отключённом
+состоянии.
 
-Без обёртки иконка имеет фиксированные цвета палитры. С обёрткой — реагирует
-на состояния родителя.
+Используй когда: иконка должна менять цвет вместе с состоянием интерактивного элемента
+(кнопка, ссылка, чип, строка списка) — оборачивай ею иконку и прокидывай `active` / `disabled`
+из состояния родителя.
 
-Используй когда: нужно сделать кликабельную/интерактивную иконку вне
-кнопки (например, в строке таблицы, в свободной вёрстке), либо когда
-иконка внутри нестандартного контейнера должна менять цвет при hover/active.
-Не используй когда: иконка внутри `ButtonIcon`/`Button` — там `hoverable`
-уже навешен.
+Не используй когда:
+- Нужен интерактивный элемент — IconWrapper не кнопка: это `<span>` без роли, фокуса и
+  клавиатурной обработки, и сам он ничего из этого не реализует, даже если прокинуть
+  обработчики через spread. Возьми `ButtonIcon` (он сам оборачивает `<button>` в IconWrapper).
+- Иконка статична и её цвет задаётся напрямую через `paletteIndex` иконки или CSS родителя —
+  обёртка избыточна.
+- Нужно менять размер иконки — IconWrapper не влияет на размер, его задаёт сама иконка
+  (`...Icon16` / `...Icon20` / `...Icon24`).
 
 ---
 
-## Файловая структура
+## Варианты и props
 
-```text
-src/components/IconWrapper/
-├── IconWrapper.tsx                    # forwardRef, <span>
-├── index.ts                           # Barrel: IconWrapper, IIconWrapperProps
-├── styles/IconWrapper.module.less     # disableInteraction, displayContents (только)
-└── __tests__/IconWrapper.test.tsx
-```
+### Обязательные props
 
----
-
-## Варианты и props
+| Prop | Тип | Описание |
+|---|---|---|
+| `children` | `React.ReactNode` | Иконка (или произвольный контент), которую оборачивает компонент |
 
-### `IIconWrapperProps extends HTMLAttributes<HTMLSpanElement>`
+### Опциональные props
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `children` | `ReactNode` | — | Обычно `<SomeIcon16 />` из `@sberbusiness/icons-next`. |
-| `active` | `boolean` | `false` | Принудительно применить стили active-цвета. Класс `active` (глобальный). |
-| `disabled` | `boolean` | `false` | Приглушённый цвет. Класс `disabled` (глобальный). |
-| `disableInteraction` | `boolean` | `false` | `pointer-events: none`. Иконка не ловит hover/click. Полезно, когда иконка внутри disabled-элемента, но сама не должна реагировать. |
-| `displayContents` | `boolean` | `false` | `display: contents` — span не создаёт box'а. Для кейсов, когда обёртка мешает grid/flex лейауту. |
-| `className`, `...HTMLSpanAttributes` | — | — | Стандартные. |
+| `active` | `boolean` | `false` | Ставит глобальный класс `active` — цвет иконки для нажатого/выбранного состояния |
+| `disabled` | `boolean` | `false` | Ставит глобальный класс `disabled` — приглушённый цвет иконки. Это только визуальное состояние, взаимодействие не блокируется |
+| `disableInteraction` | `boolean` | `false` | `pointer-events: none` на обёртке. Нужен, чтобы иконка выглядела disabled и не реагировала на hover, когда клика по ней не предполагается |
+| `displayContents` | `boolean` | `false` | `display: contents` — обёртка исчезает из layout, потомок наследует место `<span>` в сетке/флексе родителя |
+
+Компонент расширяет `React.HTMLAttributes<HTMLSpanElement>`, поэтому принимает все стандартные
+атрибуты `<span>` (`className`, `style`, `onClick`, `aria-*`, `data-*`) — они попадают на корневой
+элемент.
+
+### Ограничения
+
+- `disabled` и `disableInteraction` независимы: `disabled` красит, `disableInteraction` гасит
+  события мыши. Для «выглядит выключенным и не кликается» нужны оба — пример:
+  `stories/MultiselectField/examples/StatusesExample.tsx`. В `src/**` `disableInteraction`
+  не передаёт ни один компонент.
+- `displayContents` меняет только участие обёртки в layout; классы состояний по-прежнему стоят
+  на `<span>`, и сам `<span>` остаётся в DOM — на это опираются тесты потребителей, которые
+  достают обёртку через `parentElement` (`Button/__tests__/ButtonIcon.test.tsx`,
+  `IconWrapper/__tests__/IconWrapper.test.tsx`).
+- Класс `hoverable` выставляется всегда, включая `disabled`-состояние — так работает цветовая
+  логика `@sberbusiness/icons-next`.
 
 ---
 
-## Ключевые особенности реализации
-
-### Глобальные классы `hoverable` / `active` / `disabled`
-
-```tsx
-className={clsx("hoverable", className, {
-    active: !!active,
-    disabled: !!disabled,
-    [styles.disableInteraction]: !!disableInteraction,
-    [styles.displayContents]: !!displayContents,
-})}
-```
-
-- `hoverable`, `active`, `disabled` — **не CSS-Modules классы**, а строковые литералы. Соответствующие правила живут в **`@sberbusiness/icons-next/styles/icons.css`** и выглядят как:
-  ```css
-  @media (hover: hover) { .hoverable:hover ._cdqvp6 { fill: #21A19A; } ... }
-  .hoverable:not(:disabled):active ._cdqvp6, .hoverable.active ._cdqvp6 { fill: #007777; }
-  .hoverable:disabled ._cdqvp6, .hoverable.disabled ._cdqvp6 { fill: ... opacity: .15; }
-  ```
-- Правила написаны для каждого цветового класса палитры иконок (`._cdqvp6`, `._102z8qh` и т.д.). Переопределять их через свой CSS сложно — лучше использовать `paletteIndex` prop иконки.
-- **Не переименовывать `"hoverable"` на camelCase или `styles.hoverable`** — это сломает работу CSS из icons-next.
-
-### `disableInteraction` и `displayContents` — единственное, что у компонента есть в CSS
-
-```less
-.disableInteraction { pointer-events: none; }
-.displayContents { display: contents; }
-```
-
-Всё остальное визуальное поведение приходит от icons.css. Компонент — тонкая обёртка.
-
-### `forwardRef` + typo: ref на `<span>`
+## Дизайн-токены
 
-`IIconWrapperProps` требует `children: React.ReactNode` как обязательный prop (в отличие от стандартного `HTMLAttributes`, где `children` опциональный).
+Компонент не использует собственных CSS-переменных. Цвета иконок задают глобальные стили
+`@sberbusiness/icons-next`, привязанные к классам `hoverable` / `active` / `disabled`. Собственный
+CSS-модуль `styles/IconWrapper.module.less` содержит только два служебных класса:
+`.disableInteraction` (`pointer-events: none`) и `.displayContents` (`display: contents`).
 
 ---
 
 ## Инварианты
 
-- **Строковые классы `"hoverable"` / `"active"` / `"disabled"`** — кросс-пакетный контракт с `@sberbusiness/icons-next`. Не менять и не оборачивать в CSS-Modules.
-- **`forwardRef`** — не убирать.
-- **`children` обязателен** по типу — тонкая обёртка без контента бессмысленна.
-- **`displayContents`** — используется там, где wrapper мешает layout'у родителя; если удаляешь, нужно проверить потребителей.
+- **`forwardRef`** — обязателен, не убирать. `ref` пробрасывается на корневой `<span>`.
+- **Корневой элемент — `<span>`.** Смена тега сломает потребителей, которые верстают IconWrapper
+  внутри инлайн-контекста и опираются на `parentElement`.
+- **Глобальные классы `hoverable` / `active` / `disabled`** приходят не из CSS-модуля, а из
+  `@sberbusiness/icons-next`, поэтому пишутся строковыми литералами и не должны хешироваться или
+  переименовываться. На них опираются тесты других компонентов (например,
+  `ListItemControlsButton.test.tsx` ищет `.hoverable`).
+- **Имена `IconWrapper`, `IIconWrapperProps`** и все props (`active`, `disabled`,
+  `disableInteraction`, `displayContents`) — часть публичного API, экспортируются из barrel
+  `src/components/IconWrapper/index.ts`.
+- **`children` обязателен** по типу — обёртка без содержимого бессмысленна.
 
 ---
 
 ## Accessibility
 
-- `<span>` без семантики. Если иконка кликабельна, **потребитель должен** добавить `role="button"`/`tabIndex`/`aria-label` через `...rest` **или лучше** использовать `ButtonIcon`.
-- `disabled` prop — **чисто визуальный**, не делает элемент реально disabled (на `<span>` это невозможно). Для interaction-блокировки используй `disableInteraction`.
-- `aria-hidden` — потребитель сам решает, нужно ли прятать иконку от скринридера (если она декоративная рядом с текстом — обычно да).
-
----
-
-## Дизайн-токены
-
-Нет собственных. Цвета иконок приходят из CSS-правил `@sberbusiness/icons-next`
-по классам палитры (`_cdqvp6`, `_102z8qh`, ...), которые подставляются
-компонентами иконок автоматически по `paletteIndex`.
+- Компонент неинтерактивен и не добавляет ARIA-атрибутов: `<span>` без роли остаётся прозрачным
+  для assistive technologies, доступное имя даёт интерактивный родитель (`ButtonIcon`, `Link`,
+  `ListItemControlsButton`).
+- `disabled` — чисто визуальный класс, он не выставляет `aria-disabled` и не блокирует события.
+  Реальную блокировку обеспечивает вложенный `<button disabled>` или `disableInteraction` у
+  потребителя.
+- Если иконка декоративная и рядом есть текст — потребитель передаёт `aria-hidden` через spread.
+  Компонент не хардкодит текстовых строк (библиотека мультиязычная).
 
 ---
 
 ## Связанные компоненты
 
-- `ButtonIcon` / `Button` — уже добавляют `hoverable` вокруг иконки. Использовать IconWrapper внутри них **не нужно**.
-- `List` / `Table` — используют `IconWrapper` в служебных местах (сортировка, экспанд).
-- `IslandAccordion` — использует прямую строку `"hoverable"` для chevron-иконки (тот же паттерн, без компонента).
+- `ButtonIcon` (`src/components/Button/ButtonIcon.tsx`) — оборачивает `<button>` в
+  `IconWrapper displayContents` и прокидывает в него `active` / `disabled`. Основной способ
+  сделать кликабельную иконку.
+- `Link` (`src/components/Link/Link.tsx`) — оборачивает содержимое ссылки в
+  `IconWrapper displayContents`, чтобы иконка внутри ссылки красилась вместе с текстом.
+- `Button` (`src/components/Button/Button.tsx`) — оборачивает содержимое кнопки в
+  `IconWrapper` с кастомным `className` и прокидывает `disabled` / `active`. Единственный
+  в `src/**` случай передачи собственного `className` в IconWrapper.
+- `Chip`, `ChipSort`, `SegmentedControlSegment`, `StepperStep`, `ListItemControlsButton`,
+  `SelectExtendedFieldTarget` — используют IconWrapper для синхронизации цвета иконки
+  с состоянием элемента.
+- `CollapsibleTreeNodeHeader` (`src/components/CollapsibleTree/components/`) — не использует
+  IconWrapper, но ставит те же глобальные классы напрямую на `<button>`; при изменении логики
+  классов держи оба места синхронными.
 
 ---
 
 ## Stories
 
-`stories/Icons/IconWrapper/IconWrapper.stories.tsx`
-Примеры: `stories/Icons/IconWrapper/examples/`
+Основные истории: `stories/Icons/IconWrapper/IconWrapper.stories.tsx`
+Файлы примеров: `stories/Icons/IconWrapper/examples/`
 
 | Story | Example file | Что демонстрирует |
 |---|---|---|
-| `Default` | `DefaultExample.tsx` | Базовое использование с иконкой из icons-next. |
-| `States` | `StatesExample.tsx` | `active` / `disabled` / `disableInteraction`. |
+| `Playground` | — | Интерактивный контроль `active`, `disabled`, `disableInteraction`, `displayContents` |
+| `Default` | `DefaultExample.tsx` | Минимальное использование: обёртка вокруг иконки `@sberbusiness/icons-next` |
+| `States` | `StatesExample.tsx` | Состояния Default / Active / Disabled рядом |
 
 ---
 
@@ -142,4 +141,58 @@ className={clsx("hoverable", className, {
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-08-03 | Создан документ. AI-рефакторинг: JSDoc на `children`, комментарий о происхождении глобальных классов icons-next, убраны избыточные `!!` в `clsx`, `{...props}` перенесён перед управляемыми атрибутами, расширены unit-тесты (`displayContents`, дефолты, мердж `className`, spread rest-props, `onClick`). Публичный API не изменён. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Icons/IconWrapper/examples/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import { IconWrapper } from "@sberbusiness/triplex-next";
+import { SettingsStrokeSrvIcon20 } from "@sberbusiness/icons-next";
+
+export const DefaultExample = () => (
+    <IconWrapper>
+        <SettingsStrokeSrvIcon20 paletteIndex={5} />
+    </IconWrapper>
+);
+```
+
+### States
+
+`stories/Icons/IconWrapper/examples/StatesExample.tsx`
+
+```tsx
+import React from "react";
+import { IconWrapper } from "@sberbusiness/triplex-next";
+import { SettingsStrokeSrvIcon20 } from "@sberbusiness/icons-next";
+
+export const StatesExample = () => (
+    <div style={{ display: "flex", alignItems: "center", gap: "32px" }}>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Default</div>
+            <IconWrapper>
+                <SettingsStrokeSrvIcon20 paletteIndex={5} />
+            </IconWrapper>
+        </div>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Active</div>
+            <IconWrapper active>
+                <SettingsStrokeSrvIcon20 paletteIndex={5} />
+            </IconWrapper>
+        </div>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Disabled</div>
+            <IconWrapper disabled>
+                <SettingsStrokeSrvIcon20 paletteIndex={5} />
+            </IconWrapper>
+        </div>
+    </div>
+);
+```
+