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

package/bundle/components/ChipOptions.md

@@ -0,0 +1,329 @@
+---
+component: ChipOptions
+category: Chips
+related: [Chip, ChipGroup, ChipSort, ChipMultiselect]
+tokens: []
+stories: stories/Chips/ChipOptions.stories.tsx
+version: "1.0"
+---
+
+# ChipOptions
+
+## Назначение
+
+Чипс-точка входа в настройку опций: слева всегда иконка опций, в центре —
+количество выбранных опций, справа в выбранном состоянии — кнопка сброса.
+Сам список опций компонент не содержит: по клику потребитель открывает свой
+`Dropdown`, модальное окно или боковую панель и сам считает, что выбрано.
+
+Используй когда: рядом с фильтрами нужен чипс «Опции / Настройки» с индикацией
+количества выбранного и быстрым сбросом.
+Не используй когда: выбор идёт из готового списка значений — возьми `ChipSelect`
+(одно значение) или `ChipMultiselect` (несколько, тоже со сбросом); нужен просто
+чипс с иконкой без счётчика и сброса — возьми `Chip` с `prefix`.
+
+---
+
+## Варианты и props
+
+`IChipOptionsProps` наследует `Omit<IChipProps, "prefix" | "postfix">`: доступен
+весь API `Chip` (см. `Chip-ai.md`), кроме `prefix` / `postfix` — их занимает сам
+компонент.
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `clearSelected` | `() => void` | Сброс выбора: вызывается кликом по кнопке сброса в `postfix`. Обязателен всегда, даже если чипс никогда не бывает `selected` |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `selected` | `boolean` | `false` | Есть ли выбранные опции. Управляет и визуалом чипса, и палитрой иконки, и показом кнопки сброса |
+| `children` | `React.ReactNode` | — | Обычно число выбранных опций; оборачивается в `.chipOptionsContent` |
+| `size` | `EComponentSize` | `MD` | Размер чипса; тем же размером рисуется кнопка сброса (иконка-крестик 16 / 20 / 24px) |
+| `type` | `EChipType` | `TYPE_1` | Визуальный тип фона, как у `Chip` |
+| `disabled` | `boolean` | `false` | Визуальная блокировка, `tabIndex={-1}`. Кнопку сброса сам по себе не отключает — см. Accessibility (прочие ограничения — в `Chip-ai.md`) |
+| `clearButtonProps` | `Omit<IChipClearButtonProps, "size">` | — | Props кнопки сброса: `aria-label` для её доступного имени, `disabled`, `className`, `data-*`, собственные `onClick` / `onKeyDown`. `size` берётся из `size` чипса и в тип не входит |
+| `showNotificationIcon` | `boolean` | `false` | Значок новых уведомлений, как у `Chip` |
+| `...HTMLSpanAttributes` | — | — | Все атрибуты `<span>` кроме `prefix`, включая `onClick`, `aria-label`, `data-*` |
+
+### Ограничения
+
+- **Компонент неуправляемый.** `selected` и содержимое считает потребитель;
+  `clearSelected` обязан сам привести состояние к «ничего не выбрано» — внутреннего
+  состояния у компонента нет.
+- **`children` для «ничего не выбрано» передавай как `undefined`, а не `0`.** Обёртка
+  `.chipOptionsContent` создаётся по `children !== undefined`, поэтому ноль — это
+  определённое значение, и он отрисуется в чипсе. В примерах stories ноль отсекается
+  явно: `count > 0 ? count : undefined` или `count || undefined`.
+- **Иконка опций всегда 24×24** (`OptionsStrokeSrvIcon24`) и от `size` не зависит —
+  в отличие от иконки кнопки сброса. В `SM` она визуально крупнее, чем крестик.
+- **`prefix` / `postfix` недоступны** — исключены из типа props. Нужен свой postfix —
+  собирай чипс из `Chip` напрямую.
+- **Кнопкой сброса управляют только через `clearButtonProps`** — сам `ChipClearButton`
+  наружу не выведен. Из типа исключён единственный prop — `size`: размер кнопки задаёт
+  `size` чипса.
+- **`onClick` и `onKeyDown` из `clearButtonProps` не заменяют обработчики компонента,
+  а вызываются после них.** В `onClick` это `event.stopPropagation()` и `clearSelected()`,
+  затем внешний обработчик; в `onKeyDown` — `event.stopPropagation()` для `Enter` / `Space`,
+  затем внешний. Разрешить всплытие до чипса через внешний обработчик нельзя: гашение
+  уже произошло.
+- **`event.preventDefault()` во внешнем `onKeyDown` отменяет сброс.** Это нативная семантика
+  `<button>`: сброс приходит не из `keydown`, а из клика, которым браузер активирует кнопку
+  по `Enter` / `Space`, — отменённая активация означает и отсутствие `clearSelected()`.
+  Компонент эту возможность у потребителя не отбирает. Нужен полный контроль над кнопкой —
+  собирай чипс из `Chip` + `ChipClearButton` вручную.
+
+---
+
+## Дизайн-токены
+
+Собственных токенов нет: `ChipOptions.module.less` описывает только раскладку
+контента (`min-width`, `text-align`). Весь цвет, фон, скругления и фокус приходят
+из токенов `Chip.*` — список и правила переопределения см. в `Chip-ai.md`.
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, `ref` указывает на корневой `<span>` компонента `Chip`.
+  Не убирать.
+- **`postfix` вне выбранного состояния — пустой `<span />`, а не `undefined`.** `Chip`
+  выставляет класс `.withPostfix` (обнуляет правый `padding`) по `postfix !== undefined`,
+  поэтому замена заглушки на `undefined` сдвинет содержимое чипса при каждом
+  переключении `selected`. Тот же приём используется в `ChipIcon`.
+- **`event.stopPropagation()` в обработчике клика по кнопке сброса** — без него клик
+  по крестику всплывёт до `Chip` и потребительский `onClick` (обычно открытие списка
+  опций) отработает одновременно со сбросом.
+- **`event.stopPropagation()` на `Enter` / `Space` в обработчике `keydown` кнопки сброса** —
+  без него `Chip` вызовет `preventDefault()` на `Space` (гасит прокрутку страницы) и заодно
+  отменит нативную активацию кнопки, а на `Enter` потребительский `onKeyDown` чипса
+  отработает одновременно со сбросом. Тот же приём в `ChipMultiselect`.
+- **Палитра иконки опций переключается по `selected`** (`paletteIndex` 6 в выбранном
+  состоянии, 5 в обычном) — так иконка остаётся читаемой на контрастном фоне
+  выбранного чипса.
+- **Класс `.chipOptionsContent`** (`min-width: 14px`, `text-align: center`, `display: block`)
+  удерживает ширину чипса при смене однозначного счётчика — не удалять. `display: block`
+  здесь не декоративен: родительский `.content` не флекс-контейнер, и на inline-`<span>`
+  `min-width` не подействует.
+- **Barrel-экспорты** `ChipOptions` и `IChipOptionsProps` из `src/components/Chip/index.ts` —
+  сохранять.
+- **Story ids `chips-chipoptions--*`** завязаны на baseline-скриншоты в `__screenshots__/` —
+  переименование story требует синхронного обновления baseline.
+
+---
+
+## Accessibility
+
+- Корневой элемент — `<span role="button">` из `Chip`; клавиатурную активацию самого
+  чипса компонент не реализует (подробности и причина — в `Chip-ai.md`).
+- **Доступное имя кнопки сброса задавай сам.** Иконка-крестик рендерится с `aria-hidden`,
+  текста у кнопки нет, поэтому по умолчанию доступного имени у неё не будет. Передавай
+  `clearButtonProps={{ "aria-label": "Сбросить выбранные опции" }}` — так сделано в примере
+  story `Default`.
+- **`disabled` чипса сам по себе не отключает кнопку сброса.** `Chip` применяет `disabled`
+  только к корневому `<span>` (`tabIndex={-1}`) и к CSS-классам `IconWrapper`, на вложенную
+  кнопку он не распространяется. В состоянии `disabled selected` крестик остаётся в
+  таб-порядке и кликабельным, то есть `clearSelected` отработает на заблокированном чипсе.
+  Пробрасывай флаг явно — `clearButtonProps={{ disabled }}`.
+- **`Enter` и `Space` на сфокусированной кнопке сброса работают и до чипса не доходят.**
+  Компонент гасит всплытие этих клавиш от кнопки, поэтому `Chip` не отменяет нативную
+  активацию кнопки на `Space`, а внешний `onKeyDown` чипса не срабатывает заодно со
+  сбросом. Остальные клавиши всплывают как обычно — внешний `onKeyDown` их видит и тогда,
+  когда фокус находится на кнопке сброса.
+- Чипс со счётчиком вместо текста (`{3}`) сам себя не объясняет — передавай `aria-label`
+  через `...rest`.
+
+---
+
+## Связанные компоненты
+
+- `Chip` — база: `ChipOptions` рендерит его и наследует его props через
+  `Omit<IChipProps, "prefix" | "postfix">`
+- `ChipGroup` — рекомендуемый контейнер для ряда чипсов; `ChipOptions` имеет класс
+  `.chip` и потому не сжимается в режиме `oneLine`
+- `ChipSort` — тот же приём (иконка в `prefix` + смена палитры по `selected`), но
+  для сортировки и без кнопки сброса
+- `ChipMultiselect` — альтернатива, когда опции — это готовый список значений:
+  тоже `clearSelected` и счётчик, но с дропдауном и собственным target-элементом
+- `ChipClearButton` (`src/components/Chip/ChipClearButton.tsx`) — кнопка сброса в
+  `postfix`; размер иконки-крестика берёт из `size` чипса
+- `OptionsStrokeSrvIcon24` из `@sberbusiness/icons-next` — иконка в `prefix`
+
+---
+
+## Stories
+
+Основные истории: `stories/Chips/ChipOptions.stories.tsx`
+Файлы примеров: `stories/Chips/examples/ChipOptions/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `type`, `size`, `disabled` на живом счётчике |
+| `Default` | `DefaultExample.tsx` | Базовый сценарий: клик увеличивает счётчик, крестик сбрасывает его в ноль; заодно показывает `clearButtonProps` с `aria-label` |
+| `Types` | `TypesExample.tsx` | `TYPE_1` и `TYPE_2` |
+| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG |
+| `States` | `StatesExample.tsx` | Выбранное и заблокированное состояния во всех размерах |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-09-04 | Создан документ (TRI-133, AI-Ready Phase 1) |
+| 2026-09-04 | AI-рефакторинг (TRI-133): JSDoc на интерфейсе, `size` разобран из props явно, иконка опций собрана в один элемент со сменой `paletteIndex`, `typeof children !== "undefined"` → `children !== undefined`, комментарий про `<span />`-заглушку в `postfix`; unit-тесты расширены с 3 до 19 кейсов. Публичный API, DOM и визуал не изменены |
+| 2026-09-08 | Добавлен prop `clearButtonProps` (TRI-133): кнопке сброса можно задать `aria-label`, `disabled` и прочие props `ChipClearButton`; переданные `onClick` / `onKeyDown` вызываются после собственных обработчиков компонента. `Enter` / `Space` на кнопке сброса больше не всплывают до `Chip` — `Space` активирует кнопку, внешний `onKeyDown` чипса не срабатывает заодно со сбросом |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Chips/examples/ChipOptions/DefaultExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipOptions } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => {
+    const [count, setCount] = useState(0);
+
+    return (
+        <ChipOptions
+            selected={count > 0}
+            onClick={() => setCount((c) => c + 1)}
+            clearSelected={() => setCount(0)}
+            clearButtonProps={{ "aria-label": "Сбросить выбранные опции" }}
+        >
+            {count > 0 ? count : undefined}
+        </ChipOptions>
+    );
+};
+```
+
+### Types
+
+`stories/Chips/examples/ChipOptions/TypesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipOptions, EChipType } from "@sberbusiness/triplex-next";
+
+type TypeItemProps = {
+    type: EChipType;
+    label: string;
+};
+
+const TypeItem = ({ type, label }: TypeItemProps) => {
+    const [count, setCount] = useState(0);
+
+    const handleClick = () => setCount((prevCount) => prevCount + 1);
+
+    const handleClearSelected = () => setCount(0);
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{label}</div>
+            <ChipOptions type={type} selected={count > 0} onClick={handleClick} clearSelected={handleClearSelected}>
+                {count || undefined}
+            </ChipOptions>
+        </div>
+    );
+};
+
+const typeOptions = Object.values(EChipType).map((type) => ({
+    value: type,
+    label: type.toUpperCase(),
+}));
+
+export const TypesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {typeOptions.map(({ value, label }) => (
+            <TypeItem key={value} type={value} label={label} />
+        ))}
+    </div>
+);
+```
+
+### Sizes
+
+`stories/Chips/examples/ChipOptions/SizesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipOptions, EComponentSize } from "@sberbusiness/triplex-next";
+
+type SizeItemProps = {
+    size: EComponentSize;
+    label: string;
+};
+
+const SizeItem = ({ size, label }: SizeItemProps) => {
+    const [count, setCount] = useState(0);
+
+    const handleClick = () => setCount((prevCount) => prevCount + 1);
+
+    const handleClearSelected = () => setCount(0);
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{label}</div>
+            <ChipOptions size={size} selected={count > 0} onClick={handleClick} clearSelected={handleClearSelected}>
+                {count || undefined}
+            </ChipOptions>
+        </div>
+    );
+};
+
+const sizeOptions = Object.values(EComponentSize).map((size) => ({
+    value: size,
+    label: size.toUpperCase(),
+}));
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {sizeOptions.map(({ value, label }) => (
+            <SizeItem key={value} size={value} label={label} />
+        ))}
+    </div>
+);
+```
+
+### States
+
+`stories/Chips/examples/ChipOptions/StatesExample.tsx`
+
+```tsx
+import React from "react";
+import { ChipOptions, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const StatesExample = () => {
+    return (
+        <div style={{ display: "flex", gap: 24 }}>
+            <div style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", gap: "8px" }}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Selected</div>
+                <ChipOptions size={EComponentSize.SM} selected clearSelected={() => {}}>
+                    {1}
+                </ChipOptions>
+                <ChipOptions size={EComponentSize.MD} selected clearSelected={() => {}}>
+                    {2}
+                </ChipOptions>
+                <ChipOptions size={EComponentSize.LG} selected clearSelected={() => {}}>
+                    {3}
+                </ChipOptions>
+            </div>
+            <div style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", gap: "8px" }}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Disabled</div>
+                <ChipOptions size={EComponentSize.SM} disabled clearSelected={() => {}} />
+                <ChipOptions size={EComponentSize.MD} disabled clearSelected={() => {}} />
+                <ChipOptions size={EComponentSize.LG} disabled clearSelected={() => {}} />
+            </div>
+        </div>
+    );
+};
+```
+

package/bundle/components/ChipSort.md

@@ -0,0 +1,333 @@
+---
+component: ChipSort
+category: Chips
+related: [Chip, ChipSelect, ChipGroup, SelectExtendedField, IconWrapper]
+tokens: []
+stories: stories/Chips/ChipSort.stories.tsx
+version: "1.0"
+---
+
+# ChipSort
+
+## Назначение
+
+Чипс-переключатель сортировки: компактная иконка сортировки, по нажатию на которую
+открывается выпадающий список вариантов. Выбранное значение текстом не показывается —
+единственная обратная связь в свёрнутом виде это подсветка иконки, и она включается,
+только когда текущее значение отличается от `defaultValue`.
+
+Используй когда: в панели фильтров нужен выбор порядка сортировки, а места под
+текстовый лейбл нет — иконка занимает ровно ширину `ChipIcon`.
+Не используй когда: выбранное значение должно быть видно текстом (возьми `ChipSelect`),
+нужен множественный выбор (`ChipMultiselect`) или нужен обычный select в форме
+(`SelectField`).
+
+Компонент управляемый: `value` и `onChange` держит потребитель. Рекомендуется
+располагать внутри `ChipGroup` — он задаёт отступы и режим одной строки.
+
+---
+
+## Варианты и props
+
+`IChipSortProps` — это `Omit<IChipSelectProps, "targetProps" | "clearSelected" | "defaultValue">`
+плюс собственный `defaultValue`. То есть API совпадает с `ChipSelect`, кроме
+обязательного сброса значения (`clearSelected`): у `ChipSort` сбрасывать нечего,
+у сортировки всегда есть текущий порядок.
+
+Неизвестные компоненту атрибуты (`data-*`, `aria-*`, `style`, `id`, обработчики `<div>`)
+попадают на корневой `<div>` `SelectExtendedField`, а не на чипс-таргет.
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `size` | `EComponentSize` | Размер чипса и выпадающего списка: `SM` / `MD` / `LG` |
+| `options` | `ISelectFieldOption[]` | Список вариантов сортировки. Опция сопоставляется по `id` |
+| `onChange` | `(option: ISelectFieldOption) => void` | Вызывается с выбранной опцией; список после выбора закрывается |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `value` | `ISelectFieldOption` | — | Текущее значение. Помечает опцию в списке как выбранную и участвует в подсветке иконки |
+| `defaultValue` | `ISelectExtendedFieldDefaultOption` | — | Значение «по умолчанию». Пока `value` **глубоко равен** ему, чипс не подсвечен |
+| `type` | `EChipType` | `TYPE_1` | Визуальный тип чипса, прокидывается в `ChipIcon` |
+| `disabled` | `boolean` | `false` | Блокирует таргет (визуально + `tabIndex={-1}`, см. ограничения `Chip`) |
+| `label` | `React.ReactNode` | — | Используется **только** как заголовок списка в мобильном режиме (`mobileTitle`). В десктопной разметке не отображается |
+| `className` | `string` | — | Дополнительный класс корневого `<div>`, рядом с `.chipGroupItem` |
+| `onOpen` / `onClose` | `() => void` | — | Колбэки открытия и закрытия списка, приходят из `SelectExtendedField` |
+| `closeOnTab` | `boolean` | `false` | Закрывать список по Tab |
+
+### Семантика `defaultValue` и подсветки
+
+Это главное отличие `ChipSort` от остальных чипсов-селектов:
+
+```text
+selected = value != null && !isEqual(defaultValue, value)
+```
+
+- `value` не задан → иконка не подсвечена;
+- `value` задан, `defaultValue` не задан → подсвечена;
+- `value` глубоко равен `defaultValue` (`lodash-es/isEqual`, не по ссылке) → **не**
+  подсвечена: сортировка по умолчанию — это не изменённый фильтр;
+- иначе → подсвечена (класс `.selected` на чипсе плюс акцентный `paletteIndex` иконки).
+
+Сравнение глубокое, поэтому `defaultValue={{...options[0]}}` работает так же, как
+`defaultValue={options[0]}`. Но `label` опции — `React.ReactNode`: если в нём лежит
+JSX, `isEqual` сравнивает деревья элементов. Держи в `defaultValue` ту же опцию,
+что и в `options`, — тогда сравнение остаётся дешёвым и предсказуемым.
+
+### Известные ограничения (унаследованы от `IChipSelectProps`)
+
+- **`displayedValue`** входит в тип props, но компонентом не используется: отображать
+  нечего, таргет — иконка. Переданное значение уходит в `...restProps` на корневой
+  `<div>` и вызывает React-предупреждение о неизвестном DOM-атрибуте. Не передавай.
+- **`dropdownProps`** объявлен в типе (через `ISelectFieldProps`), но до
+  `SelectExtendedFieldDropdownDefault` не доходит — попадает в тот же спред на
+  корневой `<div>`. Настроить `Dropdown` через него сейчас нельзя. Тот же разрыв
+  есть у `ChipSelect`; чинить нужно синхронно по всему семейству, отдельной задачей.
+- **Доступное имя таргета задать нечем.** У icon-only чипса нет текста, а
+  `role="combobox"` стоит на `<span>` из `ChipIcon`. Переданные потребителем
+  `aria-label` / `aria-labelledby` попадают в `...restProps` и приземляются на
+  корневой `<div>`, у которого нет `role`: на generic-элементе эти атрибуты
+  спецификацией ARIA не поддерживаются и скринридером не озвучиваются. Добраться
+  до таргета через публичный API нельзя — `targetProps` исключён `Omit`'ом, а
+  `renderTarget` пользовательские props в `ChipIcon` не спредит. Чинится пробросом
+  до `ChipIcon` (например, возвратом `targetProps`) — изменение публичного API,
+  отдельной задачей синхронно по семейству `Chip*`.
+- **Цель `ref` разошлась с объявленным типом.** `ref` уходит на чипс-таргет
+  (`<span>` из `ChipIcon`), а тип объявлен `HTMLDivElement` — компилируется только
+  из-за структурной совместимости. Соседний `ChipSelect` прокидывает `ref` на
+  корневой `<div>` и своему типу соответствует, то есть внутри семейства контракт
+  разъехался. Кандидат на исправление в мажорной версии, не вечное правило.
+- **Ширина списка** не настраивается: `width` в `SelectExtendedFieldDropdownDefault`
+  не передаётся, поэтому работает дефолт `Dropdown` — `EDropdownWidth.CONTENT`,
+  ширина по контенту, а не по ширине таргета-иконки (что для иконки и правильно).
+
+---
+
+## Дизайн-токены
+
+Собственных токенов у компонента нет: в `styles/Chip.module.less` ему принадлежит
+только `.chipGroupItem` (`display: inline-block`). Весь визуал приходит из компонентов,
+на которых он построен:
+
+- таргет — `Chip` / `ChipIcon`, группа `Chip` (фон, цвет, тень фокуса, состояние `selected`);
+- иконка сортировки — `IconWrapper` (группа `IconWrapper`) плюс палитра иконки из
+  `@sberbusiness/icons-next` (`paletteIndex`, а не токен);
+- выпадающий список — `Dropdown` и `DropdownList`.
+
+Полный список токенов чипса — в `Chip-ai.md` → «Дизайн-токены».
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — не убирать. `ref` указывает **не** на корневой `<div>`, а на
+  чипс-таргет (`<span>` из `ChipIcon`). Цель `ref` и объявленный тип не менять без
+  breaking-окна — почему они разошлись, см. «Известные ограничения».
+- **`clearSelected` исключён из props** намеренно (`Omit`). Не возвращать: у сортировки
+  нет состояния «ничего не выбрано».
+- **`defaultValue` переопределяет DOM-атрибут** `defaultValue` из
+  `React.HTMLAttributes<HTMLDivElement>` (для этого он и в `Omit`). Тип
+  `ISelectExtendedFieldDefaultOption`, а не строка.
+- **Подсветка считается через `isEqual`**, а не по ссылке. Замена на `===` изменит
+  поведение у потребителей, передающих новый объект на каждый рендер.
+- **`role="combobox"` на таргете** перекрывает `role="button"` из `Chip` — он выставляется
+  после дефолтов `Chip` в спреде props. Порядок не менять.
+- **`aria-controls` таргета и `listId` списка — один и тот же `uniqueId()`**, живущий
+  в `useRef` на всё время жизни экземпляра. Связка target ↔ список держится только на нём.
+- **`uniqueId()` из `lodash-es`, а не `React.useId`** — код должен собираться в ветке
+  `release-0` под React 17.
+- **Класс `.chipGroupItem`** на корневом `<div>` — общий маркер семейства Chip*.
+  Не удалять и не переименовывать.
+- **Barrel `src/components/Chip/index.ts`** экспортирует `ChipSort` и `IChipSortProps` —
+  сохранять.
+- **Story ids `chips-chipsort--*`** завязаны на baseline-скриншоты в `__screenshots__/` —
+  переименование story требует обновления baseline.
+
+---
+
+## Accessibility
+
+- Таргет — `<span role="combobox">` с `aria-expanded`, отражающим состояние списка,
+  и `aria-controls`, указывающим на `id` списка (`role="listbox"`). Список рендерится
+  только когда открыт, поэтому в закрытом состоянии `aria-controls` ссылается на
+  отсутствующий элемент — это осознанный компромисс текущей реализации дропдауна.
+- **Клавиатура:** Enter и Space на закрытом таргете открывают список и вызывают
+  `preventDefault()` (гасят прокрутку страницы и «клик» по пробелу). На открытом
+  списке обработчик ничего не делает — закрытием занимается `SelectExtendedField`
+  (Escape, клик вне компонента, при `closeOnTab` — Tab). Стрелочная навигация по
+  опциям — внутри `DropdownList`.
+- Компонент **не задаёт себе доступное имя**, и задать его снаружи сейчас нечем —
+  см. «Известные ограничения». Библиотека мультиязычная, текст не хардкодится.
+- `disabled` у `Chip` не нативный: `pointer-events: none` плюс `tabIndex={-1}`.
+  Программно диспатченные события до обработчиков дойдут — см. `Chip-ai.md`.
+- В мобильном режиме (`max-width: SM_MAX`) список показывается как мобильный
+  `Dropdown` с заголовком из `label` — без `label` шапка мобильного списка пустая.
+
+---
+
+## Связанные компоненты
+
+- `Chip` — база всего семейства; отсюда классы состояний, фокус и ограничения `disabled`
+- `ChipIcon` — конкретный таргет `ChipSort`: чипс, у которого `children` уходит в `prefix`,
+  а `postfix` — пустой `<span />` ради симметричных отступов
+- `ChipSelect` — альтернатива с тем же API (`IChipSortProps` наследует `IChipSelectProps`):
+  показывает выбранное значение текстом и требует `clearSelected`
+- `ChipGroup` — рекомендуемый контейнер: отступы, перенос строк, режим `oneLine`
+- `SelectExtendedField` — база: владеет состоянием открытости, правилами закрытия
+  и корневым `<div>`; список рендерится через `SelectExtendedFieldDropdownDefault`
+- `IconWrapper` — обёртка иконки сортировки, добавляет состояния `active` / `disabled`
+
+---
+
+## Stories
+
+Основные истории: `stories/Chips/ChipSort.stories.tsx`
+Файлы примеров: `stories/Chips/examples/ChipSort/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `type`, `size`, `disabled` и индекса `defaultValue` |
+| `Default` | `DefaultExample.tsx` | Базовое управляемое использование: `value` + `defaultValue` + `onChange` |
+| `Types` | `TypesExample.tsx` | `TYPE_1` и `TYPE_2` |
+| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG |
+| `VisualTests` | `VisualTestsExample.tsx` | Скриншот-регрессия: три размера с открытым списком |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-09-04 | Создан документ (TRI-132, AI-Ready Phase 1) |
+| 2026-09-04 | AI-рефакторинг (TRI-132): codestyle-чистка `ChipSort.tsx` (объединены дублирующиеся импорты, пути приведены к `../`, magic-числа палитры иконки вынесены в именованные константы, добавлены JSDoc и комментарии к нетривиальной логике), unit-тесты расширены с 1 до 19 кейсов; публичный API, DOM и визуал не изменены |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Chips/examples/ChipSort/DefaultExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipSort, EComponentSize, type ISelectFieldOption } from "@sberbusiness/triplex-next";
+
+const options: ISelectFieldOption[] = [
+    { id: "chip-sort-1", label: "По дате", value: "i1" },
+    { id: "chip-sort-2", label: "По времени", value: "i2" },
+    { id: "chip-sort-3", label: "По названию", value: "i3" },
+];
+
+export const DefaultExample = () => {
+    const [value, setValue] = useState<ISelectFieldOption>(options[0]);
+    return (
+        <ChipSort
+            size={EComponentSize.MD}
+            defaultValue={options[0]}
+            value={value}
+            options={options}
+            onChange={setValue}
+        />
+    );
+};
+```
+
+### Types
+
+`stories/Chips/examples/ChipSort/TypesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipSort, EChipType, EComponentSize, type ISelectFieldOption } from "@sberbusiness/triplex-next";
+
+const options: ISelectFieldOption[] = [
+    { id: "chip-sort-1", label: "По дате", value: "i1" },
+    { id: "chip-sort-2", label: "По времени", value: "i2" },
+    { id: "chip-sort-3", label: "По названию", value: "i3" },
+];
+
+type TypeItemProps = {
+    type: EChipType;
+    label: string;
+};
+
+const TypeItem = ({ type, label }: TypeItemProps) => {
+    const [value, setValue] = useState<ISelectFieldOption>(options[0]);
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{label}</div>
+            <ChipSort
+                type={type}
+                size={EComponentSize.MD}
+                defaultValue={options[0]}
+                value={value}
+                options={options}
+                onChange={setValue}
+            />
+        </div>
+    );
+};
+
+const sizeOptions = Object.values(EChipType).map((type) => ({
+    value: type,
+    label: type.toUpperCase(),
+}));
+
+export const TypesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {sizeOptions.map(({ value, label }) => (
+            <TypeItem key={value} type={value} label={label} />
+        ))}
+    </div>
+);
+```
+
+### Sizes
+
+`stories/Chips/examples/ChipSort/SizesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipSort, EComponentSize, type ISelectFieldOption } from "@sberbusiness/triplex-next";
+
+const options: ISelectFieldOption[] = [
+    { id: "chip-sort-1", label: "По дате", value: "i1" },
+    { id: "chip-sort-2", label: "По времени", value: "i2" },
+    { id: "chip-sort-3", label: "По названию", value: "i3" },
+];
+
+type SizeItemProps = {
+    size: EComponentSize;
+    label: string;
+};
+
+const SizeItem = ({ size, label }: SizeItemProps) => {
+    const [value, setValue] = useState<ISelectFieldOption>(options[0]);
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{label}</div>
+            <ChipSort size={size} defaultValue={options[0]} value={value} options={options} onChange={setValue} />
+        </div>
+    );
+};
+
+const sizeOptions = Object.values(EComponentSize).map((size) => ({
+    value: size,
+    label: size.toUpperCase(),
+}));
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {sizeOptions.map(({ value, label }) => (
+            <SizeItem key={value} size={value} label={label} />
+        ))}
+    </div>
+);
+```
+