@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 1.40.0-beta

package/bundle/components/TextField.md

@@ -1,11 +1,9 @@
 ---
 component: TextField
-category: Form Controls
-figma-node: ""
-figma-file: ""
-related: [TextareaField, MaskedField, AmountField, FormField, TextFieldBase]
+category: TextFields
+related: [MaskedField, FormField, FormGroup, TextareaField, MonthYearField]
 tokens: []
-stories: stories/TextFields/TextField.stories.tsx
+stories: stories/TextField/TextField.stories.tsx
 version: "1.0"
 ---
 
@@ -13,135 +11,101 @@ version: "1.0"
 
 ## Назначение
 
-Однострочное текстовое поле: тонкая обёртка над `TextFieldBase`,
-вставляющая `FormFieldInput` (`<input type="text">`). Также в этом
-бандле — `MaskedField` (с `FormFieldMaskedInput`), идентичная по
-структуре. Компактное представление поля поверх `FormGroup` + `FormField`.
+Компонент текстового ввода — компактная альтернатива `FormGroup` для однострочного поля: input с плавающим лейблом, префиксом/постфиксом, описанием и счётчиком символов в одном компоненте. Композиция над семейством `FormField` (`FormGroup` → `FormField` → `FormFieldInput` + `FormFieldLabel`/`FormFieldPrefix`/`FormFieldPostfix`/`FormFieldDescription`/`FormFieldCounter`).
 
-Используй когда: нужен стандартный однострочный ввод с label/description/
-prefix/postfix/counter. Для многострочного — `TextareaField`. С маской —
-`MaskedField`. Для сумм — `AmountField`.
+Используй когда: нужно однострочное текстовое поле с лейблом, статусом (error/warning/disabled), префиксом/постфиксом или описанием под полем.
 
----
-
-## Файловая структура
-
-```text
-src/components/TextField/
-├── TextField.tsx        # FC<ITextFieldProps>; TextFieldBase + FormFieldInput
-├── MaskedField.tsx      # FC<IMaskedFieldProps>; TextFieldBase + FormFieldMaskedInput
-├── TextFieldBase.tsx    # forwardRef<HTMLDivElement, ITextFieldBaseProps>; общая структура
-└── index.ts             # export TextField, MaskedField
-```
+Не используй когда: нужен ввод с маской (`MaskedField`), многострочный ввод (`TextareaField`), денежная сумма (`AmountField`), выбор из подсказок (`SuggestField`) или полноформатная форма с раздельными label/field-блоками (`FormGroup` + `FormField` напрямую).
 
 ---
 
-## Публичный API
+## Варианты и props
 
-### `ITextFieldProps`
+`TextField` — тонкая обёртка: `inputProps` уходит в `FormFieldInput`, остальные props — в `TextFieldBase` (и далее в `FormField`). Собственного state нет.
 
-```ts
-extends Omit<ITextFieldBaseProps, "children">
-{
-    inputProps: IFormFieldInputProps & { ref?: RefObject<HTMLInputElement> };
-}
-```
+### Обязательные props
 
 | Prop | Тип | Описание |
 |---|---|---|
-| `inputProps` | `IFormFieldInputProps & { ref? }` | **Обязателен**. Прокидывается на `FormFieldInput`. Может содержать `ref` на `<input>`. |
-| `label?` | `ReactNode` | Лейбл (плавающий). |
-| `description?` | `ReactNode` | Описание / текст ошибки. |
-| `counter?` | `ReactNode` | Счётчик символов (внутри description). |
-| `prefix?` / `postfix?` | `ReactNode` | Префикс/постфикс (иконка, кнопка, текст). |
-| `...IFormFieldProps` | — | size, status, disabled, focused, error и т.д. от `FormField`. |
-
-### `IMaskedFieldProps`
-
-```ts
-extends Omit<ITextFieldBaseProps, "children">
-{
-    maskedInputProps: IFormFieldMaskedInputProps & { ref?: RefObject<HTMLInputElement> };
-}
-```
+| `inputProps` | `IFormFieldInputProps & { ref? }` | Свойства input: все стандартные атрибуты `<input>` (`value`, `onChange`, `placeholder`, `maxLength`…), `ref` на `HTMLInputElement`, а также render-prop `render` для подмены инпута (кастомная валидация, маска) с сохранением стилизации. |
 
-Идентична `ITextFieldProps`, но input с маской.
+### Опциональные props
 
-### `ITextFieldBaseProps`
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `size` | `EComponentSize` | `LG` | Размер поля: SM / MD / LG. |
+| `status` | `EFormFieldStatus` | `DEFAULT` | Статус: default / error / warning / disabled. `DISABLED` автоматически ставит `disabled` на input. |
+| `active` | `boolean` | `false` | Принудительно активное (focused) визуальное состояние рамки. |
+| `label` | `ReactNode` | — | Плавающий лейбл; связывается с input через `htmlFor`. |
+| `prefix` | `ReactNode` | — | Контент слева от input (иконка и т.п.), рендерится в `FormFieldPrefix`. |
+| `postfix` | `ReactNode` | — | Контент справа от input (иконка, `FormFieldClear`, `HelpBox`), рендерится в `FormFieldPostfix`. |
+| `description` | `ReactNode` | — | Описание под полем (`FormFieldDescription`); цвет наследует статус. |
+| `counter` | `ReactNode` | — | Счётчик символов справа под полем (`FormFieldCounter`). Блок описания рендерится, если задан `description` ИЛИ `counter`. |
 
-```ts
-extends Omit<IFormFieldProps, "prefix" | "postfix">
-{
-    children: ReactNode;     // обязателен — само поле ввода
-    description?: ReactNode;
-    counter?: ReactNode;
-    prefix?: ReactNode;
-    postfix?: ReactNode;
-    label?: ReactNode;
-}
-```
+Остальные неперечисленные props (`className`, data-атрибуты, div-атрибуты) пробрасываются на корневой `FormField` (div).
+
+### Особенности поведения
 
-`TextFieldBase` — `forwardRef<HTMLDivElement>`. Используется напрямую,
-если нужен кастомный input (не Input/Masked/Textarea).
+- Состояние «заполнено» (floating label) вычисляется внутри `FormFieldInput` из `value`/`defaultValue`/событий, включая браузерное автозаполнение (через CSS-анимационные хуки `autofill-*`). Потребителю управлять им не нужно.
+- Ограничение длины ввода (для связки с `counter`) — на стороне потребителя: `inputProps.maxLength` или контролируемый `onChange`.
+- Кнопка очистки не встроена — передаётся потребителем как `postfix={<FormFieldClear onClick={...} />}`.
 
 ---
 
-## Структура DOM
+## Дизайн-токены
 
-```tsx
-<FormGroup>
-    <FormField {...formFieldProps} ref={ref}>
-        {prefix && <FormFieldPrefix>{prefix}</FormFieldPrefix>}
-        {children}                        {/* FormFieldInput / MaskedInput / Textarea */}
-        {label && <FormFieldLabel>{label}</FormFieldLabel>}
-        {postfix && <FormFieldPostfix>{postfix}</FormFieldPostfix>}
-    </FormField>
-    {(description || counter) && (
-        <FormFieldDescription>
-            {description}
-            {counter && <FormFieldCounter>{counter}</FormFieldCounter>}
-        </FormFieldDescription>
-    )}
-</FormGroup>
-```
+Собственных CSS-токенов и стилей нет. Внешний вид полностью наследуется от семейства `FormField` (токены `--triplex-next-FormField-*` описаны в стилях `src/components/FormField/styles/`).
 
 ---
 
 ## Инварианты
 
-- **`TextField` / `MaskedField` — `FC, не forwardRef`**. Ref на `<input>` — через `inputProps.ref` / `maskedInputProps.ref`. `TextFieldBase` — `forwardRef<HTMLDivElement>` (сохранять).
-- **`inputProps` / `maskedInputProps` обязательны** — нельзя default'ить.
-- **Label рендерится после children в DOM** — требование `FormField` (плавающий лейбл через CSS), не менять порядок.
-- **`description` и `counter` объединены в одну `FormFieldDescription`** — counter внутри `<FormFieldCounter>`. Не дублировать обёртку.
-- **`prefix` / `postfix` поддерживаются `TextFieldBase` напрямую** (`Omit<IFormFieldProps, "prefix" | "postfix">` → переопределяет на ReactNode).
-- **`displayName` выставлен** на `TextField`, `MaskedField`, `TextFieldBase`.
-- **`MaskedField` отличается ТОЛЬКО типом input'а** — никакой собственной логики маскирования, она внутри `FormFieldMaskedInput`.
+- `forwardRef` на `TextField` и `TextFieldBase` — не убирать. Внешний `ref` указывает на корневой `<div>` `FormField`; ref на сам input — только через `inputProps.ref`.
+- Публичный API (`ITextFieldProps`: `inputProps` + `label`/`prefix`/`postfix`/`description`/`counter` + унаследованные `size`/`status`/`active`) — изменение имён/типов/значений enum — breaking change.
+- Barrel `index.ts` экспортирует `TextField` и `MaskedField` — состав экспортов не менять. `TextFieldBase` намеренно НЕ экспортируется — приватная база.
+- Известное ограничение контракта: `inputProps.ref` типизирован как `React.RefObject<HTMLInputElement>` (не `React.Ref`), callback-ref формально не проходит по типам. Исправление — breaking change, требует отдельной задачи.
+- Уникальный `id` для связки label↔input генерируется через `lodash uniqueId` в `FormFieldInput` — не заменять на `useId` (React 17 совместимость через release-0).
+- `description || counter` рендерятся в общем блоке `FormFieldDescription` — не разносить по отдельным блокам (изменит DOM и скриншоты).
 
 ---
 
 ## Accessibility
 
-- `<input>` (или masked input) — приходит из `FormFieldInput`, отвечает за `id`, `aria-describedby`, `aria-invalid`.
-- `<label htmlFor>` — связь с input'ом через `FormFieldLabel`/`FormField`.
-- Описание/ошибка — через `description` (попадает в `FormFieldDescription`), `aria-describedby` подвязывается автоматически.
-- `disabled`/`readonly`/`required` — на `inputProps`.
+- Лейбл — настоящий `<label htmlFor>` связанный с `id` инпута (id генерируется автоматически или берётся из `inputProps.id`).
+- `status={EFormFieldStatus.DISABLED}` выставляет нативный атрибут `disabled` на input — поле выпадает из таб-обхода штатно.
+- Семантика ошибки (`aria-invalid`, `aria-describedby` на description) не хардкодится — при необходимости потребитель передаёт атрибуты через `inputProps`.
+- Специальной клавиатурной логики нет — стандартное поведение `<input>`.
 
 ---
 
 ## Связанные компоненты
 
-- `TextareaField` — многострочный аналог.
-- `MaskedField` — экспортируется отсюда же; ввод по маске.
-- `AmountField` — для денежных сумм.
-- `TextFieldBase` — общая база (используется напрямую при кастомном input'е).
-- `FormField`, `FormGroup`, `FormFieldInput`, `FormFieldMaskedInput`, `FormFieldLabel`, `FormFieldDescription`, `FormFieldCounter`, `FormFieldPrefix`, `FormFieldPostfix` — внутренние составляющие.
+- `TextFieldBase` (внутренний, не в barrel) — базовая раскладка `FormGroup`/`FormField` + слоты `prefix`/`children`/`label`/`postfix` и блок `description`/`counter`. На нём построены `TextField` и `MaskedField`. Описан здесь, отдельного AI.md не имеет.
+- `MaskedField` — сосед по папке: то же самое, но с `FormFieldMaskedInput` (ввод по маске) через prop `maskedInputProps`. Документируется отдельно.
+- `FormField` / `FormFieldInput` и слоты семейства — низкоуровневые строительные блоки; используются напрямую, когда нужна нестандартная композиция.
+- `FormGroup` — контейнер вертикальной раскладки поля и описания.
+- `FormFieldClear` — кнопка очистки, передаётся в `postfix`.
+- `TextareaField`, `AmountField`, `SuggestField`, `DateField`, `MonthYearField` — специализированные поля той же группы `TextFields`.
 
 ---
 
 ## Stories
 
-Основные истории: `stories/TextFields/TextField.stories.tsx` (а также `MaskedField.stories.tsx`, `AmountField.stories.tsx` рядом).
-Примеры: `stories/TextFields/examples/`.
+Основные истории: `stories/TextField/TextField.stories.tsx`
+Файлы примеров: `stories/TextField/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль size / status / label / prefix / postfix / description / counter |
+| `Default` | `Default.tsx` | Минимальное контролируемое поле с label и placeholder |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG |
+| `Statuses` | `Statuses.tsx` | Статусы default / error / warning / disabled с description соответствующего типа |
+| `WithPrefixAndPostfix` | `WithPrefixAndPostfix.tsx` | Иконки в префиксе и постфиксе |
+| `WithClearButton` | `WithClearButton.tsx` | Кнопка очистки `FormFieldClear` в постфиксе |
+| `WithCounter` | `WithCounter.tsx` | Описание и счётчик символов под полем |
+| `PassRefToInput` | `PassRefToInput.tsx` | Проброс ref на input через `inputProps.ref` |
+| `Production` | `Production.tsx` | Production-композиция (`Example: production`): `HelpBox` в постфиксе, description со ссылкой, лимит длины со счётчиком, кнопка очистки |
+| `VisualTests` | `VisualTests.tsx` | Скриншот-регрессия: фокус (через `play`), заполненные размеры, prefix/postfix, description/counter, статусы |
 
 ---
 
@@ -149,4 +113,307 @@ extends Omit<IFormFieldProps, "prefix" | "postfix">
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-07-27 | Создан документ (TRI-5). AI-рефакторинг TextField/TextFieldBase, unit-тесты, миграция stories на modern pattern |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/TextField/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { TextField } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [value, setValue] = useState("");
+
+    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => setValue(event.target.value);
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <TextField label="Label" inputProps={{ value, onChange: handleChange, placeholder: "Type to proceed" }} />
+        </div>
+    );
+};
+```
+
+### Sizes
+
+`stories/TextField/examples/Sizes.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { TextField, EComponentSize } from "@sberbusiness/triplex-next";
+
+interface ISizeItemProps {
+    size: EComponentSize;
+}
+
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const [value, setValue] = useState("");
+
+    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => setValue(event.target.value);
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
+            <TextField
+                size={size}
+                label="Label"
+                inputProps={{ value, onChange: handleChange, placeholder: "Type to proceed" }}
+            />
+        </div>
+    );
+};
+
+const SIZES = Object.values(EComponentSize);
+
+export const Sizes = () => (
+    <div style={{ maxWidth: "300px", display: "flex", flexDirection: "column", gap: "16px" }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
+```
+
+### Statuses
+
+`stories/TextField/examples/Statuses.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { TextField, Text, EFormFieldStatus, ETextSize, EFontType } from "@sberbusiness/triplex-next";
+
+interface IStatusItemProps {
+    status: EFormFieldStatus;
+    description: string;
+    descriptionType: EFontType;
+}
+
+const StatusItem = ({ status, description, descriptionType }: IStatusItemProps) => {
+    const [value, setValue] = useState("");
+
+    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => setValue(event.target.value);
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{status.toUpperCase()}</div>
+            <TextField
+                status={status}
+                label="Label"
+                description={
+                    <Text tag="div" size={ETextSize.B4} type={descriptionType}>
+                        {description}
+                    </Text>
+                }
+                inputProps={{ value, onChange: handleChange, placeholder: "Type to proceed" }}
+            />
+        </div>
+    );
+};
+
+const STATUSES: Array<IStatusItemProps> = [
+    { status: EFormFieldStatus.DEFAULT, description: "(21) Description", descriptionType: EFontType.SECONDARY },
+    { status: EFormFieldStatus.ERROR, description: "Error text", descriptionType: EFontType.ERROR },
+    { status: EFormFieldStatus.WARNING, description: "Warning text", descriptionType: EFontType.WARNING },
+    { status: EFormFieldStatus.DISABLED, description: "(21) Description", descriptionType: EFontType.SECONDARY },
+];
+
+export const Statuses = () => (
+    <div style={{ maxWidth: "300px", display: "flex", flexDirection: "column", gap: "16px" }}>
+        {STATUSES.map((item) => (
+            <StatusItem key={item.status} {...item} />
+        ))}
+    </div>
+);
+```
+
+### WithPrefixAndPostfix
+
+`stories/TextField/examples/WithPrefixAndPostfix.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { TextField, HelpBox, ETooltipSize, ETooltipPreferPlace } from "@sberbusiness/triplex-next";
+import { DefaulticonStrokePrdIcon24 } from "@sberbusiness/icons-next";
+
+export const WithPrefixAndPostfix = () => {
+    const [value, setValue] = useState("");
+
+    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => setValue(event.target.value);
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <TextField
+                label="Label"
+                prefix={<DefaulticonStrokePrdIcon24 paletteIndex={5} />}
+                postfix={
+                    <HelpBox tooltipSize={ETooltipSize.SM} preferPlace={ETooltipPreferPlace.ABOVE}>
+                        Text
+                    </HelpBox>
+                }
+                inputProps={{ value, onChange: handleChange, placeholder: "Type to proceed" }}
+            />
+        </div>
+    );
+};
+```
+
+### WithClearButton
+
+`stories/TextField/examples/WithClearButton.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { TextField, FormFieldClear } from "@sberbusiness/triplex-next";
+
+export const WithClearButton = () => {
+    const [value, setValue] = useState("");
+
+    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => setValue(event.target.value);
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <TextField
+                label="Label"
+                postfix={<FormFieldClear onClick={() => setValue("")} />}
+                inputProps={{ value, onChange: handleChange, placeholder: "Type to proceed" }}
+            />
+        </div>
+    );
+};
+```
+
+### WithCounter
+
+`stories/TextField/examples/WithCounter.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { TextField, Text, ETextSize, EFontType } from "@sberbusiness/triplex-next";
+
+const MAX_LENGTH = 201;
+
+export const WithCounter = () => {
+    const [value, setValue] = useState("");
+
+    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+        if (event.target.value.length <= MAX_LENGTH) {
+            setValue(event.target.value);
+        }
+    };
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <TextField
+                label="Label"
+                description={
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        (21) Description
+                    </Text>
+                }
+                counter={
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        {value.length}/{MAX_LENGTH}
+                    </Text>
+                }
+                inputProps={{ value, onChange: handleChange, maxLength: MAX_LENGTH, placeholder: "Type to proceed" }}
+            />
+        </div>
+    );
+};
+```
+
+### PassRefToInput
+
+`stories/TextField/examples/PassRefToInput.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import { TextField } from "@sberbusiness/triplex-next";
+
+export const PassRefToInput = () => {
+    const [value, setValue] = useState("");
+    const ref = useRef<HTMLInputElement>(null);
+
+    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => setValue(event.target.value);
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <TextField
+                label="Label"
+                inputProps={{ ref, value, onChange: handleChange, placeholder: "Type to proceed" }}
+            />
+        </div>
+    );
+};
+```
+
+### Production
+
+`stories/TextField/examples/Production.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    TextField,
+    FormFieldClear,
+    HelpBox,
+    Text,
+    Link,
+    ETooltipSize,
+    ETooltipPreferPlace,
+    ETextSize,
+    EFontType,
+} from "@sberbusiness/triplex-next";
+import { DefaulticonStrokePrdIcon24 } from "@sberbusiness/icons-next";
+
+const MAX_LENGTH = 201;
+
+export const Production = () => {
+    const [value, setValue] = useState("");
+
+    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+        if (event.target.value.length <= MAX_LENGTH) {
+            setValue(event.target.value);
+        }
+    };
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <TextField
+                label="Label"
+                description={
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        (21) Description{" "}
+                        <Link href="#" onClick={(event) => event.preventDefault()}>
+                            Link text
+                        </Link>
+                    </Text>
+                }
+                counter={
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        {value.length}/{MAX_LENGTH}
+                    </Text>
+                }
+                prefix={<DefaulticonStrokePrdIcon24 paletteIndex={5} />}
+                postfix={
+                    <>
+                        <FormFieldClear onClick={() => setValue("")} />
+                        <DefaulticonStrokePrdIcon24 paletteIndex={5} />
+                        <HelpBox tooltipSize={ETooltipSize.SM} preferPlace={ETooltipPreferPlace.ABOVE}>
+                            Text
+                        </HelpBox>
+                    </>
+                }
+                inputProps={{ value, onChange: handleChange, placeholder: "Type to proceed" }}
+            />
+        </div>
+    );
+};
+```
+