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

package/bundle/components/Chip.md

@@ -0,0 +1,404 @@
+---
+component: Chip
+category: Chips
+figma-node: ""
+figma-file: ""
+related: [ChipGroup, Badge, IconWrapper, SelectField, MultiselectField]
+tokens:
+  - --triplex-next-Chip-Background_Default
+  - --triplex-next-Chip-Background_Hover
+  - --triplex-next-Chip-Background_Active
+  - --triplex-next-Chip-Background_Disabled
+  - --triplex-next-Chip-Background_Selected_Default
+  - --triplex-next-Chip-Background_Selected_Hover
+  - --triplex-next-Chip-Background_Selected_Active
+  - --triplex-next-Chip-Background_Selected_Disabled
+  - --triplex-next-Chip-Color_Default
+  - --triplex-next-Chip-Color_Hover
+  - --triplex-next-Chip-Color_Active
+  - --triplex-next-Chip-Color_Disabled
+  - --triplex-next-Chip-Color_Selected_Default
+  - --triplex-next-Chip-Color_Selected_Hover
+  - --triplex-next-Chip-Color_Selected_Active
+  - --triplex-next-Chip-Color_Selected_Disabled
+  - --triplex-next-Chip-Shadow_Focus
+stories: stories/Chips/Chip.stories.tsx (+ 8 других файлов)
+version: "1.0"
+---
+
+# Chip
+
+## Назначение
+
+Семейство интерактивных "таблеток" (chips): прямоугольные элементы со
+скруглением для выбора, сортировки, фильтрации. Включает **базовый `Chip`**
+и **9 вариантов на его основе**. Чипы обычно кладутся внутрь `ChipGroup`
+(горизонтальный список с gap'ами и переносом).
+
+Базовый `Chip` — `<span role="button">`, реагирует на клавиатуру (Space
+блокирует скролл), поддерживает selected/disabled, prefix/postfix иконки
+и "точку уведомления" через `Badge.Dot`.
+
+Варианты:
+- **`ChipIcon`** — чип только с иконкой (иконка в prefix, пустой span в postfix для симметрии).
+- **`ChipMultiselect`** — target-чип для `MultiselectField` с ClearButton / DropdownArrow.
+- **`ChipSelect`** (в subfolder) — target-чип для `SelectExtendedField`.
+- **`ChipOptions`** — чип с иконкой опций + clear button.
+- **`ChipSort`** — чип-иконка для сортировки + selectExtendedField dropdown.
+- **`ChipSuggest`** (в subfolder) — чип-input с саджестами.
+- **`ChipDatePicker`** (в subfolder) — чип с календарным попапом.
+- **`ChipClearButton`** — кнопка "×" для очистки выбранного.
+- **`ChipDropdownArrow`** — стрелка dropdown (ротируется при opened).
+
+Используй когда: нужен фильтр/сортировка/мультивыбор в линейном наборе.
+Рекомендуется всегда внутри `ChipGroup`.
+Не используй когда: нужна "метка-значок" без интерактива (бери `Badge`/`Tag`);
+нужен input поля формы (бери `TextField`/`SelectField`).
+
+---
+
+## Файловая структура
+
+```text
+src/components/Chip/
+├── Chip.tsx                            # Базовый, React.forwardRef
+├── ChipClearButton.tsx                 # ButtonIcon-обёртка с крестиком по size
+├── ChipDropdownArrow.tsx               # Стрелка, rotate при rotated
+├── ChipIcon.tsx                        # Chip с prefix=children и postfix=<span />
+├── ChipMultiselect.tsx                 # MultiselectField target
+├── ChipOptions.tsx                     # Chip + OptionsIcon + ChipClearButton
+├── ChipSort.tsx                        # SelectExtendedField target с SortIcon
+├── ChipDatePicker/
+│   ├── ChipDatePicker.tsx
+│   ├── ChipDatePickerTarget.tsx
+│   └── index.ts
+├── ChipSelect/
+│   ├── ChipSelect.tsx
+│   ├── ChipSelectTarget.tsx
+│   └── index.ts
+├── ChipSuggest/
+│   ├── ChipSuggest.tsx
+│   ├── ChipSuggestTarget.tsx
+│   ├── ChipSuggestDropdown.tsx
+│   ├── desktop/
+│   ├── types.ts
+│   └── index.ts
+├── index.ts                            # Barrel всех вариантов
+├── styles/
+│   ├── Chip.module.less                # Root чипа
+│   ├── ChipClearButton.module.less
+│   ├── ChipDropdownArrow.module.less
+│   ├── ChipOptions.module.less
+│   └── ChipSuggest.module.less
+└── __tests__/
+```
+
+Особенности:
+- **Нет общего enum/типов файла** — каждый чип декларирует свой интерфейс
+  через `extends IChipProps` / `Omit<IChipProps, ...>` / подобное.
+- **`ChipGroup` — отдельный компонент** (в `src/components/ChipGroup`). Большинство
+  чипов получают `styles.chipGroupItem` класс, чтобы быть валидным flex-item
+  внутри ChipGroup.
+- **`ChipIcon` делает `postfix={<span />}`** — трюк для симметричных
+  паддингов, так как Chip меняет padding при наличии postfix.
+
+---
+
+## Варианты и props
+
+### Base `Chip` — `IChipProps extends Omit<HTMLAttributes<HTMLSpanElement>, "prefix">, DataAttributes`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `size` | `EComponentSize` | `MD` | SM=28px, MD=40px, LG=56px. |
+| `disabled` | `boolean` | — | Визуальный disabled + `tabIndex=-1`. |
+| `selected` | `boolean` | — | "Активен" (галочка-выбор). |
+| `prefix` | `ReactNode` | — | Контент слева (обычно иконка). Оборачивается в `IconWrapper`. |
+| `postfix` | `ReactNode` | — | Контент справа. |
+| `showNotificationIcon` | `boolean` | — | Отрисовать `Badge.Dot` в правом-верхнем углу. |
+| `children` | `ReactNode` | — | Основной контент. |
+| `...HTMLSpanAttributes` | — | — | Все кроме `prefix` (HTML-атрибут переопределён). |
+
+### `ChipIcon` — `IChipIconProps extends Omit<IChipProps, "prefix" | "postfix">`
+
+Принимает `children` (иконку), кладёт в `prefix`, форсирует `postfix=<span/>`
+для симметричных паддингов.
+
+### `ChipClearButton` — `IChipClearButtonProps extends Omit<IButtonIconProps, "children">`
+
+Кнопка `<button>` с крестиком. Иконка выбирается по `size`:
+- SM → `CrossStrokeSrvIcon16`
+- MD → `CrossStrokeSrvIcon20`
+- LG → `CrossStrokeSrvIcon24`
+
+### `ChipDropdownArrow`
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `rotated` | `boolean` | `true` → rotate(180deg). |
+| `size` | `EComponentSize` | Выбирает иконку Caret 16/20/24. |
+
+### `ChipMultiselect` — `extends Omit<IMultiselectFieldProps, "renderTarget">`
+
+Обёртка над `MultiselectField`, где `renderTarget` рендерит `Chip` с
+`ClearButton` (если selected) или `DropdownArrow` (если нет).
+
+| Доп. prop | Тип | Описание |
+|---|---|---|
+| `clearSelected` | `() => void` | Коллбек на крестик. |
+| `disabled` | `boolean` | Форвардится в Chip и MultiselectField. |
+| `selected` | `boolean` | Включает "выбранное" состояние + ClearButton. |
+| `label` | `ReactNode` | Текст при пустом выборе. |
+| `displayedValue` | `ReactNode` | Текст при выборе (fallback на label). |
+
+### `ChipOptions` — `extends Omit<IChipProps, "prefix" | "postfix">`
+
+Иконка `OptionsStrokeSrvIcon24` слева. Справа ClearButton только если
+selected.
+
+| Доп. prop | Тип | Описание |
+|---|---|---|
+| `clearSelected` | `() => void` | Коллбек крестика. |
+
+### `ChipSort` — SelectExtendedField target с `SortStrokeSrvIcon24`
+
+`selected = Boolean(value) && !isEqual(defaultValue, value)` — в отличие от
+простого `value`: если текущее значение равно дефолту, чип не подсвечивается
+как изменённый. **Это ключевое поведение Sort-чипа** — дефолтная сортировка
+не должна выглядеть как "активный фильтр".
+
+### `ChipSelect`, `ChipSuggest`, `ChipDatePicker` — см. соответствующие
+файлы в subfolder (компонентно большие). Смотри их `<Name>Target.tsx` для
+того, как они рендерят базовый Chip.
+
+---
+
+## Ключевые особенности реализации
+
+### Space preventDefault в Chip
+
+```ts
+if (isKey(event.code, "SPACE")) {
+    event.preventDefault();
+}
+onKeyDown?.(event);
+```
+
+Блокирует скролл страницы. Не добавляет toggle-логики — это задача
+потребителя. Потребители обычно через свой `onKeyDown` обрабатывают ENTER/SPACE
+для активации.
+
+### `role="button"` + `tabIndex={disabled ? -1 : 0}`
+
+Chip — span с ARIA-ролью button. Disabled → вне tab-order. Переопределение
+`role` через `{...rest}` — возможно (например, ChipMultiselect передаёт
+`role="listbox"`).
+
+### Notification dot = Badge.Dot
+
+```tsx
+{showNotificationIcon && <Badge.Dot size={size} className={styles.notificationIcon} />}
+```
+
+Тот же `Badge.Dot` из семейства Badge. Size — тот же. Позиция абсолютная,
+настраивается в LESS по размерам (SM=3px/3px, MD=4px/4px, LG=6px/6px).
+
+### `prefix`/`postfix` через `IconWrapper`
+
+```tsx
+<IconWrapper className={styles.prefix} disabled={Boolean(disabled)}>
+    {prefix}
+</IconWrapper>
+```
+
+`IconWrapper` управляет цветом иконки через `disabled`. Если внутри prefix
+SVG с `paletteIndex` — подстраивается под текущую тему.
+
+### ChipIcon и `postfix={<span />}` — симметричные паддинги
+
+```tsx
+<Chip {...rest} prefix={children} postfix={<span />} ref={ref} />
+```
+
+Пустой span чтобы `styles.withPostfix` класс применился. Без этого padding-right
+был бы по обычному правилу, и чип выглядел бы асимметрично. **Hack, но
+намеренный.**
+
+### ChipMultiselect — role="listbox" на чипе
+
+```tsx
+<Chip role="listbox" aria-expanded={opened} ...>
+```
+
+Нестандартно — обычно listbox это UL. Это решение MultiselectField:
+chip-таргет действует как listbox button. Screen reader-ы разного качества
+по-разному интерпретируют. Если нужна более строгая семантика — потребителю
+надо делать свой renderTarget.
+
+### ChipSort — `isEqual` с defaultValue
+
+```ts
+const selected = Boolean(value) && !isEqual(defaultValue, value);
+```
+
+Использует `lodash` (не `-es`). Не менять без общего рефакторинга импортов.
+Deep equal нужен, потому что options — объекты (value, label).
+
+### `aria-expanded` → `.chip[aria-expanded="true"]` стили
+
+```less
+&:active,
+&[aria-expanded="true"] {
+    background: var(--triplex-next-Chip-Background_Active);
+}
+```
+
+CSS-селектор на атрибут. Когда dropdown раскрыт, чип выглядит "нажатым" без
+дополнительного className. Умный приём.
+
+### `styles.chipGroupItem` — маркер для ChipGroup
+
+Почти все варианты получают этот класс:
+```less
+.chipGroupItem { display: inline-block; }
+```
+
+ChipGroup рендерит flex-контейнер и ожидает inline-block детей. **Не
+удалять класс** — иначе чипы сломают layout в ChipGroup.
+
+### `uniqueId()` в ChipSort для `aria-controls`
+
+```ts
+const instanceId = useRef(uniqueId());
+```
+
+Связывает ChipIcon (role=combobox) и dropdown. Если через useRef(uniqueId())
+— значение стабильно между рендерами, но каждый инстанс получит свой id.
+
+---
+
+## Инварианты
+
+- **`Chip` — forwardRef**, не удалять.
+- **`role="button"` и `tabIndex` на Chip** — не менять семантику без
+  согласования.
+- **`Space preventDefault`** в `handleKeyDown` — не удалять (скролл
+  страницы).
+- **`Omit<HTMLAttributes, "prefix">`** — нужно, т.к. `prefix` — HTML
+  устаревший атрибут (RDFa).
+- **`IconWrapper` для prefix/postfix** — не замена на div. `IconWrapper`
+  управляет цветом иконок по disabled.
+- **`styles.chipGroupItem`** — на каждом root-элементе вариантов чипов.
+  Ожидается ChipGroup'ом.
+- **`ChipIcon` → `postfix={<span />}`** — не удалять span. Нужен для
+  симметричных паддингов.
+- **`ChipSort` — `!isEqual(defaultValue, value)` для selected** — не
+  упрощать до `Boolean(value)`. Это UX-правило (дефолт не "активный фильтр").
+- **`Badge.Dot` для notification icon** — не заменять на произвольный
+  элемент, размер синхронизирован с size чипа.
+- **Базовые токены `--triplex-next-Chip-*`** — не дублировать для вариантов.
+  Варианты используют одни и те же токены (цвета).
+- **Варианты (ChipSelect/ChipSuggest/ChipDatePicker) обёртки над
+  SelectExtendedField/SuggestField/подобными** — не инвертировать зависимость
+  (не Chip оборачивает Field, а наоборот).
+- **`lodash` (не `-es`) в ChipSort** — исторически, не менять точечно.
+
+---
+
+## Accessibility
+
+- **`role="button"`** на Chip — работает с screen reader'ом как кнопка.
+- **`tabIndex` управляется через disabled** — disabled чип вне tab-order.
+- **`aria-expanded`** на Chip в ChipMultiselect / ChipSort — для dropdown
+  состояния. Screen reader озвучит "раскрыто"/"свёрнуто".
+- **`aria-controls`** в ChipSort связывает чип с dropdown через
+  `instanceId`.
+- **Клавиатура**:
+  - Space — preventDefault (против скролла), потребитель обрабатывает
+    активацию.
+  - Enter — bubble up, потребитель вешает handler через `onKeyDown`.
+  - ChipMultiselect/ChipSort — свои `handleKeyDown` обрабатывают Enter/Space
+    для toggle opened.
+- **Notification icon `Badge.Dot`** — чисто визуальный, без ARIA. Если
+  означает "есть новые" — потребитель должен добавить `aria-label` на
+  Chip (например, "Фильтр, есть новые").
+- **Nested interactive**: ClearButton внутри Chip — кнопка в "кнопке".
+  Решается `event.stopPropagation()` на ClearButton, чтобы клик на крестик
+  не триггерил родительский toggle.
+
+---
+
+## Дизайн-токены
+
+**Базовые (разделяемые всеми вариантами):**
+```
+--triplex-next-Chip-Background_Default
+--triplex-next-Chip-Background_Hover
+--triplex-next-Chip-Background_Active
+--triplex-next-Chip-Background_Disabled
+--triplex-next-Chip-Color_Default
+--triplex-next-Chip-Color_Hover
+--triplex-next-Chip-Color_Active
+--triplex-next-Chip-Color_Disabled
+--triplex-next-Chip-Shadow_Focus                      # focus-visible
+```
+
+**Selected (включённое состояние):**
+```
+--triplex-next-Chip-Background_Selected_Default
+--triplex-next-Chip-Background_Selected_Hover
+--triplex-next-Chip-Background_Selected_Active
+--triplex-next-Chip-Background_Selected_Disabled
+--triplex-next-Chip-Color_Selected_Default
+--triplex-next-Chip-Color_Selected_Hover
+--triplex-next-Chip-Color_Selected_Active
+--triplex-next-Chip-Color_Selected_Disabled
+```
+
+Размеры (высоты, radius, padding, font-size) — hardcoded в LESS по size-
+классам, не токенизированы.
+
+---
+
+## Связанные компоненты
+
+- `ChipGroup` (`src/components/ChipGroup`) — контейнер для чипов с
+  горизонтальным скроллом/переносом.
+- `Badge` (`src/components/Badge`) — notification dot (`Badge.Dot`) —
+  та же реализация.
+- `IconWrapper` (`src/components/IconWrapper`) — обёртка для prefix/postfix
+  иконок.
+- `ButtonIcon` (`src/components/Button`) — основа для `ChipClearButton`.
+- `MultiselectField`, `SelectExtendedField`, `SuggestField` — варианты
+  чипов обёртки над этими field'ами.
+- `EComponentSize`, `createSizeToClassNameMap` — общий паттерн size'ов.
+
+---
+
+## Stories
+
+Отдельная story-файл для каждого варианта:
+
+| File | Variant |
+|---|---|
+| `stories/Chips/Chip.stories.tsx` | Base Chip |
+| `stories/Chips/ChipIcon.stories.tsx` | ChipIcon |
+| `stories/Chips/ChipGroup.stories.tsx` | ChipGroup (отдельный компонент) |
+| `stories/Chips/ChipMultiselect.stories.tsx` | ChipMultiselect |
+| `stories/Chips/ChipOptions.stories.tsx` | ChipOptions |
+| `stories/Chips/ChipSelect.stories.tsx` | ChipSelect |
+| `stories/Chips/ChipSort.stories.tsx` | ChipSort |
+| `stories/Chips/ChipSuggest.stories.tsx` | ChipSuggest |
+| `stories/Chips/ChipDatePicker.stories.tsx` | ChipDatePicker |
+
+Примеры в `stories/Chips/examples/<Name>/`. Typical: `Default`, `Playground`,
+`Sizes`, специфичные для варианта (`States`, `WithNotificationIcon`,
+`WithPrefixAndPostfix` для base Chip).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/ChipGroup.md

@@ -0,0 +1,179 @@
+---
+component: ChipGroup
+category: Chips
+figma-node: ""
+figma-file: ""
+related: [Chip, TagGroup]
+tokens: []
+stories: stories/Chips/ChipGroup.stories.tsx
+version: "1.0"
+---
+
+# ChipGroup
+
+## Назначение
+
+Контейнер для набора `Chip` (и любых `Chip*`-вариантов). Управляет
+расстоянием между чипами (`gap` по size), способом переноса (`flex-wrap`)
+или горизонтальным скроллом (`oneLine`), и скрывает скроллбар.
+
+Это **layout-only** обёртка: не передаёт `size` детям, не синхронизирует
+disabled/selected — только стайлит контейнер. Размер чипов потребитель
+задаёт на каждом Chip индивидуально (но обычно ставит тот же, что в
+ChipGroup).
+
+Используй когда: есть 2+ чипа в одной строке или блоке фильтров.
+Не используй когда: один чип (без обёртки он тоже валиден); нужен вертикальный
+список (ChipGroup только горизонтальный); нужны теги-метки — бери `TagGroup`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/ChipGroup/
+├── ChipGroup.tsx                       # React.forwardRef
+├── index.ts                            # Barrel
+└── styles/ChipGroup.module.less        # flex + oneLine (hidden scrollbar) / multiLine (wrap)
+```
+
+Особенности:
+- **Нет `__tests__`**, нет subcomponents — компонент максимально тонкий.
+- **`size` — prop, но НЕ форвардится детям**. Влияет только на `gap`.
+  Размер чипов — ответственность потребителя.
+
+---
+
+## Варианты и props
+
+### `IChipGroupProps extends React.HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `oneLine` | `boolean` | `false` | `true` → `flex` + `overflow: auto` (горизонтальный скролл, скроллбар скрыт). `false` → `flex-wrap: wrap` (многострочный). |
+| `size` | `EComponentSize` | `MD` | Управляет gap: SM=8px, MD=8px, LG=12px. **Не передаётся в Chip.** |
+| `children` | `ReactNode` | — | Обычно набор Chip/ChipIcon/ChipSelect etc. |
+| `className` | `string` | — | Dop class через `clsx`. |
+| `...HTMLDivAttributes` | — | — | Все стандартные. |
+
+---
+
+## Ключевые особенности реализации
+
+### `oneLine` → горизонтальный скролл со скрытым скроллбаром
+
+```less
+&.oneLine {
+    overflow: auto;
+    scrollbar-width: none;
+    -ms-overflow-style: none;
+    &::-webkit-scrollbar { display: none; }
+}
+```
+
+Скроллбар скрыт во всех браузерах. Пользователь скроллит свайпом (touch)
+или shift+wheel. **Без отдельной кнопки "стрелка"** — в отличие от
+`CarouselExtended`. Если нужны стрелки — оборачивай ChipGroup в
+`CarouselExtended`.
+
+### `multiLine` по умолчанию
+
+```less
+&.multiLine { flex-wrap: wrap; }
+```
+
+Без wrap — инлайновые чипы проталкивали бы родителя в overflow. Multi-line
+— стандартное поведение фильтров.
+
+### `gap` зависит от size
+
+- SM / MD: 8px
+- LG: 12px
+
+SM и MD одинаковы — это дизайн-решение. **Не объединять** в `& { gap: 8px }`
+и `&.lg { gap: 12px }` — поменяет интенсивность спецификации, может
+сломать override'ы потребителей.
+
+### `createSizeToClassNameMap(styles)` — тот же паттерн
+
+Тот же `classNameMaps.ts` утилита, что в Badge / Chip / многих других.
+Если добавить XS/XL в EComponentSize — нужно обновить и mapping, и LESS.
+
+### `data-tx={process.env.npm_package_version}` — есть
+
+Стандарт библиотеки. Не удалять.
+
+### size не передаётся детям
+
+**Это отличие от многих других групповых компонентов** (CheckboxXGroup/YGroup
+передают size через контекст). ChipGroup намеренно не передаёт — потребители
+могут иметь чипы разных размеров в одной группе (например, ChipIcon LG +
+Chip MD — визуально смотрится как отдельная подсвеченная кнопка).
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен.
+- **`display: flex`** на root — не менять на grid. Потребители могут
+  полагаться на flex-item поведение чипов (`styles.chipGroupItem`
+  декларирует `display: inline-block`).
+- **Скрытый скроллбар в `oneLine`** — три вендор-префикса, не удалять.
+- **`gap` только на root-класе `.chipGroup`** — дети (чипы) не должны
+  иметь собственных margin'ов.
+- **`size` не прокидывается детям** — осознанное решение. Не добавлять
+  контекст "для консистентности".
+- **`data-tx`** — не удалять.
+
+---
+
+## Accessibility
+
+- **Нет ARIA-ролей** — ChipGroup семантически нейтрален. Если это набор
+  фильтров — потребитель может обернуть в `<fieldset>` с `<legend>` или
+  добавить `role="group"` + `aria-label`.
+- **Клавиатурная навигация** — **не реализована**. Tab перемещается
+  линейно через tabbable-чипы внутри. Arrow keys не поддерживаются. Если
+  нужен roving-tabindex с arrow keys — это задача потребителя (или бери
+  `RadioGroup`/`TabsLine`-семейства).
+- **Скроллбар в oneLine скрыт визуально**, но работает клавиатурой (можно
+  кликнуть в ChipGroup и использовать arrow-left/right для скролла). Screen
+  reader-ы обычно читают содержимое независимо от видимости скроллбара.
+
+---
+
+## Дизайн-токены
+
+Нет. Компонент структурный — gap'ы жёстко в LESS.
+
+---
+
+## Связанные компоненты
+
+- `Chip` и все `Chip*` варианты (`src/components/Chip`) — типичные дети.
+- `TagGroup` (`src/components/Tag`) — аналогичный контейнер для тегов
+  (разная стилистика и семантика).
+- `CarouselExtended` — может обёртывать ChipGroup для добавления стрелок
+  prev/next при `oneLine` overflow.
+- `EComponentSize`, `createSizeToClassNameMap` — общий паттерн.
+
+---
+
+## Stories
+
+`stories/Chips/ChipGroup.stories.tsx`
+Примеры: `stories/Chips/examples/ChipGroup/`
+
+Типовые stories:
+- `Default` — многострочный набор чипов
+- `OneLine` — горизонтальный скролл
+- `Sizes` — MD vs LG gap
+- `Playground` — интерактивный контроль `oneLine` и `size`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |