@sberbusiness/triplex-next-mcp-server 1.50.0-beta → 1.53.1

package/bundle/components/ChipSelect.md

@@ -0,0 +1,385 @@
+---
+component: ChipSelect
+category: Chips
+related: [Chip, ChipSelectTarget, ChipMultiselect, SelectExtendedField, SelectField]
+tokens: []
+stories: stories/Chips/ChipSelect.stories.tsx
+version: "1.0"
+---
+
+# ChipSelect
+
+## Назначение
+
+Компактный фильтр с выбором одной опции из готового списка. Поле выбора выглядит
+как `Chip`: до выбора показывает `label` и стрелку, после — выбранное значение
+и кнопку сброса. На мобильной ширине список открывается в нижней шторке `Puller`.
+
+Используй когда: в панели фильтров нужен одиночный выбор с коротким текстом результата.
+Рекомендуется располагать внутри `ChipGroup`.
+
+Не используй когда: нужен множественный выбор (`ChipMultiselect`), произвольный
+выпадающий контент (`SelectExtendedField`) или поле формы с placeholder, loading
+и статусом валидации (`SelectField`).
+
+Компонент управляемый по выбору: `value` изменяет потребитель через `onChange` и
+`clearSelected`. Состоянием открытости владеет внутренний `SelectExtendedField`.
+
+---
+
+## Варианты и props
+
+### Выбор и отображение
+
+| Prop | Обязательность / по умолчанию | Назначение и ограничения |
+|---|---|---|
+| `options` | Обязателен | Массив `ISelectFieldOption`. У каждой опции должны быть стабильный уникальный `id`, `value` и отображаемый `label`. Выбранная опция сопоставляется по `id`, а не по ссылке на объект. |
+| `onChange` | Обязателен | Получает выбранный объект опции; после выбора список закрывается. Сам `value` компонент не меняет. |
+| `clearSelected` | Обязателен | Вызывается без аргументов. Для сброса потребитель устанавливает `value={undefined}`; `onChange` при сбросе не вызывается. |
+| `size` | Обязателен | `EComponentSize.SM` / `MD` / `LG`: одинаковый размер поля выбора и списка. |
+| `value` | `undefined` | Выбранная опция. При наличии значения чипс получает selected-стиль и кнопку сброса. |
+| `label` | — | Контент до выбора; одновременно заголовок списка на мобильном экране, в том числе после выбора. |
+| `displayedValue` | `value.label` | Контент вместо подписи выбранной опции. Без `value` игнорируется. `null` / `undefined` дают fallback на `value.label`; `0` и пустая строка сохраняются. |
+
+`ISelectFieldOption` наследует свойства опции `SelectExtendedField`: например,
+`showNotificationIcon` включает значок у пункта списка, а не у самого чипса.
+
+### Вид и открытость
+
+| Prop | По умолчанию | Назначение и ограничения |
+|---|---|---|
+| `type` | `EChipType.TYPE_1` | Визуальный тип `TYPE_1` / `TYPE_2` передаётся в `ChipSelectTarget`. |
+| `disabled` | `false` | Убирает target из tab-порядка, блокирует pointer-события стилями `Chip` и отключает кнопку сброса; ограничения см. в Accessibility. |
+| `onOpen`, `onClose` | — | Уведомления о смене открытости без аргументов. На первом рендере не вызываются. |
+| `closeOnTab` | `false` | Наследуется от `SelectExtendedField` и закрывает список при всплывающем Tab, в том числе из dropdown. Сам target закрывает список по Tab независимо от этого флага. |
+| `className`, HTML-атрибуты | — | Передаются корневому `<div>` `SelectExtendedField`, не вложенному чипсу. |
+
+### Граница наследуемого API
+
+`IChipSelectProps` наследует часть `IChipProps` и `ISelectFieldProps`, но компонент
+не рендерит `SelectField`. `children`, `targetProps`, `dropdownListItemClassName`,
+`mobileTitle`, `loading`, `status` и `placeholder` исключены из API: target и список
+собираются внутри, мобильный заголовок берётся из `label`.
+
+Унаследованный `dropdownProps` присутствует в типе, но текущая реализация не
+передаёт его в `SelectExtendedFieldDropdownDefault`. Не используй его для настройки
+списка.
+
+---
+
+## Дизайн-токены
+
+У `ChipSelect` нет собственных токенов: используемый класс `chipGroupItem`
+задаёт только раскладку, поэтому frontmatter содержит `tokens: []`. Поле выбора
+использует `Chip`: пути `Chip.Background_*`, `Chip.Color_*` и `Chip.Shadow_Focus`
+управляют его состояниями. Их значения определены в
+`src/components/DesignTokens/components/Chip.ts`; полный перечень и назначение —
+в [Chip-ai.md](Chip-ai.md#дизайн-токены).
+
+Список и мобильный overlay используют токены своих компонентов — см.
+[Dropdown-ai.md](../Dropdown/Dropdown-ai.md#дизайн-токены).
+Переопределение через prop `tokens` описано в
+[ThemeProvider-ai.md](../ThemeProvider/ThemeProvider-ai.md#как-переопределять-токены).
+
+---
+
+## Инварианты
+
+- Публичные импорты: `ChipSelect`, `IChipSelectProps`, `ISelectFieldOption`,
+  `EChipType`, `EComponentSize` доступны из `@sberbusiness/triplex-next`.
+- `forwardRef<HTMLDivElement>` обязателен: `ref` указывает на корневой `<div>`
+  `SelectExtendedField`. Вложенный `ChipSelectTarget` — отдельный `<span>`.
+- Сохранять barrel-экспорты `Chip/index.ts` и `Chip/ChipSelect/index.ts`, включая
+  самостоятельный `ChipSelectTarget`.
+- Корневой класс `chipGroupItem` добавляется через `clsx` рядом с пользовательским
+  `className`. Чипс внутри также имеет свой `chipGroupItem`.
+- `selected` вычисляется как `value !== undefined`; текст выбранного значения —
+  через `displayedValue ?? value.label`. Не заменять на проверку truthiness:
+  `displayedValue={0}` и `displayedValue=""` допустимы.
+- Сброс останавливает всплытие клика и не переключает открытость списка;
+  `clearSelected` и `onChange` — разные операции.
+- Значения `EChipType`, `EComponentSize`, props, ref-target и токены — публичный
+  контракт. Story IDs `chips-chipselect--*` связаны с существующими baseline.
+
+---
+
+## Accessibility
+
+- Target — `<span role="button" tabIndex={0}>` с `aria-expanded`, а не combobox.
+  Видимый текст из `label` или выбранного значения даёт имя target.
+- Клик переключает открытость. Enter и Space открывают закрытый список;
+  Tab на target закрывает открытый. Escape и клик вне поля/списка закрывают через
+  `SelectExtendedField`. Клавиатурную навигацию и выбор пунктов реализует `Dropdown`.
+- В отличие от `SelectField`, `ChipSelect` не связывает target со списком через
+  `aria-controls` / `aria-activedescendant`. Переданный `aria-label` или
+  `aria-labelledby` попадает на корневой `<div>`, не на target: не считай его
+  заменой видимого названия чипса.
+- `disabled` задаёт класс и `tabIndex={-1}` на `Chip` и нативный `disabled` на кнопку
+  сброса. Сам target — не нативная кнопка: программно отправленные события
+  не защищены проверкой флага в обработчиках.
+  Не используй такое состояние как защиту бизнес-логики.
+- В selected-состоянии вложена нативная `ChipClearButton`; Enter и Space на ней
+  не всплывают в обработчик открытия target. Доступное имя кнопки сброса текущая
+  композиция не задаёт и отдельного prop для него нет — известное ограничение
+  TRI-139.
+- Собственного управления фокусом и возврата фокуса `ChipSelect` не добавляет;
+  поведение overlay определяется компонентами `Dropdown`.
+
+---
+
+## Связанные компоненты
+
+- `Chip` — базовый компонент семейства, стили размеров, типов и выбранного состояния.
+- [ChipSelectTarget](ChipSelectTarget-ai.md) — самостоятельный публичный target с кнопкой сброса, стрелкой
+  и обработкой клавиатуры; рендерится внутри `ChipSelect`.
+- `ChipMultiselect` — альтернатива для нескольких значений и собственного dropdown-контента.
+- `SelectExtendedField` — рендерится внутри, владеет открытостью и корневым ref.
+- `SelectField` — источник наследуемого интерфейса props и типа опции;
+  полная форма поля с другими возможностями отображения.
+- `ChipGroup` — рекомендуемый контейнер раскладки фильтров.
+
+---
+
+## Stories
+
+Основные истории: `stories/Chips/ChipSelect.stories.tsx`
+Файлы примеров: `stories/Chips/examples/ChipSelect/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Контролы типа, размера, подписей и disabled |
+| `Default` | `DefaultExample.tsx` | Управляемый одиночный выбор и сброс |
+| `Sizes` | `SizesExample.tsx` | SM / MD / LG |
+| `States` | `StatesExample.tsx` | Выбранное и disabled-состояния |
+| `WithNotificationIcon` | `WithNotificationIconExample.tsx` | Значок уведомления у опции списка |
+| `WithCustomDisplayedValue` | `WithCustomDisplayedValueExample.tsx` | Замена текста выбранной опции |
+| `VisualTests` | `VisualTestsExample.tsx` | Размеры и открытый dropdown через play-функцию |
+
+Все не-Playground stories имеют baseline `xs` / `xl` в `__screenshots__/`.
+`WithNotificationIcon` дополнительно показан в `VisualTests`, поскольку его
+отдельная story пропускается test-runner.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-10-19 | Создан документ (TRI-131): описаны управляемый выбор, граница наследуемых props, токены и существующие accessibility-ограничения; собственные props оформлены JSDoc, дополнены unit-тесты контракта. |
+| 2026-10-19 | Удалена ссылка на задачу об ограничении доступности, сохранён номер TRI-139. |
+| 2026-10-21 | Переход на `Puller` (TRIPLEX-961): на мобильной ширине список открывается в нижней шторке `Puller`. |
+| 2026-11-06 | Исправлено (TRI-0): при `disabled` кнопка сброса отключена и недоступна с клавиатуры. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Chips/examples/ChipSelect/DefaultExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipSelect, EComponentSize, type ISelectFieldOption } from "@sberbusiness/triplex-next";
+
+const demoOptions: ISelectFieldOption[] = [
+    { id: "1", value: "option1", label: "Первая опция" },
+    { id: "2", value: "option2", label: "Вторая опция" },
+    { id: "3", value: "option3", label: "Третья опция" },
+    { id: "4", value: "option4", label: "Четвертая опция" },
+    { id: "5", value: "option5", label: "Пятая опция" },
+    { id: "6", value: "option6", label: "Шестая опция" },
+];
+
+export const DefaultExample = () => {
+    const [selected, setSelected] = useState<ISelectFieldOption | undefined>();
+    return (
+        <ChipSelect
+            label="Select label"
+            size={EComponentSize.MD}
+            options={demoOptions}
+            value={selected}
+            onChange={setSelected}
+            clearSelected={() => setSelected(undefined)}
+        />
+    );
+};
+```
+
+### Sizes
+
+`stories/Chips/examples/ChipSelect/SizesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipSelect, EComponentSize, type ISelectFieldOption } from "@sberbusiness/triplex-next";
+
+const demoOptions: ISelectFieldOption[] = [
+    { id: "1", value: "option1", label: "Первая опция" },
+    { id: "2", value: "option2", label: "Вторая опция" },
+    { id: "3", value: "option3", label: "Третья опция" },
+    { id: "4", value: "option4", label: "Четвертая опция" },
+    { id: "5", value: "option5", label: "Пятая опция" },
+    { id: "6", value: "option6", label: "Шестая опция" },
+];
+
+export const SizesExample = () => {
+    const [selectedSM, setSelectedSM] = useState<ISelectFieldOption | undefined>();
+    const [selectedMD, setSelectedMD] = useState<ISelectFieldOption | undefined>();
+    const [selectedLG, setSelectedLG] = useState<ISelectFieldOption | undefined>();
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+            <div>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>SM</div>
+                <ChipSelect
+                    options={demoOptions}
+                    value={selectedSM}
+                    onChange={setSelectedSM}
+                    clearSelected={() => setSelectedSM(undefined)}
+                    size={EComponentSize.SM}
+                    label="Select label"
+                />
+            </div>
+            <div>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>MD</div>
+                <ChipSelect
+                    options={demoOptions}
+                    value={selectedMD}
+                    onChange={setSelectedMD}
+                    clearSelected={() => setSelectedMD(undefined)}
+                    size={EComponentSize.MD}
+                    label="Select label"
+                />
+            </div>
+            <div>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>LG</div>
+                <ChipSelect
+                    options={demoOptions}
+                    value={selectedLG}
+                    onChange={setSelectedLG}
+                    clearSelected={() => setSelectedLG(undefined)}
+                    size={EComponentSize.LG}
+                    label="Select label"
+                />
+            </div>
+        </div>
+    );
+};
+```
+
+### States
+
+`stories/Chips/examples/ChipSelect/StatesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipSelect, EComponentSize, type ISelectFieldOption } from "@sberbusiness/triplex-next";
+
+const demoOptions: ISelectFieldOption[] = [
+    { id: "1", value: "option1", label: "Первая опция" },
+    { id: "2", value: "option2", label: "Вторая опция" },
+    { id: "3", value: "option3", label: "Третья опция" },
+    { id: "4", value: "option4", label: "Четвертая опция" },
+    { id: "5", value: "option5", label: "Пятая опция" },
+    { id: "6", value: "option6", label: "Шестая опция" },
+];
+
+export const StatesExample = () => {
+    const [selectedWithValue, setSelectedWithValue] = useState<ISelectFieldOption | undefined>(demoOptions[0]);
+    const [selectedDisabled, setSelectedDisabled] = useState<ISelectFieldOption | undefined>(demoOptions[1]);
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+            <div style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Selected</div>
+                <ChipSelect
+                    label="Select label"
+                    options={demoOptions}
+                    value={selectedWithValue}
+                    onChange={setSelectedWithValue}
+                    clearSelected={() => setSelectedWithValue(undefined)}
+                    size={EComponentSize.MD}
+                />
+            </div>
+            <div style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Disabled</div>
+                <ChipSelect
+                    label="Select label"
+                    options={demoOptions}
+                    value={selectedDisabled}
+                    onChange={setSelectedDisabled}
+                    clearSelected={() => setSelectedDisabled(undefined)}
+                    disabled
+                    size={EComponentSize.MD}
+                />
+            </div>
+        </div>
+    );
+};
+```
+
+### WithNotificationIcon
+
+`stories/Chips/examples/ChipSelect/WithNotificationIconExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipSelect, EComponentSize, type ISelectFieldOption } from "@sberbusiness/triplex-next";
+
+const options: ISelectFieldOption[] = [
+    { id: "1", value: "option1", label: "Первая опция" },
+    { id: "2", value: "option2", label: "Вторая опция", showNotificationIcon: true },
+    { id: "3", value: "option3", label: "Третья опция" },
+    { id: "4", value: "option4", label: "Четвертая опция" },
+];
+
+export const WithNotificationIconExample = () => {
+    const [selected, setSelected] = useState<ISelectFieldOption | undefined>();
+
+    return (
+        <ChipSelect
+            size={EComponentSize.MD}
+            label="Select label"
+            options={options}
+            value={selected}
+            onChange={setSelected}
+            clearSelected={() => setSelected(undefined)}
+        />
+    );
+};
+```
+
+### WithCustomDisplayedValue
+
+`stories/Chips/examples/ChipSelect/WithCustomDisplayedValueExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipSelect, EComponentSize, type ISelectFieldOption } from "@sberbusiness/triplex-next";
+
+const demoOptions: ISelectFieldOption[] = [
+    { id: "1", value: "option1", label: "Первая опция" },
+    { id: "2", value: "option2", label: "Вторая опция" },
+    { id: "3", value: "option3", label: "Третья опция" },
+    { id: "4", value: "option4", label: "Четвертая опция" },
+    { id: "5", value: "option5", label: "Пятая опция" },
+    { id: "6", value: "option6", label: "Шестая опция" },
+];
+
+export const WithCustomDisplayedValueExample = () => {
+    const [selected, setSelected] = useState<ISelectFieldOption | undefined>(demoOptions[0]);
+    return (
+        <ChipSelect
+            label="Select label"
+            options={demoOptions}
+            value={selected}
+            onChange={setSelected}
+            clearSelected={() => setSelected(undefined)}
+            displayedValue="Displayed value"
+            size={EComponentSize.MD}
+        />
+    );
+};
+```
+