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

package/bundle/components/Calendar.md

@@ -0,0 +1,445 @@
+---
+component: Calendar
+category: Date & Time
+figma-node: ""
+figma-file: ""
+related: [DateField, DateRange, DatePickerExtended, MonthYearField]
+tokens:
+  - --triplex-next-Calendar-Background
+  - --triplex-next-Calendar-View_Header_Color
+  - --triplex-next-Calendar-View_Item_Background_Default
+  - --triplex-next-Calendar-View_Item_Background_Hover
+  - --triplex-next-Calendar-View_Item_Background_Selected_Default
+  - --triplex-next-Calendar-View_Item_Background_Selected_Hover
+  - --triplex-next-Calendar-View_Item_Background_Selected_Muted_Default
+  - --triplex-next-Calendar-View_Item_Background_Selected_Muted_Hover
+  - --triplex-next-Calendar-View_Item_BorderColor_Default
+  - --triplex-next-Calendar-View_Item_BorderColor_Focus
+  - --triplex-next-Calendar-View_Item_Color_Default
+  - --triplex-next-Calendar-View_Item_Color_Disabled
+  - --triplex-next-Calendar-View_Item_Color_Muted
+  - --triplex-next-Calendar-View_Item_Color_Selected
+  - --triplex-next-Calendar-View_Item_Color_Selected_Muted_Default
+  - --triplex-next-Calendar-View_Item_Color_Selected_Muted_Hover
+  - --triplex-next-Calendar-View_Item_Mark_Basic_Background_Default
+  - --triplex-next-Calendar-View_Item_Mark_Basic_Background_Selected_Default
+  - --triplex-next-Calendar-View_Item_Mark_Basic_Background_Selected_Hover
+  - --triplex-next-Calendar-View_Item_Mark_Standard_Background_Default
+  - --triplex-next-Calendar-View_Item_Mark_Standard_Background_Selected_Default
+  - --triplex-next-Calendar-View_Item_Mark_Standard_Background_Selected_Hover
+  - --triplex-next-Calendar-View_Item_Mark_Attention_Background_Default
+  - --triplex-next-Calendar-View_Item_Mark_Attention_Background_Selected_Default
+  - --triplex-next-Calendar-View_Item_Mark_Attention_Background_Selected_Hover
+  - --triplex-next-Calendar-View_Item_Mark_Critical_Background_Default
+  - --triplex-next-Calendar-View_Item_Mark_Critical_Background_Selected_Default
+  - --triplex-next-Calendar-View_Item_Mark_Critical_Background_Selected_Hover
+stories: stories/Calendar/Calendar.stories.tsx
+version: "1.0"
+---
+
+# Calendar
+
+## Назначение
+
+Интерактивный компонент выбора даты в виде классической сетки календаря.
+Рендерит заголовок с навигацией (предыдущий/следующий период, смена вида),
+сетку периода (дни/месяцы/годы) и опциональный футер с кнопками быстрого
+перехода (Вчера/Сегодня/Завтра).
+
+Поддерживает два режима выбора: `datePick` (день → месяц → год) и
+`monthYearPick` (только месяц+год, без выбора конкретного дня). Позволяет
+отмечать дни цветными метками четырёх типов (BASIC/STANDARD/ATTENTION/CRITICAL),
+ограничивать диапазон допустимых дат, запрещать отдельные дни.
+
+Используй когда: нужен самостоятельный календарь в inline-режиме (например,
+в попапе DateField, в модальном окне бронирования).
+Не используй когда: нужен input с календарным попапом — бери `DateField`
+(обёртка с `DateFieldPicker`); нужен range picker — бери `DateRange`; нужен
+компактный picker только месяц+год — для input'а используй `MonthYearField`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Calendar/
+├── Calendar.tsx                            # React.PureComponent (class), root компонент
+├── CalendarContext.tsx                     # Контекст с format/limitRange/pickType/viewDate/viewMode/periodId + обработчики
+├── CalendarViewContext.tsx                 # Контекст с viewItemFocusedRef (mutable)
+├── enums.ts                                # ECalendarPickType, ECalendarViewMode, ECalendarDateMarkType
+├── types.ts                                # ICalendarProps, TPickedDate, TCalendarMarkedDays, и др.
+├── utils.ts                                # parsePickedDate, getHeader, formatDate, isDateOutOfRange, isDayDisabled
+├── index.ts                                # Barrel: Calendar + enums + types
+├── styles/
+│   ├── Calendar.module.less                # Root (width 300px, adaptive)
+│   ├── CalendarControls.module.less        # Заголовок с кнопками prev/next/view
+│   ├── CalendarView.module.less            # Таблица сетки, все состояния и метки
+│   └── CalendarFooter.module.less          # Футер с кнопками дат
+└── components/                             # Внутренние (не экспортируются наружу)
+    ├── CalendarControls.tsx                # Заголовок + prev/next/view кнопки
+    ├── CalendarView.tsx                    # Переключатель между Days/Months/Years
+    ├── CalendarViewDays.tsx                # Сетка дней с weekday-шапкой
+    ├── CalendarViewMonths.tsx              # Сетка 12 месяцев
+    ├── CalendarViewYears.tsx               # Сетка 12 лет (диапазон -5..+6 от viewDate)
+    ├── CalendarViewItem.tsx                # Ячейка: день/месяц/год + marks/states
+    ├── CalendarFooter.tsx                  # Контейнер футера
+    └── CalendarFooterButton.tsx            # Кнопка "Вчера"/"Сегодня"/"Завтра"
+```
+
+Особенности:
+- **`Calendar` — class component (`React.PureComponent`)**, не функция и не
+  `forwardRef`. Это легаси и осознанное решение: state-машина viewMode + viewDate
+  + header проще как класс (cоответствующая рефакторинговая задача не запланирована).
+- **Нет `forwardRef`** — один из немногих компонентов без него. Не добавлять
+  без согласования, класс не поддерживает forwardRef без обёртки.
+- **Два контекста**: `CalendarContext` (данные + обработчики) и
+  `CalendarViewContext` (мутабельный ref для управления фокусом между viewMode).
+- **`moment.js`** — зависимость времени. Весь внешний API построен вокруг
+  `Moment` и строк с `format`. Пользователь должен подключить локаль через
+  `moment.locale("ru")` (делается в stories).
+
+---
+
+## Варианты и props
+
+### `ICalendarProps extends ICalendarNestedProps`
+
+**Обязательные:**
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `pickedDate` | `TPickedDateProp = string \| Moment \| null` | Выбранная дата. Строка парсится по `format`. |
+| `onDateChange` | `(date: Moment) => void` | Коллбек при выборе даты/месяца в сетке. Всегда Moment. |
+
+**Опциональные (основные):**
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `format` | `string` | `"YYYY-MM-DD"` (`dateFormatYYYYMMDD`) | Формат для парсинга/форматирования строковых дат. |
+| `pickType` | `ECalendarPickType` | `datePick` | Режим выбора: день или месяц+год. |
+| `limitRange` | `IDateLimitRange` | `globalLimitRange` | `{ dateFrom?, dateTo? }`. Даты вне диапазона недоступны. |
+| `markedDays` | `TCalendarMarkedDays` | — | Массив строк дат (`BASIC`) или объект `{ [date]: ECalendarDateMarkType }`. |
+| `disabledDays` | `string[]` | — | Даты, недоступные для выбора (формат = `format`). |
+| `reversedPick` | `boolean` | `false` | Начинать выбор с года (YEARS → MONTHS → DAYS) вместо обычного. |
+| `defaultViewDate` | `string \| Moment` | — | Дата, на которой открывается календарь при отсутствии `pickedDate`. |
+| `adaptiveMode` | `boolean` | — | `width: auto; padding: 20px` вместо `300px/8px 12px`. Для модальных окон. |
+| `onPageChange` | `(viewDate, viewMode) => void` | — | Срабатывает при prev/next. |
+| `onViewChange` | `(viewDate, viewMode) => void` | — | Срабатывает при смене viewMode (клик по заголовку или выбор месяца/года). |
+
+**Опциональные (кастомизация кнопок и ячеек через `ICalendarNestedProps`):**
+
+Все `*ButtonProps` принимают либо объект HTML-атрибутов кнопки, либо функцию,
+возвращающую атрибуты. Для `todayButtonProps` функция получает
+`{viewMode, currentPeriodSelected}`, остальные — только `viewMode`.
+
+| Prop | Тип | Назначение |
+|---|---|---|
+| `prevButtonProps` | `TButtonHTMLAttributesWithData \| (viewMode) => ...` | Кнопка "Предыдущий". Обязательные `data-*` атрибуты. |
+| `nextButtonProps` | `TButtonHTMLAttributesWithData \| (viewMode) => ...` | Кнопка "Следующий". |
+| `viewButtonProps` | `TButtonHTMLAttributesWithData \| (viewMode) => ...` | Заголовок (кнопка смены viewMode). |
+| `yesterdayButtonProps` | `TButtonHTMLAttributesWithData \| (viewMode) => ...` | Только в `datePick`+DAYS+текущий месяц. |
+| `todayButtonProps` | `TButtonHTMLAttributesWithData \| ({viewMode, currentPeriodSelected}) => ...` | **Ключевой: если не передан — футер не рендерится вообще.** |
+| `tomorrowButtonProps` | `TButtonHTMLAttributesWithData \| (viewMode) => ...` | Только в `datePick`+DAYS+текущий месяц. |
+| `dayHtmlAttributes` | `TTdHTMLAttributesWithData \| (params: {marked}) => ...` | Атрибуты `<td>` ячейки дня. Функция получает `{marked: boolean}`. |
+| `monthHtmlAttributes` | `TTdHTMLAttributesWithData` | Атрибуты `<td>` ячейки месяца. |
+| `yearHtmlAttributes` | `TTdHTMLAttributesWithData` | Атрибуты `<td>` ячейки года. |
+
+**`TButtonHTMLAttributesWithData` / `TTdHTMLAttributesWithData`** — требуют
+минимум один `data-*` атрибут (intersection-тип). Это форсит потребителя
+добавлять testId-подобные атрибуты.
+
+---
+
+### Enums
+
+#### `ECalendarPickType` (numeric enum)
+
+| Значение | Числовой код | Описание |
+|---|---|---|
+| `datePick` | 0 | Выбор конкретного дня. ViewMode начинает с DAYS. |
+| `monthYearPick` | 1 | Выбор месяца+года. ViewMode начинает с MONTHS, нет DAYS. |
+
+#### `ECalendarViewMode` (string enum)
+
+| Значение | Что видно в сетке |
+|---|---|
+| `"days"` (DAYS) | Сетка 6×7: weekday-шапка + дни месяца (включая края соседних). |
+| `"months"` (MONTHS) | Сетка 3×4 из 12 месяцев года. |
+| `"years"` (YEARS) | Сетка 3×4 из 12 лет (диапазон viewDate −5..+6). |
+
+#### `ECalendarDateMarkType` (numeric enum)
+
+| Значение | Код | Назначение |
+|---|---|---|
+| `BASIC` | 0 | Нейтральная метка (общие события). |
+| `STANDARD` | 1 | Стандартная метка (выплаты, платежи). |
+| `ATTENTION` | 2 | Внимание (срочно, но не критично). |
+| `CRITICAL` | 3 | Критическая метка (просрочка, ошибка). |
+
+Каждая метка — отдельный токен для `Default`/`Selected_Default`/`Selected_Hover`
+(всего 12 токенов цветов меток).
+
+---
+
+## Ключевые особенности реализации
+
+### Инициализация viewMode в конструкторе
+
+```ts
+if (reversedPick) {
+    viewMode = ECalendarViewMode.YEARS;
+} else if (pickType == ECalendarPickType.monthYearPick) {
+    viewMode = ECalendarViewMode.MONTHS;
+} else {
+    viewMode = ECalendarViewMode.DAYS;
+}
+```
+
+`reversedPick` имеет приоритет над `pickType` — всегда начинает с YEARS.
+В обычном `monthYearPick` стартует с MONTHS. По умолчанию — DAYS.
+
+### Синхронизация `pickedDate` → `viewDate` в `componentDidUpdate`
+
+Если внешний `pickedDate` изменился на валидную дату в **другом месяце**
+относительно текущего `viewDate`, календарь автоматически переключается
+в DAYS и навигирует на месяц новой даты. Это не типичный controlled-паттерн —
+`viewDate` не контролируется потребителем, он производится от `pickedDate`.
+
+### `uniqueId()` для `periodId`
+
+```ts
+private periodId = `calendar-period-${uniqueId()}`;
+```
+
+Генерируется в инстансе класса. Нужен для связывания weekday-шапки в
+CalendarViewDays и сетки дней через `headers`/`id` ARIA-атрибуты (a11y для
+screen reader'а: "Понедельник, 15 января").
+
+### `CalendarContext.Provider` — единственный способ доступа subcomponent'ов
+
+Внутренние компоненты (`CalendarView`, `CalendarControls`, `CalendarFooter`)
+не принимают большинство props от Calendar напрямую. Все данные и обработчики
+идут через контекст. Исключение — `prevButtonProps`/`nextButtonProps`/
+`viewButtonProps` передаются в `CalendarControls` пропсами, так как имеют
+различные типы и легче передать явно.
+
+### Футер рендерится только при `todayButtonProps`
+
+```tsx
+{todayButtonProps && this.renderFooter()}
+```
+
+Это единственный гейт — без `todayButtonProps` футер не появляется. Кнопки
+"Вчера" и "Завтра" показываются дополнительно только в `datePick`+DAYS,
+когда `viewDate` находится в текущем месяце (`currentPeriodSelected`).
+
+### `currentPeriodSelected` имеет разный смысл для pickType
+
+```ts
+if (pickType === ECalendarPickType.datePick) {
+    currentPeriodSelected = viewMode === DAYS && viewDate.isSame(todayDate, "month");
+} else {
+    currentPeriodSelected = viewMode === MONTHS && viewDate.isSame(todayDate, "year");
+}
+```
+
+Для `datePick` — "текущий месяц в поле зрения". Для `monthYearPick` —
+"текущий год в поле зрения". Потребитель получает этот флаг в
+`todayButtonProps`-функции, чтобы менять текст кнопки ("Сегодня" vs
+"К текущей дате").
+
+### `adaptiveMode` — не responsive, а переключатель размера
+
+Не про media-queries. Прокидывает `.adaptive` класс на root, меняет ширину
+на `auto` и паддинги на `20px`. Используется в контексте модальных окон /
+DatePickerExtended, где родитель управляет шириной.
+
+### `formatDate` для YEARS показывает диапазон
+
+```ts
+case YEARS:
+    const yearFrom = checkedDate.clone().add(-5, "y").format("YYYY");
+    const yearTo = checkedDate.clone().add(6, "y").format("YYYY");
+    return `${yearFrom} - ${yearTo}`;
+```
+
+12-летний диапазон, где viewDate находится на 6-м месте (−5 назад, +6 вперёд).
+Это определяет и заголовок, и сами ячейки.
+
+### `TCalendarMarkedDays` — два формата
+
+```ts
+type TCalendarMarkedDays = string[] | Record<string, ECalendarDateMarkType>;
+```
+
+Массив → все метки `BASIC`. Объект → тип метки по дате. Внутренне
+`CalendarViewDays` нормализует оба варианта в `Record` и достаёт тип по
+строковому ключу даты.
+
+### `dayHtmlAttributes` как функция
+
+```ts
+type TDayHtmlAttributesFunction = (params: {marked: boolean}) => React.TdHTMLAttributes<...>;
+```
+
+Если передать функцию — получает `marked` для каждого дня, возвращает атрибуты.
+Позволяет делать `data-marked="true"` атрибут без ручной проверки. Для месяцев
+и годов функционального варианта нет (нет `marked`-логики).
+
+---
+
+## Инварианты
+
+- **`React.PureComponent` class** — не превращать в функцию без масштабного
+  рефакторинга state-машины. Перезапись изменит поведение `componentDidUpdate`.
+- **Нет `forwardRef`** — класс не форвардит ref. Не добавлять (осознанное
+  решение, есть в ROADMAP).
+- **`defaultProps` на классе** — не удалять, не переносить в деструктуризацию.
+  Используется в `this.context`-типизации и вычислениях конструктора.
+- **`periodId` на инстансе** (`this.periodId =`) — не static, иначе два
+  Calendar'а на странице получат одинаковый id и сломают a11y weekday-ссылок.
+- **`moment.locale("ru")` — ответственность потребителя/stories.**
+  Calendar НЕ устанавливает локаль сам. Если забыть — заголовок и дни недели
+  будут на английском.
+- **`pickedDate` — controlled**, `viewDate` / `viewMode` — internal state.
+  Не делать viewDate controlled без согласования: изменит API.
+- **`onDateChange` — обязателен**. Нет default'а, без него выбор даты не
+  работает.
+- **`todayButtonProps` — только гейт для футера**. Не рендерить футер без
+  него.
+- **`data-tx={process.env.npm_package_version}`** на root — не удалять.
+- **`CalendarContext.Provider` значение** передаётся через `pickType!` и
+  `limitRange!` (non-null assertion). Вся логика опирается на наличие
+  defaults — не убирать `defaultProps`.
+- **`TButtonHTMLAttributesWithData` / `TTdHTMLAttributesWithData`** требуют
+  хотя бы один `data-*` атрибут (intersection). Не упрощать до
+  `ButtonHTMLAttributes` — это публичное обязательство контрактов для тестов.
+- **Weekday-шапка, селектед-день и выключенный день — все проверяются через
+  `moment.isSame(..., unit)`**, не строковыми сравнениями. Не переписывать на
+  `===` по строкам: формат может отличаться.
+
+---
+
+## Accessibility
+
+- **`periodId` + `headers`** на `<td>`-ячейках — озвучивает день недели для
+  screen reader'а ("Понедельник, 15 января"). Не убирать.
+- **Фокус-менеджмент** — `CalendarViewContext.viewItemFocusedRef` хранит
+  последнюю сфокусированную ячейку, чтобы при смене viewMode (MONTHS → DAYS)
+  фокус возвращался на соответствующую ячейку. Не сломать при рефакторинге
+  CalendarViewItem.
+- **Клавиатура** — arrow keys навигация реализована в `CalendarViewItem`
+  через внутренний handler (смотри компонент при изменениях).
+- **`aria-label` на кнопках** — задаётся потребителем через
+  `prevButtonProps`/`nextButtonProps`/`viewButtonProps`. Нет default'ов,
+  потому что локализация — на стороне потребителя.
+- **`data-*` атрибуты обязательны** через типы — обеспечивает testability и
+  часто используется как hook для analytics.
+- **`disabledDays` и `limitRange`** — визуальное отключение + `disabled` на
+  `<button>` внутри ячейки. Screen reader озвучивает как "недоступно".
+- **`role="status"` на весь Calendar?** — нет. Calendar — grid of interactive
+  cells, не статус. Внутри используется семантика `<table>` → `<td>` с
+  кнопками.
+
+---
+
+## Дизайн-токены
+
+**Root:**
+```
+--triplex-next-Calendar-Background                 # Фон календаря
+```
+
+**View — заголовок и обычные ячейки:**
+```
+--triplex-next-Calendar-View_Header_Color          # Дни недели в шапке
+--triplex-next-Calendar-View_Item_Color_Default
+--triplex-next-Calendar-View_Item_Background_Default
+--triplex-next-Calendar-View_Item_Background_Hover
+--triplex-next-Calendar-View_Item_BorderColor_Default
+--triplex-next-Calendar-View_Item_BorderColor_Focus    # Keyboard-фокус
+```
+
+**View — выбранная ячейка:**
+```
+--triplex-next-Calendar-View_Item_Color_Selected
+--triplex-next-Calendar-View_Item_Background_Selected_Default
+--triplex-next-Calendar-View_Item_Background_Selected_Hover
+```
+
+**View — "приглушённый" выбранный (muted, для days вне текущего месяца):**
+```
+--triplex-next-Calendar-View_Item_Color_Selected_Muted_Default
+--triplex-next-Calendar-View_Item_Color_Selected_Muted_Hover
+--triplex-next-Calendar-View_Item_Background_Selected_Muted_Default
+--triplex-next-Calendar-View_Item_Background_Selected_Muted_Hover
+--triplex-next-Calendar-View_Item_Color_Muted          # Days из соседних месяцев
+```
+
+**View — отключённые ячейки:**
+```
+--triplex-next-Calendar-View_Item_Color_Disabled       # disabledDays + за limitRange
+```
+
+**Метки (по 3 токена на каждый из 4 типов):**
+```
+--triplex-next-Calendar-View_Item_Mark_Basic_Background_Default
+--triplex-next-Calendar-View_Item_Mark_Basic_Background_Selected_Default
+--triplex-next-Calendar-View_Item_Mark_Basic_Background_Selected_Hover
+--triplex-next-Calendar-View_Item_Mark_Standard_Background_Default
+--triplex-next-Calendar-View_Item_Mark_Standard_Background_Selected_Default
+--triplex-next-Calendar-View_Item_Mark_Standard_Background_Selected_Hover
+--triplex-next-Calendar-View_Item_Mark_Attention_Background_Default
+--triplex-next-Calendar-View_Item_Mark_Attention_Background_Selected_Default
+--triplex-next-Calendar-View_Item_Mark_Attention_Background_Selected_Hover
+--triplex-next-Calendar-View_Item_Mark_Critical_Background_Default
+--triplex-next-Calendar-View_Item_Mark_Critical_Background_Selected_Default
+--triplex-next-Calendar-View_Item_Mark_Critical_Background_Selected_Hover
+```
+
+Всего **28 токенов** — самое большое количество среди компонентов библиотеки.
+При добавлении новой метки (`ECalendarDateMarkType.X`) нужно **четыре**
+изменения: enum, 3 новых токена, обновление LESS с `.mark.x` классом, и
+обновление `CalendarViewItem` с веткой `switch`.
+
+---
+
+## Связанные компоненты
+
+- `DateField` (`src/components/DateField`) — input с календарным попапом,
+  оборачивающий Calendar через DateFieldPicker.
+- `DateRange` (`src/components/DateRange`) — двойной Calendar для выбора
+  периода (from/to).
+- `DatePickerExtended` (`src/components/DatePickerExtended`) — расширенный
+  picker с пресетами (сегодня, неделя, месяц) + Calendar в overlay.
+- `MonthYearField` (`src/components/MonthYearField`) — input с Calendar в
+  режиме `monthYearPick`.
+- `DateConst` (`src/consts/DateConst`) — `dateFormatYYYYMMDD`, `globalLimitRange`,
+  `headerDateFormat`. Используются как дефолты.
+- `IDateLimitRange` (`src/types/DateTypes`) — тип `{dateFrom?, dateTo?}`
+  на базе Moment.
+
+---
+
+## Stories
+
+`stories/Calendar/Calendar.stories.tsx`
+Файлы примеров: `stories/Calendar/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный выбор `pickType`, `defaultViewDate`, `format`, `reversedPick` |
+| `Default` | `DefaultExample.tsx` | Базовое использование с controlled `pickedDate` |
+| `PickTypes` | `PickTypesExample.tsx` | datePick vs monthYearPick бок о бок |
+| `VisualTests` | `VisualTestsExample.tsx` | Снимки всех состояний для visual regression |
+
+Stories обязательно содержат `moment.locale("ru")` — без этого заголовок/
+weekday на английском.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |