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

package/bundle/components/SelectField.md

@@ -1,9 +1,7 @@
 ---
 component: SelectField
-category: Form Controls
-figma-node: ""
-figma-file: ""
-related: [SelectExtendedField, MultiselectField, Dropdown, FormField]
+category: SelectField
+related: [SelectExtendedField, MultiselectField, SuggestField, Chip, Dropdown, Pagination]
 tokens: []
 stories: stories/SelectField/SelectField.stories.tsx
 version: "1.0"
@@ -13,201 +11,521 @@ version: "1.0"
 
 ## Назначение
 
-Готовый Select для одиночного выбора из списка опций. Под капотом —
-`SelectExtendedField` с фиксированной раскладкой target'а и dropdown'а:
-- Target = `SelectExtendedField.Target` (FormField + caret + clear).
-- Dropdown = `SelectExtendedFieldDropdownDefault` (desktop list +
-  mobile bottom-sheet) c шириной `EDropdownWidth.TARGET`.
+Готовый Select со списком опций: поле выбора и выпадающий блок собраны заранее. Тонкий слой над
+`SelectExtendedField` — состоянием открытости владеет он, а `SelectField` отвечает за подстановку
+готового поля выбора (`SelectExtendedField.Target`), готового списка
+(`SelectExtendedFieldDropdownDefault`) и за aria-связку между ними.
 
-Управляет:
-- `activeDescendant` через `DropdownListContext` — для a11y `aria-activedescendant`.
-- `instanceId` через `lodash uniqueId()` — связывает Target ↔ List через `aria-controls`.
-- **`closeOnTab = true`** захардкожен.
+Используй когда: нужен обычный выбор одного значения из плоского списка опций с текстовыми
+подписями — вместе с мобильной версией списка и клавиатурной навигацией «из коробки».
 
-Используй когда: типичный select из списка опций. Для multi-выбора —
-`MultiselectField`. Для нестандартного target/dropdown —
-`SelectExtendedField` напрямую.
+Не используй когда:
+
+- нужен множественный выбор с тегами — `MultiselectField`;
+- нужен поиск/фильтрация по вводу — `SuggestField`;
+- содержимое выпадающего блока нестандартное (форма, чекбоксы с подтверждением, дерево)
+  или нужно нестандартное поле выбора — `SelectExtendedField`, он для этого и существует;
+- выбор оформляется фильтр-чипом, а не полем формы — `Chip.Select` / `Chip.Sort`;
+- выпадающий блок не привязан к полю ввода — `Dropdown` или `ButtonDropdownExtended`.
 
 ---
 
-## Файловая структура
+## Варианты и props
 
-```text
-src/components/SelectField/
-├── SelectField.tsx   # forwardRef; склейка SelectExtendedField + Default-Dropdown
-├── index.ts
-└── __tests__/
-```
+`ISelectFieldProps` собирается из трёх источников:
 
----
+1. `Omit<ISelectExtendedFieldProps, "children" | "onChange" | "renderTarget">` — то есть
+   `onOpen`, `onClose`, `closeOnTab` и все атрибуты `React.HTMLAttributes<HTMLDivElement>`,
+   попадающие на корневой `<div>`;
+2. `Pick<ISelectExtendedFieldTargetProps, "loading" | "status" | "placeholder">` — состояния
+   поля выбора;
+3. собственные props списка.
 
-## Варианты и props
+### Обязательные props
 
-### `ISelectFieldProps`
+| Prop | Тип | Описание |
+|---|---|---|
+| `size` | `EComponentSize` | Размер. Задаётся один раз и применяется и к полю выбора, и к выпадающему блоку со списком |
+| `options` | `ISelectFieldOption[]` | Список опций. `ISelectFieldOption` — это `ISelectExtendedFieldDefaultOption`: `id`, `value`, `label` плюс props `DropdownListItem` |
+| `onChange` | `(option: ISelectFieldOption) => void` | Вызывается с **объектом опции** (не с `id` и не с `value`). Список после выбора закрывается сам |
 
-```ts
-extends Omit<ISelectExtendedFieldProps, "children" | "onChange" | "renderTarget">
-extends Pick<ISelectExtendedFieldTargetProps, "loading" | "status" | "placeholder">
-```
+### Опциональные props
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `size` | `EComponentSize` | — (обязателен) | Размер. |
-| `value?` | `ISelectFieldOption` | — | Текущая выбранная опция. |
-| `options` | `ISelectFieldOption[]` | — | Список опций. |
-| `onChange` | `(option: ISelectFieldOption) => void` | — | Колбэк выбора. |
-| `placeholder?` | `ReactNode` | — | На target. |
-| `loading?` | `boolean` | — | Спиннер в target, dropdown НЕ открывается. |
-| `status?` | `EFormFieldStatus` | — | DISABLED блокирует target. |
-| `targetProps?` | `Omit<ISelectExtendedFieldTargetProps, "opened" \| "setOpened" \| "size">` | — | Доп. props для target (spread'ятся **после** дефолтных, но **до** provide-props). |
-| `dropdownListItemClassName?` | `string` | — | className для каждого `DropdownListItem` / mobile-item. |
-| `mobileTitle?` | `ReactNode` | — | Заголовок mobile bottom-sheet. |
-| `aria-labelledby?` | `string` | — | На target. |
-| `children?` | `never` | — | Запрещено. |
-| `...ISelectExtendedFieldProps` | `onOpen`, `onClose`, ... | — | Прокидывается. **`closeOnTab` зашит в `true`**, передача игнорируется. |
-
-### `ISelectFieldOption extends ISelectExtendedFieldDefaultOption`
-
-```ts
-{ value: string; label: ReactNode; ...IDropdownListItemProps без active/onSelect/selected/key/className/keyCodesForSelection }
-```
-
-- **`id`** обязателен (часть `IDropdownListItemProps`) — используется как `key` и `selected={option.id === value?.id}`.
+| `value` | `ISelectFieldOption` | — | Выбранное значение. С опциями списка сопоставляется по полю `id` — подсветка выбранной опции считается как `option.id === value.id` |
+| `placeholder` | `React.ReactNode` | — | Отображается, пока `value` не задан |
+| `status` | `EFormFieldStatus` | `EFormFieldStatus.DEFAULT` | Визуальное состояние поля. `DISABLED` блокирует открытие списка |
+| `loading` | `boolean` | `false` | Вместо каретки — лоадер; список не раскрывается ни мышью, ни с клавиатуры |
+| `targetProps` | `Omit<ISelectExtendedFieldTargetProps, "opened" \| "setOpened" \| "size">` | — | Уходит целиком в `SelectExtendedField.Target`. Здесь задаётся **обязательный** заголовок поля `fieldLabel`, а также `prefix`, `postfix`, `onClear` |
+| `dropdownProps` | `ISelectExtendedFieldDropdownDefaultProps["dropdownProps"]` | — | Настройки `Dropdown` (`direction`, `alignment`, `className`, ...). `width`, `size`, `opened` и `targetRef` компонент задаёт сам |
+| `dropdownListItemClassName` | `string` | — | Класс каждого элемента списка — и десктопного `DropdownListItem`, и мобильного `DropdownMobileListItem` |
+| `mobileTitle` | `React.ReactNode` | — | Заголовок выпадающего блока в мобильном режиме. Отдельный prop: на мобильном список раскрывается на весь экран и `fieldLabel` в нём не виден |
+| `closeOnTab` | `boolean` | `true` | Компонент передаёт `closeOnTab={true}`, но `{...rest}` идёт после, поэтому переданное потребителем значение выигрывает |
+| `children` | `never` | — | Не принимаются: выпадающий блок компонент рендерит сам |
+
+### Что компонент задаёт сам и переопределить нельзя
+
+- **Ширина выпадающего блока** — всегда `EDropdownWidth.TARGET` (по ширине поля).
+- **Содержимое выпадающего блока** — `SelectExtendedFieldDropdownDefault` со списком `options`
+  и мобильной версией. Другого содержимого не бывает; если нужно другое — это `SelectExtendedField`.
+- **`opened` / `setOpened`** поля выбора — приходят от `SelectExtendedField` и спредятся
+  **после** `targetProps`, поэтому подменить их через `targetProps` нельзя.
+
+### Ограничения
+
+- Компонент **не управляемый снаружи** по открытости: prop'а `opened` нет, открыть список
+  программно невозможно.
+- Значение не хранится внутри: `value` + `onChange` — контролируемый компонент, состояние ведёт
+  потребитель.
+- Заголовок поля живёт в `targetProps.fieldLabel`, а не в собственном prop'е. `SelectField`
+  подставляет `fieldLabel={undefined}` до спреда `targetProps` — иначе обязательное поле
+  `ISelectExtendedFieldTargetProps` осталось бы незаполненным. Потребители, которым заголовок
+  не нужен, передают пустую строку (так делает `PaginationSelect`).
+- `role="combobox"`, `aria-controls` и прочие атрибуты поля стоят **до** `{...targetProps}`,
+  поэтому потребитель может их перекрыть. Делать это без причины не стоит — сломается
+  aria-связка со списком.
 
 ---
 
-## Ключевые особенности реализации
+## Дизайн-токены
 
-### Layered render-prop'ы
+Собственных токенов и собственных стилей у компонента нет — в папке нет `.module.less`.
+Внешний вид целиком приходит из компонентов, на которых он собран:
 
-```tsx
-<SelectExtendedField renderTarget={renderTarget} closeOnTab={true}>
-    {renderDropdown}
-</SelectExtendedField>
-```
+- `FormField` и его части (`FormFieldLabel`, `FormFieldTarget`, `FormFieldPrefix`,
+  `FormFieldPostfix`, `FormFieldClear`) — группа `FormField`;
+- `Dropdown` и `DropdownList` — группы `Dropdown` и `DropdownList`;
+- `IconWrapper` вокруг каретки и `LoaderSmall` в состоянии загрузки — их собственные группы.
 
-- `renderTarget` рендерит `SelectExtendedField.Target` с `value?.label`.
-- `renderDropdown` рендерит `SelectExtendedFieldDropdownDefault` с `width=TARGET`.
+Переопределяются они через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Если понадобится собственное визуальное состояние поля выбора,
+токен заводится в `SelectExtendedFieldTarget`, а не здесь.
 
-### `DropdownListContext` — `activeDescendant` для a11y
+---
 
-```tsx
-<DropdownListContext.Provider value={{ activeDescendant, setActiveDescendant }}>
-    <SelectExtendedFieldDropdownDefault ... />
-</DropdownListContext.Provider>
-```
+## Инварианты
 
-- `DropdownList` items пишут свой `id` в `activeDescendant` при keyboard-навигации.
-- Target читает `activeDescendant` и ставит `aria-activedescendant` — корректная семантика combobox.
+- **`forwardRef`** — не убирать. `ref` уходит в `SelectExtendedField.Target`, то есть указывает
+  на `FormFieldTarget` — элемент со значением, а **не** на корневой `<div>` компонента.
+  Корневой `<div>` — это `SelectExtendedField`, и своей ссылки на него `SelectField` наружу не отдаёт.
+- **Имена `SelectField`, `ISelectFieldProps`, `ISelectFieldOption`** и `displayName` — публичный API:
+  экспортируются из barrel `src/components/SelectField/index.ts` и из `src/components/index.ts`.
+  От `ISelectFieldProps` строятся `IChipSelectProps` (`Chip.Select`) и `IPaginationSelectProps`
+  (`Pagination`), `ISelectFieldOption` используется в тестах и stories `Chip` — переименование
+  ломает их.
+- **`ISelectFieldOption` — пустой `extends ISelectExtendedFieldDefaultOption`.** Это осознанный
+  публичный алиас: потребитель не должен импортировать тип из чужой папки. Не схлопывать в
+  `type ... = ...` и не удалять.
+- **Accessibility-контракт поля выбора** — `role="combobox"`, `aria-controls`,
+  `aria-activedescendant`, проброс `aria-labelledby`. Менять только вместе с `DropdownList`.
+- **`aria-labelledby` не уходит в `...rest`**: он адресован полю выбора, а не корневому `<div>`.
+  Если вернуть его в `rest`, `PaginationSelect` потеряет связь с подписью пагинации.
+- **Идентификатор списка стабилен на всё время жизни компонента** (`useState(() => uniqueId())`).
+  На него ссылается `aria-controls`; пересоздание на каждый рендер рвёт связку.
+- **`EDropdownWidth.TARGET`** — часть дизайна компонента, а не деталь реализации: список всегда
+  по ширине поля.
+- **React 17-совместимость** (ветка `release-0`): не использовать `useId`,
+  `useSyncExternalStore`, `useInsertionEffect` и поведение, зависящее от automatic batching.
+  Уникальный идентификатор берётся из `uniqueId` (`lodash-es`).
+- **`SelectExtendedFieldDropdownDefault` импортируется по прямому пути**
+  (`components/SelectExtendedFieldDropdownDefault`) — он не экспортируется из barrel
+  `SelectExtendedField`. Не выносить его в публичный API «заодно».
 
-### `instanceId = uniqueId()` через `useRef`
+---
 
-```ts
-const instanceId = useRef(uniqueId());
-```
+## Accessibility
 
-- **SSR-небезопасно** (`uniqueId` глобальный счётчик).
-- Используется как `aria-controls` на target и `id` на List — связывает их.
+- Поле выбора получает `role="combobox"` и `aria-controls` с идентификатором списка опций.
+  Идентификатор генерируется компонентом и передаётся в `SelectExtendedFieldDropdownDefault`
+  как `listId` — то есть в `id` реального `DropdownList`. Пока список закрыт (а также при
+  `loading`), выпадающего блока в DOM нет, поэтому `aria-controls` указывает на несуществующий
+  `id` — так же было и до появления этого документа. Скринридеры такую ссылку игнорируют,
+  а `aria-expanded` при этом корректно сообщает, что список свёрнут.
+- `aria-activedescendant` отражает опцию, подсвеченную с клавиатуры. Значение поднимается снизу:
+  `DropdownList` кладёт `id` активного элемента в `DropdownListContext`, провайдер которого
+  `SelectField` рендерит вокруг выпадающего блока. Без этого провайдера связка не работает.
+- `aria-expanded` и `aria-haspopup="listbox"` выставляет `SelectExtendedFieldTarget`;
+  роли `listbox` / `option` и навигацию `ArrowUp` / `ArrowDown` — `DropdownList`.
+- Клавиши открытия списка: `Space`, `Enter`, `ArrowDown`, `ArrowUp`. Закрытие — `Escape`
+  (из любого места страницы), `Tab` (`closeOnTab`) и нажатие мышью вне поля и списка.
+- В состояниях `loading` и `status={EFormFieldStatus.DISABLED}` поле не реагирует ни на клик,
+  ни на клавиатуру.
+- **Доступное имя задаёт потребитель.** Компонент не хардкодит текст (библиотека мультиязычная):
+  имя приходит либо из `targetProps.fieldLabel`, либо из `aria-labelledby` — так поступает
+  `PaginationSelect`, связывая поле с подписью пагинации и передавая пустой `fieldLabel`.
+- Фокус компонент не перехватывает и не возвращает: focus trap, если он нужен, добавляет потребитель.
 
-### Target props order
+---
 
-```tsx
-<SelectExtendedField.Target
-    label={value?.label} placeholder={...} loading={...} status={...}
-    role="combobox"
-    aria-controls={instanceId.current}
-    aria-activedescendant={activeDescendant}
-    aria-labelledby={ariaLabelledby}
-    ref={setRef}
-    size={size}
-    fieldLabel={undefined}
-    {...targetProps}    // потребительские targetProps — переопределяют дефолты
-    {...props}          // provide-props (opened, setOpened) — переопределяют всё
-/>
-```
+## Связанные компоненты
 
-- Порядок: defaults → `targetProps` (потребитель) → `provide-props` (system).
-- **`fieldLabel: undefined`** по умолчанию — потребитель должен передать через `targetProps.fieldLabel`.
+- `SelectExtendedField` — база. `ISelectFieldProps` строится из его props, а сам компонент
+  рендерит `SelectExtendedField` с `SelectExtendedField.Target` в `renderTarget` и
+  `SelectExtendedFieldDropdownDefault` в `children`. Любая правка в нём отражается на `SelectField`.
+- `MultiselectField` — множественный выбор с тегами, тоже на `SelectExtendedField`.
+  Альтернатива, когда значений может быть несколько.
+- `SuggestField` — поле выбора с поиском по вводу. Собран на `Dropdown` напрямую, не на
+  `SelectExtendedField`, поэтому правки в `SelectField` его не затрагивают.
+- `Chip` — `Chip.Select` и `Chip.Sort` решают ту же задачу в виде фильтр-чипа;
+  `IChipSelectProps` собирается из `ISelectFieldProps`.
+- `Dropdown` — выпадающий блок, `DropdownList` / `DropdownListItem` и `DropdownListContext`,
+  через который поднимается активная опция для `aria-activedescendant`.
+- `Pagination` — потребитель внутри библиотеки: `PaginationSelect` оборачивает `SelectField`
+  для выбора количества элементов на странице и опирается на проброс `aria-labelledby`
+  и на пустой `targetProps.fieldLabel`.
 
-### Жёстко зашито
+---
 
-- **`closeOnTab: true`**.
-- **`width: EDropdownWidth.TARGET`** — dropdown ровно ширины target'а.
-- **`role="combobox"`** на target.
-- **Default Dropdown layout** (desktop List + mobile bottom-sheet) — нельзя заменить (для нестандартного — использовать `SelectExtendedField`).
+## Stories
 
-### `loading` блокирует открытие dropdown'а
+Основные истории: `stories/SelectField/SelectField.stories.tsx`
+Файлы примеров: `stories/SelectField/examples/`
 
-В `SelectExtendedFieldDropdownDefault`:
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `size`, `status`, `loading`, `placeholder`, заголовка поля и описания под ним |
+| `Default` | `Default.tsx` | Минимальный сценарий: список опций и выбранное значение в состоянии потребителя |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG |
+| `Statuses` | `Statuses.tsx` | Состояния поля: DEFAULT / DISABLED / ERROR / WARNING |
+| `Loading` | `Loading.tsx` | Состояние загрузки: лоадер вместо каретки, список не раскрывается |
+| `WithDescription` | `WithDescription.tsx` | Композиция с `FormGroup` и `FormFieldDescription`: описание и текст ошибки под полем |
+| `Example` | `Example.tsx` | Production-like композиция: зависимые списки «Организация» → «Счёт списания» |
+| `VisualTests` | `VisualTests.tsx` | Скриншот-регрессия: раскрытый список с подсвеченной опцией (через `play`), длинное значение, загрузка в размере SM, пустое заблокированное поле |
 
-```tsx
-opened={opened && !loading}
-```
+`Playground` исключён из скриншот-тестов, `WithDescription` — тоже: поле в нём повторяет
+состояния из `Default` и `Statuses`.
 
-- При `loading=true` dropdown не показывается, в target — спиннер.
+---
 
-### `setRef` мерж forwardRef + targetRef
+## История изменений
 
-Стандартный паттерн.
+| Дата | Изменение |
+|---|---|
+| 2026-09-03 | Создан документ (TRI-75). AI-рефакторинг: удалён мёртвый внутренний `targetRef`, внешний `ref` пробрасывается напрямую и больше не пересоздаётся на каждый рендер; идентификатор списка переведён с `useRef(uniqueId())` на `useState(() => uniqueId())`, чтобы счётчик не крутился на каждом рендере; параметры рендер-функций перестали затенять `props` компонента; импорты приведены к алиасу пакета; JSDoc на всех props и на компоненте. Unit-тесты расширены с 15 до 24 кейсов (`onChange` с аргументом, опции и выбранное значение, `aria-activedescendant` через `DropdownListContext`, стабильность `listId`, ref-target). Stories переведены на modern pattern, `States` разделена на `Statuses` и `Loading`. Публичный API не изменён |
 
 ---
 
-## Инварианты
+## Примеры использования
 
-- **`size` обязателен** (нет default).
-- **`closeOnTab=true`** захардкожен.
-- **`width=TARGET`** захардкожен.
-- **`role="combobox"`** на target — публичный a11y-контракт.
-- **`aria-controls`** + **`aria-activedescendant`** связывают target и list через `instanceId` и `DropdownListContext`.
-- **`uniqueId()` через `useRef`** — SSR-небезопасно (тех-долг).
-- **`children: never`** — запрещены.
-- **`option.id`** — обязательный (наследуется от `IDropdownListItemProps`); используется как `key` и `selected`.
-- **`targetProps` мержатся между defaults и provide-props** — порядок важен.
-- **`fieldLabel` по умолчанию `undefined`** — потребитель добавляет через `targetProps.fieldLabel`.
-- **`loading` блокирует Dropdown** (`opened && !loading`).
-- **Default Dropdown layout фиксирован** — для кастомного использовать `SelectExtendedField`.
-- **`forwardRef<HTMLDivElement>`** — на target ref.
+### Default
 
----
+`stories/SelectField/examples/Default.tsx`
 
-## Accessibility
+```tsx
+import React, { useState } from "react";
+import { EComponentSize, ISelectFieldOption, SelectField } from "@sberbusiness/triplex-next";
+
+const OPTIONS: ISelectFieldOption[] = [
+    { id: "option1", value: "option1", label: "Первая опция" },
+    { id: "option2", value: "option2", label: "Вторая опция" },
+    { id: "option3", value: "option3", label: "Третья опция" },
+];
+
+export const Default = () => {
+    const [value, setValue] = useState<ISelectFieldOption>();
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <SelectField
+                size={EComponentSize.MD}
+                value={value}
+                options={OPTIONS}
+                onChange={setValue}
+                placeholder="Не выбрано"
+                targetProps={{ fieldLabel: "Выберите опцию" }}
+                mobileTitle="Выберите опцию"
+            />
+        </div>
+    );
+};
+```
 
-- `role="combobox"` + `aria-haspopup="listbox"` (от Target) + `aria-expanded` + `aria-controls` + `aria-activedescendant` — каноническая combobox-семантика.
-- `aria-labelledby` — потребитель.
-- ESC закрывает (от SelectExtendedField).
-- `closeOnTab=true` — Tab закрывает (UX-выбор).
-- `loading` — клики/keys блокированы (с known bug в keydown — см. SelectExtendedField-AI).
-- **`uniqueId()` SSR-небезопасно** — может привести к несовпадению `id` между сервером и клиентом.
+### Sizes
 
----
+`stories/SelectField/examples/Sizes.tsx`
 
-## Дизайн-токены
+```tsx
+import React, { useState } from "react";
+import { EComponentSize, ISelectFieldOption, SelectField } from "@sberbusiness/triplex-next";
+
+const OPTIONS: ISelectFieldOption[] = [
+    { id: "option1", value: "option1", label: "Первая опция" },
+    { id: "option2", value: "option2", label: "Вторая опция" },
+    { id: "option3", value: "option3", label: "Третья опция" },
+];
+
+const SIZES = Object.values(EComponentSize);
+
+interface ISizeItemProps {
+    size: EComponentSize;
+}
+
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const [value, setValue] = useState<ISelectFieldOption | undefined>(OPTIONS[0]);
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
+            <SelectField
+                size={size}
+                value={value}
+                options={OPTIONS}
+                onChange={setValue}
+                placeholder="Не выбрано"
+                targetProps={{ fieldLabel: "Выберите опцию" }}
+                mobileTitle="Выберите опцию"
+            />
+        </div>
+    );
+};
+
+export const Sizes = () => (
+    <div style={{ maxWidth: "300px", display: "flex", flexDirection: "column", gap: "16px" }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
+```
 
-Нет собственных — наследуются от `SelectExtendedField` / `Dropdown` / `FormField`.
+### Statuses
 
----
+`stories/SelectField/examples/Statuses.tsx`
 
-## Связанные компоненты
+```tsx
+import React, { useState } from "react";
+import { EComponentSize, EFormFieldStatus, ISelectFieldOption, SelectField } from "@sberbusiness/triplex-next";
+
+const OPTIONS: ISelectFieldOption[] = [
+    { id: "option1", value: "option1", label: "Первая опция" },
+    { id: "option2", value: "option2", label: "Вторая опция" },
+    { id: "option3", value: "option3", label: "Третья опция" },
+];
+
+const STATUSES = Object.values(EFormFieldStatus);
+
+interface IStatusItemProps {
+    status: EFormFieldStatus;
+}
+
+const StatusItem = ({ status }: IStatusItemProps) => {
+    const [value, setValue] = useState<ISelectFieldOption | undefined>(OPTIONS[0]);
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{status.toUpperCase()}</div>
+            <SelectField
+                size={EComponentSize.LG}
+                status={status}
+                value={value}
+                options={OPTIONS}
+                onChange={setValue}
+                placeholder="Не выбрано"
+                targetProps={{ fieldLabel: "Выберите опцию" }}
+                mobileTitle="Выберите опцию"
+            />
+        </div>
+    );
+};
+
+export const Statuses = () => (
+    <div style={{ maxWidth: "300px", display: "flex", flexDirection: "column", gap: "16px" }}>
+        {STATUSES.map((status) => (
+            <StatusItem key={status} status={status} />
+        ))}
+    </div>
+);
+```
 
-- `SelectExtendedField` — базовый, для кастомных Select'ов.
-- `MultiselectField` — multi-выбор.
-- `SelectExtendedFieldDropdownDefault` — переиспользуется для default-раскладки.
-- `Dropdown` (+`DropdownList`+`DropdownMobile*`) — popover.
-- `DropdownListContext` — для `activeDescendant`.
-- `EDropdownWidth.TARGET`, `EComponentSize`.
-- `lodash uniqueId`.
+### Loading
 
----
+`stories/SelectField/examples/Loading.tsx`
 
-## Stories
+```tsx
+import React, { useState } from "react";
+import { EComponentSize, ISelectFieldOption, SelectField } from "@sberbusiness/triplex-next";
+
+const OPTIONS: ISelectFieldOption[] = [
+    { id: "option1", value: "option1", label: "Первая опция" },
+    { id: "option2", value: "option2", label: "Вторая опция" },
+    { id: "option3", value: "option3", label: "Третья опция" },
+];
+
+export const Loading = () => {
+    const [value, setValue] = useState<ISelectFieldOption>();
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <SelectField
+                size={EComponentSize.LG}
+                loading
+                value={value}
+                options={OPTIONS}
+                onChange={setValue}
+                placeholder="Не выбрано"
+                targetProps={{ fieldLabel: "Загрузка опций" }}
+                mobileTitle="Загрузка опций"
+            />
+        </div>
+    );
+};
+```
 
-`stories/SelectField/SelectField.stories.tsx`
-Примеры: `stories/SelectField/examples/`
+### WithDescription
 
----
+`stories/SelectField/examples/WithDescription.tsx`
 
-## История изменений
+```tsx
+import React, { useState } from "react";
+import {
+    EComponentSize,
+    EFontType,
+    EFormFieldStatus,
+    ETextSize,
+    FormFieldDescription,
+    FormGroup,
+    ISelectFieldOption,
+    SelectField,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+const OPTIONS: ISelectFieldOption[] = [
+    { id: "option1", value: "option1", label: "Первая опция" },
+    { id: "option2", value: "option2", label: "Вторая опция" },
+    { id: "option3", value: "option3", label: "Третья опция" },
+];
+
+export const WithDescription = () => {
+    const [value, setValue] = useState<ISelectFieldOption>();
+    // Поле считается тронутым после первого закрытия списка: до взаимодействия ошибку не показываем.
+    const [touched, setTouched] = useState(false);
+
+    const status = touched && !value ? EFormFieldStatus.ERROR : EFormFieldStatus.DEFAULT;
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <FormGroup>
+                <SelectField
+                    size={EComponentSize.LG}
+                    status={status}
+                    value={value}
+                    options={OPTIONS}
+                    onChange={setValue}
+                    onClose={() => setTouched(true)}
+                    placeholder="Не выбрано"
+                    targetProps={{ fieldLabel: "Выберите опцию" }}
+                    mobileTitle="Выберите опцию"
+                />
+                <FormFieldDescription>
+                    <Text
+                        tag="div"
+                        size={ETextSize.B4}
+                        type={status === EFormFieldStatus.ERROR ? EFontType.ERROR : EFontType.SECONDARY}
+                    >
+                        {status === EFormFieldStatus.ERROR ? "Обязательное поле" : "Значение можно изменить позже"}
+                    </Text>
+                </FormFieldDescription>
+            </FormGroup>
+        </div>
+    );
+};
+```
+
+### Example
+
+`stories/SelectField/examples/Example.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    EComponentSize,
+    EFontType,
+    EFormFieldStatus,
+    ETextSize,
+    ETooltipSize,
+    FormFieldDescription,
+    FormGroup,
+    HelpBox,
+    ISelectFieldOption,
+    SelectField,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+/** Организации, доступные пользователю. */
+const ORGANIZATIONS: ISelectFieldOption[] = [
+    { id: "alpha", value: "alpha", label: "ООО «Альфа»" },
+    { id: "beta", value: "beta", label: "ООО «Бета»" },
+];
+
+/** Счета в разрезе организации: список второго поля зависит от выбора в первом. */
+const ACCOUNTS_BY_ORGANIZATION: Record<string, ISelectFieldOption[]> = {
+    alpha: [
+        { id: "alpha-rub", value: "alpha-rub", label: "40702810 ··· 4501 — рубли" },
+        { id: "alpha-usd", value: "alpha-usd", label: "40702840 ··· 7712 — доллары" },
+    ],
+    beta: [
+        { id: "beta-rub", value: "beta-rub", label: "40702810 ··· 9034 — рубли" },
+        { id: "beta-eur", value: "beta-eur", label: "40702978 ··· 2288 — евро" },
+    ],
+};
+
+export const Example = () => {
+    const [organization, setOrganization] = useState<ISelectFieldOption>();
+    const [account, setAccount] = useState<ISelectFieldOption>();
+
+    const accounts = organization ? ACCOUNTS_BY_ORGANIZATION[organization.id] : [];
+
+    /** Смена организации сбрасывает счёт: выбранный счёт относился к другой организации. */
+    const handleOrganizationChange = (option: ISelectFieldOption) => {
+        setOrganization(option);
+        setAccount(undefined);
+    };
+
+    const handleOrganizationClear = () => {
+        setOrganization(undefined);
+        setAccount(undefined);
+    };
+
+    return (
+        <div style={{ maxWidth: "320px", display: "flex", flexDirection: "column", gap: "16px" }}>
+            <FormGroup>
+                <SelectField
+                    size={EComponentSize.LG}
+                    value={organization}
+                    options={ORGANIZATIONS}
+                    onChange={handleOrganizationChange}
+                    placeholder="Не выбрана"
+                    targetProps={{
+                        fieldLabel: "Организация",
+                        onClear: organization ? handleOrganizationClear : undefined,
+                        postfix: (
+                            <HelpBox tooltipSize={ETooltipSize.SM}>Организации, к которым у вас есть доступ.</HelpBox>
+                        ),
+                    }}
+                    mobileTitle="Организация"
+                />
+            </FormGroup>
+
+            <FormGroup>
+                <SelectField
+                    size={EComponentSize.LG}
+                    status={organization ? EFormFieldStatus.DEFAULT : EFormFieldStatus.DISABLED}
+                    value={account}
+                    options={accounts}
+                    onChange={setAccount}
+                    placeholder="Не выбран"
+                    targetProps={{ fieldLabel: "Счёт списания" }}
+                    mobileTitle="Счёт списания"
+                />
+                <FormFieldDescription>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        {organization ? "Доступны счета выбранной организации" : "Сначала выберите организацию"}
+                    </Text>
+                </FormFieldDescription>
+            </FormGroup>
+        </div>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |