@sberbusiness/triplex-next-mcp-server 0.24.0-beta1

package/bundle/components/DateField.md

@@ -0,0 +1,371 @@
+---
+component: DateField
+category: Form
+figma-node: ""
+figma-file: ""
+related: [DatePickerExtended, Calendar, MaskedField, MonthYearField, DateRange, Tooltip, MobileView]
+tokens: []
+stories: stories/DateField/DateField.stories.tsx
+version: "1.0"
+---
+
+# DateField
+
+## Назначение
+
+Поле ввода даты с **маской** (`ДД.ММ.ГГГГ`) + выпадающим календарём
+(`DatePickerExtended`). Объединяет текстовый ввод с пикером, валидирует
+дату (`moment`), синхронизирует состояние input ↔ calendar ↔ внешний
+`value`, показывает подсказку-tooltip при невалидном вводе на десктопе.
+
+На мобильных (`MobileView`) ведёт себя как `Dropdown` с масочным input'ом
+в заголовке (`DropdownMobileMaskedInput`), без tooltip'а.
+
+`DateField` — **controlled-only**. `value: string` в формате `format`
+(default `YYYY-MM-DD`), `onChange(value: string)` — реакция на изменение.
+
+Используй когда: нужно однократное поле даты в форме с возможностью
+ввести руками **или** выбрать в календаре.
+Не используй когда: нужен диапазон дат — бери `DateRange`; нужен выбор
+только месяца/года — `MonthYearField`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/DateField/
+├── DateField.tsx                        # forwardRef<HTMLDivElement>, root FC
+├── DateFieldTarget.tsx                  # FC, target для DatePickerExtended (MaskedField + иконка календаря + clear)
+├── DateFieldContext.ts                  # React.Context с inputFocusedRef, onChange, triggerChangeFromInput
+├── types.ts                             # IDateFieldProps
+├── utils.ts                             # DateFieldUtils (getPickerValues, getCalendarDate, isAvailableDate)
+├── constants.ts                         # inputDateFormat = "DD.MM.YYYY"
+├── index.ts                             # Barrel
+└── __tests__/DateField.test.tsx
+```
+
+Особенности:
+- **`displayName = "DatePicker"`** (не `"DateField"`) — известная
+  особенность, исторически. Не переименовывать без согласования — может
+  сломать snapshot-тесты потребителей.
+- **Нет собственных стилей** — вся визуалка от `DatePickerExtended` +
+  `MaskedField`.
+- **Нет собственных токенов** — наследуется от формы и календаря.
+- Есть `__tests__/DateField.test.tsx` — unit-тесты ввода/валидации.
+
+---
+
+## Варианты и props
+
+### `IDateFieldProps`
+
+```ts
+extends Omit<IDatePickerExtendedProps,
+    "pickedDate" | "onDateChange" | "renderTarget" | "renderDropdownHeaderTarget">,
+Pick<IMaskedFieldProps, "size" | "status" | "label">
+```
+
+**Основные:**
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `value` | `string` | — | **Controlled** — дата в формате `format`. Пустая строка = нет даты. |
+| `onChange` | `(value: string) => void` | — | Вызывается при валидном вводе/выборе. `value` может быть пустой строкой (очистка). |
+| `format` | `string` | `dateFormatYYYYMMDD` (`"YYYY-MM-DD"`) | moment-формат для `value`. **Не путать с `inputDateFormat` = `"DD.MM.YYYY"`** (формат отображения в маске). |
+| `limitRange` | `IDateLimitRange` | `globalLimitRange` | `{ dateFrom, dateTo }` — допустимый диапазон. |
+| `disabledDays` | `string[]` | — | Массив дат в формате `format`, которые нельзя выбрать. |
+| `placeholderMask` | `string` | — | Плейсхолдер-символы для пустых позиций в маске (обычно `"дд.мм.гггг"`). |
+| `invalidDateHint` | `ReactNode` | — | Текст в тултипе при невалидной введённой дате. |
+| `size` | `EComponentSize` | `MD` | Размер MaskedField (SM/MD/LG). |
+| `status` | `EFormFieldStatus` | — | Валидация + disabled. |
+| `label` | `ReactNode` | — | Label над полем. |
+| `aria-label` / `aria-labelledby` | `string` | — | Прокидываются в MaskedInput. |
+| `targetProps` | `DeepPartial<IMaskedFieldProps>` | — | Глубокий частичный override для MaskedField. Позволяет точечно перебить. |
+| `onDropdownOpen` | `() => void` | — | Coincidence callback при открытии календаря. |
+| `onDropdownClose` | `() => void` | — | Callback при закрытии (запускает trigger, если input дирти). |
+| `...IDatePickerExtendedProps` | — | — | Остальные пропсы пикера (минус 4 omitted). |
+
+### `DateFieldContext` — внутренний
+
+```ts
+interface IDateFieldContext {
+    inputFocusedRef: MutableRefObject<boolean | null>;
+    onChange: (value: string) => void;
+    triggerChangeFromInput: () => void;
+}
+```
+
+Контекст существует **только для передачи callback'ов в `DateFieldTarget`**,
+который живёт внутри `DatePickerExtended` (другая ветка дерева). Публично
+не экспортируется.
+
+### `DateFieldUtils`
+
+```ts
+{
+    getPickerValues(value, format, limitRange, disabledDays): { inputString, calendarDate }
+    getCalendarDate(value, format, limitRange, disabledDays): Moment | null
+    isAvailableDate(date, value, limitRange, disabledDays): boolean
+}
+```
+
+Конвертирует внешний `value` (в `format`) → внутреннее состояние
+(`inputString` в `inputDateFormat` + `calendarDate` Moment|null).
+
+---
+
+## Ключевые особенности реализации
+
+### Два формата: `format` (внешний) vs `inputDateFormat` (внутренний)
+
+- **Внешний `value`** и `onChange` — в moment-формате, по умолчанию
+  `YYYY-MM-DD`. Настраивается через пропс `format`.
+- **Внутренний ввод (маска)** — всегда `"DD.MM.YYYY"`. Захардкожен
+  в `constants.ts`.
+
+**Почему:** визуальный формат — фирменный российский (дд.мм.гггг), а
+внутренний API — ISO для backend. Конвертация через `moment(date,
+format)` / `date.format(inputDateFormat)`.
+
+### Локальное состояние `pickerValues = { inputString, calendarDate }`
+
+```ts
+const [pickerValues, setPickerValues] = useState(
+    DateFieldUtils.getPickerValues(value, format, limitRange, disabledDays),
+);
+```
+
+Хранит **и** строку для input'а, **и** moment-дату для календаря.
+Синхронизируется с внешним `value` через `useEffect`:
+
+```ts
+useEffect(() => {
+    const newPickerValues = DateFieldUtils.getPickerValues(...);
+    if (newPickerValues.inputString !== pickerValues.inputString) {
+        setPickerValues(newPickerValues);
+    }
+    lastValidPickerValuesRef.current = newPickerValues;
+}, [value, format, limitRange, disabledDays]);
+```
+
+**Важно:** сравнение по `inputString`, не по `value`. Причина — если
+пользователь частично отредактировал строку (`"12.05."`, невалидно),
+внешний value не менялся, новый эффект пришёл бы с тем же value, и
+мы **не должны** сбрасывать ввод пользователя. `lastValidPickerValuesRef`
+хранит последнее валидное состояние для отката.
+
+### Откат при невалидном вводе
+
+```ts
+const triggerChangeFromInput = () => {
+    if (pickerValues.inputString.length === 0 && value.length !== 0) {
+        return onChange(pickerValues.inputString); // очистка
+    }
+    const date = moment(pickerValues.inputString, inputDateFormat, true);
+    if (date.isValid()) {
+        const newValue = date.format(format);
+        if (newValue === value) return;
+        if (DateFieldUtils.isAvailableDate(...)) {
+            return onChange(newValue);
+        }
+    }
+    // Откат к последнему валидному
+    if (pickerValues.inputString !== lastValidPickerValuesRef.current.inputString) {
+        tooltipOpened.current = false;
+        setPickerValues(lastValidPickerValuesRef.current);
+    }
+};
+```
+
+Триггерится при blur input'а (если dropdown закрыт) и при закрытии
+dropdown'а (если input был расфокусирован и грязный). **Логика "не дать
+пользователю повесить невалидную дату"** — UX-решение.
+
+### Tooltip с `invalidDateHint` через ref
+
+```tsx
+<MobileView
+    fallback={
+        <Tooltip targetRef={tooltipTargetRef} size={SM} isOpen={tooltipOpened.current}>
+            <Tooltip.Body>{invalidDateHint}</Tooltip.Body>
+            <Tooltip.Target>{renderDatePickerExtended()}</Tooltip.Target>
+        </Tooltip>
+    }
+>
+    {renderDatePickerExtended()}
+</MobileView>
+```
+
+Tooltip появляется **только на десктопе** и **только при `tooltipOpened.current === true`**
+(= длина ввода = длина маски, но дата невалидна). На мобильных — нет
+tooltip'а, нет подсказки; валидация через собственный UI потребителя.
+
+### Mobile-ветка: `DropdownMobileMaskedInput`
+
+```tsx
+const renderDropdownHeaderTarget = () => (
+    <DropdownMobileMaskedInput
+        value={pickerValues.inputString}
+        mask={DropdownMobileMaskedInput.presets.masks.date}
+        placeholderMask={placeholderMask}
+        onChange={handleInputChange}
+        autoFocus={true}
+    />
+);
+```
+
+На мобильных `DatePickerExtended` открывается как Dropdown с **инпутом
+в заголовке** (не отдельным target'ом). `autoFocus={true}` ставит курсор
+в поле при открытии.
+
+### `DateFieldTarget` живёт в чужой ветке дерева
+
+`DateFieldTarget` рендерится внутри `DatePickerExtended` (target-prop).
+Он не прямой потомок `DateField`, поэтому **обмен с корнем идёт через
+`DateFieldContext`** (inputFocusedRef, onChange, triggerChangeFromInput).
+
+**Это известная архитектурная особенность**: Target — это HOC над
+MaskedField + calendar icon + clear button + keyboard (`Enter`/`Space`
+открывают dropdown).
+
+### `setRef` — double-duty ref
+
+```ts
+const setRef = (instance: HTMLDivElement | null) => {
+    tooltipTargetRef.current = instance;
+    if (typeof ref === "function") ref(instance);
+    else if (ref) ref.current = instance;
+};
+```
+
+Один и тот же DOM-элемент используется:
+1. Как target для Tooltip (`tooltipTargetRef`).
+2. Как forwarded ref для потребителя.
+
+### `dropdownClosedByCalendarRef` — флаг "закрыто по выбору даты"
+
+```ts
+const dropdownClosedByCalendarRef = useRef(false);
+// ...
+const handleDateChange = (date: moment.Moment) => {
+    dropdownClosedByCalendarRef.current = true;
+    // ...
+};
+const handleDropdownClose = () => {
+    if (dropdownClosedByCalendarRef.current) {
+        dropdownClosedByCalendarRef.current = false; // reset
+    } else if (!inputFocusedRef.current && dirty) {
+        triggerChangeFromInput(); // откат/commit
+    }
+};
+```
+
+**Защита от двойной обработки**: если dropdown закрылся потому что
+пользователь выбрал дату в календаре, не дергать `triggerChangeFromInput`
+— значение уже применено через `onChange` в `handleDateChange`.
+
+### DateFieldTarget: клавиатурная навигация
+
+```ts
+if (isKey(event.code, "ENTER")) setDropdownOpen(!dropdownOpen);
+else if (isKey(event.code, "SPACE")) {
+    event.preventDefault();
+    setDropdownOpen(!dropdownOpen);
+}
+```
+
+**Enter / Space** открывают/закрывают dropdown. `preventDefault` на
+Space нужен, чтобы не ввести пробел в input (маска бы его съела,
+но всё равно нежелательно).
+
+---
+
+## Инварианты
+
+- **`forwardRef`** на root — обязателен (HTMLDivElement).
+- **`displayName = "DatePicker"`** — исторический, не менять.
+- **`value` — controlled only** — нет uncontrolled-ветки. Пустая строка
+  = нет даты.
+- **`format` ≠ `inputDateFormat`** — не смешивать. Внешний формат =
+  `format`, внутренний (маска) = всегда `"DD.MM.YYYY"`.
+- **`lastValidPickerValuesRef` и откат** — если удалить, пользователь
+  сможет оставить невалидную дату в поле.
+- **`dropdownClosedByCalendarRef`** флаг — защита от двойного
+  `triggerChangeFromInput`. Не удалять.
+- **`DateFieldContext`** — только внутренний, не экспортировать публично.
+- **Tooltip только на десктопе** — мобильный fallback без tooltip'а
+  (MobileView отсекает). Не переносить tooltip в мобильную ветку без
+  дизайн-согласования.
+- **`Enter`/`Space` в input** — открывают dropdown. Не добавлять другие
+  keys без согласования с DatePickerExtended.
+- **Иконка календаря меняется по size** (CalendarStrokeSrvIcon16 для SM,
+  CalendarStrokeSrvIcon20 для MD/LG) — map в `sizeToCalendarIconMap`.
+
+---
+
+## Accessibility
+
+- **`aria-label` / `aria-labelledby`** передаются в MaskedInput. Если
+  есть `label` — он уже создаёт `<label>`-связь; label-only обычно
+  достаточно.
+- **Клавиатура:**
+  - Tab — фокус на input, следующий Tab — на иконку календаря (ButtonIcon).
+  - Enter/Space на input — открыть dropdown.
+  - Дальнейшая навигация по календарю — см. `DatePickerExtended`/`Calendar`.
+- **Tooltip `invalidDateHint`** — не имеет ARIA-связи с input (не
+  `aria-describedby`). Если нужна screen-reader подсказка — передавать
+  через `status` + `hint` на `MaskedField` (их стандартный механизм).
+- **FormFieldClear** кнопка — имеет `aria-label` внутри (см. FormField
+  документацию).
+
+---
+
+## Дизайн-токены
+
+**Нет собственных.** Все визуальные токены — от `MaskedField` (fonts,
+colors, borders, focus-ring) и `DatePickerExtended` (dropdown, calendar).
+
+---
+
+## Связанные компоненты
+
+- `DatePickerExtended` (`src/components/DatePickerExtended`) — сам
+  пикер-обёртка вокруг Dropdown + Calendar. DateField его настраивает.
+- `Calendar` (`src/components/Calendar`) — low-level выбор даты, живёт
+  внутри DatePickerExtended.
+- `MaskedField` (`src/components/TextField`) — input с маской. Основа
+  `DateFieldTarget`.
+- `MonthYearField` (`src/components/MonthYearField`) — близнец для
+  выбора месяца/года.
+- `DateRange` (`src/components/DateRange`) — выбор диапазона дат.
+- `Tooltip` (`src/components/Tooltip`) — подсказка `invalidDateHint`
+  на десктопе.
+- `MobileView` (`src/components/MobileView`) — разветвление mobile/desktop.
+- `DropdownMobileMaskedInput` — мобильный input в заголовке Dropdown'а.
+- `FormFieldClear` — кнопка-крестик очистки поля.
+- `ButtonIcon` — кнопка-иконка календаря.
+
+---
+
+## Stories
+
+`stories/DateField/DateField.stories.tsx`
+Примеры: `stories/DateField/examples/`
+
+Типовые stories:
+- `Default` — базовое поле
+- `WithLabel` — с label
+- `Sizes` — SM/MD/LG
+- `Statuses` — default/error/success/disabled
+- `LimitRange` — ограниченный диапазон
+- `DisabledDays` — выборочно отключённые даты
+- `Playground` — интерактив
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |