@sberbusiness/triplex-next-mcp-server 1.50.0-beta → 1.53.1

package/bundle/components/LoaderSmall.md

@@ -96,9 +96,9 @@ Loader: `Element_Background_Brand` использует также `LoaderMiddle
 - **`displayName = "LoaderSmall"`** — используется в React DevTools.
 - **Значения `ELoaderSmallTheme`** (`brand` / `neutral`) и наличие `ELoaderSmallSize` в barrel —
   часть публичного API, удаление или переименование — breaking change.
-- **`ILoaderSmallProps` — не только props этого компонента.** `DropdownMobileLoader` строит из
-  него свой публичный интерфейс: `IDropownMobileLoaderProps extends Omit<ILoaderSmallProps,
-  "theme" | "size">` (`src/components/Dropdown/mobile/DropdownMobileLoader.tsx:8`). Любое
+- **`ILoaderSmallProps` — не только props этого компонента.** `PullerLoader` строит из
+  него свой публичный интерфейс: `IPullerLoaderProps extends Omit<ILoaderSmallProps,
+  "theme" | "size">` (`src/components/Puller/PullerLoader.tsx:8`). Любое
   изменение формы `ILoaderSmallProps` автоматически меняет публичный API и этого компонента.
 - **Токены `Loader-*` общие для семейства** — переименование ломает темизацию у потребителей
   и затрагивает `LoaderMiddle`.
@@ -135,7 +135,7 @@ Loader: `Element_Background_Brand` использует также `LoaderMiddle
   вида `queryByRole("status")` → `null`.
   Тему выбирает по теме кнопки (`SECONDARY` / `SECONDARY_LIGHT` → `BRAND`,
   остальные → `NEUTRAL`), размер — по размеру кнопки.
-- `Dropdown` (`DropdownList`, `DropdownMobileList`, `DropdownMobileLoader`), `SuggestField`,
+- `Dropdown` (`DropdownList`), `Puller` (`PullerList`, `PullerLoader`), `SuggestField`,
   `ChipSuggest`, `SelectExtendedField`, `ListItemLoading` — показывают `LoaderSmall` с темой
   `BRAND` во время подгрузки данных. В `related` не входят: это контракт по рендеру, ссылка
   стоит с их стороны. `Button` — исключение «потребитель, опирающийся на хрупкую деталь»
@@ -172,6 +172,7 @@ Loader: `Element_Background_Brand` использует также `LoaderMiddle
 |---|---|
 | 2026-08-06 | Создан документ. AI-рефакторинг: JSDoc на компоненте, props и значениях `ELoaderSmallTheme`, документирован неиспользуемый `ELoaderSmallSize`, порядок импортов приведён к codestyle, константы-маппинги переименованы в `THEME_TO_CLASS_NAME_MAP` / `SIZE_TO_CLASS_NAME_MAP`, в стилях объединено дублирующееся объявление анимации точек — сама анимация задана один раз на `.dot`, а у `.dot1` / `.dot2` / `.dot3` осталась только `animation-delay` (правило `.dot1` с нулевой задержкой обязательно: без него класс исчезнет из CSS-модуля и из разметки), unit-тесты расширены с 3 до 6 кейсов. В stories `controls: { disable: true }` перенесён на верхний уровень `parameters` — внутри `docs` он не применялся. Публичный API, DOM и визуальное поведение не изменены. |
 | 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны имена без строки в `docs/ai/ROADMAP.md` (`ListItemLoading`); из `related` убраны потребители `Dropdown`, `SuggestField`, `SelectExtendedField` — ссылка на контракт по рендеру стоит с их стороны; `Button` оставлен как исключение «потребитель, опирающийся на хрупкую деталь». Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
+| 2026-10-21 | Переход на `Puller` (TRIPLEX-961): `IDropownMobileLoaderProps` переименован в `IPullerLoaderProps` и перенесён в `src/components/Puller/PullerLoader.tsx`. |
 
 ---
 

package/bundle/components/MonthYearRange.md

@@ -0,0 +1,334 @@
+---
+component: MonthYearRange
+category: Date components
+related: [DateRange]
+tokens: []
+stories: stories/MonthYearRange/MonthYearRange.stories.tsx
+version: "1.0"
+---
+
+# MonthYearRange
+
+## Назначение
+
+Управляемый диапазон месяцев с двумя полями «от» / «до» и кнопками сдвига обеих границ назад и вперёд. Поля и кнопки предоставляет потребитель через render-props; компонент задаёт раскладку, согласует выбранные границы и выполняет арифметику дат.
+
+Используй когда: нужно выбрать период с точностью до месяца и перелистывать его на месяц, квартал или год.
+
+Не используй когда: нужен диапазон полных дат с выбором дня — `DateRange`; нужен один месяц — `MonthYearField` или `ChipMonthYearPicker`; нужна только сетка календаря — `Calendar`.
+
+---
+
+## Варианты и props
+
+`IMonthYearRangeProps` наследует HTML-атрибуты `div` без `defaultValue` и стандартного `onChange`. Состояние диапазона хранит потребитель: компонент вызывает `onChange`, а новые значения получает через `value`.
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `value` | `TMonthYearRangeValue` | Кортеж `[start, end]` в формате `format` (по умолчанию `YYYYMMDD`). Пустая строка означает невыбранную границу. |
+| `onChange` | Callback | Получает обе границы при изменении любого поля или сдвиге диапазона. |
+| `renderPickerFrom` | Render-prop | Поле выбора месяца «от». |
+| `renderPickerTo` | Render-prop | Поле выбора месяца «до». |
+| `renderButtonBack` | Render-prop | Кнопка сдвига назад. Обязателен по типу даже при `hideNavigation`. |
+| `renderButtonForward` | Render-prop | Кнопка сдвига вперёд. Обязателен по типу даже при `hideNavigation`. |
+
+### Опциональные props
+
+| Prop | По умолчанию | Описание |
+|---|---|---|
+| `format` | `dateFormatYYYYMMDD` | Формат дат moment в `value` и в `onChange` пикеров. Передаётся пикерам в render-props вместе с `value` и `onChange`. |
+| `shiftAmount` | `1` | Величина сдвига обеих границ в единицах `shiftUnit`. |
+| `shiftUnit` | `EMonthYearRangeShiftUnit.MONTH` | `MONTH`, `QUARTER` или `YEAR`: значения enum — строки `month`, `quarter`, `year` для Moment. |
+| `hideNavigation` | `false` | Скрывает обе кнопки: их render-props не вызываются. |
+| `className` | — | Дополнительный класс корневого контейнера, объединяется с внутренним через `clsx`. |
+
+### Значение и согласование границ
+
+Формат дат задаёт `format`, по умолчанию — `dateFormatYYYYMMDD` из `src/consts/DateConst.ts`. Хотя поля выбирают месяц, компонент хранит полную дату и не приводит день к первому числу месяца. Допускается неполный диапазон: `["", end]`, `[start, ""]` или `["", ""]`.
+
+Обработчики полей сравнивают даты хронологически через `isDateAfter` из `src/components/DateRange/utils.ts`: обе строго парсятся `moment(value, format, true)`, сравнение строк не используется.
+
+- новая граница «от» больше непустой «до» → `onChange([date, ""])`;
+- новая граница «до» меньше непустой «от» → `onChange(["", date])`;
+- равные границы сохраняются; если новая или противоположная граница пустая, порядок не проверяется.
+
+Если хотя бы одна из сравниваемых дат невалидна в `format`, порядок считается корректным и значение записывается как есть: компонент не валидирует строку пикера в обработчике поля. Потребитель отвечает за формат и исходный порядок `value`.
+
+### Что получают render-props
+
+| Поле | Кому передаётся | Контракт |
+|---|---|---|
+| `value` | Пикерам | Соответствующая строка `start` или `end`. |
+| `format` | Пикерам | Значение `format` компонента. При spread в `MonthYearField` задаёт полю тот же формат. |
+| `onChange` | Пикерам | Принимает новую строку и согласует границы по правилам выше. |
+| `children` | Кнопкам | Иконка направления: `CaretleftStrokeSrvIcon20` / `CaretrightStrokeSrvIcon20` с `paletteIndex={5}`. |
+| `className` | Кнопкам | Класс `monthYearRangeButton` из LESS-модуля; отдельный класс `disabled` не добавляется. |
+| `disabled` | Кнопкам | `true`, если хотя бы одна граница пустая. Применить его к DOM-кнопке обязан потребитель. |
+| `onClick` | Кнопкам | Обработчик сдвига; при неполном или невалидном диапазоне не вызывает `onChange`. |
+
+В примерах объект пикера целиком передаётся в `MonthYearField`, объект кнопки — в `ButtonIcon`. Собственных props `size`, `status` или `limitRange` у диапазона нет: их настраивают на полях. `format` задаётся на MonthYearRange и приходит в объект пикера. Не задавай `format` полю отдельно: если он стоит в JSX до spread, его перезапишет формат диапазона; если после — формат поля и диапазона разойдутся.
+
+### Сдвиг диапазона
+
+- Сдвиг (`shiftDateRange` из `src/components/DateRange/utils.ts`, общий с `DateRange`) строго парсит обе границы через `moment(value, format, true)`. Если хотя бы одна невалидна, функция возвращает `null` и `onChange` не вызывается.
+- Кнопка назад сдвигает границы на `-shiftAmount`, вперёд — на `shiftAmount` через `Moment.add`. Обе границы сдвигаются независимо на одну величину; день сохраняется или сокращается до последнего дня целевого месяца. Например, `20240331` минус месяц → `20240229`, `20240229` плюс год → `20250228`.
+- `shiftAmount` передаётся в Moment без проверки: рассчитан на целые положительные значения, отрицательное меняет направление кнопок.
+- Сдвиг не исправляет порядок входного кортежа и не проверяет ограничения календаря `limitRange`. Потребитель согласует их с полями самостоятельно.
+- Результат сериализуется обратно в `format`. Сдвиг на месяц, квартал или год может изменить длину диапазона в днях.
+
+### Корневой элемент
+
+`ref` указывает на корневой `div`. Остальные HTML-атрибуты (`id`, `data-*`, `aria-*`, `style`, обработчики событий) передаются на этот же элемент. `children` допускается унаследованным типом, но содержимое контейнера задаётся render-props и иконкой-разделителем.
+
+---
+
+## Дизайн-токены
+
+Собственных дизайн-токенов нет: `styles/MonthYearRange.module.less` задаёт только flex-раскладку, `z-index` кнопок и размер разделителя 16 × 16 px. Цвета иконок задаются `paletteIndex={5}`.
+
+Внешний вид полей и кнопок зависит от компонентов, возвращённых из render-props. Их токены переопределяются через `ThemeProvider`; см. `MonthYearField-ai.md`, `ButtonIcon-ai.md` и `ThemeProvider-ai.md`.
+
+---
+
+## Инварианты
+
+- `forwardRef` обязателен; корневой DOM-элемент и ref-target — `HTMLDivElement`.
+- Публичные имена `MonthYearRange`, `IMonthYearRangeProps`, `IMonthYearRangeButtonProvideProps`, `IMonthYearRangePickerProvideProps`, `TMonthYearRangeValue` и `EMonthYearRangeShiftUnit` экспортируются через `src/components/MonthYearRange/index.ts`; интерфейсы и `TMonthYearRangeValue` живут в `types.ts`, компонент — в `MonthYearRange.tsx`, enum — в `enums.ts`. Имена, типы и enum-значения нельзя менять без согласования. Собственного `utils.ts` нет: сравнение и сдвиг импортируются из `DateRange/utils.ts`, поэтому значения `EMonthYearRangeShiftUnit` должны оставаться строковыми единицами `moment`.
+- Формат по умолчанию `YYYYMMDD` и пустая строка как невыбранная граница — часть контракта. `value` и аргумент `onChange` пикера должны быть в формате `format`.
+- `disabled` кнопок зависит только от пустых границ; невалидные даты блокирует сам обработчик сдвига.
+- Порядок содержимого: кнопка назад → поле «от» → иконка-разделитель → поле «до» → кнопка вперёд. `hideNavigation` исключает вызовы обоих render-props кнопок.
+- `displayName` — `"MonthYearRange"`; React 17-совместимость сохраняется, React 18-only API не добавлять.
+- Story IDs `components-date-components-monthyearrange--*` связаны с baseline `__screenshots__/date-components-monthyearrange--{story}--{xs|xl}.png`: test-runner удаляет префикс `components-` из имени файла. Не переименовывать stories без обновления скриншот-тестов.
+
+---
+
+## Accessibility
+
+- Корневой `div` — контейнер без собственной роли, фокус-менеджмента или клавиатурной навигации. Переданные `aria-*` относятся к нему.
+- Доступные имена полей «от» / «до» и кнопок с иконками задаёт потребитель. В `renderButtonBack` / `renderButtonForward` следует передать локализованные `aria-label` или `title`; компонент текста не добавляет.
+- Переданный render-prop `disabled` нужно применить к нативной кнопке. Даже если потребитель его проигнорирует, обработчик дополнительно блокирует сдвиг неполного диапазона.
+- Поведение полей, календаря, сообщения об ошибке и порядок табуляции определяются возвращёнными компонентами. Собственного `aria-live` и автоматического объявления изменённого диапазона нет.
+
+---
+
+## Связанные компоненты
+
+- `DateRange` — альтернатива для диапазона полных дат. Имеет похожий render-prop API и дополнительные единицы сдвига `DAY` / `WEEK`; валидность дат перед сдвигом проверяет так же.
+- `MonthYearField` — поле выбора одного месяца, используемое в примерах для обеих границ. Компонент диапазона не импортирует его напрямую.
+- `ButtonIcon` — кнопка для переданных иконки, класса, `disabled` и `onClick` в примерах; доступное имя добавляет потребитель.
+
+В `related` включён `DateRange` как альтернатива. Поля и кнопки выбирает потребитель, прямой зависимости по рендеру или наследования их интерфейсов в MonthYearRange нет.
+
+---
+
+## Stories
+
+Основные истории: `stories/MonthYearRange/MonthYearRange.stories.tsx`
+Файлы примеров: `stories/MonthYearRange/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивное управление `shiftAmount`, `shiftUnit` и `hideNavigation`. |
+| `Default` | `Default.tsx` | Два пустых `MonthYearField`, неактивные кнопки и сдвиг на месяц. |
+| `Sizes` | `Sizes.tsx` | Поля SM / MD / LG; размер задаётся полям в render-props. |
+| `WithoutNavigation` | `WithoutNavigation.tsx` | Только поля и разделитель; кнопки скрыты. |
+| `Production` | `Production.tsx` | Пример `Example: production`: поля с `HelpBox` в постфиксе. |
+| `VisualTests` | `VisualTests.tsx` | Заполненный диапазон `["19700101", "19700101"]` с активными кнопками. |
+
+`Playground` исключён из скриншот-тестов. Остальные пять stories покрыты десятью baseline для viewport xs / xl в `__screenshots__/`. `Playground` и `VisualTests` не включаются в MCP bundle.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-10-08 | Создан документ |
+| 2026-10-15 | Добавлен prop `format` (по умолчанию `YYYYMMDD`), передаётся пикерам в render-props (`IMonthYearRangePickerProvideProps.format`). Границы сравниваются хронологически вместо сравнения строк. Сравнение и сдвиг используют `isDateAfter` и `shiftDateRange` из `DateRange/utils.ts`. Интерфейсы props и `TMonthYearRangeValue` вынесены в `types.ts` |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/MonthYearRange/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    ButtonIcon,
+    MonthYearField,
+    MonthYearRange,
+    EMonthYearRangeShiftUnit,
+    IMonthYearRangeButtonProvideProps,
+    IMonthYearRangePickerProvideProps,
+    TMonthYearRangeValue,
+} from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [value, setValue] = useState<TMonthYearRangeValue>(["", ""]);
+    const renderPicker = (props: IMonthYearRangePickerProvideProps) => (
+        <MonthYearField label="Label" placeholder="Select to proceed" {...props} />
+    );
+    const renderButton = (props: IMonthYearRangeButtonProvideProps) => <ButtonIcon {...props} />;
+
+    return (
+        <div style={{ maxWidth: "400px" }}>
+            <MonthYearRange
+                value={value}
+                onChange={setValue}
+                shiftAmount={1}
+                shiftUnit={EMonthYearRangeShiftUnit.MONTH}
+                renderPickerFrom={renderPicker}
+                renderPickerTo={renderPicker}
+                renderButtonBack={renderButton}
+                renderButtonForward={renderButton}
+            />
+        </div>
+    );
+};
+```
+
+### Sizes
+
+`stories/MonthYearRange/examples/Sizes.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    ButtonIcon,
+    MonthYearField,
+    MonthYearRange,
+    EMonthYearRangeShiftUnit,
+    IMonthYearRangeButtonProvideProps,
+    IMonthYearRangePickerProvideProps,
+    TMonthYearRangeValue,
+    EComponentSize,
+} from "@sberbusiness/triplex-next";
+
+interface ISizeItemProps {
+    size: EComponentSize;
+}
+
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const [value, setValue] = useState<TMonthYearRangeValue>(["", ""]);
+
+    const renderPicker = (props: IMonthYearRangePickerProvideProps) => (
+        <MonthYearField label="Label" placeholder="Select to proceed" size={size} {...props} />
+    );
+    const renderButton = (props: IMonthYearRangeButtonProvideProps) => <ButtonIcon {...props} />;
+
+    return (
+        <div style={{ maxWidth: 500 }}>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
+            <MonthYearRange
+                value={value}
+                onChange={setValue}
+                shiftAmount={1}
+                shiftUnit={EMonthYearRangeShiftUnit.MONTH}
+                renderPickerFrom={renderPicker}
+                renderPickerTo={renderPicker}
+                renderButtonBack={renderButton}
+                renderButtonForward={renderButton}
+            />
+        </div>
+    );
+};
+
+const SIZES = Object.values(EComponentSize);
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
+```
+
+### WithoutNavigation
+
+`stories/MonthYearRange/examples/WithoutNavigation.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    MonthYearField,
+    MonthYearRange,
+    IMonthYearRangePickerProvideProps,
+    TMonthYearRangeValue,
+} from "@sberbusiness/triplex-next";
+
+export const WithoutNavigation = () => {
+    const [value, setValue] = useState<TMonthYearRangeValue>(["", ""]);
+    const renderPicker = (props: IMonthYearRangePickerProvideProps) => (
+        <MonthYearField label="Label" placeholder="Select to proceed" {...props} />
+    );
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <MonthYearRange
+                value={value}
+                onChange={setValue}
+                hideNavigation
+                renderPickerFrom={renderPicker}
+                renderPickerTo={renderPicker}
+                renderButtonBack={() => null}
+                renderButtonForward={() => null}
+            />
+        </div>
+    );
+};
+```
+
+### Production
+
+`stories/MonthYearRange/examples/Production.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    ButtonIcon,
+    MonthYearField,
+    MonthYearRange,
+    EMonthYearRangeShiftUnit,
+    IMonthYearRangeButtonProvideProps,
+    IMonthYearRangePickerProvideProps,
+    TMonthYearRangeValue,
+    HelpBox,
+    ETooltipSize,
+} from "@sberbusiness/triplex-next";
+
+export const Production = () => {
+    const [value, setValue] = useState<TMonthYearRangeValue>(["", ""]);
+
+    const renderPicker = (props: IMonthYearRangePickerProvideProps) => (
+        <MonthYearField
+            label="Label"
+            placeholder="Select to proceed"
+            targetProps={{ postfix: <HelpBox tooltipSize={ETooltipSize.SM}>HelpBox text</HelpBox>, inputProps: {} }}
+            {...props}
+        />
+    );
+    const renderButton = (props: IMonthYearRangeButtonProvideProps) => <ButtonIcon {...props} />;
+
+    return (
+        <div style={{ maxWidth: 660 }}>
+            <MonthYearRange
+                value={value}
+                onChange={setValue}
+                shiftAmount={1}
+                shiftUnit={EMonthYearRangeShiftUnit.MONTH}
+                renderPickerFrom={renderPicker}
+                renderPickerTo={renderPicker}
+                renderButtonBack={renderButton}
+                renderButtonForward={renderButton}
+            />
+        </div>
+    );
+};
+```
+