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

package/bundle/components/SMSField.md

@@ -1,16 +1,16 @@
 ---
 component: SMSField
-category: Form Controls
-figma-node: ""
-figma-file: ""
-related: [TextField, Tooltip, ButtonIcon, FormField]
+category: TextFields
+related: [FormField, FormGroup, ButtonIcon, Tooltip]
 tokens:
-  - --triplex-next-SMSField-Submit_Background_Default
-  - --triplex-next-SMSField-Submit_Background_Hover
-  - --triplex-next-SMSField-Submit_Background_Active
-  - --triplex-next-SMSField-Refresh_Fill_Empty
-  - --triplex-next-SMSField-Refresh_Fill_Full
-  - --triplex-next-SMSField-Refresh_Disabled
+  - FormField.Input_Color_Disabled
+  - SMSField.Refresh_Disabled
+  - SMSField.Refresh_Fill_Empty
+  - SMSField.Refresh_Fill_Full
+  - SMSField.Submit_Background_Active
+  - SMSField.Submit_Background_Default
+  - SMSField.Submit_Background_Hover
+  - Typography.Error_Color
 stories: stories/SMSField/SMSField.stories.tsx
 version: "1.0"
 ---
@@ -19,137 +19,129 @@ version: "1.0"
 
 ## Назначение
 
-Композитный компонент для ввода SMS-кода: поле ввода + кнопка отправки +
-кнопка повторного запроса кода с обратным отсчётом + tooltip над Refresh.
-Работает через `SMSFieldContext` — подкомпоненты обязаны быть детьми `SMSField`.
+Управляемое поле ввода СМС-кода с кнопками повторного запроса и отправки. Корневой компонент хранит контекст для составных частей `SMSField.Input`, `SMSField.Refresh`, `SMSField.Submit` и `SMSField.Tooltip`; значение кода и обратный отсчёт хранит потребитель.
 
-Используй когда: нужно подтверждение действия SMS-кодом (логин, оплата,
-verification). Для произвольных цифровых полей используй `TextField` с
-`type="tel"`.
+Используй когда: нужен ввод цифрового кода подтверждения с повторным запросом и отправкой кнопкой или клавишей Enter.
 
----
-
-## Файловая структура
-
-```text
-src/components/SMSField/
-├── SMSField.tsx               # FC + статичные Composition
-├── SMSFieldContext.ts         # Shared state (code, disabled, size...)
-├── types.ts                   # ISMSFieldProps
-├── components/
-│   ├── SMSFieldInput.tsx      # <input> на базе FormField/FormFieldInput
-│   ├── SMSFieldSubmit.tsx     # ButtonIcon (CIRCLE) с SubmitIcon
-│   ├── SMSFieldRefresh.tsx    # ButtonIcon (SQUIRCLE) + круговой прогресс
-│   ├── SMSFieldTooltip.tsx    # Оборачивает Refresh в Tooltip
-│   ├── RefreshIcon.tsx
-│   └── SubmitIcon.tsx
-├── styles/
-└── index.ts
-```
+Не используй когда: нужен произвольный текст (`TextField`), форматирование по маске (`MaskedField`) или выбор значения из подсказок (`SuggestField`). SMSField не выполняет запрос к серверу и не проверяет правильность кода.
 
 ---
 
-## Slot-компоненты
+## Варианты и props
+
+### Обязательные props
 
-| Slot | Props | Назначение |
+| Prop | Тип | Описание |
 |---|---|---|
-| `SMSField.Input` | `ISMSFieldInputProps` (`InputHTMLAttributes` + `counter?`, `description?`) | Поле ввода кода; фильтрует ввод (только цифры), `maxLength = 8` по умолчанию, `Enter` → `onSubmitCode`. |
-| `SMSField.Submit` | `ButtonHTMLAttributes` | Кнопка отправки (ButtonIcon CIRCLE); автоматически disabled, когда `code === ""`. |
-| `SMSField.Refresh` | `countdownTime`, `countdownTimeLeft`, `onRefresh` | Кнопка запроса кода с круговым прогрессом; disabled пока `countdownTimeLeft > 0`. |
-| `SMSField.Tooltip` | `Partial<ITooltipProps>` + `message`, `children` (ReactElement), `targetRef` | Оборачивает `Refresh` (через `targetRef`) в `Tooltip` с hover-триггером. |
+| `code` | `string` | Текущее значение кода. Для пустого поля передавай `""`; обновляй значение в ответ на `onChangeCode`. |
+| `onChangeCode` | callback | Получает новое значение при допустимом вводе в `SMSField.Input`: строку из цифр `0–9` или пустую строку. |
+| `onSubmitCode` | callback | Получает текущий `code` при нажатии доступной `SMSField.Submit` или Enter в `SMSField.Input`. |
+| `size` | `EComponentSize` | Общий размер поля и кнопок: SM / MD / LG. Дефолта у корневого компонента нет. |
 
----
+### Опциональные props
 
-## Варианты и props
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `status` | `EFormFieldStatus` без `WARNING` | `DEFAULT` | `DEFAULT`, `ERROR` или `DISABLED`. Ошибка сохраняет возможность ввода, disabled блокирует поле и обе кнопки. |
+| `children` | `ReactNode` | — | Составные части поля; корень не добавляет Input, Refresh, Submit или Tooltip автоматически. |
+| `className` | `string` | — | Добавляется на корневой `div`. |
 
-### `ISMSFieldProps`
+Остальные HTML-атрибуты `div`, обработчики и `data-test-id` передаются корневому контейнеру. Атрибуты поля ввода (`id`, `aria-label`, `placeholder`, `maxLength` и другие) задаются на `SMSField.Input`.
 
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `code` | `string` | — | Текущее значение кода. |
-| `onChangeCode` | `(code: string) => void` | — | Вызывается при валидном вводе (только цифры). |
-| `onSubmitCode` | `(code: string) => void` | — | Вызывается из `SMSField.Submit` и по Enter в `SMSField.Input`. |
-| `size` | `EComponentSize` | — | Прокидывается в дочерние FormField/ButtonIcon. |
-| `disabled?` | `boolean` | `false` | Блокирует все вложенные контролы. |
-| `error?` | `boolean` | `false` | Устанавливает `EFormFieldStatus.ERROR` у `SMSField.Input`. |
-| `...HTMLAttributes<HTMLDivElement>` | — | — | Прокидываются на корневой div. |
-| `TestProps` | — | — | `data-test-*` атрибуты. |
-
-### `ISMSFieldInputProps`
-
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `counter?` | `ReactNode` | — | Отображается в `FormFieldCounter` внутри description. |
-| `description?` | `ReactNode` | — | Текст под полем. |
-| `maxLength?` | `number` | `8` | Максимальная длина кода. |
-| `...InputHTMLAttributes` | — | — | Стандартные атрибуты input. |
+### Составные части
 
-### `ISMSFieldRefreshProps`
+- `SMSField.Input` (`SMSFieldInput`) — ввод на базе `FormFieldInput`. Значение задавай через корневой `code`. По умолчанию `maxLength={8}`, `autoComplete="off"`; при попытке ввода нецифровой строки не вызывает ни `onChangeCode`, ни собственный `onChange`. `description` и `counter` выводятся в общем блоке под полем, счётчик вычисляет потребитель.
+- `errorText` у Input заменяет placeholder в статусе `ERROR`, пока поле не в фокусе. В фокусе возвращается обычный placeholder. Текущее значение кода сохраняется; текст ошибки виден как placeholder только у пустого поля. Без `errorText` остаются рамка ошибки и `aria-invalid`.
+- `SMSField.Submit` (`SMSFieldSubmit`) — кнопка отправки. Недоступна при пустом `code`, корневом `DISABLED` или собственном `disabled`; при доступном клике вызывает `onSubmitCode(code)`, затем свой `onClick`. Наличие кода включает активный вид кнопки. Ref указывает на `button`. Полноту и правильность кода компонент не проверяет: непустое значение можно отправить до достижения `maxLength`.
+- `SMSField.Refresh` (`SMSFieldRefresh`) — кнопка повторного запроса. Требует `countdownTime`, `countdownTimeLeft` и `onRefresh`; недоступна при корневом `DISABLED`, собственном `disabled` или `countdownTimeLeft > 0`. При доступном клике вызывает `onRefresh()`, затем свой `onClick`. Таймер, очистку кода и сетевой запрос реализует потребитель. Радиальное заполнение иконки отображает долю прошедшего времени.
+- `SMSField.Tooltip` (`SMSFieldTooltip`) — обёртка над одним React-элементом с обязательными `message` и `targetRef`. Для обычной композиции используй тот же ref на `SMSField.Refresh` и в `targetRef`. Размер SM, выравнивание START, hover-переключение и отключение адаптивного режима заданы как настройки по умолчанию и могут переопределяться props Tooltip.
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `countdownTime` | `number` | Полное время отсчёта (сек). Для расчёта прогресса. |
-| `countdownTimeLeft` | `number` | Оставшееся время (сек). Если `> 0` — кнопка disabled. |
-| `onRefresh` | `() => void` | Вызывается при клике. |
+### Синхронизация и ограничения
+
+- Корень передаёт `code`, callbacks, `size` и `status` составным частям через `SMSFieldContext`. Фильтр цифр работает только при вводе в Input: переданный снаружи `code` не нормализуется.
+- `disabledSubmit` хранится в корне и изначально равен `true`. `SMSField.Submit` синхронизирует его эффектом со своей доступностью; Input использует это значение для отправки по Enter. Для согласованного поведения Enter размещай Submit внутри того же SMSField.
+- `tooltipId` хранится в корневом контексте: Tooltip записывает туда свой `id` (без него — значение `uniqueId`, сгенерированное при монтировании), Refresh берёт его для `aria-describedby`. Для воспроизводимых визуальных примеров задавай стабильный `id`.
+- У составных частей нет собственных `size` и `status` — они задаются только через корень.
 
 ---
 
-## Контекст (`SMSFieldContext`)
+## Дизайн-токены
+
+Прямые ссылки общего `styles/SMSField.module.less`:
 
-Поля: `code`, `disabled`, `error`, `onChangeCode`, `onSubmitCode`, `size`,
-`sizeClassName`, `disabledSubmit` / `setDisabledSubmit`, `tooltipId` / `setTooltipId`.
+```text
+FormField.Input_Color_Disabled
+SMSField.Refresh_Disabled
+SMSField.Refresh_Fill_Empty
+SMSField.Refresh_Fill_Full
+SMSField.Submit_Background_Active
+SMSField.Submit_Background_Default
+SMSField.Submit_Background_Hover
+Typography.Error_Color
+```
+
+Токены `SMSField.Refresh_*` управляют заполнением и недоступным видом иконки повторного запроса. `SMSField.Submit_Background_*` управляют заливкой иконки отправки: DEFAULT для неактивного состояния, ACTIVE при наличии кода, HOVER при наведении на доступную активную кнопку. `FormField.Input_Color_Disabled` используется для placeholder недоступного Input, `Typography.Error_Color` — для placeholder с текстом ошибки.
 
-- `disabledSubmit` — вычисляется в `SMSField.Submit` (через `useEffect`) и
-  читается в `SMSField.Input` для обработки Enter.
-- `tooltipId` — генерируется в `SMSField.Tooltip` и читается в `SMSField.Refresh`
-  для `aria-describedby`.
+Значения по умолчанию находятся в `src/components/DesignTokens/components/SMSField.ts`, `FormField.ts` и `Typography.ts`. Переопределяй их через `ThemeProvider` (prop `tokens`) — см. [ThemeProvider-ai.md](../ThemeProvider/ThemeProvider-ai.md), раздел «Как переопределять токены».
+
+Внешний вид базовых поля, кнопок и подсказки также наследует токены семейств FormField, Button/IconWrapper и Tooltip.
 
 ---
 
 ## Инварианты
 
-- **Регэксп ввода `/^[0-9]*$/`** — только цифры; нецифровой ввод отбрасывается в `SMSFieldInput.handleChange`.
-- **`maxLength` default `8`** — переопределяемо, но не нужно без причины.
-- **Enter в `Input`** вызывает `onSubmitCode(code)` только когда `!disabledSubmit`.
-- **`Submit` disabled, если `code === ""`** — «пустой» код не отправляется.
-- **`Refresh` disabled, если `countdownTimeLeft > 0`** — пользователь не может запросить код повторно до окончания отсчёта.
-- **`Refresh` остаётся enabled при `allDisabled && error`** (`(allDisabled && !error) || disabled || isSmsCountdownTicking`) — пользователь должен иметь возможность перезапросить код при ошибке.
-- **`SMSField.Tooltip` требует `targetRef`** — ref на Refresh-кнопку.
-- **`ISMSFieldTooltipProps.children: React.ReactElement`** — единственный ребёнок.
-- **`SMSField` — FC** (не forwardRef). `Input`, `Refresh` — forwardRef на соответствующие HTML-элементы.
-- **`FormField`/`FormFieldInput`** используется внутри Input — это фиксирует error/disabled-стилизацию.
+- `forwardRef<HTMLDivElement>` на SMSField сохраняется; внешний ref указывает на прежний корневой `div`, а не на input. Ref на поле ввода передаётся в `SMSField.Input`, ref на кнопки — в `SMSField.Refresh` и `SMSField.Submit`.
+- Статические части `SMSField.Input`, `.Refresh`, `.Submit`, `.Tooltip` и отдельные экспорты `SMSFieldInput`, `SMSFieldRefresh`, `SMSFieldSubmit`, `SMSFieldTooltip` из barrel сохраняются. Имена и типы props, значения `EComponentSize` и допустимые значения `EFormFieldStatus` — публичный API.
+- Корневой `div` остаётся контейнером с `position: relative` и полной шириной; кнопки позиционируются внутри него. `className`, HTML-атрибуты и `data-tx` относятся к корню.
+- Связь через единый `SMSFieldContext`, синхронизация `disabledSubmit` кнопкой Submit и передача `tooltipId` от Tooltip к Refresh определяют поведение композиции; не меняй их независимо друг от друга.
+- Сохраняй фильтрацию ввода, порядок callbacks и текущую передачу `code` при отправке. Enter сейчас определяется по `keyCode` через `EVENT_KEY_CODES.ENTER`; замена клавиатурного контракта требует проверки поведения.
+- Имена дизайн-токенов, LESS-классы и существующие story IDs `components-smsfield--*` нельзя переименовывать без согласования и синхронизации тестов. Цвета берутся из токенов.
+- Генерацию tooltip ID через `uniqueId` не заменяй на React 18-only API: библиотека поддерживает React 17 через ветку `release-0`.
 
 ---
 
 ## Accessibility
 
-- `SMSField.Input` наследует accessibility от `FormFieldInput`.
-- `SMSField.Refresh` получает `aria-describedby={tooltipId}` → screen reader озвучивает tooltip как описание кнопки.
-- `autoComplete="off"` захардкожен на input — предотвращает автозаполнение.
-- Tooltip-триггер — `hover`; для клавиатуры — фокус на кнопке активирует tooltip в Tooltip-компоненте (см. Tooltip-AI).
+- Корневой `div` не имеет роли и label и не управляет фокусом; для фокуса используй ref `SMSField.Input`.
+- Доступное имя Input и обеих кнопок-иконок задаёт потребитель: например, `aria-label` или связь через `aria-labelledby`. Placeholder и `description` сами по себе не заменяют доступное имя. Компонент не хардкодит язык подписей.
+- Input в `ERROR` выставляет `aria-invalid="true"`, в других статусах атрибут отсутствует. Текст `errorText` отображается как placeholder; автоматического `aria-live` или связи input с текстом ошибки нет. При необходимости связь через `aria-describedby` задаёт потребитель на Input.
+- Корневой `DISABLED` выставляет нативный `disabled` на Input, Submit и Refresh: они исключаются из обычного таб-обхода. Локальный `disabled` кнопки действует дополнительно.
+- Enter в Input отправляет текущий код только при `disabledSubmit === false`; пользовательский `onKeyDown` Input вызывается на самом `input` после этой обработки. SMSField не вызывает `preventDefault` для Enter. Tab, фокус/blur и активация кнопок сохраняют нативное поведение.
+- Refresh получает `aria-describedby={tooltipId}` из контекста. Tooltip связывает подсказку с target через `targetRef` и ID; сам базовый Tooltip не добавляет `role="tooltip"`.
 
 ---
 
 ## Связанные компоненты
 
-- `FormField`, `FormFieldInput`, `FormFieldCounter`, `FormFieldDescription` — основа поля ввода.
-- `ButtonIcon` — основа для Submit/Refresh.
-- `Tooltip` — обёртка Refresh.
-- `TextField` — общий аналог для не-SMS кейсов.
+- `SMSFieldInput`, `SMSFieldRefresh`, `SMSFieldSubmit`, `SMSFieldTooltip` — составные части, доступны также как `SMSField.*`. Зависимости ниже рендерят они, а не корень.
+- `FormField` — через Input передаёт статус и размер базовому полю; `FormFieldInput`, `FormFieldDescription` и `FormFieldCounter` формируют ввод и нижний блок.
+- `FormGroup` — через Input объединяет поле с описанием и счётчиком.
+- `ButtonIcon` — база Submit и Refresh; даёт нативный `button`, недоступное состояние и обработчики.
+- `Tooltip` — база SMSField.Tooltip; её `targetRef` и дополнительные props определяют размещение и открытие подсказки.
+- `RefreshIcon` и `SubmitIcon` — внутренние SVG-иконки Refresh и Submit, из barrel не экспортируются.
+- `TextField`, `MaskedField`, `SuggestField` — поля для других задач ввода, описанных в «Не используй когда».
 
 ---
 
 ## Stories
 
 Основные истории: `stories/SMSField/SMSField.stories.tsx`
-Примеры: `stories/SMSField/examples/`
+Файлы примеров: `stories/SMSField/examples/`
 
-| Story | Что демонстрирует |
-|---|---|
-| `Playground` | Интерактивный контроль |
-| `Error` | Состояние ошибки + Refresh доступен |
-| `Disabled` | Общий disabled |
-| `Sizes` | Все размеры (MD/LG) |
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Управляемый код, size/status, настройки Input, счётчик и внешний обратный отсчёт; Actions для callbacks. |
+| `Default` | `Default.tsx` | Минимальная контролируемая композиция с доступными именами поля и кнопок. |
+| `Sizes` | `Sizes.tsx` | Пустое поле DEFAULT в размерах SM / MD / LG с подписями. |
+| `Statuses` | `Statuses.tsx` | Пустое поле в DEFAULT, ERROR (errorText вместо placeholder) и DISABLED; WARNING не поддерживается. |
+| `Example` | `Example.tsx` | Внешний таймер повторного запроса, Tooltip, описание, maxLength и счётчик. |
+| `VisualTests` | `VisualTests.tsx` | Заполненный код в DEFAULT / ERROR / DISABLED, начало и середина обратного отсчёта, описание и счётчик. |
+| `VisualTestsFocused` | `VisualTestsFocused.tsx` | Фокус пустого поля DEFAULT через play. |
+| `VisualTestsErrorFocused` | `VisualTestsErrorFocused.tsx` | Фокус пустого ERROR: обычный placeholder вместо errorText. |
+| `VisualTestsSubmitHovered` | `VisualTestsSubmitHovered.tsx` | Hover доступной активной кнопки отправки при заполненном коде. |
+| `VisualTestsRefreshHovered` | `VisualTestsRefreshHovered.tsx` | Hover кнопки повторного запроса с открытой подсказкой в портале и стабильным ID. |
+
+Код документационных примеров показывается через `?raw`. Из скриншот-тестов исключены Playground, Default (дублирует LG в Sizes) и Example (живой таймер). Stories с одним размером используют LG — основной размер на формах: статус меняет только цвета, а геометрию размеров проверяет Sizes. В hover-stories курсор наводит test-runner по `parameters.testRunner.hoverSelector` (CSS `:hover`), а `play` открывает подсказку.
 
 ---
 
@@ -157,4 +149,187 @@ src/components/SMSField/
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-10-05 | Создан документ (TRI-72). Описаны контролируемый код, составные части, контекст и accessibility; добавлен ref на корневой div и на SMSField.Submit, stories переведены на modern pattern. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/SMSField/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { SMSField, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [code, setCode] = useState("");
+
+    return (
+        <div style={{ width: 300 }}>
+            <SMSField code={code} onChangeCode={setCode} onSubmitCode={() => {}} size={EComponentSize.LG}>
+                <SMSField.Refresh
+                    aria-label="Запросить новый код"
+                    countdownTime={10}
+                    countdownTimeLeft={0}
+                    onRefresh={() => {}}
+                />
+                <SMSField.Input aria-label="СМС-код" placeholder="Введите код" />
+                <SMSField.Submit aria-label="Отправить код" />
+            </SMSField>
+        </div>
+    );
+};
+```
+
+### Sizes
+
+`stories/SMSField/examples/Sizes.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { SMSField, EComponentSize } from "@sberbusiness/triplex-next";
+
+interface ISizeItemProps {
+    size: EComponentSize;
+}
+
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const [code, setCode] = useState("");
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+            <SMSField code={code} onChangeCode={setCode} onSubmitCode={() => {}} size={size}>
+                <SMSField.Refresh
+                    aria-label="Запросить новый код"
+                    countdownTime={10}
+                    countdownTimeLeft={0}
+                    onRefresh={() => {}}
+                />
+                <SMSField.Input aria-label={`СМС-код ${size}`} placeholder="Введите код" />
+                <SMSField.Submit aria-label="Отправить код" />
+            </SMSField>
+        </div>
+    );
+};
+
+const SIZES = Object.values(EComponentSize);
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16, width: 300 }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
+```
+
+### Statuses
+
+`stories/SMSField/examples/Statuses.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { SMSField, EComponentSize, EFormFieldStatus, ISMSFieldProps } from "@sberbusiness/triplex-next";
+
+interface IStatusItemProps {
+    status: NonNullable<ISMSFieldProps["status"]>;
+}
+
+const StatusItem = ({ status }: IStatusItemProps) => {
+    const [code, setCode] = useState("");
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{status.toUpperCase()}</div>
+            <SMSField
+                code={code}
+                onChangeCode={setCode}
+                onSubmitCode={() => {}}
+                size={EComponentSize.LG}
+                status={status}
+            >
+                <SMSField.Refresh
+                    aria-label="Запросить новый код"
+                    countdownTime={10}
+                    countdownTimeLeft={0}
+                    onRefresh={() => {}}
+                />
+                <SMSField.Input aria-label={`СМС-код ${status}`} errorText="Неверный код" placeholder="Введите код" />
+                <SMSField.Submit aria-label="Отправить код" />
+            </SMSField>
+        </div>
+    );
+};
+
+// WARNING в SMSField не поддерживается.
+const STATUSES = [EFormFieldStatus.DEFAULT, EFormFieldStatus.ERROR, EFormFieldStatus.DISABLED] as const;
+
+export const Statuses = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16, width: 300 }}>
+        {STATUSES.map((status) => (
+            <StatusItem key={status} status={status} />
+        ))}
+    </div>
+);
+```
+
+### Example
+
+`stories/SMSField/examples/Example.tsx`
+
+```tsx
+import React, { useEffect, useRef, useState } from "react";
+import { SMSField, EComponentSize } from "@sberbusiness/triplex-next";
+
+const COUNTDOWN_TIME = 10;
+const MAX_LENGTH = 8;
+
+export const Example = () => {
+    const [code, setCode] = useState("");
+    const [countdownTimeLeft, setCountdownTimeLeft] = useState(0);
+    const targetRef = useRef<HTMLButtonElement>(null);
+
+    useEffect(() => {
+        if (countdownTimeLeft === 0) {
+            return;
+        }
+
+        const timeoutId = window.setTimeout(() => setCountdownTimeLeft((timeLeft) => timeLeft - 1), 1000);
+
+        return () => window.clearTimeout(timeoutId);
+    }, [countdownTimeLeft]);
+
+    const handleRefresh = () => {
+        setCode("");
+        setCountdownTimeLeft(COUNTDOWN_TIME);
+    };
+
+    return (
+        <div style={{ width: 300 }}>
+            <SMSField code={code} onChangeCode={setCode} onSubmitCode={() => {}} size={EComponentSize.LG}>
+                <SMSField.Tooltip targetRef={targetRef} message="Запросить СМС-код ещё раз">
+                    <SMSField.Refresh
+                        aria-label="Запросить новый код"
+                        countdownTime={COUNTDOWN_TIME}
+                        countdownTimeLeft={countdownTimeLeft}
+                        onRefresh={handleRefresh}
+                        ref={targetRef}
+                    />
+                </SMSField.Tooltip>
+                <SMSField.Input
+                    aria-label="СМС-код"
+                    counter={`${code.length}/${MAX_LENGTH}`}
+                    description="Введите код из СМС"
+                    maxLength={MAX_LENGTH}
+                    placeholder="Введите код"
+                />
+                <SMSField.Submit aria-label="Отправить код" />
+            </SMSField>
+        </div>
+    );
+};
+```
+

package/bundle/components/SelectExtendedField.md

@@ -1,7 +1,7 @@
 ---
 component: SelectExtendedField
 category: SelectExtendedField
-related: [SelectField, MultiselectField, SuggestField, Dropdown, FormField, KeyDownListener, IconWrapper, LoaderSmall]
+related: [SelectField, MultiselectField, SuggestField, Dropdown, Puller, FormField, KeyDownListener, IconWrapper, LoaderSmall]
 tokens: []
 stories: stories/SelectExtendedField/SelectExtendedField.stories.tsx
 version: "1.0"
@@ -75,8 +75,8 @@ version: "1.0"
 | `label` | `React.ReactNode` | — | Выбранное значение |
 | `placeholder` | `React.ReactNode` | — | Отображается, пока нет `label` |
 | `loading` | `boolean` | `false` | Вместо каретки — лоадер; клик и клавиатура не открывают блок |
-| `onClear` | `() => void` | — | Если передан, в постфиксе появляется кнопка очистки |
-| `prefix` / `postfix` | `React.ReactNode` | — | Слоты `FormFieldPrefix` / `FormFieldPostfix`. Постфикс идёт **после** каретки |
+| `onClear` | `React.MouseEventHandler<HTMLButtonElement>` | — | Если передан, в постфиксе появляется кнопка очистки |
+| `prefix` / `postfix` | `React.ReactNode` | — | Слоты `FormFieldPrefix` / `FormFieldPostfix`. Постфикс идёт **после** каретки. Обработка событий — см. «Ограничения» |
 | `size` | `EComponentSize` | `EComponentSize.MD` | Размер поля. Определяет размер каретки и лоадера |
 | `status` | `EFormFieldStatus` | `EFormFieldStatus.DEFAULT` | Визуальное состояние. `DISABLED` блокирует открытие |
 
@@ -86,7 +86,7 @@ version: "1.0"
 а через prop `forwardedRef` — рендер-функция `children` отдаёт готовый `dropdownRef`,
 и передать его через `ref` в JSX было бы невозможно без промежуточной обёртки.
 Остальные props — как у `Dropdown` (`size`, `width`, `direction`, `alignment`,
-`mobileViewProps`, ...). Статическое свойство `List` — это `DropdownList`.
+`pullerProps`, ...). Статическое свойство `List` — это `DropdownList`.
 
 ### Ограничения
 
@@ -94,7 +94,8 @@ version: "1.0"
 - `SelectExtendedFieldDropdown` — не `forwardRef`-компонент. Ссылка передаётся через `forwardedRef`.
 - Выпадающий блок компонент не рендерит сам и не знает, открыт ли он визуально: `opened` нужно передать в `SelectExtendedFieldDropdown` (или в свою разметку) самостоятельно.
 - Компонент не хранит выбранное значение и не знает про опции. Значение — целиком забота потребителя.
-- Клик по кнопке очистки (`onClear`) не раскрывает выпадающий блок: `SelectExtendedFieldTarget` останавливает всплытие в обработчике `FormFieldClear`. Без этого событие дошло бы до `onClick` на `FormField` и переключило `opened` — так же гасят всплытие `Chip.Select` и `Chip.DatePicker`. Не убирать: затрагивает `SelectField` и `MultiselectField.Target`, которые рендерят тот же `Target`.
+- Клик по фокусируемым элементам внутри поля (`tabIndex >= 0`: кнопка очистки, `HelpBox`, кнопки тегов в значении) и по содержимому порталов (Tooltip) не переключает выпадающий блок; Enter / Space на них не открывают блок и не отменяют их нативный клик. Клик по остальному содержимому поля, включая элементы с `tabIndex < 0` (`<button tabIndex={-1}>`, `div` с `onClick` без `tabIndex`), блок переключает. Затрагивает `SelectField` и `MultiselectField.Target`.
+- Клик по кнопке очистки (`onClear`) не всплывает: `onClick` поля и обработчики внешних элементов его не получают.
 
 ---
 
@@ -135,7 +136,7 @@ version: "1.0"
 
 - `SelectExtendedFieldTarget` выставляет на корневом элементе `aria-haspopup="listbox"` и `aria-expanded`, отражающий `opened`.
 - Роли `listbox` / `option` и клавиатурную навигацию по опциям (`ArrowUp` / `ArrowDown`, выбор по `Enter` / `Space`) даёт `DropdownList` — то есть `SelectExtendedField.Dropdown.List`. Если выпадающий блок не список, эти роли не появляются и навигацию организует потребитель.
-- Клавиши открытия на поле выбора: `Space`, `Enter`, `ArrowDown`, `ArrowUp`. Обработчик вызывает `preventDefault` (чтобы страница не прокручивалась) и `stopPropagation` — иначе то же нажатие поймает документный обработчик `DropdownListItem` и список сразу выберет опцию.
+- Клавиши открытия на поле выбора: `Space`, `Enter`, `ArrowDown`, `ArrowUp` (только когда фокус на самом поле). Обработчик вызывает `preventDefault` (чтобы страница не прокручивалась) и `stopPropagation` — иначе то же нажатие поймает документный обработчик `DropdownListItem` и список сразу выберет опцию.
 - В состояниях `loading` и `status={EFormFieldStatus.DISABLED}` поле не реагирует ни на клик, ни на клавиатуру; `onClick` / `onKeyDown` потребителя в этих состояниях тоже не вызываются.
 - `Escape` закрывает блок из любого места страницы — слушатель `KeyDownListener` висит на `window`.
 - `Tab` закрывает блок только при `closeOnTab`. Фокус компонент не перехватывает и не возвращает: focus trap, если нужен, добавляет потребитель.
@@ -171,7 +172,8 @@ version: "1.0"
 
 **Инфраструктура:**
 
-- `Dropdown` — выпадающее меню через `Portal`, позиционирование, мобильная версия.
+- `Dropdown` — выпадающее меню через `Portal`, позиционирование, переключение на мобильную версию.
+- `Puller` — мобильная версия выпадающего блока в `SelectExtendedFieldDropdownDefault` (`PullerHeader`, `PullerClose`, `PullerBody`, `PullerList`, `PullerListItem`).
 - `FormField` — визуальный контейнер поля, контекст размера и статуса.
 - `KeyDownListener` — закрытие по `Escape`.
 - `IconWrapper`, `LoaderSmall` — каретка и лоадер в постфиксе поля.
@@ -204,6 +206,8 @@ version: "1.0"
 | 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 не изменён. |
 | 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны несимметричные имена (`Chip`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
+| 2026-10-21 | **Breaking** (TRIPLEX-961): prop `mobileViewProps`, унаследованный `SelectExtendedField.Dropdown` от `Dropdown`, переименован в `pullerProps`. |
+| 2026-10-29 | TRIPLEX-1028: `SelectExtendedField.Target` переключает выпадающий блок только по событиям самого поля — см. «Ограничения». `onClear` получает событие клика. |
 
 ---
 

package/bundle/components/SelectField.md

@@ -59,8 +59,8 @@ version: "1.0"
 | `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` в нём не виден |
+| `dropdownListItemClassName` | `string` | — | Класс каждого элемента списка — и десктопного `DropdownListItem`, и мобильного `PullerListItem` |
+| `mobileTitle` | `React.ReactNode` | — | Заголовок выпадающего блока в мобильном режиме. Отдельный prop: на мобильном список открывается в нижней шторке `Puller`, и `fieldLabel` в ней не виден |
 | `closeOnTab` | `boolean` | `true` | Компонент передаёт `closeOnTab={true}`, но `{...rest}` идёт после, поэтому переданное потребителем значение выигрывает |
 | `children` | `never` | — | Не принимаются: выпадающий блок компонент рендерит сам |
 
@@ -147,8 +147,9 @@ version: "1.0"
   `SelectField` рендерит вокруг выпадающего блока. Без этого провайдера связка не работает.
 - `aria-expanded` и `aria-haspopup="listbox"` выставляет `SelectExtendedFieldTarget`;
   роли `listbox` / `option` и навигацию `ArrowUp` / `ArrowDown` — `DropdownList`.
-- Клавиши открытия списка: `Space`, `Enter`, `ArrowDown`, `ArrowUp`. Закрытие — `Escape`
-  (из любого места страницы), `Tab` (`closeOnTab`) и нажатие мышью вне поля и списка.
+- Клавиши открытия списка: `Space`, `Enter`, `ArrowDown`, `ArrowUp` (только когда фокус на самом
+  поле). Закрытие — `Escape` (из любого места страницы), `Tab` (`closeOnTab`) и нажатие мышью
+  вне поля и списка.
 - В состояниях `loading` и `status={EFormFieldStatus.DISABLED}` поле не реагирует ни на клик,
   ни на клавиатуру.
 - **Доступное имя задаёт потребитель.** Компонент не хардкодит текст (библиотека мультиязычная):
@@ -206,6 +207,8 @@ version: "1.0"
 |---|---|
 | 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 не изменён |
 | 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны несимметричные имена (`Chip`); добавлены обратные ссылки (`FormField`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
+| 2026-10-21 | Переход на `Puller` (TRIPLEX-961): мобильный элемент списка — `PullerListItem` (бывший `DropdownMobileListItem`). |
+| 2026-10-29 | TRIPLEX-1028: Enter / Space на кнопке очистки и других фокусируемых элементах внутри поля больше не открывают список, клик по таким элементам, кроме очистки, — не переключает. Клавиши открытия — см. «Accessibility». `targetProps.onClear` получает событие клика. |
 
 ---