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

package/bundle/components/DateField.md

@@ -1,9 +1,7 @@
 ---
 component: DateField
-category: Form
-figma-node: ""
-figma-file: ""
-related: [DatePickerExtended, Calendar, MaskedField, MonthYearField, DateRange, Tooltip, MobileView]
+category: Date components
+related: [DatePickerExtended, MonthYearField, ChipDatePicker, MaskedField, Calendar, Tooltip]
 tokens: []
 stories: stories/DateField/DateField.stories.tsx
 version: "1.0"
@@ -13,359 +11,280 @@ version: "1.0"
 
 ## Назначение
 
-Поле ввода даты с **маской** (`ДД.ММ.ГГГГ`) + выпадающим календарём
-(`DatePickerExtended`). Объединяет текстовый ввод с пикером, валидирует
-дату (`moment`), синхронизирует состояние input ↔ calendar ↔ внешний
-`value`, показывает подсказку-tooltip при невалидном вводе на десктопе.
+Поле ввода и выбора даты. Поле ввода с маской (`MaskedField` + `FormFieldMaskedInput`) и иконкой календаря в постфиксе, по клику раскрывающее выпадающий календарь `DatePickerExtended`. Дату можно как ввести с клавиатуры в формате `дд.мм.гггг`, так и выбрать в календаре.
 
-На мобильных (`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-тесты ввода/валидации.
+Не используй когда: нужен выбор только месяца и года (`MonthYearField`), диапазона дат (`DateRange`), компактный chip-триггер вместо полноценного поля (`ChipDatePicker`), или календарь без поля ввода (`DatePickerExtended` / `Calendar` напрямую).
 
 ---
 
 ## Варианты и props
 
-### `IDateFieldProps`
+`DateField` — обёртка над `DatePickerExtended`, поэтому помимо собственных props принимает все props `DatePickerExtended` (включая props `Calendar`: `limitRange`, `disabledDays`, `markedDays`, `format` и др.), кроме управляемых внутри (`pickedDate`, `onDateChange`, `renderTarget`, `renderDropdownHeaderTarget`), и часть props `MaskedField` (`size`, `status`, `label`). Остальные неперечисленные props пробрасываются в `DatePickerExtended`.
 
-```ts
-extends Omit<IDatePickerExtendedProps,
-    "pickedDate" | "onDateChange" | "renderTarget" | "renderDropdownHeaderTarget">,
-Pick<IMaskedFieldProps, "size" | "status" | "label">
-```
+### Обязательные props
 
-**Основные:**
+| Prop | Тип | Описание |
+|---|---|---|
+| `value` | `string` | Значение даты в формате `format`. Пустая строка — поле очищено. Невалидное значение, дата вне `limitRange` или дата из `disabledDays` отображаются как пустое поле. |
+| `onChange` | `(value: string) => void` | Вызывается при фиксации значения. Аргумент — строка даты в формате `format` либо пустая строка при очистке поля. |
+| `invalidDateHint` | `ReactNode` | Текст тултипа, который показывается, когда в поле введена полная (10 символов), но недоступная для выбора дата. |
 
-| 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;
-}
-```
+### Опциональные props
 
-Контекст существует **только для передачи callback'ов в `DateFieldTarget`**,
-который живёт внутри `DatePickerExtended` (другая ветка дерева). Публично
-не экспортируется.
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `size` | `EComponentSize` | `MD` (в target) | Размер поля: SM / MD / LG. Определяет и размер иконки календаря, и `min-width` поля ввода. |
+| `status` | `EFormFieldStatus` | `default` | Статус поля: default / error / warning / disabled. `disabled` блокирует поле и кнопку календаря. |
+| `label` | `ReactNode` | — | Лейбл поля (проброс в `MaskedField`). |
+| `placeholderMask` | `string` | — | Символы для заполнения пустых редактируемых позиций маски, например `"дд.мм.гггг"`. |
+| `format` | `string` | `dateFormatYYYYMMDD` (`"YYYYMMDD"`) | Формат парсинга/сериализации `value` и аргумента `onChange`. На отображение НЕ влияет — в поле всегда показывается `"DD.MM.YYYY"`. |
+| `limitRange` | `IDateLimitRange` | `globalLimitRange` | Допустимый диапазон дат. Значение вне диапазона трактуется как пустое и не фиксируется через `onChange`. |
+| `disabledDays` | `string[]` | — | Недоступные для выбора дни. **Строки должны быть в формате `format`**, а не в формате отображения. |
+| `onClear` | `MouseEventHandler<HTMLButtonElement>` | — | Если передан — в постфиксе появляется кнопка очистки. Реальную очистку значения выполняет потребитель. |
+| `onDropdownOpen` / `onDropdownClose` | `() => void` | — | Колбэки открытия/закрытия выпадающего календаря. Вызываются после внутренней обработки: при закрытии `onChange` (фиксация введённого значения) может сработать раньше `onDropdownClose`. |
+| `targetProps` | `DeepPartial<IMaskedFieldProps>` | — | Дополнительные props внутреннего `MaskedField` (`postfix`, `description`, `maskedInputProps` и т.д.). Приоритет: верхнеуровневые ключи `targetProps` **переопределяют** заданные компонентом `size` / `status` / `label` / `onClear` (`{...restTargetProps}` разворачивается после них). Значения `maskedInputProps.value`, `mask`, `placeholderMask`, `aria-label`, `aria-labelledby` — тоже лишь **значения по умолчанию**, переданные одноимённые ключи их переопределяют. **Но обработчики не переопределяются, а дополняются:** `onChange`, `onFocus`, `onBlur`, `onKeyDown`, `onMouseDown` из `maskedInputProps` вызываются ПОСЛЕ внутренних, поэтому свой `onBlur` не отключает фиксацию значения. `className` не переопределяется, а мержится через `clsx`. |
+
+### Логика фиксации значения
+
+Ключевая особенность компонента: ввод с клавиатуры **не** вызывает `onChange` на каждое нажатие. Значение фиксируется, когда пользователь заканчивает редактирование:
+
+- **При вводе** обновляется только внутренний стейт (`pickerValues`): строка поля и подсвеченная в календаре дата. Если введены все 10 символов и дата невалидна/недоступна — открывается тултип с `invalidDateHint`.
+- **По blur** поля (при закрытом дропдауне) и **по закрытию дропдауна** (если поле не в фокусе) вызывается `triggerChangeFromInput`:
+  - поле очищено, а `value` не пустое → `onChange("")`;
+  - введена валидная и доступная дата, отличная от текущего `value` → `onChange(date.format(format))`;
+  - иначе поле откатывается к последнему валидному значению (`lastValidPickerValuesRef`).
+- **Выбор даты в календаре** вызывает `onChange` сразу.
+
+Компонент контролируемый: пока потребитель не обновит `value` в ответ на `onChange`, зафиксированное значение в поле не изменится.
 
-### `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).
+Собственных токенов нет — в `styles/DateFieldTarget.module.less` заданы только `min-width` поля по размерам. Внешний вид наследуется от `MaskedField` / `FormField`, `ButtonIcon`, `FormFieldClear`, `Tooltip` и `Calendar` / `DatePickerExtended`.
 
 ---
 
-## Ключевые особенности реализации
+## Инварианты
 
-### Два формата: `format` (внешний) vs `inputDateFormat` (внутренний)
+- `forwardRef` на компоненте — не убирать. Ref пробрасывается в `DatePickerExtended` (корневой DOM-элемент — элемент `DatePickerExtended`); та же ссылка используется внутри как `targetRef` тултипа, поэтому `setRef` должен продолжать писать и в `tooltipTargetRef`.
+- Публичный API (`IDateFieldProps`: `value`, `onChange`, `onClear`, `invalidDateHint`, `placeholderMask`, `targetProps` + унаследованные `size`/`status`/`label` и props `DatePickerExtended`) — изменение имён/типов/значений — breaking change.
+- Отображаемый формат ввода зафиксирован константой `inputDateFormat = "DD.MM.YYYY"` (`constants.ts`) и связан с маской `FormFieldMaskedInput.presets.masks.date`. Менять его нужно синхронно с маской — иначе разъедутся длина ввода (`event.target.value.length === inputDateFormat.length`) и парсинг.
+- `disabledDays` сравниваются со строкой даты в формате `format` (`isDayDisabled` делает `includes`) — не менять формат сравнения без обновления документации потребителя.
+- Sync-эффект в `DateField.tsx` (`useEffect` по `[value, format, limitRange, disabledDays]` с `eslint-disable react-hooks/exhaustive-deps`) — намеренная синхронизация derived-стейта `pickerValues` с внешним `value`. `pickerValues` намеренно не в зависимостях: иначе эффект затирал бы промежуточный ввод пользователя. Сравнение идёт по `inputString`.
+- Внутренние символы `DateFieldUtils` (`utils.ts`), `DateFieldContext`, `DateFieldTarget`, `inputDateFormat` не экспортируются через barrel — это приватные детали реализации. **Исключение — тип `IDateFieldTargetProps`:** он лежит в `types.ts`, а `index.ts` делает `export * from "./types"`, поэтому тип уходит в публичный API пакета. Переименование или изменение его полей — breaking change.
+- **`isOpen={tooltipOpenedRef.current}` читает ref во время рендера** (`DateField.tsx`, ветка `MobileView.fallback`). Это работает только потому, что `handleInputChange` в том же вызове делает `setPickerValues` и тем самым провоцирует ре-рендер. Любая «оптимизация» вида «не вызывать `setPickerValues`, если строка не изменилась» тихо сломает показ `invalidDateHint`, при этом тесты на ввод останутся зелёными. Трогать эту пару (ref + `setPickerValues`) только вместе.
+- **`DateFieldUtils` и `inputDateFormat` переиспользует `ChipDatePicker`** (`src/components/Chip/ChipDatePicker/ChipDatePicker.tsx`), который повторяет ту же логику ввода даты. Переименование или изменение сигнатур этих символов ломает `ChipDatePicker` — правь их только синхронно с ним.
 
-- **Внешний `value`** и `onChange` — в moment-формате, по умолчанию
-  `YYYY-MM-DD`. Настраивается через пропс `format`.
-- **Внутренний ввод (маска)** — всегда `"DD.MM.YYYY"`. Захардкожен
-  в `constants.ts`.
+---
 
-**Почему:** визуальный формат — фирменный российский (дд.мм.гггг), а
-внутренний API — ISO для backend. Конвертация через `moment(date,
-format)` / `date.format(inputDateFormat)`.
+## Accessibility
 
-### Локальное состояние `pickerValues = { inputString, calendarDate }`
+- Триггер — поле ввода с маской. Открытие/закрытие календаря по клику (`mousedown`), по клавише `Enter` и по `Space` (с `preventDefault` для `Space`, чтобы не вводить пробел и не скроллить страницу). Обработчики в `DateFieldTarget`.
+- `aria-label` и `aria-labelledby` пробрасываются потребителем на элемент input через одноимённые props `DateField`. Компонент не хардкодит текст — библиотека мультиязычная.
+- Состояние `disabled` (`status === EFormFieldStatus.DISABLED`) блокирует и поле, и кнопку календаря.
+- Тултип с `invalidDateHint` показывается только в desktop-ветке (`MobileView.fallback`); в мобильном представлении ввод идёт через `DropdownMobileMaskedInput` в заголовке дропдауна.
+- ARIA-роль выпадающего календаря (`dialog`) и навигация по нему — на стороне `DatePickerExtended` / `Calendar`.
+- **Известный пробел:** кнопка-иконка календаря (`ButtonIcon` в `DateFieldTarget`) фокусируема и не имеет `aria-label` — скринридер объявит её без имени. В `MonthYearFieldTarget` аналогичная кнопка выведена из таб-обхода (`role="presentation"`, `tabIndex={-1}`). Приведение к общему поведению требует изменения публичного API (новый prop для локализованного лейбла) и вынесено за рамки AI-рефакторинга.
 
-```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);
-    }
-};
-```
+- `DatePickerExtended` — база выпадающего календаря; `DateField` конфигурирует её через render-props (`renderTarget`, `renderDropdownHeaderTarget`) и наследует её props.
+- `MonthYearField` — альтернатива для выбора только месяца и года; устроен по той же схеме, но поле read-only.
+- `ChipDatePicker` — выбор даты в виде чипа-фильтра, а не поля формы; альтернатива, когда дата задаётся в панели фильтров. Одновременно единственный потребитель, опирающийся на приватные детали `DateField` — импортирует `DateFieldUtils` и `inputDateFormat` (см. «Инварианты»), поэтому правки этих символов проверяй и на нём.
+- `MaskedField` — внутреннее поле-триггер; его props частично входят в публичный API (`size`, `status`, `label`, `targetProps`).
+- `Calendar` — календарь внутри дропдауна; его props (`limitRange`, `disabledDays`, `markedDays`, `format`) входят в публичный API через `DatePickerExtended`.
+- `Tooltip` — показывает `invalidDateHint` при вводе недоступной даты (только desktop-ветка).
+- `DateFieldTarget` (внутренний, не в barrel) — рендерит `MaskedField` с иконкой календаря и кнопкой очистки, обрабатывает клик/клавиатуру/фокус. Описан здесь, отдельного AI.md не имеет. Покрыт `__tests__/DateFieldTarget.test.tsx`.
+- `DateFieldContext` (внутренний, не в barrel) — прокидывает `onChange`, `inputFocusedRef` и `triggerChangeFromInput` в target.
+- `DateFieldUtils` (`utils.ts`, внутренний) — чистые функции парсинга/валидации даты (`getPickerValues`, `getCalendarDate`, `isAvailableDate`). Покрыты `__tests__/utils.test.tsx`.
 
-Триггерится при blur input'а (если dropdown закрыт) и при закрытии
-dropdown'а (если input был расфокусирован и грязный). **Логика "не дать
-пользователю повесить невалидную дату"** — UX-решение.
+---
 
-### Tooltip с `invalidDateHint` через ref
+## Stories
 
-```tsx
-<MobileView
-    fallback={
-        <Tooltip targetRef={tooltipTargetRef} size={SM} isOpen={tooltipOpened.current}>
-            <Tooltip.Body>{invalidDateHint}</Tooltip.Body>
-            <Tooltip.Target>{renderDatePickerExtended()}</Tooltip.Target>
-        </Tooltip>
-    }
->
-    {renderDatePickerExtended()}
-</MobileView>
-```
+Основные истории: `stories/DateField/DateField.stories.tsx`
+Файлы примеров: `stories/DateField/examples/`
 
-Tooltip появляется **только на десктопе** и **только при `tooltipOpened.current === true`**
-(= длина ввода = длина маски, но дата невалидна). На мобильных — нет
-tooltip'а, нет подсказки; валидация через собственный UI потребителя.
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль size / status / label / placeholderMask / invalidDateHint + настройки postfix и description |
+| `Default` | `DefaultExample.tsx` | Минимальное поле с label и маской-плейсхолдером |
+| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG |
+| `Statuses` | `StatusesExample.tsx` | Статусы default / disabled / error / warning |
+| `Production` | `ProductionExample.tsx` | Production-композиция (`Example: production`): postfix `HelpBox`, description со ссылкой, кнопка очистки и возврат фокуса на input |
+| `VisualTests` | `VisualTestsExample.tsx` | Скриншот-регрессия: заполненные поля всех размеров; `play` кликает по последнему полю, раскрывая календарь |
 
-### 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}` ставит курсор
-в поле при открытии.
+| Дата | Изменение |
+|---|---|
+| 2026-09-08 | Создан документ. AI-рефакторинг (JSDoc-фиксы, `displayName` у `DateFieldTarget`), unit-тесты для `utils.ts`, поведения поля (ввод, blur, клавиатура, колбэки дропдауна) и `DateFieldTarget` (фокус, mousedown, клавиатура, проброс обработчиков) |
 
-### `DateFieldTarget` живёт в чужой ветке дерева
+---
 
-`DateFieldTarget` рендерится внутри `DatePickerExtended` (target-prop).
-Он не прямой потомок `DateField`, поэтому **обмен с корнем идёт через
-`DateFieldContext`** (inputFocusedRef, onChange, triggerChangeFromInput).
+## Примеры использования
 
-**Это известная архитектурная особенность**: Target — это HOC над
-MaskedField + calendar icon + clear button + keyboard (`Enter`/`Space`
-открывают dropdown).
+### Default
 
-### `setRef` — double-duty ref
+`stories/DateField/examples/DefaultExample.tsx`
 
-```ts
-const setRef = (instance: HTMLDivElement | null) => {
-    tooltipTargetRef.current = instance;
-    if (typeof ref === "function") ref(instance);
-    else if (ref) ref.current = instance;
+```tsx
+import React, { useState } from "react";
+import { DateField } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => {
+    const [value, setValue] = useState("");
+
+    return (
+        <div style={{ maxWidth: 300 }}>
+            <DateField
+                value={value}
+                label="Label"
+                placeholderMask="дд.мм.гггг"
+                invalidDateHint="Указана недоступная для выбора дата."
+                onChange={setValue}
+            />
+        </div>
+    );
 };
 ```
 
-Один и тот же DOM-элемент используется:
-1. Как target для Tooltip (`tooltipTargetRef`).
-2. Как forwarded ref для потребителя.
+### Sizes
 
-### `dropdownClosedByCalendarRef` — флаг "закрыто по выбору даты"
+`stories/DateField/examples/SizesExample.tsx`
 
-```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: клавиатурная навигация
+```tsx
+import React, { useState } from "react";
+import { DateField, EComponentSize } from "@sberbusiness/triplex-next";
 
-```ts
-if (isKey(event.code, "ENTER")) setDropdownOpen(!dropdownOpen);
-else if (isKey(event.code, "SPACE")) {
-    event.preventDefault();
-    setDropdownOpen(!dropdownOpen);
+interface ISizeItemProps {
+    size: EComponentSize;
 }
-```
-
-**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
-  документацию).
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const [value, setValue] = useState<string>("");
+
+    return (
+        <div style={{ maxWidth: 300 }}>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+            <DateField
+                size={size}
+                value={value}
+                label="Label"
+                placeholderMask="дд.мм.гггг"
+                invalidDateHint="Указана недоступная для выбора дата."
+                onChange={setValue}
+            />
+        </div>
+    );
+};
 
----
+const SIZES = Object.values(EComponentSize);
 
-## Дизайн-токены
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
+```
 
-**Нет собственных.** Все визуальные токены — от `MaskedField` (fonts,
-colors, borders, focus-ring) и `DatePickerExtended` (dropdown, calendar).
+### Statuses
 
----
+`stories/DateField/examples/StatusesExample.tsx`
 
-## Связанные компоненты
+```tsx
+import React, { useState } from "react";
+import { DateField, EFormFieldStatus } from "@sberbusiness/triplex-next";
 
-- `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` — кнопка-иконка календаря.
+interface IStatusItemProps {
+    status: EFormFieldStatus;
+}
 
----
+const StatusItem = ({ status }: IStatusItemProps) => {
+    const [value, setValue] = useState<string>("");
+
+    return (
+        <div style={{ maxWidth: 300 }}>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{status.toUpperCase()}</div>
+            <DateField
+                status={status}
+                value={value}
+                label="Label"
+                placeholderMask="дд.мм.гггг"
+                invalidDateHint="Указана недоступная для выбора дата."
+                onChange={setValue}
+            />
+        </div>
+    );
+};
 
-## Stories
+const STATUSES = Object.values(EFormFieldStatus);
 
-`stories/DateField/DateField.stories.tsx`
-Примеры: `stories/DateField/examples/`
+export const StatusesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {STATUSES.map((status) => (
+            <StatusItem key={status} status={status} />
+        ))}
+    </div>
+);
+```
 
-Типовые stories:
-- `Default` — базовое поле
-- `WithLabel` — с label
-- `Sizes` — SM/MD/LG
-- `Statuses` — default/error/success/disabled
-- `LimitRange` — ограниченный диапазон
-- `DisabledDays` — выборочно отключённые даты
-- `Playground` — интерактив
+### Production
 
----
+`stories/DateField/examples/ProductionExample.tsx`
 
-## История изменений
+```tsx
+import React, { useState, useRef } from "react";
+import { DateField, HelpBox, Text, Link, ETooltipSize, ETextSize, EFontType } from "@sberbusiness/triplex-next";
+
+export const ProductionExample = () => {
+    const [value, setValue] = useState("");
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    const handleLinkClick: React.MouseEventHandler<HTMLAnchorElement> = (event) => {
+        event.preventDefault();
+    };
+
+    const handleClear: React.MouseEventHandler<HTMLButtonElement> = () => {
+        setValue("");
+        inputRef.current?.focus();
+    };
+
+    return (
+        <div style={{ maxWidth: 300 }}>
+            <DateField
+                value={value}
+                label="Label"
+                placeholderMask="дд.мм.гггг"
+                invalidDateHint="Указана недоступная для выбора дата."
+                onChange={setValue}
+                onClear={handleClear}
+                targetProps={{
+                    maskedInputProps: {
+                        forwardedRef: inputRef,
+                    },
+                    postfix: <HelpBox tooltipSize={ETooltipSize.SM}>Helpful details appear here</HelpBox>,
+                    description: (
+                        <Text size={ETextSize.B4} type={EFontType.SECONDARY}>
+                            (21) Description{" "}
+                            <Link href="#" onClick={handleLinkClick}>
+                                Link text
+                            </Link>
+                        </Text>
+                    ),
+                }}
+            />
+        </div>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |

package/bundle/components/DatePickerExtended.md

@@ -1,7 +1,7 @@
 ---
 component: DatePickerExtended
 category: Date components
-related: [Calendar, Dropdown, DateField, MonthYearField, ChipDatePicker]
+related: [Calendar, Dropdown, DateField, MonthYearField, ChipDatePicker, ChipMonthYearPicker]
 tokens: []
 stories: stories/DatePickerExtended/DatePickerExtended.stories.tsx
 version: "1.0"
@@ -97,6 +97,7 @@ version: "1.0"
 - `DateField` — поле ввода даты; передаёт `dropdownTargetRef` и открывает календарь из `DateFieldTarget` через контекст.
 - `MonthYearField` — выбор месяца и года; конфигурирует `pickType={ECalendarPickType.MONTH_YEAR}`.
 - `ChipDatePicker` — чип-фильтр с календарём; открывает дропдаун из `ChipDatePickerTarget` через контекст.
+- `ChipMonthYearPicker` — чип-фильтр с выбором месяца (`pickType` фиксирован в `MONTH_YEAR`); открывает дропдаун из `ChipMonthYearPickerTarget` через контекст.
 - `DatePickerExtendedContext` — контекст открытости дропдауна для целевого элемента. Экспортируется из barrel вместе с типом `IDatePickerExtendedContext`, отдельного AI.md не имеет.
 
 Внутренние части (в barrel не экспортируются, отдельного AI.md не имеют):
@@ -130,6 +131,7 @@ version: "1.0"
 
 | Дата | Изменение |
 |---|---|
+| 2026-09-07 | В потребители базы добавлен `ChipMonthYearPicker` (чип-фильтр с `pickType` `MONTH_YEAR`) |
 | 2026-08-24 | `DatePickerExtendedContext` и `IDatePickerExtendedContext` экспортируются из barrel — целевой элемент можно написать снаружи библиотеки. `adaptiveMode` исключён из `IDatePickerExtendedProps` (ломающее изменение, затрагивает также `DateField`, `MonthYearField`, `ChipDatePicker`) |
 | 2026-08-20 | Создан документ. AI-рефакторинг, unit-тесты (`__tests__/DatePickerExtended.test.tsx`), stories по modern pattern. Исправлено: `yesterdayButtonProps` / `tomorrowButtonProps` пробрасываются в `Calendar`, `adaptiveMode` больше не попадает в DOM |