@sberbusiness/triplex-next-mcp-server 1.43.0-beta → 1.44.0-beta

package/bundle/components/Tag.md

@@ -1,10 +1,8 @@
 ---
 component: Tag
-category: Data Display
-figma-node: ""
-figma-file: ""
-related: [TagColor, TagGroup, ButtonIcon]
-tokens: []
+category: Tag
+related: [TagGroup, TagColor, ButtonIcon, Text]
+tokens: [--triplex-next-Tag-Background]
 stories: stories/Tag/Tag.stories.tsx
 version: "1.0"
 ---
@@ -13,118 +11,150 @@ version: "1.0"
 
 ## Назначение
 
-Тег для отображения выбранного значения параметра (фильтра/категории).
-Структура: `<span>` с `Text` контентом + опциональная кнопка редактирования
-(`ButtonIcon` с edit-иконкой) + всегда кнопка удаления (`ButtonIcon` с
-cross-иконкой). Иконки масштабируются по `size` (16/20/24).
+Тег — компактная плашка с выбранным значением параметра и кнопками управления им: удалением
+и, опционально, редактированием. Типичное место — строка применённых фильтров или список выбранных
+в форме значений, где пользователь должен видеть выбор и уметь его снять.
 
-Используй когда: нужно показать выбранное значение со встроенной возможностью
-удалить или редактировать. Для цветной маркировки (categorical labels) —
-`TagColor`. Для управления коллекцией тегов — `TagGroup`.
+Используй когда: значение выбрано пользователем и его нужно показать вместе с возможностью убрать
+или изменить.
+Не используй когда: нужна неинтерактивная цветная метка статуса — это `TagColor`, у него нет кнопок,
+но есть `status`. Нужен интерактивный элемент выбора фильтра (открывает выпадающий список,
+хранит выбор) — это семейство `Chip`.
 
 ---
 
-## Файловая структура
+## Варианты и props
 
-```text
-src/components/Tag/
-├── Tag.tsx          # forwardRef<HTMLSpanElement, ITagProps>
-├── types.ts         # ITagProps
-├── styles/Tag.module.less
-├── __tests__/
-└── index.ts
-```
+### Обязательные props
 
----
+| Prop | Тип | Описание |
+|---|---|---|
+| `id` | `string` | Идентификатор тега. Рендерится атрибутом `id` на корневом `<span>` и уходит аргументом в `onEdit` и `onRemove` — по нему потребитель понимает, какой тег группы изменили. Значение должно быть уникальным в пределах документа |
+| `size` | `EComponentSize` | Размер: SM (высота 20px) / MD (28px) / LG (32px). Задаёт высоту, внутренние отступы, размер текста (`ETextSize.B4` / `B3` / `B2`) и размер иконок (16 / 20 / 24) |
 
-## Публичный API
+### Опциональные props
 
-### `ITagProps`
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `children` | `React.ReactNode` | — | Контент тега. Рендерится внутри `Text`, длинный текст обрезается многоточием |
+| `disabled` | `boolean` | `false` | Текст переключается на `EFontType.DISABLED`, обе кнопки получают `disabled` — но своё значение в `editButtonProps` / `removeButtonProps` его перекрывает |
+| `onEdit` | `(id: string) => void` | — | Колбэк редактирования. **Управляет наличием кнопки редактирования** — без него кнопка не рендерится |
+| `onRemove` | `(id: string) => void` | — | Колбэк удаления. На наличие кнопки удаления НЕ влияет — она рендерится всегда |
+| `editButtonProps` | `IButtonIconProps` | — | Props кнопки редактирования. Здесь потребитель задаёт `aria-label` |
+| `removeButtonProps` | `IButtonIconProps` | — | Props кнопки удаления. Здесь потребитель задаёт `aria-label` |
 
-```ts
-extends HTMLAttributes<HTMLSpanElement>
-```
+Остальные props — стандартные атрибуты `span` (`ITagProps extends React.HTMLAttributes<HTMLSpanElement>`),
+уходят на корневой элемент через `...restProps`.
 
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `id` | `string` | — | Уникальный id; передаётся в `onEdit(id)` / `onRemove(id)`. |
-| `size` | `EComponentSize` | — | **Обязателен** (нет default'а). Маппится на размер иконки и текста. |
-| `disabled?` | `boolean` | — | Disabled-состояние; влияет на цвет текста (`EFontType.DISABLED`) и `disabled` обеих кнопок. |
-| `onEdit?` | `(id: string) => void` | — | Если передан — рендерится edit-кнопка. |
-| `onRemove?` | `(id: string) => void` | — | Колбэк удаления; **remove-кнопка рендерится всегда**. |
-| `editButtonProps?` | `IButtonIconProps` | — | HTML/aria-атрибуты для edit-кнопки (объединяется с `onClick`). |
-| `removeButtonProps?` | `IButtonIconProps` | — | HTML/aria-атрибуты для remove-кнопки. |
-| `children` | `ReactNode` | — | Содержимое (текст тега). |
-| `...HTMLAttributes<HTMLSpanElement>` | — | — | На корневой `<span>`. |
-
-### Размер → иконка/текст
-
-| `size` | Edit/Remove иконка | Text size |
-|---|---|---|
-| `SM` | `*StrokeSrvIcon16` | `B4` |
-| `MD` | `*StrokeSrvIcon20` | `B3` |
-| `LG` | `*StrokeSrvIcon24` | `B2` |
+### Асимметрия кнопок
 
-Иконки — `paletteIndex={5}` (приглушённая палитра).
+Две кнопки живут по разным правилам, и это легко перепутать:
 
----
+- кнопка **редактирования** рендерится только при переданном `onEdit`;
+- кнопка **удаления** рендерится всегда, даже без `onRemove` — тогда клик по ней просто ничего
+  не делает.
 
-## Поведение
+### Порядок обработчиков клика
 
-### Edit-кнопка
+`onClick` внутри `editButtonProps` / `removeButtonProps` не заменяет `onEdit` / `onRemove`,
+а вызывается **после** него: компонент вынимает `onClick` из этих props и вешает на кнопку
+собственный обработчик, который сначала зовёт колбэк тега, потом пользовательский `onClick`.
 
-- Рендерится **только** если передан `onEdit`.
-- `onClick` объединяет `onEdit(id)` + `editButtonProps.onClick(event)`.
+---
 
-### Remove-кнопка
+## Дизайн-токены
 
-- Рендерится **всегда** (даже без `onRemove`).
-- `onClick` вызывает `onRemove?.(id)` (опционально) + `removeButtonProps.onClick(event)`.
-- Если `onRemove` не передан — кнопка остаётся видимой, но клик ничего не делает (кроме `removeButtonProps.onClick`).
+```text
+--triplex-next-Tag-Background
+```
 
-### Disabled
+Единственный собственный токен — фон плашки. Цвет текста задаёт `Text` через токены типографики
+(`Typography-Primary_Color` / `Typography-Disabled_Color`), цвет иконок — палитра
+`@sberbusiness/icons-next` (`paletteIndex={5}`), кольцо фокуса кнопок — `ButtonIcon`
+(`Button-Icon_Shadow_Focus`).
 
-- `Text type = DISABLED`.
-- `ButtonIcon disabled` — обе кнопки.
+Размерные значения (высоты 20/28/32px, отступы, `border-radius: 4px`, `gap: 2px`) заданы литералами
+в `styles/Tag.module.less` — они специфичны для компонента.
 
 ---
 
 ## Инварианты
 
-- **`forwardRef<HTMLSpanElement>`** — не убирать.
-- **`size` обязателен** — нет default'а; передавать всегда.
-- **Remove-кнопка всегда в DOM** — даже без `onRemove`. Если нужно скрыть — `display:none` через `removeButtonProps.style` (или собственная обёртка); поведение `Tag` это не поддерживает напрямую.
-- **`onEdit` определяет видимость edit-кнопки** — единственный механизм. `editButtonProps` без `onEdit` не отрендерит кнопку.
-- **`id` прокидывается ТОЛЬКО в колбэки** (`onEdit`/`onRemove`), не в DOM. Если нужен HTML id — через `restProps`.
-- **Иконки `paletteIndex={5}`** — намеренно. Менять только координированно с дизайн-системой.
-- **`Text` size маппится через `sizeToTextSizeMap`**, иконки — через `sizeTo{Edit,Remove}IconMap`. Все три должны обновляться синхронно при добавлении нового размера.
-- **Корень — `<span>`**, не `<div>` — чтобы тег был inline-friendly.
+- `forwardRef<HTMLSpanElement>` — не убирать. Ref всегда указывает на корневой `<span>`.
+- Корневой элемент — `<span>` (тег инлайновый, встаёт в строку текста и в `TagGroup`).
+  Менять на `div` нельзя.
+- `displayName` — `"Tag"`. Не менять.
+- `id` рендерится атрибутом на корневом `<span>` и одновременно служит бизнес-идентификатором
+  в `onEdit` / `onRemove`. Prop обязательный, поэтому идентификатор попадает в DOM у всех
+  потребителей: значение должно быть уникальным в пределах документа. Если бизнес-идентификатор
+  уже используется другим элементом страницы (типовой случай — тег выбранного значения и опция
+  списка в `MultiselectField`), тегу нужен свой префикс.
+- Кнопка удаления рендерится безусловно, вне зависимости от `onRemove` — менять на условный
+  рендер нельзя без согласования, это изменит вёрстку у потребителей, не передающих `onRemove`.
+- Порядок в DOM: текст → кнопка редактирования → кнопка удаления. Он же задаёт порядок фокуса,
+  на него опираются скриншот-тесты.
+- Собственный `onClick` тега на кнопках всегда вызывается раньше пользовательского
+  `onClick` из `*ButtonProps`.
+- Компонент не хардкодит текстовые строки: `aria-label` / `title` кнопок задаёт потребитель.
+  Библиотека мультиязычная.
+- Экспорты `Tag` и `ITagProps` идут в barrel `src/components/Tag/index.ts` — сохранять.
+- Ширина ограничена контейнером (`max-width: 100%`), текст обрезается многоточием
+  (`.content` с `overflow: hidden`, `text-overflow: ellipsis`, `min-width: 0`) — часть
+  визуального контракта, покрыта stories `WithOverflow` и `VisualTests`.
 
 ---
 
 ## Accessibility
 
-- Корневой `<span>` без явной ARIA-роли — потребитель должен задать смысл через `aria-label` или родительский контекст (`TagGroup`).
-- Edit/Remove кнопки — `<button>` через `ButtonIcon`; добавлять `aria-label` через `editButtonProps`/`removeButtonProps` (например, `aria-label="Удалить тег Москва"`).
-- `disabled` отключает кнопки (`aria-disabled` + `disabled` атрибут от `ButtonIcon`).
-- Иконки декоративные — содержание описывается через `aria-label` кнопки.
+- Собственной ARIA-роли у тега нет: корневой `<span>` — контейнер. Роль группы задаёт `TagGroup`
+  (`role="group"`).
+- Кнопки — `ButtonIcon` без текстового контента, поэтому **доступное имя обязан задать
+  потребитель**: `editButtonProps={{ "aria-label": "..." }}` и
+  `removeButtonProps={{ "aria-label": "..." }}`. Без них кнопки остаются безымянными
+  для скринридера. Компонент не подставляет умолчание намеренно — строки на конкретном языке
+  внутри библиотеки запрещены.
+- Клавиатура: собственных обработчиков у тега нет, работает нативная семантика `<button>`
+  (Tab / Enter / Space). Порядок фокуса совпадает с порядком в DOM: сначала редактирование,
+  затем удаление.
+- Кольцо фокуса рисует `ButtonIcon` через `:focus-visible`, то есть только при переходе
+  с клавиатуры.
+- При `disabled` обе кнопки получают нативный `disabled` и выпадают из порядка фокуса,
+  колбэки не вызываются. `disabled` спредится до `editButtonProps` / `removeButtonProps`,
+  поэтому собственное значение в них перекрывает состояние тега — в отличие от `onClick`,
+  который тег вынимает из props принудительно.
 
 ---
 
 ## Связанные компоненты
 
-- `TagColor` — категориальные цветные теги (без edit/remove).
-- `TagGroup` — контейнер для коллекции тегов (с overflow).
-- `ButtonIcon` — кнопки edit/remove.
-- `Typography.Text` — текст внутри.
-- `@sberbusiness/icons-next` — `EditStrokeSrvIcon{16,20,24}`, `CrossStrokeSrvIcon{16,20,24}`.
+- `TagGroup` — контейнер группы тегов (`role="group"`), задаёт раскладку и переносы;
+  собственный `size` передаётся ему отдельно, теги внутри свой `size` получают сами.
+- `TagColor` — визуально похожая плашка, но неинтерактивная: без кнопок, зато со `status`
+  (`DEFAULT` / `SUCCESS` / `INFO` / `WARNING` / `ERROR`). Берётся, когда нужна метка состояния,
+  а не снимаемое значение.
+- `ButtonIcon` — рендерится внутри как кнопка редактирования и удаления; от него тег получает
+  форму, состояние `disabled` и стили фокуса. Все props из `editButtonProps` / `removeButtonProps`
+  уходят именно на него.
+- `Text` — рендерит контент тега; тег выбирает `size` (`ETextSize`) и `type` (`EFontType`)
+  по своим `size` и `disabled`.
 
 ---
 
 ## Stories
 
 Основные истории: `stories/Tag/Tag.stories.tsx`
-Примеры: `stories/Tag/examples/`
+Файлы примеров: `stories/Tag/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `children`, `size`, `disabled` и наличия кнопки редактирования |
+| `Default` | `Default.tsx` | Минимальный тег: контент и кнопка удаления |
+| `Editable` | `Editable.tsx` | Тег с кнопкой редактирования — появляется вместе с `onEdit` |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG |
+| `Disabled` | `Disabled.tsx` | Отключенное состояние: приглушённый текст и заблокированные кнопки |
+| `WithCustomButtonProps` | `WithCustomButtonProps.tsx` | `editButtonProps` / `removeButtonProps`: `title`, `aria-label` и собственный `onClick` |
+| `WithOverflow` | `WithOverflow.tsx` | Обрезка длинного контента многоточием по ширине контейнера |
+| `VisualTests` | `VisualTests.tsx` | Матрица размеров и состояний плюс кольцо фокуса кнопки — для скриншот-тестов |
 
 ---
 
@@ -132,4 +162,155 @@ extends HTMLAttributes<HTMLSpanElement>
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-08-27 | `id` пробрасывается атрибутом на корневой `<span>` — раньше деструктурировался из props и в DOM не попадал (ломающее изменение). |
+| 2026-08-26 | Создан документ. AI-рефакторинг (`displayName`, снят лишний `useCallback` с render-функций, константы приведены к UPPER_SNAKE_CASE, JSDoc на props), расширены unit-тесты, stories переведены на modern pattern. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Tag/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import { Tag, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const Default = () => (
+    <Tag id="default-tag" size={EComponentSize.LG} onRemove={() => {}} removeButtonProps={{ "aria-label": "Удалить" }}>
+        Selected value
+    </Tag>
+);
+```
+
+### Editable
+
+`stories/Tag/examples/Editable.tsx`
+
+```tsx
+import React from "react";
+import { Tag, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const Editable = () => (
+    <Tag
+        id="editable-tag"
+        size={EComponentSize.LG}
+        onEdit={() => {}}
+        onRemove={() => {}}
+        editButtonProps={{ "aria-label": "Редактировать" }}
+        removeButtonProps={{ "aria-label": "Удалить" }}
+    >
+        Selected value
+    </Tag>
+);
+```
+
+### Sizes
+
+`stories/Tag/examples/Sizes.tsx`
+
+```tsx
+import React from "react";
+import { Tag, EComponentSize } from "@sberbusiness/triplex-next";
+
+const SIZES = Object.values(EComponentSize);
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SIZES.map((size) => (
+            <div key={size}>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+                <Tag
+                    id={`${size}-tag`}
+                    size={size}
+                    onEdit={() => {}}
+                    onRemove={() => {}}
+                    editButtonProps={{ "aria-label": "Редактировать" }}
+                    removeButtonProps={{ "aria-label": "Удалить" }}
+                >
+                    Selected value
+                </Tag>
+            </div>
+        ))}
+    </div>
+);
+```
+
+### Disabled
+
+`stories/Tag/examples/Disabled.tsx`
+
+```tsx
+import React from "react";
+import { Tag, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const Disabled = () => (
+    <Tag
+        id="disabled-tag"
+        size={EComponentSize.LG}
+        disabled
+        onEdit={() => {}}
+        onRemove={() => {}}
+        editButtonProps={{ "aria-label": "Редактировать" }}
+        removeButtonProps={{ "aria-label": "Удалить" }}
+    >
+        Selected value
+    </Tag>
+);
+```
+
+### WithCustomButtonProps
+
+`stories/Tag/examples/WithCustomButtonProps.tsx`
+
+```tsx
+import React from "react";
+import { Tag, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const WithCustomButtonProps = () => (
+    <Tag
+        id="custom-props-tag"
+        size={EComponentSize.LG}
+        onEdit={() => {}}
+        onRemove={() => {}}
+        editButtonProps={{
+            title: "Редактировать тег",
+            "aria-label": "Редактировать тег",
+            onClick: () => {},
+        }}
+        removeButtonProps={{
+            title: "Удалить тег",
+            "aria-label": "Удалить тег",
+            onClick: () => {},
+        }}
+    >
+        Selected value
+    </Tag>
+);
+```
+
+### WithOverflow
+
+`stories/Tag/examples/WithOverflow.tsx`
+
+```tsx
+import React from "react";
+import { Tag, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const WithOverflow = () => (
+    <div style={{ maxWidth: 440 }}>
+        <Tag
+            id="long-tag"
+            size={EComponentSize.LG}
+            onEdit={() => {}}
+            onRemove={() => {}}
+            editButtonProps={{ "aria-label": "Редактировать" }}
+            removeButtonProps={{ "aria-label": "Удалить" }}
+        >
+            Very long tag text that should be truncated with ellipsis
+        </Tag>
+    </div>
+);
+```
+