@sberbusiness/triplex-next-mcp-server 1.45.0-beta → 1.48.0-beta

package/bundle/components/Avatar.md

@@ -1,11 +1,9 @@
 ---
 component: Avatar
-category: Avatars
-figma-node: ""
-figma-file: ""
-related: [Badge, IconWrapper]
+category: Avatar
+related: []
 tokens:
-  - --triplex-next-Avatar-Background
+  - Avatar.Background
 stories: stories/Avatar/Avatar.stories.tsx
 version: "1.0"
 ---
@@ -14,191 +12,162 @@ version: "1.0"
 
 ## Назначение
 
-Контейнер-"плитка" для представления пользовательской идентичности: картинки
-профиля, инициалов, иконки или любого другого ReactNode. Задаёт квадратные
-размеры, скруглённые углы и фоновый цвет. Сам по себе никакого контента не
-рендерит — только обёртка со стилями; визуальное наполнение — через children.
+Квадратный контейнер фиксированного размера со скруглением и фоном-подложкой —
+визуальное представление пользователя, организации или сущности. Собственного
+содержимого не рисует: изображение, инициалы или иконка передаются потребителем.
 
-Размер шкалы (XXS → XXL) покрывает от маленькой иконки в списке до большого
-hero-аватара в профиле.
-
-Используй когда: нужно представить пользователя/сущность в виде стандартного
-квадратного блока с картинкой или инициалами.
-Не используй когда: нужен только круглый avatar — в этой реализации формы
-фиксированы (squircle с разными radius), круг не предусмотрен. Если нужны
-инициалы с авто-генерацией — это задача потребителя, компонент не рендерит текст.
-
----
-
-## Файловая структура
-
-```text
-src/components/Avatar/
-├── Avatar.tsx                     # React.forwardRef, минимальная обёртка
-├── enums.ts                       # EAvatarSize (XXS, XS, SM, MD, LG, XL, XXL)
-├── types.ts                       # IAvatarProps
-├── index.ts                       # Barrel: enums + types + Avatar
-├── styles/Avatar.module.less      # Размеры + border-radius + фон
-└── __tests__/Avatar.test.tsx
-```
-
-Особенности:
-- **Типы и enum вынесены в отдельные файлы** (`types.ts`, `enums.ts`) —
-  это паттерн более крупных компонентов, здесь избыточен, но сохранён для
-  единообразия. Не сводить в один файл без общего рефакторинга стайл-гайда.
-- **Нет helpers, нет subcomponents** — компонент максимально тонкий.
+Используй когда: нужно показать изображение профиля, инициалы или иконку в
+одном из семи типовых размеров — в шапке, в карточке, в списке, рядом с именем.
+Не используй когда: нужен произвольный размер или неквадратная форма —
+`Avatar` жёстко задаёт `width`/`height` и не тянется по содержимому;
+нужна кликабельность или состояние выбора — оберни `Avatar` в интерактивный
+компонент, сам он остаётся неинтерактивным `<div>`.
 
 ---
 
 ## Варианты и props
 
-### `IAvatarProps extends React.HTMLAttributes<HTMLDivElement>`
+Оба собственных props — **обязательные**, значений по умолчанию нет: размер и
+скругление всегда задаёт потребитель явно.
 
-| Prop | Тип | Обязателен | Описание |
-|---|---|---|---|
-| `size` | `EAvatarSize` | **Да** | Размер + скругление углов. Нет значения по умолчанию — потребитель обязан указать. |
-| `children` | `React.ReactNode` | Нет | Содержимое (через `...HTMLAttributes`). Обычно `<img>`, `<svg>`, `<Text>` или их комбинация. Overflow скрывается (`overflow: hidden`) — контент обрезается по форме. |
-| `className` | `string` | Нет | Объединяется с `styles.avatar + sizeClass` через `clsx`. |
-| `...HTMLDivAttributes` | — | — | Все стандартные атрибуты `<div>`, включая `onClick`, `role`, `aria-*`, `style`. |
+### Обязательные props
 
-### `EAvatarSize` — полная шкала
-
-| Значение | Width/Height | Border-radius |
+| Prop | Тип | Описание |
 |---|---|---|
-| `XXS` | 28px | 6px |
-| `XS` | 32px | 8px |
-| `SM` | 40px | 10px |
-| `MD` | 56px | 16px |
-| `LG` | 80px | 20px |
-| `XL` | 96px | 24px |
-| `XXL` | 128px | 28px |
-
-Радиусы непропорциональны размеру (MD=56px с radius=16px ≈ 28%, XXL=128px с
-radius=28px ≈ 22%). Это **дизайн-решение**, а не формула — не пересчитывать.
-Уменьшение относительного радиуса на больших размерах даёт более "квадратный"
-squircle-вид на крупных аватарах.
+| `size` | `EAvatarSize` | Размер стороны квадрата |
+| `borderRadius` | `TAvatarBorderRadius` | Радиус скругления, px |
 
----
+### Размеры (`EAvatarSize`)
 
-## Ключевые особенности реализации
+| Значение | Сторона |
+|---|---|
+| `XXS` | 28px |
+| `XS` | 32px |
+| `SM` | 40px |
+| `MD` | 56px |
+| `LG` | 80px |
+| `XL` | 96px |
+| `XXL` | 128px |
 
-### flex-центрирование контента
+Ширина и высота равны — компонент всегда квадратный, содержимое центрируется
+по обеим осям через `flex`.
 
-```less
-.avatar {
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    overflow: hidden;
-}
-```
+### Радиус скругления (`TAvatarBorderRadius`)
 
-Любой children центрируется автоматически. Для `<img>` потребитель обычно задаёт
-`width: 100%; height: 100%; object-fit: cover;` чтобы заполнить всю область —
-compon компонент не делает этого сам, намеренно: потребитель может показать
-маленькую иконку по центру, а не растянутое изображение.
+Union числовых литералов `6 | 8 | 10 | 12 | 16`, а не enum: значение
+передаётся числом (`borderRadius={12}`). Произвольные радиусы не поддерживаются —
+каждому значению соответствует отдельный CSS-класс. Сочетание размера и радиуса
+ничем не ограничено: любой `borderRadius` допустим с любым `size`.
 
-### `overflow: hidden` обрезает по форме
+### Остальные props
 
-Любой child обрезается по squircle-границам. Это ключевое свойство — картинка
-автоматически получает скруглённые углы без собственного `border-radius`.
+`IAvatarProps` расширяет `React.HTMLAttributes<HTMLDivElement>`: `className`,
+`style`, `children`, `aria-*`, `data-*` и обработчики событий проходят на
+корневой `<div>` как есть. Собственных обработчиков у компонента нет, поэтому
+переданные ни с чем не конкурируют.
 
-### `sizeToClassNameMap` — прямой маппинг enum → className
+### Как задаётся содержимое
 
-```ts
-const sizeToClassNameMap = {
-    [EAvatarSize.XXS]: styles.xxs,
-    // ...
-};
-```
+Компонент — только оболочка, способ наполнения выбирает потребитель:
+
+- **Изображение** — фоном через `style`/`className`
+  (`backgroundImage` + `backgroundSize`), см. story `Example`. Корневой элемент
+  имеет `overflow: hidden`, поэтому содержимое обрезается по радиусу скругления.
+- **Инициалы** — текстовым компонентом в `children` (в примере — `Title`).
+- **Иконка** — иконкой из `@sberbusiness/icons-next` в `children`.
+
+Своего состояния у компонента нет: вывод полностью определяется props.
 
-Объект, не функция. Полный охват всех значений enum (TypeScript проверяет через
-Record-тип на ключах). При добавлении нового размера — **обновлять обе точки**:
-enum и map.
+---
 
-### Фон через CSS-переменную
+## Дизайн-токены
 
-`background: var(--triplex-next-Avatar-Background)` — единственный токен
-компонента. Фон виден, когда children прозрачен или меньше области. Потребитель
-может переопределить через `style` или `className` (например, для цветных
-avatar'ов с инициалами).
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Avatar.ts`.
 
-### `forwardRef` на `<div>`
+```text
+Avatar.Background
+```
 
-Ref идёт на root div. Используется для анимаций, позиционирования Tooltip и т.д.
-Не убирать.
+Токен задаёт цвет подложки, видимой, пока содержимое не перекрывает её целиком
+(например, под инициалами или иконкой). Собственного цвета текста у компонента
+нет — его определяет вложенный типографический компонент.
 
 ---
 
 ## Инварианты
 
-- **`forwardRef`** — обязателен. Не убирать.
-- **`size` обязателен** — не делать defaultValue, чтобы потребитель явно выбирал
-  масштаб (избежать случайного использования мелких аватаров в hero-контексте).
-- **`EAvatarSize` значения** — публичное API, не переименовывать.
-- **Размеры и radius в LESS** — не менять без согласования с дизайнером.
-  Значения подобраны под токены отступов сетки (28, 32, 40, 56, 80, 96, 128 —
-  кратны 4/8).
-- **`overflow: hidden`** на root — не убирать, от этого зависит скругление
-  контента.
-- **`background: var(--triplex-next-Avatar-Background)`** — единственный
-  дизайн-токен, не хардкодить цвета.
-- **`flex` центрирование** — не менять на grid без согласования, это затрагивает
-  все потребительские стили внутри Avatar.
-- **Компонент — тонкая обёртка, НЕ рендерит children-специфику** (например, не
-  генерирует инициалы из имени). Всё — на стороне потребителя. Не усложнять.
-- **Типы в отдельном файле (`types.ts`)** — сохранять паттерн для консистентности
-  с другими компонентами, даже если выглядит избыточным.
+- `forwardRef` на компоненте — не убирать; ref всегда указывает на корневой `<div>`.
+- `size` и `borderRadius` — обязательные props. Сделать любой из них
+  опциональным со значением по умолчанию — изменение публичного API.
+- Значения `EAvatarSize` (`xxs`…`xxl`) — часть публичного API: строковые
+  значения enum видны потребителям, поэтому переименование любого из них —
+  ломающее изменение. Дополнительно на совпадение значений с именами
+  CSS-классов размеров опираются unit-тесты (`toHaveClass(size)`); сам
+  компонент от этого совпадения не зависит — `SIZE_TO_CLASS_NAME_MAP` в
+  `Avatar.tsx` сопоставляет их явно.
+- `TAvatarBorderRadius` — именно union числовых литералов. Тип стирается при
+  компиляции, рантайм-источника правды у набора нет, поэтому расширение набора
+  синхронизируется вручную в шести местах: сам union в `enums.ts`, CSS-класс
+  `borderRadius{N}` в `styles/Avatar.module.less`,
+  `BORDER_RADIUS_TO_CLASS_NAME_MAP` в `Avatar.tsx`, `BORDER_RADIUSES` в
+  `__tests__/Avatar.test.tsx`, `argTypes.borderRadius.options` в
+  `stories/Avatar/Avatar.stories.tsx` и `BORDER_RADIUSES` в
+  `stories/Avatar/examples/BorderRadiusExample.tsx`. Последний особенно легко
+  пропустить: story `BorderRadius` рендерит радиусы по своему списку, поэтому
+  новый радиус в ней просто не появится, а visual-тест этого не заметит —
+  скриншот останется прежним. Набор перечислен ещё и прозой в
+  `docs.description` того же stories-файла — эту строку тоже нужно обновить.
+- Корневой элемент — `<div>` с `overflow: hidden`; содержимое обрезается по
+  скруглению, на этом построен вариант с фоновым изображением.
 
 ---
 
 ## Accessibility
 
-- **Никаких ARIA-ролей по умолчанию** — `<div>` без роли. Если Avatar
-  интерактивный (clickable), потребитель обязан:
-  - Передать `role="button"` + `tabIndex={0}` + `onKeyDown` для клавиатуры.
-  - Или обернуть в `<button>` / `<a>` (с учётом того, что Avatar — div, а div
-    внутри button валиден, но button внутри div — нет).
-- **`<img>` внутри** — alt-текст задаёт потребитель. Avatar не добавляет
-  `aria-label`, не озвучивает children.
-- **Инициалы как children (`<Text>`)** — screen reader прочитает их как текст.
-  Для полного имени — потребитель может скрыть инициалы от screen reader
-  (`aria-hidden`) и добавить `aria-label="Иван Иванов"` на Avatar.
-
----
-
-## Дизайн-токены
+Неинтерактивный контейнер: собственной роли, фокуса и клавиатурных обработчиков
+у компонента нет, `<div>` остаётся семантически нейтральным.
 
-```
---triplex-next-Avatar-Background    # Фон контейнера
-```
+Смысл содержимого описывает потребитель:
 
-Единственный токен. Цвет контента (иконки, текста) определяется самим
-контентом, не компонентом.
+- Аватар несёт информацию (имя пользователя, организация) — одного `aria-label`
+  недостаточно: корневой `<div>` без роли попадает в `generic`, а для него
+  доступное имя запрещено и скринридером игнорируется. Передай роль,
+  поддерживающую имя, вместе с текстом — `role="img"` и `aria-label` (оба уйдут
+  в `...rest`) — либо продублируй смысл текстом рядом. Компонент не хардкодит
+  текст: библиотека мультиязычная.
+- Аватар декоративен и дублирует находящийся рядом текст — скрой его от
+  скринридера через `aria-hidden`.
+- Изображение задаётся фоном, а не `<img>`, поэтому альтернативного текста у него
+  нет по умолчанию — если картинка значима, подпись обязательна.
 
 ---
 
 ## Связанные компоненты
 
-- `Badge` (`src/components/Badge`) — часто комбинируется с Avatar (индикатор
-  статуса / счётчика в углу). Позиционирование — задача потребителя.
-- `IconWrapper` (`src/components/IconWrapper`) — может быть использован внутри
-  Avatar как children для показа иконки вместо фото.
-- `Text` / Typography — используется для рендера инициалов внутри Avatar.
+Отдельного семейства и близких альтернатив у компонента нет — `related` пуст.
+
+Типовые соседи в разметке (связь композиционная, не структурная): типографика
+(`Title`, `Text`) для инициалов и подписи рядом с аватаром, иконки из
+`@sberbusiness/icons-next` в качестве содержимого.
 
 ---
 
 ## Stories
 
-`stories/Avatar/Avatar.stories.tsx`
+Основные истории: `stories/Avatar/Avatar.stories.tsx`
 Файлы примеров: `stories/Avatar/examples/`
 
 | Story | Example file | Что демонстрирует |
 |---|---|---|
-| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `size` |
-| `Default` | `DefaultExample.tsx` | Базовое использование (XXL) |
-| `Sizes` | `SizesExample.tsx` | Все 7 размеров на одной шкале |
-| `Example` | `ExampleUsage.tsx` | Композиция с другими компонентами |
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `size` и `borderRadius` |
+| `Default` | `DefaultExample.tsx` | Пустой аватар XXL со скруглением 12px — базовая подложка |
+| `Sizes` | `SizesExample.tsx` | Все семь размеров от XXS до XXL с подписями |
+| `BorderRadius` | `BorderRadiusExample.tsx` | Все допустимые радиусы скругления: 6 / 8 / 10 / 12 / 16 |
+| `Example` | `ExampleUsage.tsx` | Три способа наполнения: фоновое изображение, инициалы через `Title`, иконка |
+
+Имена файлов примеров (`DefaultExample.tsx`, `ExampleUsage.tsx`) — локальный
+legacy-паттерн папки; новые примеры называются по имени story (`Sizes.tsx`).
 
 ---
 
@@ -206,7 +175,7 @@ Ref идёт на root div. Используется для анимаций, п
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-14 | Создан документ |
 
 ---
 
@@ -220,7 +189,7 @@ Ref идёт на root div. Используется для анимаций, п
 import React from "react";
 import { Avatar, EAvatarSize } from "@sberbusiness/triplex-next";
 
-export const DefaultExample = () => <Avatar size={EAvatarSize.XXL} />;
+export const DefaultExample = () => <Avatar size={EAvatarSize.XXL} borderRadius={12} />;
 ```
 
 ### Sizes
@@ -238,7 +207,29 @@ export const SizesExample = () => (
         {SIZES.map((size) => (
             <div key={size} style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
                 <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
-                <Avatar size={size} />
+                <Avatar size={size} borderRadius={12} />
+            </div>
+        ))}
+    </div>
+);
+```
+
+### BorderRadius
+
+`stories/Avatar/examples/BorderRadiusExample.tsx`
+
+```tsx
+import React from "react";
+import { Avatar, EAvatarSize, TAvatarBorderRadius } from "@sberbusiness/triplex-next";
+
+const BORDER_RADIUSES: TAvatarBorderRadius[] = [6, 8, 10, 12, 16];
+
+export const BorderRadiusExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+        {BORDER_RADIUSES.map((borderRadius) => (
+            <div key={borderRadius} style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{borderRadius}</div>
+                <Avatar size={EAvatarSize.XXL} borderRadius={borderRadius} />
             </div>
         ))}
     </div>
@@ -265,14 +256,15 @@ export const ExampleUsage = () => (
     <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
         <Avatar
             size={EAvatarSize.XXL}
+            borderRadius={12}
             style={{ backgroundImage: "url(assets/images/avatar.png)", backgroundSize: "contain" }}
         />
-        <Avatar size={EAvatarSize.XXL} style={{ backgroundColor: "#339FF1" }}>
+        <Avatar size={EAvatarSize.XXL} borderRadius={12} style={{ backgroundColor: "#339FF1" }}>
             <TypographyTitle size={ETitleSize.H1} weight={EFontWeightTitle.REGULAR} type={EFontType.PRIMARY_INVERT}>
                 AA
             </TypographyTitle>
         </Avatar>
-        <Avatar size={EAvatarSize.XXL} style={{ backgroundColor: "#339FF1" }}>
+        <Avatar size={EAvatarSize.XXL} borderRadius={12} style={{ backgroundColor: "#339FF1" }}>
             <DefaulticonStrokePrdIcon32 paletteIndex={7} />
         </Avatar>
     </div>