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

package/bundle/components/Calendar.md

@@ -1,9 +1,7 @@
 ---
 component: Calendar
-category: Date & Time
-figma-node: ""
-figma-file: ""
-related: [DateField, DateRange, DatePickerExtended, MonthYearField]
+category: Date components
+related: [DatePickerExtended, DateField, DateRange, MonthYearField, MonthYearRange, ChipDatePicker]
 tokens:
   - --triplex-next-Calendar-Background
   - --triplex-next-Calendar-View_Header_Color
@@ -17,6 +15,7 @@ tokens:
   - --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_Hover
   - --triplex-next-Calendar-View_Item_Color_Muted
   - --triplex-next-Calendar-View_Item_Color_Selected
   - --triplex-next-Calendar-View_Item_Color_Selected_Muted_Default
@@ -41,348 +40,76 @@ version: "1.0"
 
 ## Назначение
 
-Интерактивный компонент выбора даты в виде классической сетки календаря.
-Рендерит заголовок с навигацией (предыдущий/следующий период, смена вида),
-сетку периода (дни/месяцы/годы) и опциональный футер с кнопками быстрого
-перехода (Вчера/Сегодня/Завтра).
+Календарная сетка выбора даты или месяца: заголовок с периодом и кнопками перелистывания, таблица дней / месяцев / годов и опциональный футер с кнопками быстрого перехода. Компонент полностью управляемый — выбранную дату хранит потребитель (`pickedDate` + `onDateChange`), внутри хранится только состояние навигации (текущая страница и вид отображения).
 
-Поддерживает два режима выбора: `datePick` (день → месяц → год) и
-`monthYearPick` (только месяц+год, без выбора конкретного дня). Позволяет
-отмечать дни цветными метками четырёх типов (BASIC/STANDARD/ATTENTION/CRITICAL),
-ограничивать диапазон допустимых дат, запрещать отдельные дни.
+Используй когда: нужна встроенная в макет календарная сетка (внутри поповера, дропдауна, карточки) — например, при построении собственного date picker'а.
 
-Используй когда: нужен самостоятельный календарь в 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).
+Не используй когда: нужен готовый инпут с датой (`DateField`), выпадающий календарь у поля (`DatePickerExtended`), выбор месяца и года через поле (`MonthYearField`) или выбор диапазона (`DateRange`, `MonthYearRange`) — все они уже используют `Calendar` внутри.
 
 ---
 
 ## Варианты и props
 
-### `ICalendarProps extends ICalendarNestedProps`
-
-**Обязательные:**
+### Обязательные props
 
 | Prop | Тип | Описание |
 |---|---|---|
-| `pickedDate` | `TPickedDateProp = string \| Moment \| null` | Выбранная дата. Строка парсится по `format`. |
-| `onDateChange` | `(date: Moment) => void` | Коллбек при выборе даты/месяца в сетке. Всегда Moment. |
+| `pickedDate` | `string \| Moment \| null` | Выбранная дата. Строка парсится по `format`. `null` — дата не выбрана. |
+| `onDateChange` | `(date: Moment) => void` | Вызывается при выборе даты пользователем. Компонент не хранит выбор — потребитель обязан обновить `pickedDate`. |
 
-**Опциональные (основные):**
+### Опциональные props
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `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
+| `format` | `string` | `dateFormatYYYYMMDD` (`"YYYYMMDD"`) | Формат парсинга `pickedDate` / `defaultViewDate` и ключей `markedDays` / `disabledDays`. |
+| `pickType` | `ECalendarPickType` | `DATE` | `DATE` — выбор дня (стартовый вид `DAYS`), `MONTH_YEAR` — выбор месяца (стартовый вид `MONTHS`, клик по месяцу вызывает `onDateChange`). |
+| `defaultViewDate` | `string \| Moment` | — | Страница, открываемая при пустой `pickedDate`. Учитывается только при инициализации. |
+| `limitRange` | `IDateLimitRange` | `globalLimitRange` (1900-01-01 — 2199-12-31) | Допустимый период. Даты вне периода отключены, кнопки перелистывания у границы — `disabled`. Обе границы (`dateFrom` / `dateTo`) опциональны — незаданная сторона берётся из `globalLimitRange`. |
+| `markedDays` | `string[] \| Record<string, ECalendarDateMarkType>` | — | Дни с точкой-отметкой. Массив — отметка типа `BASIC`; объект — тип отметки на каждый день. Ключи в формате `format`. |
+| `disabledDays` | `string[]` | — | Дни, недоступные для выбора (в формате `format`). При клавиатурной навигации пропускаются. |
+| `reversedPick` | `boolean` | `false` | Обратный порядок выбора: старт с вида `YEARS` (год → месяц → день). Учитывается только при инициализации. |
+| `adaptiveMode` | `boolean` | `false` | Адаптивная (мобильная) вёрстка: резиновая ширина и увеличенные ячейки, кнопки футера размера `MD` вместо `SM`. |
+| `onPageChange` | `(viewDate: Moment, viewMode: ECalendarViewMode) => void` | — | Смена страницы внутри текущего вида (перелистывание, уход навигации за пределы страницы). |
+| `onViewChange` | `(viewDate: Moment, viewMode: ECalendarViewMode) => void` | — | Смена вида отображения (дни ⇄ месяцы ⇄ годы). |
+
+### Props вложенных элементов (`ICalendarNestedProps`)
 
-#### `ECalendarPickType` (numeric enum)
-
-| Значение | Числовой код | Описание |
+| Prop | Тип | Описание |
 |---|---|---|
-| `datePick` | 0 | Выбор конкретного дня. ViewMode начинает с DAYS. |
-| `monthYearPick` | 1 | Выбор месяца+года. ViewMode начинает с MONTHS, нет DAYS. |
+| `dayHtmlAttributes` | `TTdHTMLAttributesWithData \| (({marked}) => TTdHTMLAttributesWithData)` | Атрибуты ячейки дня. Функциональный вариант получает признак `marked` — им удобно помечать дни с отметкой. Оба варианта допускают `data-*` атрибуты. |
+| `monthHtmlAttributes` / `yearHtmlAttributes` | `TTdHTMLAttributesWithData` | Атрибуты ячеек месяца / года. |
+| `prevButtonProps` / `nextButtonProps` | `TButtonHTMLAttributesWithData \| ((viewMode) => ...)` | Props кнопок перелистывания. `disabled` объединяется с внутренним расчётом по `limitRange`, `onClick` вызывается после смены страницы. |
+| `viewButtonProps` | `TButtonHTMLAttributesWithData \| ((viewMode) => ...)` | Props кнопки заголовка (смена вида). В виде `YEARS` кнопка не рендерится — период выводится как `<span>`. |
+| `todayButtonProps` | `TButtonHTMLAttributesWithData \| (({viewMode, currentPeriodSelected}) => ...)` | **Наличие этого prop включает футер.** Без него футер не рендерится вовсе. Текст задаёт потребитель (обычно «Сегодня» / «К текущей дате» по `currentPeriodSelected`). |
+| `yesterdayButtonProps` / `tomorrowButtonProps` | `TButtonHTMLAttributesWithData \| ((viewMode) => ...)` | Кнопки «Вчера» / «Завтра». Рендерятся только вместе с футером и только когда открыта страница текущего месяца в виде `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>` с
-  кнопками.
+- `defaultViewDate` и `reversedPick` влияют на стартовое состояние и не пересчитываются при последующих ререндерах (кроме синхронизации страницы с изменившейся `pickedDate`).
+- `pickType` задаёт стартовый вид только при инициализации, но продолжает влиять на поведение при каждом рендере: от него зависят выбор месяца (`MONTH_YEAR` возвращает дату, иначе — проваливается в дни) и состав футера.
 
 ---
 
 ## Дизайн-токены
 
-**Root:**
-```
---triplex-next-Calendar-Background                 # Фон календаря
 ```
-
-**View — заголовок и обычные ячейки:**
-```
---triplex-next-Calendar-View_Header_Color          # Дни недели в шапке
---triplex-next-Calendar-View_Item_Color_Default
+--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_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_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_Hover
+--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
@@ -397,44 +124,72 @@ type TDayHtmlAttributesFunction = (params: {marked: boolean}) => React.TdHTMLAtt
 --triplex-next-Calendar-View_Item_Mark_Critical_Background_Selected_Hover
 ```
 
-Всего **28 токенов** — самое большое количество среди компонентов библиотеки.
-При добавлении новой метки (`ECalendarDateMarkType.X`) нужно **четыре**
-изменения: enum, 3 новых токена, обновление LESS с `.mark.x` классом, и
-обновление `CalendarViewItem` с веткой `switch`.
+Кнопки заголовка и футера используют токены `Button` / `ButtonIcon`.
+
+---
+
+## Инварианты
+
+- **`Calendar` — классовый компонент** (`React.PureComponent`), один из немногих оставшихся в библиотеке. `ref` на нём — экземпляр класса, а не DOM-элемент. Перевод на функциональный компонент или добавление `forwardRef` — breaking change, требует отдельного решения мейнтейнера.
+- Компонент полностью управляемый: клик по дате не меняет `pickedDate`, а только вызывает `onDateChange`. Внутреннее состояние — `viewDate` (страница), `viewMode` (вид) и производная от `pickedDate` копия.
+- Публичный API (`ICalendarProps`, `ICalendarNestedProps`, `ICalendarViewProps`, `TPickedDate`, `TPickedDateProp`, `TCalendarMarkedDays`, `TDayHtmlAttributes`, `TTdHTMLAttributesWithData`, `TButtonHTMLAttributesWithData`, `ECalendarPickType`, `ECalendarViewMode`, `ECalendarDateMarkType`) экспортируется через `src/components/Calendar/index.ts` — переименования и изменения значений enum'ов недопустимы.
+- `ECalendarDateMarkType` — числовой enum. Проверки типа отметки делаются через `markType !== undefined`, а не через truthy — `BASIC` равен `0`.
+- Компонент не хардкодит текст: подписи кнопок футера, `aria-label` кнопок перелистывания и любые заголовки передаёт потребитель через `*ButtonProps`. Библиотека мультиязычная.
+- Внутренние модули (`utils.ts`, `CalendarContext`, `CalendarViewContext`, `components/*`) в barrel не экспортируются, но `isDayDisabled` и `isDateOutOfRange` из `utils.ts` импортируются соседними компонентами (`DateField`, `MonthYearField`) — не удалять и не переименовывать без проверки потребителей внутри `src`.
+- `periodId` (`calendar-period-{uniqueId}`) связывает заголовок и таблицу через `aria-labelledby` — не удалять.
+- В библиотеке действует React 17-совместимость (ветка `release-0`): не переводить компонент на `useId` и другие React 18-only API.
+
+---
+
+## Accessibility
+
+- Таблица вида имеет `role="grid"` и `aria-labelledby={periodId}`, указывающий на заголовок с текущим периодом. Заголовок помечен `aria-live="polite"` — смена месяца/года озвучивается скринридером.
+- Внутри сетки реализована roving tabindex-навигация: ровно одна ячейка имеет `tabIndex=0` (выбранная дата, либо первая доступная дата страницы), остальные — `tabIndex=-1`.
+- Клавиатура в сетке:
+  - `ArrowLeft` / `ArrowRight` — соседняя ячейка строки (день / месяц / год);
+  - `ArrowUp` / `ArrowDown` — соседняя строка (неделя / 3 месяца / 3 года);
+  - `PageUp` / `PageDown` — предыдущая / следующая страница (месяц / год / 12 лет);
+  - `Enter` / `Space` — выбор даты (с `preventDefault`).
+- Недоступные дни (`disabledDays`, выход за `limitRange`) при навигации стрелками пропускаются; попытка выйти за `limitRange` оставляет фокус на текущей дате.
+- Уход навигации за пределы текущей страницы автоматически перелистывает страницу (`onPageChange`) и возвращает фокус на новую tabbable-ячейку. Фокус восстанавливается только если он уже находился внутри сетки — программная смена страницы (кнопки перелистывания, внешняя смена `pickedDate`) фокус не забирает.
+- Выбранная ячейка помечается `aria-selected="true"`; отключённая — классом `disabled` и `pointer-events: none` (атрибут `disabled` у `<td>` невозможен).
+- Кнопки перелистывания — `ButtonIcon` без текста: потребитель обязан передать `aria-label` через `prevButtonProps` / `nextButtonProps`.
 
 ---
 
 ## Связанные компоненты
 
-- `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.
+- `DatePickerExtended` — выпадающий календарь над произвольным таргетом; рендерит `Calendar` внутри дропдауна.
+- `DateField` — поле ввода даты с календарём; использует `isDayDisabled` и `isDateOutOfRange` из `Calendar/utils` и тип `TPickedDate` из `Calendar/types`.
+- `MonthYearField`, `MonthYearRange` — выбор месяца и года, конфигурируют `Calendar` через `pickType={ECalendarPickType.MONTH_YEAR}`; `MonthYearField` использует `isDateOutOfRange` из `Calendar/utils`.
+- `DateRange` — выбор диапазона дат двумя полями.
+- `ChipDatePicker` — чип-фильтр с календарём.
+
+Внутренние субкомпоненты (в barrel не экспортируются, отдельного AI.md не имеют):
+
+- `CalendarControls` — заголовок с кнопками перелистывания и смены вида.
+- `CalendarView` — переключатель видов; хранит `viewItemFocusedRef` (признак фокуса внутри сетки) в `CalendarViewContext`, чтобы не сбрасывать выбранную для фокуса ячейку при перелистывании.
+- `CalendarViewDays` / `CalendarViewMonths` / `CalendarViewYears` — сетки дней, месяцев и годов.
+- `CalendarViewItem` — ячейка сетки: классы состояний, отметка, `aria-selected`, обработка `Enter` / `Space` и фокуса.
+- `CalendarFooter` / `CalendarFooterButton` — футер и его кнопки быстрого перехода («Вчера» / «Сегодня» / «Завтра»).
+- `utils.ts` — чистые функции: парсинг даты, формат заголовка, проверки периода и отключённых дней, сдвиг даты при клавиатурной навигации. Покрыты `__tests__/utils.test.tsx`.
 
 ---
 
 ## Stories
 
-`stories/Calendar/Calendar.stories.tsx`
+Основные истории: `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 на английском.
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `defaultViewDate` / `adaptiveMode` и переключатели отмеченных дней, отключённых дней и кнопок футера |
+| `Default` | `DefaultExample.tsx` | Минимальный управляемый календарь: `pickedDate` + `onDateChange` |
+| `MarkedDays` | `MarkedDaysExample.tsx` | Отображается как «With marked days». Все четыре типа отметок (`BASIC` / `STANDARD` / `ATTENTION` / `CRITICAL`) |
+| `DisabledDays` | `DisabledDaysExample.tsx` | Отображается как «With disabled days». Дни, недоступные для выбора |
+| `Buttons` | `ButtonsExample.tsx` | Отображается как «With buttons». Футер с кнопками «Вчера» / «Сегодня» / «Завтра» и текстом по `currentPeriodSelected` |
+| `ReversedPick` | `ReversedPickExample.tsx` | Обратный порядок выбора: год → месяц → день |
+| `VisualTests` | `VisualTestsExample.tsx` | Скриншот-регрессия: календарь на фиксированной дате (январь 1970), чтобы снимок не зависел от текущей даты |
 
 ---
 
@@ -442,7 +197,8 @@ weekday на английском.
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-07-30 | Создан документ. AI-рефакторинг: общие хелперы клавиатурной навигации и сдвига даты в `utils.ts`, чистка дублирования в `CalendarControls` и сетках, JSDoc на публичных типах, `displayName` у субкомпонентов; добавлены unit-тесты (`Calendar`, `CalendarViewItem`, `utils`) |
+| 2026-07-30 | Исправлены найденные при рефакторинге баги: выбор первой tabbable-ячейки перебирал кандидатов с накоплением шага (в виде годов — месяцами вместо лет; хелпер `getFirstEnabledDate`); заголовок при внешней смене `pickedDate` игнорировал формат вида (`MONTH_YEAR` показывал «March 1970» вместо «1970»); фокус после `PageUp`/`PageDown` не возвращался на tabbable-ячейку, если её позиция сетки не менялась; шаг страницы в `changeTabbableDate`/`changeFocusedDate` переведён на `NAVIGATION_STEPS.page`. Расширения API: `dateFrom`/`dateTo` в `IDateLimitRange` стали опциональными, функциональный `dayHtmlAttributes` допускает `data-*` (`TTdHTMLAttributesWithData`) |
 
 ---
 
@@ -453,8 +209,8 @@ weekday на английском.
 `stories/Calendar/examples/DefaultExample.tsx`
 
 ```tsx
-import moment from "moment";
 import React, { useState } from "react";
+import moment from "moment";
 import { Calendar } from "@sberbusiness/triplex-next";
 
 export const DefaultExample = () => {
@@ -464,40 +220,99 @@ export const DefaultExample = () => {
 };
 ```
 
-### PickTypes
+### MarkedDays
+
+`stories/Calendar/examples/MarkedDaysExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import moment from "moment";
+import { Calendar, dateFormatYYYYMMDD, ECalendarDateMarkType } from "@sberbusiness/triplex-next";
+
+export const MarkedDaysExample = () => {
+    const [pickedDate, setPickedDate] = useState(moment());
+
+    return (
+        <Calendar
+            pickedDate={pickedDate}
+            markedDays={{
+                [moment().subtract(2, "days").format(dateFormatYYYYMMDD)]: ECalendarDateMarkType.BASIC,
+                [moment().subtract(4, "days").format(dateFormatYYYYMMDD)]: ECalendarDateMarkType.STANDARD,
+                [moment().add(2, "days").format(dateFormatYYYYMMDD)]: ECalendarDateMarkType.ATTENTION,
+                [moment().add(4, "days").format(dateFormatYYYYMMDD)]: ECalendarDateMarkType.CRITICAL,
+            }}
+            onDateChange={setPickedDate}
+        />
+    );
+};
+```
+
+### DisabledDays
 
-`stories/Calendar/examples/PickTypesExample.tsx`
+`stories/Calendar/examples/DisabledDaysExample.tsx`
 
 ```tsx
+import React, { useState } from "react";
 import moment from "moment";
+import { Calendar, dateFormatYYYYMMDD } from "@sberbusiness/triplex-next";
+
+export const DisabledDaysExample = () => {
+    const [pickedDate, setPickedDate] = useState(moment());
+
+    return (
+        <Calendar
+            pickedDate={pickedDate}
+            disabledDays={[
+                moment().subtract(3, "days").format(dateFormatYYYYMMDD),
+                moment().subtract(5, "days").format(dateFormatYYYYMMDD),
+                moment().add(3, "days").format(dateFormatYYYYMMDD),
+                moment().add(5, "days").format(dateFormatYYYYMMDD),
+            ]}
+            onDateChange={setPickedDate}
+        />
+    );
+};
+```
+
+### Buttons
+
+`stories/Calendar/examples/ButtonsExample.tsx`
+
+```tsx
 import React, { useState } from "react";
-import { Calendar, ECalendarPickType } from "@sberbusiness/triplex-next";
+import moment from "moment";
+import { Calendar } from "@sberbusiness/triplex-next";
 
-export const PickTypesExample = () => {
-    const initialDate = moment("2024-01-15");
-    const [pickedDateDatePick, setPickedDateDatePick] = useState(initialDate);
-    const [pickedDateMonthYearPick, setPickedDateMonthYearPick] = useState(initialDate);
+export const ButtonsExample = () => {
+    const [pickedDate, setPickedDate] = useState(moment());
 
     return (
-        <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
-            <div>
-                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>DATEPICK</div>
-                <Calendar
-                    pickType={ECalendarPickType.datePick}
-                    pickedDate={pickedDateDatePick}
-                    onDateChange={setPickedDateDatePick}
-                />
-            </div>
-            <div>
-                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>MONTHYEARPICK</div>
-                <Calendar
-                    pickType={ECalendarPickType.monthYearPick}
-                    pickedDate={pickedDateMonthYearPick}
-                    onDateChange={setPickedDateMonthYearPick}
-                />
-            </div>
-        </div>
+        <Calendar
+            pickedDate={pickedDate}
+            onDateChange={setPickedDate}
+            todayButtonProps={({ currentPeriodSelected }) => ({
+                children: currentPeriodSelected ? "Сегодня" : "К текущей дате",
+            })}
+            yesterdayButtonProps={{ children: "Вчера" }}
+            tomorrowButtonProps={{ children: "Завтра" }}
+        />
     );
 };
 ```
 
+### ReversedPick
+
+`stories/Calendar/examples/ReversedPickExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import moment from "moment";
+import { Calendar } from "@sberbusiness/triplex-next";
+
+export const ReversedPickExample = () => {
+    const [pickedDate, setPickedDate] = useState(moment());
+
+    return <Calendar pickedDate={pickedDate} onDateChange={setPickedDate} reversedPick />;
+};
+```
+