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

package/bundle/components/MaskedField.md

@@ -0,0 +1,481 @@
+---
+component: MaskedField
+category: TextFields
+related: [TextField, FormField, FormFieldMaskedInput, FormGroup, DateField, MonthYearField]
+tokens: []
+stories: stories/MaskedField/MaskedField.stories.tsx
+version: "1.0"
+---
+
+# MaskedField
+
+## Назначение
+
+Компонент однострочного ввода по маске — то же поле, что `TextField`, но вместо обычного input внутри используется `FormFieldMaskedInput`: ввод форматируется на лету (телефон, дата, номер карты, ИНН, СНИЛС и другие пресеты), а незаполненная часть маски подсказывается пользователю. Композиция над семейством `FormField` (`FormGroup` → `FormField` → `FormFieldMaskedInput` + `FormFieldLabel`/`FormFieldPrefix`/`FormFieldPostfix`/`FormFieldDescription`/`FormFieldCounter`).
+
+Используй когда: значение имеет фиксированный формат, и его нужно форматировать во время ввода — номер телефона, дата, номер счёта/карты, ИНН/КПП/БИК, СНИЛС, паспортные данные, идентификаторы ЖКУ. Готовые маски лежат в `FormFieldMaskedInput.presets.masks`, подсказки формата — в `FormFieldMaskedInput.presets.placeholderMasks`.
+
+Не используй когда: формат произвольный (`TextField`), нужен календарный выбор даты (`DateField`) или месяца (`MonthYearField`), нужна денежная сумма с разрядами (`AmountField`), многострочный ввод (`TextareaField`) или выбор из подсказок (`SuggestField`).
+
+---
+
+## Варианты и props
+
+`MaskedField` — тонкая обёртка без собственного state: `maskedInputProps` уходит в `FormFieldMaskedInput`, остальные props — в `TextFieldBase` (и далее в `FormField`). Вся логика маски живёт в `FormFieldMaskedInput` (на базе `react-text-mask`).
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `maskedInputProps` | `IFormFieldMaskedInputProps & { ref? }` | Свойства поля с маской. Обязательные внутри: `mask` (массив строк и регулярных выражений) и `value` (строка, поле контролируемое). Опционально: `placeholderMask` (текстовая подсказка формата, например `дд.мм.гггг`), `placeholderChar` (символ-заполнитель, по умолчанию `"0"`), `forwardedRef` (ссылка на input), `ref` (ссылка на div-обёртку), `onChange` и остальные атрибуты `<input>`. |
+
+### Опциональные props
+
+| 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`. |
+
+Остальные неперечисленные props (`className`, data-атрибуты, div-атрибуты) пробрасываются на корневой `FormField` (div).
+
+### Особенности поведения
+
+- **Значение всегда контролируемое.** `maskedInputProps.value` пропускается через `conformToMask`, поэтому в `onChange` приходит уже отформатированное значение (`"12.12."` после ввода четырёх цифр даты). Хранить в state можно как форматированное, так и «сырое» значение — маска применяется к обоим.
+- **`onChange` вызывается только при реальном изменении** отформатированного значения: повторное событие с тем же значением игнорируется.
+- **Подсказка маски** (`placeholderMask` или заполнение символом `placeholderChar`) рисуется отдельным `aria-hidden` слоем поверх поля и показывается, только когда поле в фокусе или заполнено. Если задан обычный `placeholder`, у пустого поля показывается он, а не маска.
+- **Пресеты масок для телефона и SWIFT обрабатываются особо:** телефон нормализует вставку номера с `7`/`8`/`+7` в начале, SWIFT-код приводится к верхнему регистру.
+- Ограничение длины задаёт сама маска — `maxLength` не нужен; `counter`, если он нужен, считает потребитель.
+- Кнопка очистки не встроена — передаётся потребителем как `postfix={<FormFieldClear onClick={...} />}`.
+
+---
+
+## Дизайн-токены
+
+Собственных CSS-токенов и стилей у `MaskedField` нет — поэтому `tokens` во frontmatter пустой. Внешний вид наследуется от семейства `FormField`; слой подсказки маски рисует `FormFieldMaskedInput` своим токеном `--triplex-next-FormField-Placeholder_Color`.
+
+---
+
+## Инварианты
+
+- `forwardRef` на `MaskedField` — не убирать. Внешний `ref` указывает на корневой `<div>` `FormField`.
+- Публичный API (`IMaskedFieldProps`: `maskedInputProps` + `label`/`prefix`/`postfix`/`description`/`counter` + унаследованные `size`/`status`/`active`) — изменение имён/типов/значений enum — breaking change.
+- Barrel `index.ts` экспортирует `TextField` и `MaskedField` — состав экспортов не менять. `TextFieldBase` намеренно НЕ экспортируется — приватная база.
+- Ссылка на элемент input передаётся только через `maskedInputProps.forwardedRef`. `maskedInputProps.ref` (`React.RefObject<HTMLDivElement>`) попадает на корневой `<div>` обёртки `FormFieldMaskedInput` — это ref самого `FormFieldMaskedInput`, а не поля ввода.
+- `maskedInputProps.value` обязателен: `FormFieldMaskedInput` — контролируемый компонент. `defaultValue` исключён из props (`Omit<MaskedInputProps, ... | "defaultValue">`) и не передаётся внутрь `<input>`: `react-text-mask` подставляет его равным `value`, а на контролируемом поле это даёт предупреждение React о смешении controlled и uncontrolled.
+- Маски и подсказки берутся из `FormFieldMaskedInput.presets` — состав пресетов и их значения часть публичного API.
+- Уникальный `id` для связки label↔input генерируется через `lodash uniqueId` в `FormFieldInput` — не заменять на `useId` (React 17 совместимость через release-0).
+
+---
+
+## Accessibility
+
+- Лейбл — настоящий `<label htmlFor>`, связанный с `id` инпута (id генерируется автоматически или берётся из `maskedInputProps.id`).
+- Слой подсказки маски помечен `aria-hidden="true"` и не читается скринридером — формат ввода дополнительно стоит объяснить в `description` или `placeholder`.
+- `status={EFormFieldStatus.DISABLED}` выставляет нативный атрибут `disabled` на input — поле штатно выпадает из таб-обхода.
+- Семантика ошибки (`aria-invalid`, `aria-describedby`) не хардкодится — при необходимости потребитель передаёт атрибуты через `maskedInputProps`.
+- Собственной клавиатурной логики нет; позицию каретки при вводе и вставке ведёт `react-text-mask`.
+
+---
+
+## Связанные компоненты
+
+- `TextField` — сосед по папке: то же поле, но с обычным `FormFieldInput`. Документируется отдельно.
+- `TextFieldBase` (внутренний, не в barrel) — базовая раскладка `FormGroup`/`FormField` + слоты `prefix`/`children`/`label`/`postfix` и блок `description`/`counter`. На нём построены `TextField` и `MaskedField`. Описан в `TextField-ai.md`.
+- `FormFieldMaskedInput` — сам элемент ввода с маской и статическим свойством `presets` (`masks`, `placeholderMasks`). Используется напрямую, когда нужна нестандартная композиция поля.
+- `FormFieldClear` — кнопка очистки, передаётся в `postfix`.
+- `FormGroup` / `FormField` — контейнеры раскладки поля и описания.
+- `DateField`, `MonthYearField`, `AmountField`, `SuggestField`, `TextareaField` — специализированные поля той же группы `TextFields`.
+
+---
+
+## Stories
+
+Основные истории: `stories/MaskedField/MaskedField.stories.tsx`
+Файлы примеров: `stories/MaskedField/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль size / status / label / prefix / postfix / description / counter и выбор маски из пресетов |
+| `Default` | `Default.tsx` | Минимальное контролируемое поле с маской телефона |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG на пустом поле |
+| `Statuses` | `Statuses.tsx` | Статусы default / error / warning / disabled на пустом поле |
+| `WithPlaceholderMask` | `WithPlaceholderMask.tsx` | Подсказка формата: поле с `placeholderMask` против поля без него |
+| `PassRefToInput` | `PassRefToInput.tsx` | Проброс ref на input через `maskedInputProps.forwardedRef` |
+| `AllMasks` | `AllMasks.tsx` | Все пресеты масок `FormFieldMaskedInput.presets.masks` с подписями |
+| `Production` | `Production.tsx` | Production-композиция (`Example: production`): телефон, кнопка очистки и `HelpBox` в постфиксе, description со ссылкой |
+| `VisualTests` | `VisualTests.tsx` | Скриншот-регрессия: фокус с подсказкой маски (через `play`), частично заполненная маска, заполненные размеры, prefix/postfix, description/counter, статусы |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-08-07 | Создан документ (TRI-56). AI-рефакторинг MaskedField, unit-тесты, миграция stories на modern pattern |
+| 2026-08-11 | Тип `maskedInputProps.ref` исправлен на `React.RefObject<HTMLDivElement>` — соответствует фактическому ref-таргету (правки по ревью PR #515) |
+| 2026-08-12 | Исправления в `FormFieldMaskedInput` по ревью PR #515: убрана мутация prop `value` в `getValue()`, `defaultValue` больше не уходит в `<input>` (предупреждение React о controlled/uncontrolled) и исключён из `IFormFieldMaskedInputProps` |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/MaskedField/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { MaskedField, FormFieldMaskedInput } 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" }}>
+            <MaskedField
+                label="Label"
+                maskedInputProps={{
+                    mask: FormFieldMaskedInput.presets.masks.phone,
+                    value,
+                    onChange: handleChange,
+                }}
+            />
+        </div>
+    );
+};
+```
+
+### Sizes
+
+`stories/MaskedField/examples/Sizes.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { MaskedField, FormFieldMaskedInput, 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>
+            <MaskedField
+                size={size}
+                label="Label"
+                maskedInputProps={{
+                    mask: FormFieldMaskedInput.presets.masks.phone,
+                    value,
+                    onChange: handleChange,
+                }}
+            />
+        </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/MaskedField/examples/Statuses.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { MaskedField, FormFieldMaskedInput, EFormFieldStatus } from "@sberbusiness/triplex-next";
+
+interface IStatusItemProps {
+    status: EFormFieldStatus;
+}
+
+const StatusItem = ({ status }: 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>
+            <MaskedField
+                status={status}
+                label="Label"
+                maskedInputProps={{
+                    mask: FormFieldMaskedInput.presets.masks.phone,
+                    value,
+                    onChange: handleChange,
+                }}
+            />
+        </div>
+    );
+};
+
+const STATUSES = Object.values(EFormFieldStatus);
+
+export const Statuses = () => (
+    <div style={{ maxWidth: "300px", display: "flex", flexDirection: "column", gap: "16px" }}>
+        {STATUSES.map((status) => (
+            <StatusItem key={status} status={status} />
+        ))}
+    </div>
+);
+```
+
+### WithPlaceholderMask
+
+`stories/MaskedField/examples/WithPlaceholderMask.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { MaskedField, FormFieldMaskedInput } from "@sberbusiness/triplex-next";
+
+/**
+ * placeholderMask подсказывает формат ввода: незаполненная часть маски отображается
+ * за введённым значением. Без него незаполненная часть заполняется символом placeholderChar.
+ */
+export const WithPlaceholderMask = () => {
+    const [valueWithMask, setValueWithMask] = useState("12");
+    const [valueWithoutMask, setValueWithoutMask] = useState("12");
+
+    const handleWithMaskChange = (event: React.ChangeEvent<HTMLInputElement>) => setValueWithMask(event.target.value);
+
+    const handleWithoutMaskChange = (event: React.ChangeEvent<HTMLInputElement>) =>
+        setValueWithoutMask(event.target.value);
+
+    return (
+        <div style={{ maxWidth: "300px", display: "flex", flexDirection: "column", gap: "16px" }}>
+            <div>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>С placeholderMask</div>
+                <MaskedField
+                    label="Дата"
+                    maskedInputProps={{
+                        mask: FormFieldMaskedInput.presets.masks.date,
+                        placeholderMask: FormFieldMaskedInput.presets.placeholderMasks.date,
+                        value: valueWithMask,
+                        onChange: handleWithMaskChange,
+                    }}
+                />
+            </div>
+
+            <div>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Без placeholderMask</div>
+                <MaskedField
+                    label="Дата"
+                    maskedInputProps={{
+                        mask: FormFieldMaskedInput.presets.masks.date,
+                        value: valueWithoutMask,
+                        onChange: handleWithoutMaskChange,
+                    }}
+                />
+            </div>
+        </div>
+    );
+};
+```
+
+### PassRefToInput
+
+`stories/MaskedField/examples/PassRefToInput.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import { MaskedField, FormFieldMaskedInput } from "@sberbusiness/triplex-next";
+
+/** Ссылка на элемент input передаётся через maskedInputProps.forwardedRef. */
+export const PassRefToInput = () => {
+    const [value, setValue] = useState("");
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => setValue(event.target.value);
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <MaskedField
+                label="Label"
+                maskedInputProps={{
+                    forwardedRef: inputRef,
+                    mask: FormFieldMaskedInput.presets.masks.phone,
+                    value,
+                    onChange: handleChange,
+                }}
+            />
+        </div>
+    );
+};
+```
+
+### AllMasks
+
+`stories/MaskedField/examples/AllMasks.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { MaskedField, FormFieldMaskedInput, TFormFieldMaskedInputMask } from "@sberbusiness/triplex-next";
+
+const { masks, placeholderMasks } = FormFieldMaskedInput.presets;
+
+interface IMaskItem {
+    /** Ключ пресета, используется как ключ значения в state. */
+    key: string;
+    /** Лейбл поля. */
+    label: string;
+    /** Маска из пресетов FormFieldMaskedInput. */
+    mask: TFormFieldMaskedInputMask;
+    /** Плейсхолдер маски, если он есть в пресетах. */
+    placeholderMask?: string;
+}
+
+const MASK_ITEMS: Array<IMaskItem> = [
+    { key: "account", label: "Номер счёта", mask: masks.account },
+    { key: "bic", label: "БИК", mask: masks.bic },
+    { key: "carNumber", label: "Номер автомобиля", mask: masks.carNumber, placeholderMask: placeholderMasks.carNumber },
+    { key: "cardNumber", label: "Номер карты", mask: masks.cardNumber, placeholderMask: placeholderMasks.cardNumber },
+    { key: "date", label: "Дата", mask: masks.date, placeholderMask: placeholderMasks.date },
+    { key: "driversLicense", label: "Водительское удостоверение", mask: masks.driversLicense },
+    { key: "inn", label: "ИНН", mask: masks.inn, placeholderMask: placeholderMasks.inn },
+    { key: "kbk", label: "КБК", mask: masks.kbk },
+    { key: "kpp", label: "КПП", mask: masks.kpp },
+    { key: "latitude", label: "Широта", mask: masks.latitude },
+    { key: "longitude", label: "Долгота", mask: masks.longitude },
+    { key: "ogrn", label: "ОГРН", mask: masks.ogrn },
+    { key: "oktmo", label: "ОКТМО", mask: masks.oktmo },
+    { key: "passportSeries", label: "Серия паспорта", mask: masks.passport.series },
+    { key: "passportNumber", label: "Номер паспорта", mask: masks.passport.number },
+    { key: "passportDepartmentCode", label: "Код подразделения", mask: masks.passport.departmentCode },
+    { key: "phone", label: "Номер телефона", mask: masks.phone },
+    {
+        key: "phoneExtension",
+        label: "Добавочный номер",
+        mask: masks.phoneExtension,
+        placeholderMask: placeholderMasks.phoneExtension,
+    },
+    { key: "postalCode", label: "Почтовый индекс", mask: masks.postalCode },
+    { key: "snils", label: "СНИЛС", mask: masks.snils },
+    { key: "swiftCode", label: "SWIFT-код", mask: masks.swiftCode, placeholderMask: placeholderMasks.swiftCode },
+    { key: "time", label: "Время", mask: masks.time, placeholderMask: placeholderMasks.time },
+    { key: "uin", label: "УИН", mask: masks.uin, placeholderMask: placeholderMasks.uin },
+    {
+        key: "zhkuAccount",
+        label: "Лицевой счёт ЖКУ",
+        mask: masks.zhkuAccount,
+        placeholderMask: placeholderMasks.zhkuAccount,
+    },
+    { key: "zhkuId", label: "Идентификатор ЖКУ", mask: masks.zhkuId, placeholderMask: placeholderMasks.zhkuId },
+    {
+        key: "zhkuPaymentDocumentId",
+        label: "Платёжный документ ЖКУ",
+        mask: masks.zhkuPaymentDocumentId,
+        placeholderMask: placeholderMasks.zhkuPaymentDocumentId,
+    },
+];
+
+export const AllMasks = () => {
+    const [values, setValues] = useState<Record<string, string>>({});
+
+    const handleChange = (key: string) => (event: React.ChangeEvent<HTMLInputElement>) => {
+        const { value } = event.target;
+
+        setValues((prevValues) => ({ ...prevValues, [key]: value }));
+    };
+
+    return (
+        <div
+            style={{
+                display: "grid",
+                gridTemplateColumns: "repeat(auto-fit, minmax(280px, 1fr))",
+                gap: "24px",
+                maxWidth: "800px",
+            }}
+        >
+            {MASK_ITEMS.map(({ key, label, mask, placeholderMask }) => (
+                <MaskedField
+                    key={key}
+                    label={label}
+                    maskedInputProps={{
+                        mask,
+                        placeholderMask,
+                        value: values[key] || "",
+                        onChange: handleChange(key),
+                    }}
+                />
+            ))}
+        </div>
+    );
+};
+```
+
+### Production
+
+`stories/MaskedField/examples/Production.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    MaskedField,
+    FormFieldMaskedInput,
+    FormFieldClear,
+    HelpBox,
+    Text,
+    Link,
+    ETooltipSize,
+    ETooltipPreferPlace,
+    ETextSize,
+    EFontType,
+} from "@sberbusiness/triplex-next";
+
+export const Production = () => {
+    const [value, setValue] = useState("");
+
+    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => setValue(event.target.value);
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <MaskedField
+                label="Номер телефона"
+                description={
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        (21) Description{" "}
+                        <Link href="#" onClick={(event) => event.preventDefault()}>
+                            Link text
+                        </Link>
+                    </Text>
+                }
+                postfix={
+                    <>
+                        <FormFieldClear onClick={() => setValue("")} />
+                        <HelpBox tooltipSize={ETooltipSize.SM} preferPlace={ETooltipPreferPlace.ABOVE}>
+                            Text
+                        </HelpBox>
+                    </>
+                }
+                maskedInputProps={{
+                    mask: FormFieldMaskedInput.presets.masks.phone,
+                    value,
+                    onChange: handleChange,
+                }}
+            />
+        </div>
+    );
+};
+```
+