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

package/bundle/components/SelectExtendedField.md

@@ -1,9 +1,7 @@
 ---
 component: SelectExtendedField
-category: Form Controls
-figma-node: ""
-figma-file: ""
-related: [SelectField, MultiselectField, Dropdown, FormField, KeyDownListener]
+category: SelectExtendedField
+related: [SelectField, MultiselectField, SuggestField, Chip, Dropdown, FormField, KeyDownListener, IconWrapper, LoaderSmall]
 tokens: []
 stories: stories/SelectExtendedField/SelectExtendedField.stories.tsx
 version: "1.0"
@@ -13,310 +11,767 @@ version: "1.0"
 
 ## Назначение
 
-**Базовый компонент** для построения custom-Select'ов: оркестрирует
-открытие/закрытие dropdown'а, click-outside, ESC и (опционально)
-TAB-закрытие, прокидывает `opened/setOpened/targetRef/dropdownRef` в
-**render-prop'ы** для target и dropdown. Сам не диктует ни форму
-target'а (icon vs text vs input), ни содержимое dropdown'а — потребитель
-рендерит их через render-функции.
+Базовый компонент Select. Владеет **только** состоянием открытости выпадающего блока и
+правилами его закрытия. Разметку поля выбора компонент отдаёт в рендер-функцию
+`renderTarget`, разметку выпадающего блока — в рендер-функцию `children`. Собственной
+разметки, кроме позиционирующего `<div>`-обёртки, у него нет.
 
-`SelectExtendedField.Target` (`SelectExtendedFieldTarget`) и
-`SelectExtendedField.Dropdown` — типичные реализации; их можно заменить
-своими.
+Используй когда: нужно поле выбора с **нестандартным** содержимым выпадающего блока
+(форма фильтра, чекбоксы с подтверждением, дерево, произвольный контент) или
+нестандартным полем выбора — и при этом нужна готовая логика открытия/закрытия.
 
-Используй когда: строишь нестандартный Select (например, multi-select с
-поиском, color-picker как select, и т.п.). Для типичных — `SelectField`,
-`MultiselectField`.
+Не используй когда:
 
----
-
-## Файловая структура
-
-```text
-src/components/SelectExtendedField/
-├── SelectExtendedField.tsx                                 # forwardRef + Object.assign({Target, Dropdown})
-├── components/
-│   ├── SelectExtendedFieldTarget.tsx                       # forwardRef; FormField + caret + clear + loader
-│   ├── SelectExtendedFieldDropdown.tsx                     # FC; <Dropdown> wrapper + .List
-│   └── SelectExtendedFieldDropdownDefault.tsx              # FC; готовая раскладка опций (desktop + mobile)
-├── styles/
-├── index.ts
-└── __tests__/
-```
+- нужен обычный select со списком опций — используй `SelectField`;
+- нужен множественный выбор с тегами — используй `MultiselectField`;
+- нужен поиск по вводу — используй `SuggestField`;
+- нужен фильтр-чип со списком — используй `Chip.Select` / `Chip.Sort`;
+- выпадающий блок не привязан к полю ввода — используй `Dropdown` или `ButtonDropdownExtended`.
 
 ---
 
-## Compound-структура (через render-prop'ы)
+## Варианты и props
 
-```tsx
-<SelectExtendedField
-    closeOnTab
-    onOpen={...} onClose={...}
-    renderTarget={({ opened, setOpened }) => (
-        <SelectExtendedField.Target
-            opened={opened}
-            setOpened={setOpened}
-            label={selected?.label}
-            placeholder="Выбрать..."
-            fieldLabel="Label"
-            size={EComponentSize.MD}
-            onClear={() => onChange(undefined)}
-        />
-    )}
->
-    {({ opened, setOpened, targetRef, dropdownRef }) => (
-        <SelectExtendedField.Dropdown
-            opened={opened}
-            setOpened={setOpened}
-            targetRef={targetRef}
-            forwardedRef={dropdownRef}
-        >
-            <SelectExtendedField.Dropdown.List dropdownOpened={opened}>
-                {options.map(...)}
-            </SelectExtendedField.Dropdown.List>
-        </SelectExtendedField.Dropdown>
-    )}
-</SelectExtendedField>
-```
+### `SelectExtendedField`
 
----
+`ISelectExtendedFieldProps` расширяет `React.HTMLAttributes<HTMLDivElement>` c
+переопределённым `children`. Неизвестные компоненту атрибуты попадают на корневой `<div>`.
 
-## Варианты и props
+#### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `renderTarget` | `(props: ISelectExtendedFieldTargetProvideProps) => React.ReactNode` | Рендер-функция поля выбора. Получает `opened` и `setOpened` |
+| `children` | `(props: ISelectExtendedFieldDropdownProvideProps) => React.ReactNode` | Рендер-функция выпадающего блока. Получает `opened`, `setOpened`, `targetRef`, `dropdownRef` |
 
-### SelectExtendedField — `ISelectExtendedFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, "children">`
+#### Опциональные props
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `renderTarget` | `(props: ISelectExtendedFieldTargetProvideProps) => ReactNode` | — | Render-prop для target. Получает `{ opened, setOpened }`. |
-| `children` | `(props: ISelectExtendedFieldDropdownProvideProps) => ReactNode` | — | Render-prop для dropdown. Получает `{ opened, setOpened, targetRef, dropdownRef }`. |
-| `onOpen?` | `() => void` | — | Только при реальном переходе `false → true` (skip mount). |
-| `onClose?` | `() => void` | — | Только при `true → false`. |
-| `closeOnTab?` | `boolean` | `false` | Tab закрывает dropdown. |
-| `...HTMLAttributes` | — | — | На корневой `<div>`. |
+| `closeOnTab` | `boolean` | `false` | Закрывать выпадающий блок по нажатию Tab внутри компонента |
+| `onOpen` | `() => void` | — | Вызывается при переходе `opened` в `true`. На первом рендере не вызывается |
+| `onClose` | `() => void` | — | Вызывается при переходе `opened` в `false`. На первом рендере не вызывается |
+| `className` | `string` | — | Дополнительный класс корневого `<div>` |
+
+#### Что получают рендер-функции
+
+| Поле | Кому | Описание |
+|---|---|---|
+| `opened` | обеим | Текущее состояние открытости |
+| `setOpened` | обеим | Сеттер состояния открытости. Стабилен между рендерами (сеттер `useState`) |
+| `targetRef` | `children` | Ссылка на **корневой `<div>` компонента**, а не на поле ввода. По ней `Dropdown` считает своё положение |
+| `dropdownRef` | `children` | Ссылка, которую нужно повесить на контейнер выпадающего блока. По ней компонент отличает нажатие внутри блока от нажатия вне его |
+
+### `SelectExtendedField.Target` (`SelectExtendedFieldTarget`)
 
-### SelectExtendedField.Target — `ISelectExtendedFieldTargetProps extends Omit<IFormFieldProps, "prefix" \| "postfix">`
+Готовое поле выбора поверх `FormField`. `ISelectExtendedFieldTargetProps` расширяет
+`IFormFieldProps` без `prefix` / `postfix` (они переопределены своими типами).
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `opened` | `boolean` | — | Из render-prop'а. |
-| `setOpened` | `(opened: boolean) => void` | — | Из render-prop'а. |
-| `fieldLabel` | `ReactNode` | — | Label, рендерится через `FormFieldLabel`. |
-| `label?` | `ReactNode` | — | Текущий выбранный (отображается в `FormFieldTarget`). |
-| `placeholder?` | `ReactNode` | — | Когда `label` пуст. |
-| `loading?` | `boolean` | — | Заменяет caret на `LoaderSmall` (BRAND). Блокирует клики и keys. |
-| `prefix?` / `postfix?` | `ReactNode` | — | До/после target. Caret/Loader всегда рендерятся в Postfix. |
-| `onClear?` | `() => void` | — | Если передан — рендерится `FormFieldClear`. |
-| `size` | `EComponentSize` | `MD` | Размер. Маппится на `CaretdownStrokeSrvIcon{16/20/24}` и `LoaderSmall size`. |
-| `status` | `EFormFieldStatus` | — | `DISABLED` блокирует клики/keys. |
-| `tabIndex` | `number` | — | Стандартно. |
-
-- `aria-expanded={opened}`, `aria-haspopup="listbox"` — на корне FormField.
-- Открытие по: **click**, **Enter**, **Space**, **ArrowDown**, **ArrowUp** (только когда `!opened`); тогда `preventDefault + stopPropagation`.
-
-### SelectExtendedField.Dropdown — `ISelectExtendedFieldDropdownProps extends Omit<IDropdownProps, "forwardedRef">`
+| `fieldLabel` | `React.ReactNode` | — | Обязательный. Заголовок поля (плавающий label) |
+| `opened` | `boolean` | — | Обязательный. Состояние открытости: поворот каретки, `aria-expanded`, активное состояние `FormField` |
+| `setOpened` | `(opened: boolean) => void` | — | Обязательный. Вызывается по клику и по клавишам открытия |
+| `label` | `React.ReactNode` | — | Выбранное значение |
+| `placeholder` | `React.ReactNode` | — | Отображается, пока нет `label` |
+| `loading` | `boolean` | `false` | Вместо каретки — лоадер; клик и клавиатура не открывают блок |
+| `onClear` | `() => void` | — | Если передан, в постфиксе появляется кнопка очистки |
+| `prefix` / `postfix` | `React.ReactNode` | — | Слоты `FormFieldPrefix` / `FormFieldPostfix`. Постфикс идёт **после** каретки |
+| `size` | `EComponentSize` | `EComponentSize.MD` | Размер поля. Определяет размер каретки и лоадера |
+| `status` | `EFormFieldStatus` | `EFormFieldStatus.DEFAULT` | Визуальное состояние. `DISABLED` блокирует открытие |
+
+### `SelectExtendedField.Dropdown` (`SelectExtendedFieldDropdown`)
+
+Обёртка над `Dropdown`. Отличается только тем, что ссылку принимает не через `ref`,
+а через prop `forwardedRef` — рендер-функция `children` отдаёт готовый `dropdownRef`,
+и передать его через `ref` в JSX было бы невозможно без промежуточной обёртки.
+Остальные props — как у `Dropdown` (`size`, `width`, `direction`, `alignment`,
+`mobileViewProps`, ...). Статическое свойство `List` — это `DropdownList`.
+
+### Ограничения
+
+- Компонент **не управляемый снаружи**: состояние открытости внутреннее, prop'а `opened` у него нет. Открыть блок программно можно только через `setOpened`, полученный в рендер-функции.
+- `SelectExtendedFieldDropdown` — не `forwardRef`-компонент. Ссылка передаётся через `forwardedRef`.
+- Выпадающий блок компонент не рендерит сам и не знает, открыт ли он визуально: `opened` нужно передать в `SelectExtendedFieldDropdown` (или в свою разметку) самостоятельно.
+- Компонент не хранит выбранное значение и не знает про опции. Значение — целиком забота потребителя.
+- Клик по кнопке очистки (`onClear`) не раскрывает выпадающий блок: `SelectExtendedFieldTarget` останавливает всплытие в обработчике `FormFieldClear`. Без этого событие дошло бы до `onClick` на `FormField` и переключило `opened` — так же гасят всплытие `Chip.Select` и `Chip.DatePicker`. Не убирать: затрагивает `SelectField` и `MultiselectField.Target`, которые рендерят тот же `Target`.
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `forwardedRef` | `RefObject<HTMLDivElement>` | Из render-prop'а (dropdownRef). |
-| `targetRef` | `RefObject<HTMLElement>` | Из render-prop'а. |
-| `opened` | `boolean` | — |
-| `children?` | `ReactNode` | — |
-| `...IDropdownProps` | — | width, mobileViewProps, size и т.п. |
+---
 
-Slots: **`SelectExtendedField.Dropdown.List`** = `DropdownList` (re-export).
+## Дизайн-токены
 
-### Provide-types
+Собственных токенов у компонента нет: `SelectExtendedField.module.less` задаёт только
+`position: relative`, а `SelectExtendedFieldTarget.module.less` — раскладку, поворот
+каретки и блокировку указателя в `disabled`. Цвета, фон, границы и тени приходят из
+компонентов, на которых построено поле:
 
-```ts
-ISelectExtendedFieldTargetProvideProps:    { opened, setOpened }
-ISelectExtendedFieldDropdownProvideProps:  { opened, setOpened, targetRef, dropdownRef }
-ISelectExtendedFieldDefaultOption: { value: string; label: ReactNode; ...IDropdownListItemProps без active/onSelect/selected/key/className/keyCodesForSelection }
-```
+- `FormField` и его части (`FormFieldLabel`, `FormFieldTarget`, `FormFieldPrefix`, `FormFieldPostfix`, `FormFieldClear`) — `--triplex-next-FormField-*`;
+- `Dropdown` и `DropdownList` — `--triplex-next-Dropdown-*`, `--triplex-next-DropdownList-*`;
+- `IconWrapper` вокруг каретки — `--triplex-next-IconWrapper-*`;
+- `LoaderSmall` в состоянии загрузки — токены лоадера.
 
-### SelectExtendedFieldDropdownDefault (отдельная утилита)
+Если понадобится собственное визуальное состояние поля выбора — токен заводится
+в `SelectExtendedFieldTarget`, а не в `FormField`.
 
-Готовая раскладка опций для desktop (`Dropdown.List`) **и** mobile (`DropdownMobileHeader/Body/List`). Не часть Object.assign — импортируется отдельно:
+---
 
-```ts
-import { SelectExtendedFieldDropdownDefault } from "@sberbusiness/triplex-next/components/SelectExtendedField";
-```
+## Инварианты
 
-(используется в `SelectField`).
+- `forwardRef` на `SelectExtendedField` и `SelectExtendedFieldTarget` — не убирать. Ref `SelectExtendedField` указывает на корневой `<div>` (тот же элемент, что и `targetRef`), ref `SelectExtendedFieldTarget` — на `FormFieldTarget`, то есть на элемент со значением, а не на корень поля.
+- Barrel `src/components/SelectExtendedField/index.ts` должен сохраняться: компонент используется внутри `SelectField`, `MultiselectField`, `Chip.Select`, `Chip.Sort`, `Chip.Multiselect`.
+- `SelectExtendedFieldDropdownDefault` — **внутренний** компонент, из barrel не экспортируется. Его импортируют по прямому пути `components/SelectExtendedFieldDropdownDefault` внутри библиотеки. Не выносить в публичный API без отдельного решения.
+- Статические свойства `SelectExtendedField.Target` и `SelectExtendedField.Dropdown`, а также `SelectExtendedFieldDropdown.List` — часть публичного API.
+- `setOpened`, отдаваемый рендер-функциям, — это сеттер `useState`. Он обязан оставаться стабильным между рендерами: построенные на нём компоненты кладут его в зависимости колбэков — например `Chip.Select` через `ChipSelectTarget` (`useCallback(..., [opened, setOpened, onKeyDown])`).
+- `onOpen` / `onClose` вызываются **только на смену состояния** и не срабатывают на первом рендере и на повторном маунте в React 18 StrictMode. Реализовано сравнением предыдущего значения `opened` (`prevOpenedRef`), а не флагом «смонтирован» — флаг ломается на двойном маунте.
+- Актуальные `onOpen` / `onClose` хранятся в ref: эффект зависит только от `opened`, поэтому смена идентичности колбэков между рендерами их не вызывает.
+- Закрытие по нажатию мышью вне блока опирается на `dropdownRef`, а не на DOM-вложенность: `Dropdown` рендерится через `Portal` в `document.body`. Если потребитель не повесит `dropdownRef` на свой контейнер, любое нажатие внутри выпадающего блока закроет его.
+- Слушатель `mousedown` на `document` навешивается только пока блок открыт и снимается в cleanup эффекта.
+- Компонент React 17-совместим (ветка `release-0`): не использовать `useId`, `useSyncExternalStore`, `useInsertionEffect` и поведение, зависящее от automatic batching.
+- В `SelectExtendedFieldTarget.module.less` нет классов `loading`, `placeholder`, `label`. Не добавлять ссылки на них в `clsx`: у CSS-модуля такого свойства нет, и в атрибут `class` попадёт литерал `undefined` (баг был исправлен в 1.41.0). Если состоянию нужен стиль — сначала заведи класс в LESS.
 
 ---
 
-## Ключевые особенности реализации
+## Accessibility
 
-### Stable `onOpen`/`onClose` через ref
+- `SelectExtendedFieldTarget` выставляет на корневом элементе `aria-haspopup="listbox"` и `aria-expanded`, отражающий `opened`.
+- Роли `listbox` / `option` и клавиатурную навигацию по опциям (`ArrowUp` / `ArrowDown`, выбор по `Enter` / `Space`) даёт `DropdownList` — то есть `SelectExtendedField.Dropdown.List`. Если выпадающий блок не список, эти роли не появляются и навигацию организует потребитель.
+- Клавиши открытия на поле выбора: `Space`, `Enter`, `ArrowDown`, `ArrowUp`. Обработчик вызывает `preventDefault` (чтобы страница не прокручивалась) и `stopPropagation` — иначе то же нажатие поймает документный обработчик `DropdownListItem` и список сразу выберет опцию.
+- В состояниях `loading` и `status={EFormFieldStatus.DISABLED}` поле не реагирует ни на клик, ни на клавиатуру; `onClick` / `onKeyDown` потребителя в этих состояниях тоже не вызываются.
+- `Escape` закрывает блок из любого места страницы — слушатель `KeyDownListener` висит на `window`.
+- `Tab` закрывает блок только при `closeOnTab`. Фокус компонент не перехватывает и не возвращает: focus trap, если нужен, добавляет потребитель.
+- Связь поля со списком (`aria-controls`, `aria-activedescendant`) компонент **не выставляет** — это делает потребитель. `SelectField` передаёт `listId` в `SelectExtendedFieldDropdownDefault` именно для этого.
+- Компонент не хардкодит текстовые строки: `fieldLabel`, `placeholder`, `aria-label` для кнопки очистки и заголовок мобильной версии передаёт потребитель — библиотека мультиязычная.
 
-```ts
-const onOpenRef = useRef(onOpen);
-const onCloseRef = useRef(onClose);
+---
 
-useLayoutEffect(() => {
-    onOpenRef.current = onOpen;
-    onCloseRef.current = onClose;
-});
-```
+## Связанные компоненты
 
-- Колбэки хранятся в ref'ах и обновляются после каждого коммита через `useLayoutEffect` без deps.
-- `useEffect([opened])` читает `onOpenRef.current` — поэтому **эффект не пересоздаётся** при смене ссылок на колбэки.
+Отдельного AI.md пока нет ни у `SelectExtendedFieldTarget`, ни у
+`SelectExtendedFieldDropdown` — они описаны здесь. Это область задачи TRI-74
+(«Scope: только SelectExtendedField; соседние экспортируемые компоненты из
+`src/components/SelectExtendedField/` — отдельные задачи»), а не вывод по критериям
+`docs/ai/CONTEXT.md` → «Когда создавать `{ComponentName}-ai.md`». По этим критериям
+оба заслуживают собственных AI.md и отдельных строк в `docs/ai/ROADMAP.md`.
+Решение о том, заводить ли их, за владельцем репозитория.
 
-### Skip mount-вызов `onOpen` / `onClose`
+**Внутри папки компонента:**
 
-```ts
-if (!isMountedRef.current) {
-    isMountedRef.current = true;
-    return;
-}
-if (opened) onOpenRef.current?.();
-else onCloseRef.current?.();
-```
+- `SelectExtendedFieldTarget` (`SelectExtendedField.Target`) — готовое поле выбора поверх `FormField`.
+- `SelectExtendedFieldDropdown` (`SelectExtendedField.Dropdown`) — обёртка над `Dropdown` со ссылкой через `forwardedRef`. Статическое свойство `List` — `DropdownList`.
+- `SelectExtendedFieldDropdownDefault` — внутренний компонент: готовый выпадающий блок со списком опций и мобильной версией. Не экспортируется из barrel, используется в `Chip.Select`, `Chip.Sort` и `SelectField`.
 
-- Default `opened = false` → без skip'а `onClose` вызвался бы при mount.
+**Построены на SelectExtendedField:**
 
-### Click-outside через `document.mousedown`
+- `SelectField` — обычный select со списком опций.
+- `MultiselectField` — множественный выбор.
+- `Chip.Select`, `Chip.Sort`, `Chip.Multiselect` — фильтр-чипы.
 
-```ts
-useEffect(() => {
-    document.addEventListener("mousedown", listenMouseDown);
-    return () => document.removeEventListener("mousedown", listenMouseDown);
-}, [listenMouseDown]);
-```
+`SuggestField` на `SelectExtendedField` **не** построен: он собран на `Dropdown`
+напрямую. Правки в этом компоненте его не затрагивают.
 
-- Закрывает, если клик вне `targetRef` и `dropdownRef`.
-- **`mousedown`**, не `click` — закрывает раньше, чем сработает `click` на dropdown items.
+**Инфраструктура:**
 
-### ESC — через KeyDownListener (window)
+- `Dropdown` — выпадающее меню через `Portal`, позиционирование, мобильная версия.
+- `FormField` — визуальный контейнер поля, контекст размера и статуса.
+- `KeyDownListener` — закрытие по `Escape`.
+- `IconWrapper`, `LoaderSmall` — каретка и лоадер в постфиксе поля.
 
-```tsx
-<KeyDownListener onMatch={closeDropdown} eventKeyCode={EVENT_KEY_CODES.ESCAPE}>
-    ...
-</KeyDownListener>
-```
+---
 
-- Глобальный listener, см. `KeyDownListener-AI.md`.
+## Stories
 
-### TAB — через onKeyDown в самом контейнере
+Основные истории: `stories/SelectExtendedField/SelectExtendedField.stories.tsx`
+Файлы примеров: `stories/SelectExtendedField/examples/`
 
-```ts
-if (closeOnTab && isKey(key, "TAB")) closeDropdown();
-```
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `closeOnTab` и настроек поля выбора: размер, статус, загрузка, кнопка очистки |
+| `Default` | `Default.tsx` | Базовый сценарий: поле выбора и список опций |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG |
+| `Statuses` | `Statuses.tsx` | Состояния поля: DEFAULT / DISABLED / ERROR / WARNING |
+| `Loading` | `Loading.tsx` | Состояние загрузки: лоадер вместо каретки, поле не открывается |
+| `WithClearButton` | `WithClearButton.tsx` | Кнопка очистки значения через `onClear`; видна пока поле под курсором или в фокусе |
+| `WithPrefixAndPostfix` | `WithPrefixAndPostfix.tsx` | Слоты `prefix` и `postfix` поля выбора |
+| `Example` | `Example.tsx` | Произвольный выпадающий блок: чекбоксы и кнопки вместо списка, значение подтверждается явно |
+| `VisualTests` | `VisualTests.tsx` | Раскрытый список и видимая кнопка очистки (через `play`), длинное значение, загрузка в размере SM |
 
-- Опционально. Контракт: `closeOnTab` — потребитель решает (по UX).
+---
 
-### Target: открытие по клавишам
+## История изменений
 
-```ts
-if (!opened && [SPACE, ENTER, ARROW_DOWN, ARROW_UP].includes(event.keyCode)) {
-    event.preventDefault();
-    event.stopPropagation();  // чтобы dropdown сразу не среагировал тем же keydown
-    setOpened(!opened);
-}
-```
+| Дата | Изменение |
+|---|---|
+| 2026-08-07 | Создан документ AI-ready для `SelectExtendedField` (TRI-74). |
+| 2026-08-07 | AI-рефакторинг (TRI-74): `onOpen` / `onClose` сравнивают предыдущее значение `opened` вместо флага «смонтирован» — колбэки больше не срабатывают ложно при двойном маунте в React 18 StrictMode. Удалены ссылки на несуществующие CSS-классы в `SelectExtendedFieldTarget` (в `class` попадал литерал `undefined`). Клик по кнопке очистки больше не раскрывает выпадающий блок — всплытие останавливается, как в `Chip.Select`. Слушатель `mousedown` навешивается только пока блок открыт, callback-ref стабилизирован через `useCallback`, убран мёртвый внутренний `targetRef` в `SelectExtendedFieldTarget`, дедуплицирован список опций десктопной и мобильной версий в `SelectExtendedFieldDropdownDefault`. JSDoc на всех props, unit-тесты разбиты по субкомпонентам и расширены с 42 до 69 кейсов. Stories переведены на modern pattern. Публичный API не изменён. |
 
-- `event.keyCode` — **deprecated** API (тех-долг).
-- `stopPropagation` — комментарий в коде: предотвращает срабатывание `keydown` в `DropdownListItem` через `document.addEventListener("keydown")`.
+---
 
-### Target: caret + loader через size-map
+## Примеры использования
 
-- `CaretdownStrokeSrvIcon{16/20/24}` для `SM/MD/LG`.
-- `LoaderSmall theme=BRAND` тех же размеров.
-- `IconWrapper active={opened} disabled={status===DISABLED}` оборачивает caret — управляет цветом через `@sberbusiness/icons-next` глобальные классы.
+### Default
 
-### `setRef` мерж forwardRef + targetRef
+`stories/SelectExtendedField/examples/Default.tsx`
 
-```ts
-const setRef = (instance) => {
-    targetRef.current = instance;
-    if (typeof ref === "function") ref(instance); else if (ref) ref.current = instance;
+```tsx
+import React, { useState } from "react";
+import {
+    DropdownListItem,
+    EDropdownWidth,
+    SelectExtendedField,
+    SelectExtendedFieldDropdown,
+    SelectExtendedFieldTarget,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS = [
+    { id: "option1", label: "Первая опция" },
+    { id: "option2", label: "Вторая опция" },
+    { id: "option3", label: "Третья опция" },
+];
+
+export const Default = () => {
+    const [selectedId, setSelectedId] = useState<string>();
+
+    const selectedOption = OPTIONS.find((option) => option.id === selectedId);
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <SelectExtendedField
+                closeOnTab
+                renderTarget={({ opened, setOpened }) => (
+                    <SelectExtendedFieldTarget
+                        opened={opened}
+                        setOpened={setOpened}
+                        fieldLabel="Выберите опцию"
+                        label={selectedOption?.label}
+                        placeholder="Не выбрано"
+                    />
+                )}
+            >
+                {({ opened, setOpened, targetRef, dropdownRef }) => (
+                    <SelectExtendedFieldDropdown
+                        opened={opened}
+                        setOpened={setOpened}
+                        targetRef={targetRef}
+                        forwardedRef={dropdownRef}
+                        width={EDropdownWidth.TARGET}
+                    >
+                        <SelectExtendedFieldDropdown.List dropdownOpened={opened}>
+                            {OPTIONS.map((option) => (
+                                <DropdownListItem
+                                    key={option.id}
+                                    id={option.id}
+                                    selected={option.id === selectedId}
+                                    onSelect={() => {
+                                        setSelectedId(option.id);
+                                        setOpened(false);
+                                    }}
+                                >
+                                    {option.label}
+                                </DropdownListItem>
+                            ))}
+                        </SelectExtendedFieldDropdown.List>
+                    </SelectExtendedFieldDropdown>
+                )}
+            </SelectExtendedField>
+        </div>
+    );
 };
 ```
 
-### Target слоты Postfix
+### Sizes
 
-```tsx
-<FormFieldPostfix>
-    {onClear && <FormFieldClear onClick={onClear} />}
-    {loading ? <LoaderSmall .../> : <IconWrapper .../>}
-    {postfix}
-</FormFieldPostfix>
-```
+`stories/SelectExtendedField/examples/Sizes.tsx`
 
-- Порядок: clear → loader/caret → custom postfix.
+```tsx
+import React, { useState } from "react";
+import {
+    DropdownListItem,
+    EComponentSize,
+    EDropdownWidth,
+    SelectExtendedField,
+    SelectExtendedFieldDropdown,
+    SelectExtendedFieldTarget,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS = [
+    { id: "option1", label: "Первая опция" },
+    { id: "option2", label: "Вторая опция" },
+    { id: "option3", label: "Третья опция" },
+];
+
+const SIZES = Object.values(EComponentSize);
+
+interface ISizeItemProps {
+    size: EComponentSize;
+}
 
-### Loading блокирует клики и keydown
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const [selectedId, setSelectedId] = useState<string>("option1");
+
+    const selectedOption = OPTIONS.find((option) => option.id === selectedId);
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
+            <SelectExtendedField
+                closeOnTab
+                renderTarget={({ opened, setOpened }) => (
+                    <SelectExtendedFieldTarget
+                        opened={opened}
+                        setOpened={setOpened}
+                        size={size}
+                        fieldLabel="Выберите опцию"
+                        label={selectedOption?.label}
+                        placeholder="Не выбрано"
+                    />
+                )}
+            >
+                {({ opened, setOpened, targetRef, dropdownRef }) => (
+                    <SelectExtendedFieldDropdown
+                        opened={opened}
+                        setOpened={setOpened}
+                        targetRef={targetRef}
+                        forwardedRef={dropdownRef}
+                        size={size}
+                        width={EDropdownWidth.TARGET}
+                    >
+                        <SelectExtendedFieldDropdown.List dropdownOpened={opened} size={size}>
+                            {OPTIONS.map((option) => (
+                                <DropdownListItem
+                                    key={option.id}
+                                    id={option.id}
+                                    selected={option.id === selectedId}
+                                    onSelect={() => {
+                                        setSelectedId(option.id);
+                                        setOpened(false);
+                                    }}
+                                >
+                                    {option.label}
+                                </DropdownListItem>
+                            ))}
+                        </SelectExtendedFieldDropdown.List>
+                    </SelectExtendedFieldDropdown>
+                )}
+            </SelectExtendedField>
+        </div>
+    );
+};
 
-```ts
-if (loading || status === DISABLED) return;  // в handleClick
-if (loading && status === DISABLED) return;  // в handleKeyDown — bug? && вместо ||
+export const Sizes = () => (
+    <div style={{ maxWidth: "300px", display: "flex", flexDirection: "column", gap: "16px" }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
 ```
 
-- В `handleKeyDown` используется `&&` — **похоже на баг**: keys блокируются только если ОБА условия true. Тех-долг, не трогать без задачи.
-
----
+### Statuses
 
-## Инварианты
+`stories/SelectExtendedField/examples/Statuses.tsx`
 
-- **`renderTarget` и `children` — render-prop'ы** (функции). Изменение API — breaking.
-- **`onOpen` / `onClose` через ref'ы** — stable callback pattern. Не пересоздавать эффект на смене ссылок.
-- **Skip mount-вызов** колбэков через `isMountedRef`.
-- **Click-outside на `mousedown`** (не `click`) — public behavior contract.
-- **ESC закрывает через `KeyDownListener` (window)** — глобальный listener.
-- **`closeOnTab` default `false`** — UX-выбор.
-- **Target открывает по `Enter / Space / ArrowDown / ArrowUp`** + `preventDefault + stopPropagation`.
-- **Target использует `event.keyCode`** — deprecated, тех-долг.
-- **Target loading: `&&` вместо `||`** в handleKeyDown — известный потенциальный баг.
-- **`aria-haspopup="listbox"`** — публичная семантика.
-- **`SelectExtendedField.Dropdown.List = DropdownList`** — реэкспорт.
-- **`SelectExtendedFieldDropdownDefault`** — не slot, отдельный экспорт.
-- **`Target.size` default `MD`**.
-- **Target caret-icon фиксирован** (`CaretdownStrokeSrvIcon`) — нельзя заменить.
-- **`forwardRef`** на SelectExtendedField и Target; **`FC`** на Dropdown.
+```tsx
+import React, { useState } from "react";
+import {
+    DropdownListItem,
+    EDropdownWidth,
+    EFormFieldStatus,
+    SelectExtendedField,
+    SelectExtendedFieldDropdown,
+    SelectExtendedFieldTarget,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS = [
+    { id: "option1", label: "Первая опция" },
+    { id: "option2", label: "Вторая опция" },
+    { id: "option3", label: "Третья опция" },
+];
+
+const STATUSES = Object.values(EFormFieldStatus);
+
+interface IStatusItemProps {
+    status: EFormFieldStatus;
+}
 
----
+const StatusItem = ({ status }: IStatusItemProps) => {
+    const [selectedId, setSelectedId] = useState<string>("option1");
+
+    const selectedOption = OPTIONS.find((option) => option.id === selectedId);
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{status.toUpperCase()}</div>
+            <SelectExtendedField
+                closeOnTab
+                renderTarget={({ opened, setOpened }) => (
+                    <SelectExtendedFieldTarget
+                        opened={opened}
+                        setOpened={setOpened}
+                        status={status}
+                        fieldLabel="Выберите опцию"
+                        label={selectedOption?.label}
+                        placeholder="Не выбрано"
+                    />
+                )}
+            >
+                {({ opened, setOpened, targetRef, dropdownRef }) => (
+                    <SelectExtendedFieldDropdown
+                        opened={opened}
+                        setOpened={setOpened}
+                        targetRef={targetRef}
+                        forwardedRef={dropdownRef}
+                        width={EDropdownWidth.TARGET}
+                    >
+                        <SelectExtendedFieldDropdown.List dropdownOpened={opened}>
+                            {OPTIONS.map((option) => (
+                                <DropdownListItem
+                                    key={option.id}
+                                    id={option.id}
+                                    selected={option.id === selectedId}
+                                    onSelect={() => {
+                                        setSelectedId(option.id);
+                                        setOpened(false);
+                                    }}
+                                >
+                                    {option.label}
+                                </DropdownListItem>
+                            ))}
+                        </SelectExtendedFieldDropdown.List>
+                    </SelectExtendedFieldDropdown>
+                )}
+            </SelectExtendedField>
+        </div>
+    );
+};
 
-## Accessibility
+export const Statuses = () => (
+    <div style={{ maxWidth: "300px", display: "flex", flexDirection: "column", gap: "16px" }}>
+        {STATUSES.map((status) => (
+            <StatusItem key={status} status={status} />
+        ))}
+    </div>
+);
+```
 
-- `aria-expanded={opened}` + `aria-haspopup="listbox"` на target — корректная семантика combobox-like.
-- ESC закрывает (стандарт).
-- Open by `Enter`/`Space`/`Arrow*` — стандартное keyboard поведение для select.
-- **Target — `<div>` (от FormField)**, не `<button>` — для AT может звучать как regular область. Если нужен strict role — потребитель добавляет через `...rest` (`role="combobox"` и т.п.).
-- `aria-label` / `aria-labelledby` для target — потребитель.
-- `loading` блокирует клики и (по идее) keys — но по факту `keydown` блокировка имеет потенциальный баг (см. выше).
-- `tabIndex` — наследуется от FormField/FormFieldProps.
+### Loading
 
----
+`stories/SelectExtendedField/examples/Loading.tsx`
 
-## Дизайн-токены
+```tsx
+import React, { useState } from "react";
+import {
+    DropdownListItem,
+    EDropdownWidth,
+    SelectExtendedField,
+    SelectExtendedFieldDropdown,
+    SelectExtendedFieldTarget,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS = [
+    { id: "option1", label: "Первая опция" },
+    { id: "option2", label: "Вторая опция" },
+    { id: "option3", label: "Третья опция" },
+];
+
+export const Loading = () => {
+    const [selectedId, setSelectedId] = useState<string>();
+
+    const selectedOption = OPTIONS.find((option) => option.id === selectedId);
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <SelectExtendedField
+                closeOnTab
+                renderTarget={({ opened, setOpened }) => (
+                    <SelectExtendedFieldTarget
+                        opened={opened}
+                        setOpened={setOpened}
+                        loading
+                        fieldLabel="Выберите опцию"
+                        label={selectedOption?.label}
+                        placeholder="Не выбрано"
+                    />
+                )}
+            >
+                {({ opened, setOpened, targetRef, dropdownRef }) => (
+                    <SelectExtendedFieldDropdown
+                        opened={opened}
+                        setOpened={setOpened}
+                        targetRef={targetRef}
+                        forwardedRef={dropdownRef}
+                        width={EDropdownWidth.TARGET}
+                    >
+                        <SelectExtendedFieldDropdown.List dropdownOpened={opened}>
+                            {OPTIONS.map((option) => (
+                                <DropdownListItem
+                                    key={option.id}
+                                    id={option.id}
+                                    selected={option.id === selectedId}
+                                    onSelect={() => {
+                                        setSelectedId(option.id);
+                                        setOpened(false);
+                                    }}
+                                >
+                                    {option.label}
+                                </DropdownListItem>
+                            ))}
+                        </SelectExtendedFieldDropdown.List>
+                    </SelectExtendedFieldDropdown>
+                )}
+            </SelectExtendedField>
+        </div>
+    );
+};
+```
 
-Нет собственных. Цвета/spacing — от `FormField`, `Dropdown`, `Loader`.
+### WithClearButton
 
----
+`stories/SelectExtendedField/examples/WithClearButton.tsx`
 
-## Связанные компоненты
+```tsx
+import React, { useState } from "react";
+import {
+    DropdownListItem,
+    EDropdownWidth,
+    SelectExtendedField,
+    SelectExtendedFieldDropdown,
+    SelectExtendedFieldTarget,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS = [
+    { id: "option1", label: "Первая опция" },
+    { id: "option2", label: "Вторая опция" },
+    { id: "option3", label: "Третья опция" },
+];
+
+export const WithClearButton = () => {
+    const [selectedId, setSelectedId] = useState<string | undefined>("option2");
+
+    const selectedOption = OPTIONS.find((option) => option.id === selectedId);
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <SelectExtendedField
+                closeOnTab
+                renderTarget={({ opened, setOpened }) => (
+                    <SelectExtendedFieldTarget
+                        opened={opened}
+                        setOpened={setOpened}
+                        fieldLabel="Выберите опцию"
+                        label={selectedOption?.label}
+                        placeholder="Не выбрано"
+                        onClear={selectedOption ? () => setSelectedId(undefined) : undefined}
+                    />
+                )}
+            >
+                {({ opened, setOpened, targetRef, dropdownRef }) => (
+                    <SelectExtendedFieldDropdown
+                        opened={opened}
+                        setOpened={setOpened}
+                        targetRef={targetRef}
+                        forwardedRef={dropdownRef}
+                        width={EDropdownWidth.TARGET}
+                    >
+                        <SelectExtendedFieldDropdown.List dropdownOpened={opened}>
+                            {OPTIONS.map((option) => (
+                                <DropdownListItem
+                                    key={option.id}
+                                    id={option.id}
+                                    selected={option.id === selectedId}
+                                    onSelect={() => {
+                                        setSelectedId(option.id);
+                                        setOpened(false);
+                                    }}
+                                >
+                                    {option.label}
+                                </DropdownListItem>
+                            ))}
+                        </SelectExtendedFieldDropdown.List>
+                    </SelectExtendedFieldDropdown>
+                )}
+            </SelectExtendedField>
+        </div>
+    );
+};
+```
 
-- `SelectField` — высокоуровневая обёртка для типичного Select.
-- `MultiselectField` — multi-выбор.
-- `Dropdown` — popover.
-- `FormField` (Target/Label/Prefix/Postfix/Clear) — основа target.
-- `KeyDownListener` — ESC.
-- `LoaderSmall` — индикатор загрузки в target.
-- `IconWrapper` — управление цветом caret.
-- `CaretdownStrokeSrvIcon{16/20/24}` — иконка раскрытия.
-- `EComponentSize`, `EFormFieldStatus`.
+### WithPrefixAndPostfix
 
----
+`stories/SelectExtendedField/examples/WithPrefixAndPostfix.tsx`
 
-## Stories
+```tsx
+import React, { useState } from "react";
+import { DefaulticonStrokePrdIcon20, QuestioncircleFilledSrvIcon16 } from "@sberbusiness/icons-next";
+import {
+    DropdownListItem,
+    EDropdownWidth,
+    SelectExtendedField,
+    SelectExtendedFieldDropdown,
+    SelectExtendedFieldTarget,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS = [
+    { id: "option1", label: "Первая опция" },
+    { id: "option2", label: "Вторая опция" },
+    { id: "option3", label: "Третья опция" },
+];
+
+export const WithPrefixAndPostfix = () => {
+    const [selectedId, setSelectedId] = useState<string | undefined>("option1");
+
+    const selectedOption = OPTIONS.find((option) => option.id === selectedId);
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <SelectExtendedField
+                closeOnTab
+                renderTarget={({ opened, setOpened }) => (
+                    <SelectExtendedFieldTarget
+                        opened={opened}
+                        setOpened={setOpened}
+                        fieldLabel="Выберите опцию"
+                        label={selectedOption?.label}
+                        placeholder="Не выбрано"
+                        prefix={<DefaulticonStrokePrdIcon20 paletteIndex={5} />}
+                        postfix={<QuestioncircleFilledSrvIcon16 paletteIndex={5} />}
+                    />
+                )}
+            >
+                {({ opened, setOpened, targetRef, dropdownRef }) => (
+                    <SelectExtendedFieldDropdown
+                        opened={opened}
+                        setOpened={setOpened}
+                        targetRef={targetRef}
+                        forwardedRef={dropdownRef}
+                        width={EDropdownWidth.TARGET}
+                    >
+                        <SelectExtendedFieldDropdown.List dropdownOpened={opened}>
+                            {OPTIONS.map((option) => (
+                                <DropdownListItem
+                                    key={option.id}
+                                    id={option.id}
+                                    selected={option.id === selectedId}
+                                    onSelect={() => {
+                                        setSelectedId(option.id);
+                                        setOpened(false);
+                                    }}
+                                >
+                                    {option.label}
+                                </DropdownListItem>
+                            ))}
+                        </SelectExtendedFieldDropdown.List>
+                    </SelectExtendedFieldDropdown>
+                )}
+            </SelectExtendedField>
+        </div>
+    );
+};
+```
 
-`stories/SelectExtendedField/SelectExtendedField.stories.tsx`
-Примеры: `stories/SelectExtendedField/examples/`
+### Example
 
----
+`stories/SelectExtendedField/examples/Example.tsx`
 
-## История изменений
+```tsx
+import React, { useState } from "react";
+import {
+    Button,
+    Checkbox,
+    EButtonTheme,
+    EComponentSize,
+    EDropdownWidth,
+    ETextSize,
+    SelectExtendedField,
+    SelectExtendedFieldDropdown,
+    SelectExtendedFieldTarget,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+const CATEGORIES = [
+    { id: "income", label: "Поступления" },
+    { id: "outcome", label: "Списания" },
+    { id: "commission", label: "Комиссии" },
+];
+
+/**
+ * Произвольное содержимое выпадающего блока: чекбоксы и кнопки вместо списка опций.
+ * Значение подтверждается кнопкой «Применить», поэтому выбор хранится в двух состояниях.
+ */
+export const Example = () => {
+    const [appliedIds, setAppliedIds] = useState<string[]>(["income"]);
+    const [draftIds, setDraftIds] = useState<string[]>(["income"]);
+
+    const appliedLabel = CATEGORIES.filter((category) => appliedIds.includes(category.id))
+        .map((category) => category.label)
+        .join(", ");
+
+    const toggleDraftId = (id: string) => {
+        setDraftIds((ids) => (ids.includes(id) ? ids.filter((draftId) => draftId !== id) : [...ids, id]));
+    };
+
+    return (
+        <div style={{ maxWidth: "320px" }}>
+            <SelectExtendedField
+                closeOnTab
+                onOpen={() => setDraftIds(appliedIds)}
+                renderTarget={({ opened, setOpened }) => (
+                    <SelectExtendedFieldTarget
+                        opened={opened}
+                        setOpened={setOpened}
+                        size={EComponentSize.LG}
+                        fieldLabel="Категории операций"
+                        label={appliedLabel || undefined}
+                        placeholder="Все категории"
+                    />
+                )}
+            >
+                {({ opened, setOpened, targetRef, dropdownRef }) => (
+                    <SelectExtendedFieldDropdown
+                        opened={opened}
+                        setOpened={setOpened}
+                        targetRef={targetRef}
+                        forwardedRef={dropdownRef}
+                        size={EComponentSize.LG}
+                        width={EDropdownWidth.MIN_TARGET}
+                    >
+                        <div style={{ display: "flex", flexDirection: "column", gap: "12px", padding: "16px" }}>
+                            <Text tag="div" size={ETextSize.B3}>
+                                Показывать операции
+                            </Text>
+                            {CATEGORIES.map((category) => (
+                                <Checkbox
+                                    key={category.id}
+                                    checked={draftIds.includes(category.id)}
+                                    onChange={() => toggleDraftId(category.id)}
+                                >
+                                    {category.label}
+                                </Checkbox>
+                            ))}
+                            <div style={{ display: "flex", gap: "8px" }}>
+                                <Button
+                                    theme={EButtonTheme.GENERAL}
+                                    size={EComponentSize.MD}
+                                    onClick={() => {
+                                        setAppliedIds(draftIds);
+                                        setOpened(false);
+                                    }}
+                                >
+                                    Применить
+                                </Button>
+                                <Button
+                                    theme={EButtonTheme.SECONDARY}
+                                    size={EComponentSize.MD}
+                                    onClick={() => setDraftIds([])}
+                                >
+                                    Сбросить
+                                </Button>
+                            </div>
+                        </div>
+                    </SelectExtendedFieldDropdown>
+                )}
+            </SelectExtendedField>
+        </div>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |