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

package/bundle/components/DatePickerExtended.md

@@ -0,0 +1,342 @@
+---
+component: DatePickerExtended
+category: Internal
+figma-node: ""
+figma-file: ""
+related: [DateField, DateRange, MonthYearField, Calendar, Dropdown, FocusTrap]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# DatePickerExtended
+
+## Назначение
+
+Внутренняя "база" для всех полей выбора даты: объединяет `Dropdown`
+(с desktop + mobile веткой), `Calendar` (внутри dropdown'а) и
+`FocusTrap` (клавиатурная навигация). Управляет открытием/закрытием
+dropdown'а (controlled/uncontrolled внутри себя — state), ловит
+`Esc` для закрытия, отличает "мышиное" взаимодействие от "клавиатурного"
+(флаг `mouseUsedRef`) для настройки `FocusTrap`.
+
+Публично импортируется потребителями вроде `DateField`, `DateRange`,
+`MonthYearField`, но **render-props-интерфейс** (`renderTarget`,
+`renderDropdownHeaderTarget`) делает его сложным для прямого
+использования в приложениях — обычно его оборачивают.
+
+Используй когда: строишь новый компонент выбора даты со своим target'ом
+и своей валидацией — DatePickerExtended даёт dropdown + calendar +
+focus management бесплатно.
+Не используй как замену `DateField`/`DateRange`/`MonthYearField` —
+бери эти готовые обёртки.
+
+---
+
+## Файловая структура
+
+```text
+src/components/DatePickerExtended/
+├── DatePickerExtended.tsx               # forwardRef, root
+├── DatePickerExtendedContext.tsx        # Context { dropdownOpen, mouseUsedRef, setDropdownOpen }
+├── DatePickerExtendedDropdown.tsx       # forwardRef, обёртка Dropdown + FocusTrap + mobile ветка
+└── styles/DatePickerExtended.module.less # Только .datePickerExtendedMobileDropdown { max-height: 100vh }
+```
+
+Особенности:
+- **Нет `index.ts`** — импортируется как `import { DatePickerExtended } from ".../DatePickerExtended/DatePickerExtended"`.
+  Это намеренно — компонент считается "полупубличным" (используется
+  внутри библиотеки и потребителями при необходимости, но без красивого
+  barrel-a).
+- **Нет `__tests__`** — покрывается через тесты `DateField`.
+- **Нет собственных stories** — только через обёртки.
+- **Почти нет LESS** — один класс для мобильного max-height.
+
+---
+
+## Варианты и props
+
+### `IDatePickerExtendedProps`
+
+```ts
+extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange">,
+        Pick<IDropdownProps, "alignment">,
+        ICalendarProps
+```
+
+**Рендер-пропсы (обязательные):**
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `renderTarget` | `() => React.ReactNode` | Target (поле ввода) на десктопе. |
+| `renderDropdownHeaderTarget` | `() => React.ReactNode` | Target в заголовке dropdown'а в мобильном режиме (обычно тот же input, но в другом контейнере). |
+
+**Dropdown:**
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `alignment` | `EDropdownAlignment` | `LEFT` | Выравнивание dropdown'а относительно target'а. |
+| `focusTrapProps` | `FocusTrapProps` | — | Прокидывается в `FocusTrap` (`focus-trap-react`). |
+| `onDropdownOpen` | `() => void` | — | Callback при открытии. |
+| `onDropdownClose` | `() => void` | — | Callback при закрытии. |
+
+**Calendar (все пропсы `ICalendarProps` форвардятся):** `pickType`,
+`format`, `defaultViewDate`, `pickedDate`, `limitRange`, `markedDays`,
+`disabledDays`, `reversedPick`, `dayHtmlAttributes`, `monthHtmlAttributes`,
+`yearHtmlAttributes`, `prevButtonProps`, `nextButtonProps`, `viewButtonProps`,
+`todayButtonProps`, `onDateChange`, `onPageChange`, `onViewChange`.
+
+**HTMLDivAttributes:** все, кроме `onChange` (конфликт с Calendar).
+
+### `DatePickerExtendedContext`
+
+```ts
+interface IDatePickerExtendedContext {
+    dropdownOpen: boolean;
+    mouseUsedRef: React.MutableRefObject<boolean>;
+    setDropdownOpen: (open: boolean) => void;
+}
+```
+
+Передаётся в `renderTarget` через контекст (target живёт в другой ветке
+дерева). `DateFieldTarget` и аналоги используют `useContext` для
+управления dropdown'ом из input'а.
+
+### `DatePickerExtendedDropdown` — внутренний compound
+
+`IDatePickerExtendedDropdownProps extends IDropdownProps` +
+`renderCalendar`, `renderHeaderTarget`, `focusTrapProps`.
+Не экспортируется публично.
+
+---
+
+## Ключевые особенности реализации
+
+### `mouseUsedRef` — отличение мышь vs клавиатура
+
+```ts
+const mouseUsedRef = useRef(false);
+
+const handleMouseDown = (event) => {
+    mouseUsedRef.current = true;
+    onMouseDown?.(event);
+};
+```
+
+Сбрасывается при закрытии dropdown'а (в `useEffect`, ветка else).
+Используется в `FocusTrap`:
+
+```tsx
+<FocusTrap
+    focusTrapOptions={{
+        initialFocus: !mouseUsedRef.current && undefined,
+        returnFocusOnDeactivate: !mouseUsedRef.current,
+    }}
+>
+```
+
+**Зачем:** если пользователь кликнул по полю мышью → не ставить
+программный initialFocus внутрь dropdown'а (пользователь не хочет,
+чтобы фокус "прыгал") и не возвращать фокус на target при закрытии.
+Если клавиатурой (Enter/Space на input) → focus-trap работает, по Esc
+фокус вернётся на input.
+
+**Это UX-тонкость**, нельзя просто удалить `mouseUsedRef` — пострадает
+клавиатурная доступность.
+
+### Outside mousedown → закрытие dropdown'а
+
+```ts
+useEffect(() => {
+    const handleOutsideMouseDown = (event: MouseEvent) => {
+        if (
+            !containerRef.current?.contains(event.target as Node) &&
+            !dropdownRef.current?.contains(event.target as Node)
+        ) {
+            setDropdownOpen(false);
+        }
+    };
+    if (dropdownOpen) {
+        document.addEventListener("mousedown", handleOutsideMouseDown);
+        return () => document.removeEventListener("mousedown", handleOutsideMouseDown);
+    } else {
+        mouseUsedRef.current = false;
+    }
+}, [dropdownOpen]);
+```
+
+**Проверяет два контейнера** — корневой (`containerRef`, target) и
+`dropdownRef` (сам dropdown). Если клик не в них обоих — закрыть.
+`dropdownRef` нужен потому что Dropdown рендерится через Portal и
+не является DOM-потомком `containerRef`.
+
+**`mouseUsedRef` сбрасывается в else-ветке** — при каждом закрытии
+флаг становится `false`, чтобы следующее открытие корректно решало,
+как вести себя с focus trap'ом.
+
+### Esc → закрыть dropdown (локальный onKeyDown)
+
+```ts
+const handleKeyDown = (event) => {
+    if (isKey(key, "ESCAPE")) {
+        if (dropdownOpen) setDropdownOpen(false);
+    }
+    onKeyDown?.(event);
+};
+```
+
+**Esc обрабатывается на root div**, не на document. Нужно, чтобы Esc
+внутри input'а (фокус в target) → закрыть dropdown. Не фильтруется
+`event.defaultPrevented` — если потребитель уже обработал Esc, он
+всё равно закроет dropdown. Это компромисс.
+
+### `renderCalendar(adaptiveMode)` — две ветки
+
+```tsx
+const renderMobileContent = () => (
+    <>
+        <DropdownMobileHeader controlButtons={<DropdownMobileClose onClick={...} />}>
+            {renderHeaderTarget()}
+        </DropdownMobileHeader>
+        <DropdownMobileBody>{renderCalendar(true)}</DropdownMobileBody>
+    </>
+);
+// desktop:
+<FocusTrap ...>
+    <div role="presentation">{renderCalendar(false)}</div>
+</FocusTrap>
+```
+
+**`adaptiveMode=true`** — календарь на мобильном (полноэкранный,
+другие размеры и поведение).
+**`adaptiveMode=false`** — десктопный компактный календарь в dropdown'е.
+
+Calendar сам смотрит на `adaptiveMode` и меняет поведение.
+
+### `onDateChange` → закрыть dropdown + вызвать внешний
+
+```ts
+const handleChangeDate = (date: moment.Moment) => {
+    setDropdownOpen(false);
+    onDateChange(date);
+};
+```
+
+Выбор даты → dropdown закрывается автоматически. Это жёсткое
+поведение, потребитель не может отключить. Если нужно "мультидневный
+выбор" — Calendar не подходит, нужен другой компонент.
+
+### `FocusTrap` с `clickOutsideDeactivates`
+
+```ts
+focusTrapOptions={{
+    clickOutsideDeactivates: true,
+    fallbackFocus: targetRef.current!,
+    ...
+}}
+```
+
+- `clickOutsideDeactivates` — клик вне → FocusTrap отпускает фокус,
+  но outside-handler всё равно закрывает dropdown. Это **защита**:
+  FocusTrap не борется с outside-handler'ом.
+- `fallbackFocus: targetRef.current!` — если FocusTrap не может найти
+  focusable элемент внутри, поставить фокус на target (non-null
+  assertion обязателен потому что при первой активации targetRef
+  уже mounted).
+
+### `role="dialog" aria-modal="true"` на Dropdown
+
+Семантика модального диалога для содержимого (календарь). Screen reader
+объявит как модал. **Jарко** (не опционально), `...rest` идёт в
+Dropdown после `role`/`aria-modal`, но `role` и `aria-modal` не
+подлежат перебиванию снаружи потребителя (IDatePickerExtendedProps не
+принимает role).
+
+### `data-tx={process.env.npm_package_version}` — есть
+
+Стандарт библиотеки. Не удалять.
+
+### `setRef` — double-duty ref
+
+```ts
+const setRef = (node: HTMLDivElement | null) => {
+    containerRef.current = node;
+    if (typeof ref === "function") ref(node);
+    else if (ref) ref.current = node;
+};
+```
+
+Один DOM-узел = target для Dropdown (`targetRef`) + forwarded ref.
+
+---
+
+## Инварианты
+
+- **`forwardRef`** на root — обязателен (нужен для тулов).
+- **`mouseUsedRef`** — не удалять. Управляет UX focus-trap'а.
+- **Outside-handler проверяет оба ref'а** (containerRef + dropdownRef) —
+  не сводить к одному.
+- **`mouseUsedRef.current = false` в else-ветке useEffect** — сбросить
+  флаг при каждом закрытии, иначе следующий цикл не получит корректный
+  initialFocus.
+- **`role="dialog" aria-modal="true"`** на Dropdown — обязательно.
+- **`clickOutsideDeactivates: true`** в FocusTrap — иначе outside-click
+  не закрывает dropdown (FocusTrap борется).
+- **`setDropdownOpen(false)` в `handleChangeDate`** — выбор даты
+  закрывает dropdown. Неопциональное поведение.
+- **Esc → закрытие независимо от defaultPrevented** — осознанное
+  решение. Не фильтровать.
+- **Render-props `renderTarget` и `renderDropdownHeaderTarget`** —
+  единственный способ вставить target. Не принимать children.
+
+---
+
+## Accessibility
+
+- **`FocusTrap`** (`focus-trap-react`) — клавиатурный фокус заперт
+  внутри dropdown'а, Tab ходит по кнопкам календаря.
+- **`role="dialog" aria-modal="true"`** на Dropdown — семантика модала.
+- **Esc** — закрывает dropdown.
+- **`initialFocus`/`returnFocusOnDeactivate`** — условно, только для
+  клавиатурного открытия. При мышином открытии фокус не трогается
+  (UX-паттерн).
+- **`<div role="presentation">`** вокруг календаря — убирает лишнюю
+  семантику. Сам Calendar имеет свою ARIA.
+- **Mobile** — собственная разметка с `DropdownMobileHeader`/`Body`,
+  включая кнопку закрытия (`DropdownMobileClose`).
+
+---
+
+## Дизайн-токены
+
+**Нет собственных.** Dropdown и Calendar — источники всех визуальных
+токенов.
+
+---
+
+## Связанные компоненты
+
+- `Dropdown` (`src/components/Dropdown`) — контейнер (Portal + positioning).
+- `Calendar` (`src/components/Calendar`) — собственно выбор даты.
+- `DropdownMobile*` (`src/components/Dropdown/mobile`) — мобильные
+  подкомпоненты (Header/Body/Close).
+- `FocusTrap` (`focus-trap-react`) — внешний пакет для захвата фокуса.
+- `DateField` (`src/components/DateField`) — основной потребитель.
+- `DateRange` (`src/components/DateRange`) — потребитель для диапазона.
+- `MonthYearField` (`src/components/MonthYearField`) — потребитель
+  для месяца/года.
+
+---
+
+## Stories
+
+**Нет собственных stories.** Документируется косвенно через
+`DateField`/`DateRange`/`MonthYearField`.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/DateRange.md

@@ -0,0 +1,275 @@
+---
+component: DateRange
+category: Form
+figma-node: ""
+figma-file: ""
+related: [DateField, DatePickerExtended, Calendar, MonthYearField]
+tokens: []
+stories: stories/DateRange/DateRange.stories.tsx
+version: "1.0"
+---
+
+# DateRange
+
+## Назначение
+
+Layout-контейнер для выбора **диапазона дат** (от … до) с опциональными
+кнопками "сдвинуть диапазон назад/вперёд" на фиксированную величину
+(день/неделя/месяц/квартал/год). Сам **не рендерит пикеры** — принимает
+их через render-props (`renderPickerFrom`, `renderPickerTo`,
+`renderButtonBack`, `renderButtonForward`), потребитель обычно
+передаёт два `DateField`.
+
+Автоматически **валидирует пересечение**: если пользователь поставил
+`from > to`, компонент очищает `to` (или наоборот очищает `from`, если
+пользователь ставит `to < from`).
+
+Используй когда: нужен диапазон дат в форме (например, фильтр периода).
+Не используй когда: нужна **одна** дата — бери `DateField`; нужен выбор
+одного **периода** (месяц/квартал) — `MonthYearField`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/DateRange/
+├── DateRange.tsx                   # FC, НЕ forwardRef
+├── enums.ts                        # EDateRangeShiftUnit (day/week/month/quarter/year)
+├── index.ts                        # Barrel
+├── styles/DateRange.module.less    # .dateRange flex + .separator 20x20 + .dateRangeButton z-index: 1
+└── __tests__/DateRange.test.tsx
+```
+
+Особенности:
+- **НЕ `forwardRef`** — FC. Ref-форвардинг не реализован. Известный
+  AI-ready debt.
+- **Render-props-first** — `renderPickerFrom`, `renderPickerTo`,
+  `renderButtonBack`, `renderButtonForward` — все 4 обязательны.
+- **`moment.js`** для арифметики сдвига диапазона.
+- **Тесты есть** — `__tests__/DateRange.test.tsx` покрывает валидацию
+  пересечения и сдвиги.
+
+---
+
+## Варианты и props
+
+### `IDateRangeProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange">`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `value` | `TDateRangeValue = [string, string]` | — | Диапазон `[from, to]` в формате `YYYY-MM-DD`. |
+| `onChange` | `(value: [string, string]) => void` | — | Вызывается при изменении любой даты или при сдвиге. |
+| `shiftAmount` | `number` | `1` | Величина сдвига диапазона. |
+| `shiftUnit` | `EDateRangeShiftUnit` | `MONTH` | Единица сдвига (`"day" \| "week" \| "month" \| "quarter" \| "year"` — значения moment-совместимы). |
+| `hideNavigation` | `boolean` | `false` | Скрыть кнопки сдвига. |
+| `renderPickerFrom` | `(props: IDateRangePickerProvideProps) => ReactNode` | — | Обязателен. Рендерит поле "от". |
+| `renderPickerTo` | `(props: IDateRangePickerProvideProps) => ReactNode` | — | Обязателен. Рендерит поле "до". |
+| `renderButtonBack` | `(props: IDateRangeButtonProvideProps) => ReactNode` | — | Обязателен. Рендерит кнопку "назад". |
+| `renderButtonForward` | `(props: IDateRangeButtonProvideProps) => ReactNode` | — | Обязателен. Рендерит кнопку "вперёд". |
+| `className`, `...HTMLDivAttributes` | — | — | Стандартные. |
+
+### Provide-props
+
+**`IDateRangePickerProvideProps`:**
+```ts
+{ value: string; onChange: (value: string) => void; }
+```
+
+**`IDateRangeButtonProvideProps`:**
+```ts
+{
+    children: ReactNode;      // стрелка-иконка Caretleft/rightStrokeSrvIcon20
+    className: string;        // .dateRangeButton + .disabled при пустом диапазоне
+    onClick: () => void;      // shiftRangeBack / shiftRangeForward
+    disabled: boolean;        // true если start или end пустые
+}
+```
+
+### `TDateRangeValue = [string, string]`
+
+Кортеж из двух строк. Пустая строка = "дата не задана". Это важно: **не
+`undefined`, а именно `""`**. Потребитель должен всегда передавать
+массив длиной 2.
+
+### `EDateRangeShiftUnit`
+
+```ts
+enum EDateRangeShiftUnit {
+    DAY = "day",
+    WEEK = "week",
+    MONTH = "month",
+    QUARTER = "quarter",
+    YEAR = "year",
+}
+```
+
+Значения — строки, совместимые с `moment().add(n, unit)`.
+
+---
+
+## Ключевые особенности реализации
+
+### Валидация пересечения: очистка при инверсии
+
+```ts
+const handleChangePickerFrom = (date: string) => {
+    if (!date || !end || date <= end) {
+        onChange([date, end]);
+    } else {
+        onChange([date, ""]);   // from > to → чистим to
+    }
+};
+
+const handleChangePickerTo = (date: string) => {
+    if (!date || !start || date >= start) {
+        onChange([start, date]);
+    } else {
+        onChange(["", date]);   // to < from → чистим from
+    }
+};
+```
+
+**Важная деталь:** сравнение `date <= end` / `date >= start` — это
+**лексикографическое** сравнение строк. Работает **только** для формата
+`YYYY-MM-DD` (ISO). Для других форматов (`DD.MM.YYYY` и т. п.) сравнение
+сломается.
+
+**Инвариант:** `value` и всё, что DateRange возвращает через `onChange`,
+строго в `YYYY-MM-DD`. Потребитель отвечает за форматирование в
+собственных пикерах (`DateField` сам конвертирует через `format` проп,
+но по умолчанию тоже `YYYY-MM-DD`).
+
+### Сдвиг диапазона — `moment` арифметика
+
+```ts
+const shiftRangeBack = () => {
+    if (!start || !end) return;
+    const momentStart = moment(start, dateFormatYYYYMMDD);
+    const momentEnd = moment(end, dateFormatYYYYMMDD);
+    onChange([
+        momentStart.subtract(shiftAmount, shiftUnit).format(dateFormatYYYYMMDD),
+        momentEnd.subtract(shiftAmount, shiftUnit).format(dateFormatYYYYMMDD),
+    ]);
+};
+```
+
+**Защита:** если start или end пустые → no-op. Кнопка тоже
+`disabled={!(start && end)}`.
+
+**Сдвигаются обе границы на одно и то же значение** — не "растянуть
+диапазон", а "сдвинуть целиком". Размер диапазона сохраняется.
+
+**Граничный случай:** если `shiftUnit=MONTH` и `start=2026-01-31`, то
+`moment.subtract(1, 'month') = 2025-12-31` (moment сам обрабатывает
+конец месяца). Для шага `1 year + 29 feb` — может быть скачок на 1
+день. Это поведение `moment` и осознанное допущение.
+
+### Separator — `MinusStrokeSrvIcon20`
+
+Между двумя пикерами рендерится иконка-минус 20x20 (`flex-shrink: 0`,
+чтобы не сжималась).
+
+### Кнопки сдвига — позиция z-index: 1
+
+```less
+.dateRangeButton { z-index: 1; }
+```
+
+**Зачем:** в макете кнопки могут визуально перекрываться с soft-edge
+полями пикеров (Dropdown может показываться поверх). z-index: 1 даёт
+кнопкам приоритет над содержимым пикера при совпадении контекста.
+**Не удалять** — без этого кнопки могут "уйти под" пикер.
+
+### `disabled` = нет диапазона (пусто)
+
+Кнопки сдвига становятся `disabled`, пока не выбраны **обе** даты.
+Логично — не можем сдвинуть "не определённый" диапазон.
+
+### `hideNavigation` — скрывает кнопки, не сам сдвиг
+
+Внешний `shiftRange*` не публичные методы — доступ к сдвигам есть
+только через UI-кнопки. Если `hideNavigation=true`, сдвиги недоступны.
+
+Если нужны **кастомные триггеры сдвига** (например, кнопки в другом
+месте UI), это не поддерживается — потребитель должен сам арифметику
+`moment` реализовать и пушить новое значение.
+
+### Нет forwardRef — известный debt
+
+`React.FC` без ref-forwarding. Потребителю ref недоступен. Если нужен —
+оборачивать в собственный div с ref (deviates от паттерна).
+
+### `data-tx={process.env.npm_package_version}` — **нет**
+
+Этот компонент **не** ставит data-tx. Исключение из общего правила
+библиотеки. Возможно debt — при ревизии может быть добавлен.
+
+---
+
+## Инварианты
+
+- **`value` и `onChange` — в `YYYY-MM-DD`** (`dateFormatYYYYMMDD`).
+  Лексикографическое сравнение не будет работать в других форматах.
+- **Все 4 render-props обязательны** — `renderPickerFrom`, `renderPickerTo`,
+  `renderButtonBack`, `renderButtonForward`.
+- **Инверсия диапазона очищает противоположную границу** —
+  `from > to` → чистим `to`; `to < from` → чистим `from`. Не менять.
+- **Сдвиг блокируется при пустом диапазоне** — `!start || !end` → no-op +
+  `disabled: true`.
+- **`shiftUnit` значения совместимы с moment** — не добавлять значения,
+  не поддерживаемые `moment.add/subtract`.
+- **Separator — иконка минуса 20x20** — не заменять на "–" текст
+  (не масштабируется).
+- **`.dateRangeButton { z-index: 1 }`** — не удалять.
+- **НЕТ forwardRef** — известный debt, не добавлять точечно.
+- **НЕТ data-tx** — наследованный пропуск.
+
+---
+
+## Accessibility
+
+- **Кнопки "назад"/"вперёд"** — потребитель отвечает за `aria-label`
+  (через render-props). DateRange не задаёт `aria-label`.
+- **`disabled`** — передаётся в render-props, обычно попадает на
+  `<button disabled>`.
+- **Separator** — декоративная иконка, screen reader её не озвучит
+  (SVG без `role`/`aria-label`).
+- **Связь полей from-to** — ARIA связи не выставлены. Если нужна
+  явная связь "это пара полей" — обёртывать в `<fieldset><legend>`.
+
+---
+
+## Дизайн-токены
+
+**Нет.** Layout-компонент, разметка flex + фиксированный separator.
+
+---
+
+## Связанные компоненты
+
+- `DateField` (`src/components/DateField`) — типичный `renderPickerFrom`/`To`.
+- `DatePickerExtended` — низкоуровневый пикер.
+- `MonthYearField` — близнец, но для выбора отдельного периода.
+- `Button`/`ButtonIcon` — типично для `renderButtonBack`/`Forward`.
+
+---
+
+## Stories
+
+`stories/DateRange/DateRange.stories.tsx`
+Примеры: `stories/DateRange/examples/`
+
+Типовые stories:
+- `Default` — два DateField + кнопки сдвига
+- `HideNavigation` — без кнопок
+- `ShiftUnits` — перебор DAY/WEEK/MONTH/QUARTER/YEAR
+- `Playground` — интерактив
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |