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

package/bundle/components/MonthYearField.md

@@ -1,9 +1,7 @@
 ---
 component: MonthYearField
-category: Form Controls
-figma-node: ""
-figma-file: ""
-related: [DatePickerExtended, Calendar, TextField, DropdownMobileInput, FormField]
+category: Date components
+related: [DatePickerExtended, MonthYearRange, TextField, Calendar]
 tokens: []
 stories: stories/MonthYearField/MonthYearField.stories.tsx
 version: "1.0"
@@ -13,156 +11,194 @@ version: "1.0"
 
 ## Назначение
 
-Поле для выбора **месяца и года** (без числа дня). Built on top of
-`DatePickerExtended` c `pickType=monthYearPick`. Превращает строковое
-значение ISO-даты (YYYY-MM-DD) в отображение "Mar 2026" в `TextField`,
-показывает календарь по клику / Enter / Space, реализует clear-кнопку.
+Поле для выбора месяца и года. Read-only текстовое поле (`TextField`) с иконкой календаря в постфиксе, по клику раскрывающее выпадающий календарь `DatePickerExtended` в режиме выбора месяца (`ECalendarPickType.MONTH_YEAR`). Выбранная дата форматируется и отображается в поле.
 
-Используй когда: нужен month-picker (отчётные периоды, выбор срока).
-Для полноценной даты — `DateField`. Для диапазона — `DateRange`/аналог.
+Используй когда: нужно выбрать только месяц и год (без дня), а ввод с клавиатуры не требуется — значение задаётся через календарь.
 
----
-
-## Файловая структура
-
-```text
-src/components/MonthYearField/
-├── MonthYearField.tsx          # forwardRef, обёртка над DatePickerExtended
-├── MonthYearFieldTarget.tsx    # TextField с клик/keyboard → открытие dropdown
-├── MonthYearFieldContext.tsx   # { onChange } — для clear в Target
-├── constants.ts                # inputMonthYearFormat = "MMM YYYY"
-├── types.ts                    # IMonthYearFieldProps
-├── utils.ts                    # MonthYearPickerUtils: parse/validate даты
-├── index.ts                    # Barrel
-└── __tests__/
-```
+Не используй когда: нужен полноценный ввод даты с клавиатуры (`DateField`), выбор диапазона месяцев (`MonthYearRange`) или произвольной даты с днём (`DatePickerExtended` напрямую).
 
 ---
 
 ## Варианты и props
 
-### `IMonthYearFieldProps extends Omit<IDatePickerExtendedProps, "pickedDate" | "onDateChange" | "renderTarget" | "renderDropdownHeaderTarget">, Pick<ITextFieldProps, "size" | "status" | "label">`
+`MonthYearField` — обёртка над `DatePickerExtended`, поэтому помимо собственных props принимает все props `DatePickerExtended`, кроме управляемых внутри (`pickedDate`, `onDateChange`, `renderTarget`, `renderDropdownHeaderTarget`), и часть props `TextField` (`size`, `status`, `label`). Остальные неперечисленные props пробрасываются в `DatePickerExtended`.
 
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `value` | `string` | — (обязателен) | ISO-дата (формата `format`), например `"2026-04-01"`. |
-| `onChange` | `(value: string) => void` | — (обязателен) | Вызывается при выборе нового месяца. Передаётся дата в `format`. |
-| `format` | `string` | `dateFormatYYYYMMDD` (`"YYYY-MM-DD"`) | moment-формат для `value`. |
-| `limitRange` | `IDateLimitRange` | `globalLimitRange` | Границы доступных дат. |
-| `placeholder` | `string` | — | Плейсхолдер input'а. |
-| `size` | `EComponentSize` | — | Пробрасывается в TextField. |
-| `status` | `EFormFieldStatus` | — | Пробрасывается в TextField (`DISABLED` → readOnly). |
-| `label` | `ReactNode` | — | Label TextField'а. |
-| `targetProps` | `ITextFieldProps` | — | Дополнительные props TextField. `inputProps` мержатся с внутренними. |
-| `...DatePickerExtended-props` | — | — | Все остальные, кроме исключённых. |
+### Обязательные props
 
-**Исключены из `IDatePickerExtendedProps`**: `pickedDate`, `onDateChange`, `renderTarget`, `renderDropdownHeaderTarget` — они управляются внутренне.
+| Prop | Тип | Описание |
+|---|---|---|
+| `value` | `string` | Значение даты в формате `format`. Пустая строка — поле очищено. Невалидное значение или дата вне `limitRange` отображаются как пустое поле. |
+| `onChange` | `(value: string) => void` | Вызывается при выборе даты в календаре. Аргумент — строка даты в формате `format`. |
 
-### Внутренние формирующие константы
+### Опциональные props
 
-- `inputMonthYearFormat = "MMM YYYY"` — как показывается в TextField (moment-format).
-- `ECalendarPickType.monthYearPick` — `pickType` DatePickerExtended.
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `size` | `EComponentSize` | `MD` (в target) | Размер поля: SM / MD / LG. Определяет и размер иконки календаря. |
+| `status` | `EFormFieldStatus` | `default` | Статус поля: default / error / warning / disabled. `disabled` блокирует поле и кнопку календаря. |
+| `label` | `ReactNode` | — | Лейбл поля (проброс в `TextField`). |
+| `placeholder` | `string` | — | Текст подсказки, когда значение пустое. |
+| `format` | `string` | `dateFormatYYYYMMDD` (`"YYYYMMDD"`) | Формат парсинга/сериализации `value`. На отображение НЕ влияет — в поле всегда показывается формат `"MMM YYYY"`. |
+| `limitRange` | `IDateLimitRange` | `globalLimitRange` | Допустимый диапазон дат. Значение вне диапазона трактуется как пустое. |
+| `onClear` | `MouseEventHandler<HTMLButtonElement>` | — | Если передан — в постфиксе появляется кнопка очистки. Реальную очистку значения выполняет потребитель. |
+| `targetProps` | `ITextFieldProps` | — | Дополнительные props для внутреннего `TextField` (postfix, description, inputProps и т.д.). `inputProps.value`, `placeholder`, `readOnly` устанавливаются компонентом, но могут быть переопределены через `targetProps.inputProps`. |
 
----
+### Особенности отображения
 
-## Ключевые особенности реализации
+- Отображаемая строка в поле формируется по фиксированному формату `inputMonthYearFormat = "MMM YYYY"` (`constants.ts`), независимо от `format`. `format` управляет только парсингом `value` и аргументом `onChange`.
+- Поле всегда `readOnly` — ввод значения возможен только выбором в календаре.
 
-### Внутренний state `pickerValues`
+---
 
-```ts
-const [pickerValues, setPickerValues] = useState(
-    MonthYearPickerUtils.getPickerValues(value, format, limitRange)
-);
-```
+## Дизайн-токены
 
-- `pickerValues = { inputString: "Mar 2026", calendarDate: moment }` — два представления одной даты.
-- Синхронизируется с `value` через `useEffect(() => { if (newInputString !== current) setPickerValues(...) })` — обновление только при реальном изменении строки.
+Собственных CSS-токенов нет. Внешний вид наследуется от `TextField`, `ButtonIcon`, `FormFieldClear` и `Calendar`/`DatePickerExtended`.
 
-### `MonthYearPickerUtils.getPickerValues`
+---
 
-```ts
-if (value.length === 0) return { calendarDate: null, inputString: "" };
-const date = moment(value, format, true); // strict
-if (!valid || outsideRange) return { calendarDate: null, inputString: "" };
-return { calendarDate: date, inputString: date.format(inputMonthYearFormat) };
-```
+## Инварианты
 
-- **Strict-парсинг** (третий аргумент `true`) — формат должен совпадать один-в-один.
-- Выход за `limitRange` → `null` calendar date + пустая строка в input'е. **Невалидное значение воспринимается как отсутствующее** — потребитель не получит обратный callback.
+- `forwardRef` на компоненте — не убирать. Ref пробрасывается в `DatePickerExtended` (корневой DOM-элемент — элемент `DatePickerExtended`).
+- Публичный API (`IMonthYearFieldProps`: `value`, `onChange`, `onClear`, `targetProps`, `placeholder` + унаследованные `size`/`status`/`label` и props `DatePickerExtended`) — изменение имён/типов/значений — breaking change.
+- Поле read-only по контракту — не делать его редактируемым без обсуждения (компонент не имеет логики валидации клавиатурного ввода).
+- Отображаемый формат `"MMM YYYY"` зафиксирован в `inputMonthYearFormat`; менять его — визуальный breaking change для потребителей.
+- Sync-эффект в `MonthYearField.tsx` (`useEffect` по `[value, format, limitRange]` с `eslint-disable react-hooks/exhaustive-deps`) — намеренная синхронизация derived-стейта `pickerValues` с внешним `value`. Не переписывать без анализа поведения: сравнение идёт по `inputString`, чтобы не сбрасывать стейт при эквивалентных значениях.
+- Внутренние символы `MonthYearPickerUtils` (`utils.ts`), `MonthYearFieldContext`, `MonthYearFieldTarget` не экспортируются через barrel — это приватные детали реализации.
 
-### `MonthYearFieldContext` — только для `onChange`
+---
 
-Нужен, чтобы `FormFieldClear` (внутри Target'а) мог вызвать `onChange("")` без prop-drilling через `renderTarget`.
+## Accessibility
 
-### `MonthYearFieldTarget` — Enter/Space → открыть dropdown
+- Триггер — текстовое поле `TextField` с `readOnly`. Открытие/закрытие календаря по клику и по клавишам `Enter` / `Space` (с `preventDefault` для `Space`, чтобы не скроллить страницу). Обработчики в `MonthYearFieldTarget`.
+- Кнопка иконки календаря — `ButtonIcon` с `role="presentation"` и `tabIndex={-1}`: она не попадает в таб-обход (фокус остаётся на поле), клик дублирует открытие календаря.
+- Состояние `disabled` (`status === EFormFieldStatus.DISABLED`) блокирует и поле, и кнопку календаря.
+- ARIA-роль выпадающего календаря (`dialog`) и навигация по нему — на стороне `DatePickerExtended` / `Calendar`.
 
-```ts
-handleInputKeyDown: isKey(event.code, "ENTER") → toggleDropdown;
-                    isKey(event.code, "SPACE") → preventDefault + toggleDropdown;
-```
+---
+
+## Связанные компоненты
 
-- Клик по input'у — тоже toggleDropdown.
-- Input всегда `readOnly` (выбор только через календарь).
-- В postfix'е — `FormFieldClear` + `ButtonIcon` с иконкой календаря. Иконка меняется по `size`: `CalendarStrokeSrvIcon16` (SM) / `CalendarStrokeSrvIcon20` (MD/LG).
+- `DatePickerExtended` — родительский компонент выпадающего календаря; `MonthYearField` конфигурирует его в режим `MONTH_YEAR` через render-props.
+- `MonthYearRange` — выбор диапазона месяцев; использует `MonthYearField` как поля «от» и «до».
+- `TextField` — внутреннее поле-триггер.
+- `MonthYearFieldTarget` (внутренний, не в barrel) — рендерит `TextField` с иконкой календаря и кнопкой очистки, обрабатывает клик/клавиатуру для открытия дропдауна. Описан здесь, отдельного AI.md не имеет.
+- `MonthYearFieldContext` (внутренний, не в barrel) — прокидывает `onChange` в target; тривиальный контекст без своей логики.
+- `MonthYearPickerUtils` (`utils.ts`, внутренний) — чистые функции парсинга/валидации даты (`getPickerValues`, `getCalendarDate`, `isAvailableDate`). Покрыты `__tests__/utils.test.tsx`.
 
-### Fallback на `dateFormatYYYYMMDD` и `globalLimitRange`
+---
 
-Если потребитель не передал `format`/`limitRange`, используются глобальные из `consts/DateConst`. Ожидается, что сам проект задаёт эти константы.
+## Stories
 
-### `DropdownMobileInput` как header-target для мобильного dropdown'а
+Основные истории: `stories/MonthYearField/MonthYearField.stories.tsx`
+Файлы примеров: `stories/MonthYearField/examples/`
 
-На mobile (в `DatePickerExtended`) вместо TextField'а рендерится упрощённый input.
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль size / status / label / placeholder + настройки postfix и description |
+| `Default` | `DefaultExample.tsx` | Минимальное поле с label и placeholder |
+| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG |
+| `Statuses` | `StatusesExample.tsx` | Статусы default / disabled / error / warning |
+| `Production` (`Example: production`) | `ProductionExample.tsx` | Production-композиция: postfix `HelpBox`, description со ссылкой, кнопка очистки и фокус на input |
+| `VisualTests` | `VisualTestsExample.tsx` | Скриншот-регрессия: все размеры (пустые/заполненные), статусы, поле с очисткой и постфиксом |
+| `VisualTestsOpen` | `VisualTestsOpenExample.tsx` | Скриншот-регрессия раскрытого состояния: dropdown с календарём открывается через `play` |
 
 ---
 
-## Инварианты
+## История изменений
 
-- **`value: string` в `format`** — контракт. Не переключать на `Date`/`moment.Moment` без миграции.
-- **Strict moment-parsing** — пустая/невалидная строка → `""` в UI. Потребитель должен синхронизировать невалидные значения сам.
-- **`limitRange` — hard-clamp**: дата вне диапазона → пустое значение.
-- **`MonthYearFieldContext` shape** (`{ onChange }`) — публичная точка расширения, не менять.
-- **`inputMonthYearFormat = "MMM YYYY"`** — display-формат, не i18n-аизрован (moment уже локализован через global moment.locale, но формат-строка фиксирована).
-- **`pickType=monthYearPick`** — контракт с DatePickerExtended. Изменение — breaking.
-- **`targetProps.inputProps` мержатся** с внутренним `{ value, placeholder, readOnly }` — потребитель может переопределить.
-- **ForwardRef<HTMLDivElement>** на корневую node DatePickerExtended.
+| Дата | Изменение |
+|---|---|
+| 2026-06-16 | Создан документ. AI-рефакторинг (JSDoc-фиксы), unit-тесты для `utils.ts`, story `VisualTests` и включение скриншот-тестов |
+| 2026-06-16 | Добавлена story `VisualTestsOpen` — скриншот раскрытого dropdown с календарём (через `play`) |
 
 ---
 
-## Accessibility
+## Примеры использования
 
-- Input `readOnly` — фокусируется, но не редактируется. Открытие: Enter / Space / click.
-- **`<button>` с иконкой** (ButtonIcon) — `role="presentation"` и `tabIndex={-1}` — **не в tab-последовательности** (основной target — input). Дизайн-решение, чтобы не дублировать Tab-остановки.
-- `FormFieldClear` — стандартная кнопка очистки (см. FormField-AI).
-- Нет `aria-label` на иконке календаря — потребитель должен добавить через `targetProps` при необходимости.
+### Default
 
----
+`stories/MonthYearField/examples/DefaultExample.tsx`
 
-## Дизайн-токены
+```tsx
+import React, { useState } from "react";
+import { MonthYearField } from "@sberbusiness/triplex-next";
 
-Нет собственных — наследуются от `TextField` и `Calendar`.
+export const DefaultExample = () => {
+    const [value, setValue] = useState("");
 
----
+    return (
+        <div style={{ maxWidth: 300 }}>
+            <MonthYearField value={value} placeholder="мм.гггг" label="Label" onChange={setValue} />
+        </div>
+    );
+};
+```
 
-## Связанные компоненты
+### Sizes
 
-- `DatePickerExtended` — основа логики (dropdown, popup, mobile-variant).
-- `Calendar` — сам календарь (`pickType=monthYearPick` — режим месяца).
-- `TextField` — визуальный target.
-- `FormField.Clear` — кнопка очистки.
-- `ButtonIcon` — кнопка календаря в postfix.
-- `moment.js` — парсинг/форматирование (peerDependency в библиотеке).
+`stories/MonthYearField/examples/SizesExample.tsx`
 
----
+```tsx
+import React, { useState } from "react";
+import { MonthYearField, EComponentSize } from "@sberbusiness/triplex-next";
 
-## Stories
+interface ISizeItemProps {
+    size: EComponentSize;
+}
 
-`stories/MonthYearField/MonthYearField.stories.tsx`
-Примеры: `stories/MonthYearField/examples/`
+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>
+            <MonthYearField size={size} value={value} label="Label" placeholder="мм.гггг" 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>
+);
+```
+
+### Statuses
+
+`stories/MonthYearField/examples/StatusesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { MonthYearField, EFormFieldStatus } from "@sberbusiness/triplex-next";
+
+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>
+            <MonthYearField status={status} value={value} label="Label" placeholder="мм.гггг" onChange={setValue} />
+        </div>
+    );
+};
+
+const STATUSES = Object.values(EFormFieldStatus);
+
+export const StatusesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {STATUSES.map((status) => (
+            <StatusItem key={status} status={status} />
+        ))}
+    </div>
+);
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |