@sberbusiness/triplex-next-mcp-server 1.43.0-beta → 1.45.0-beta

package/bundle/components/DatePickerExtended.md

@@ -1,11 +1,9 @@
 ---
 component: DatePickerExtended
-category: Internal
-figma-node: ""
-figma-file: ""
-related: [DateField, DateRange, MonthYearField, Calendar, Dropdown, FocusTrap]
+category: Date components
+related: [Calendar, Dropdown, DateField, MonthYearField, ChipDatePicker]
 tokens: []
-stories: ""
+stories: stories/DatePickerExtended/DatePickerExtended.stories.tsx
 version: "1.0"
 ---
 
@@ -13,330 +11,479 @@ version: "1.0"
 
 ## Назначение
 
-Внутренняя "база" для всех полей выбора даты: объединяет `Dropdown`
-(с desktop + mobile веткой), `Calendar` (внутри dropdown'а) и
-`FocusTrap` (клавиатурная навигация). Управляет открытием/закрытием
-dropdown'а (controlled/uncontrolled внутри себя — state), ловит
-`Esc` для закрытия, отличает "мышиное" взаимодействие от "клавиатурного"
-(флаг `mouseUsedRef`) для настройки `FocusTrap`.
+Связка «произвольный целевой элемент + выпадающий календарь». Компонент рендерит целевой элемент (render-prop `renderTarget`) и `Calendar` внутри `Dropdown`, хранит состояние открытости календаря и отдаёт его целевому элементу через `DatePickerExtendedContext`. На мобильной ширине экрана вместо десктопного дропдауна открывается полноэкранный `DropdownMobile` с заголовком из `renderDropdownHeaderTarget`.
 
-Публично импортируется потребителями вроде `DateField`, `DateRange`,
-`MonthYearField`, но **render-props-интерфейс** (`renderTarget`,
-`renderDropdownHeaderTarget`) делает его сложным для прямого
-использования в приложениях — обычно его оборачивают.
+Используй когда: строишь собственный компонент выбора даты с нестандартным триггером (поле, чип, кнопка) и хочешь переиспользовать готовую механику дропдауна с календарём. Именно так устроены `DateField`, `MonthYearField` и `ChipDatePicker`.
 
-Используй когда: строишь новый компонент выбора даты со своим target'ом
-и своей валидацией — DatePickerExtended даёт dropdown + calendar +
-focus management бесплатно.
-Не используй как замену `DateField`/`DateRange`/`MonthYearField` —
-бери эти готовые обёртки.
+Не используй когда: подходит готовый компонент — поле ввода даты (`DateField`), выбор месяца и года (`MonthYearField`), диапазон (`DateRange`, `MonthYearRange`), чип-фильтр (`ChipDatePicker`); или календарь нужен без дропдауна — тогда бери `Calendar` напрямую.
 
 ---
 
-## Файловая структура
+## Варианты и props
 
-```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 }
-```
+`IDatePickerExtendedProps` собирается из трёх источников: собственные props (ниже), props календаря (`ICalendarProps` без `adaptiveMode`, включая `ICalendarNestedProps`) и `alignment` из `IDropdownProps`. Плюс `React.HTMLAttributes<HTMLDivElement>` без `onChange` — они уходят на корневой `div`.
 
-Особенности:
-- **Нет `index.ts`** — импортируется как `import { DatePickerExtended } from ".../DatePickerExtended/DatePickerExtended"`.
-  Это намеренно — компонент считается "полупубличным" (используется
-  внутри библиотеки и потребителями при необходимости, но без красивого
-  barrel-a).
-- **Нет `__tests__`** — покрывается через тесты `DateField`.
-- **Нет собственных stories** — только через обёртки.
-- **Почти нет LESS** — один класс для мобильного max-height.
+### Обязательные props
 
----
+| Prop | Тип | Описание |
+|---|---|---|
+| `renderTarget` | `() => ReactNode` | Рендер целевого элемента. Вызывается внутри `DatePickerExtendedContext.Provider`, поэтому возвращённое дерево может читать и менять открытость календаря через контекст. |
+| `renderDropdownHeaderTarget` | `() => ReactNode` | Рендер целевого элемента в заголовке мобильного дропдауна (`DropdownMobileHeader`). Обычно — `DropdownMobileInput` с текущим значением. |
+| `pickedDate` | `string \| Moment \| null` | Выбранная дата (prop `Calendar`). Компонент неуправляемый только в части открытости — выбранную дату хранит потребитель. |
+| `onDateChange` | `(date: Moment) => void` | Вызывается при выборе даты в календаре. Компонент дополнительно закрывает дропдаун. |
 
-## Варианты и props
+### Собственные опциональные props
 
-### `IDatePickerExtendedProps`
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `dropdownTargetRef` | `RefObject<HTMLElement>` | корневой элемент | Элемент, относительно которого позиционируется дропдаун. Нужен, когда целевой элемент занимает не всю ширину корневого `div` (так делает `DateField`). |
+| `alignment` | `EDropdownAlignment` | `LEFT` | Выравнивание дропдауна относительно целевого элемента. |
+| `onDropdownOpen` | `() => void` | — | Дропдаун открылся (проброшен в `Dropdown.onOpen`). |
+| `onDropdownClose` | `() => void` | — | Дропдаун закрылся (проброшен в `Dropdown.onClose`). |
+| `focusTrapProps` | `FocusTrapProps` | — | Props `FocusTrap` (`focus-trap-react`) вокруг десктопного календаря. Переданный `focusTrapOptions` объединяется с внутренним: пользовательские ключи имеют приоритет. |
 
-```ts
-extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange">,
-        Pick<IDropdownProps, "alignment">,
-        ICalendarProps
-```
+### Props календаря
 
-**Рендер-пропсы (обязательные):**
+Пробрасываются в `Calendar` как есть: `pickType`, `format`, `defaultViewDate`, `limitRange`, `markedDays`, `disabledDays`, `reversedPick`, `onPageChange`, `onViewChange`, `dayHtmlAttributes`, `monthHtmlAttributes`, `yearHtmlAttributes`, `prevButtonProps`, `nextButtonProps`, `viewButtonProps`, `yesterdayButtonProps`, `todayButtonProps`, `tomorrowButtonProps`. Семантика — в `Calendar-ai.md`.
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `renderTarget` | `() => React.ReactNode` | Target (поле ввода) на десктопе. |
-| `renderDropdownHeaderTarget` | `() => React.ReactNode` | Target в заголовке dropdown'а в мобильном режиме (обычно тот же input, но в другом контейнере). |
+Исключение — `adaptiveMode`: он входит в `ICalendarProps`, но исключён из `IDatePickerExtendedProps` через `Omit`. Режим определяет версия дропдауна (десктопный — `false`, мобильный — `true`), задать его снаружи нельзя.
 
-**Dropdown:**
+Футер календаря (`yesterdayButtonProps`, `todayButtonProps`, `tomorrowButtonProps`) рендерится только при переданном `todayButtonProps` — без него «Вчера» и «Завтра» не появятся. «Вчера» и «Завтра» дополнительно требуют открытой страницы текущего месяца в режиме `DAYS`.
 
-| 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;
-}
-```
+### Что уходит на корневой элемент
+
+Всё, что не перечислено выше (`className`, `style`, `id`, `data-*`, `aria-*`, обработчики), спредится на корневой `div`. Собственные `onKeyDown` и `onMouseDown` компонента вызываются первыми, пользовательские — после них (не отменяются).
 
-Передаётся в `renderTarget` через контекст (target живёт в другой ветке
-дерева). `DateFieldTarget` и аналоги используют `useContext` для
-управления dropdown'ом из input'а.
+---
 
-### `DatePickerExtendedDropdown` — внутренний compound
+## Дизайн-токены
 
-`IDatePickerExtendedDropdownProps extends IDropdownProps` +
-`renderCalendar`, `renderHeaderTarget`, `focusTrapProps`.
-Не экспортируется публично.
+Собственных CSS-токенов нет. Единственный стиль компонента — `datePickerExtendedMobileDropdown` (`max-height: 100vh` для мобильного дропдауна). Внешний вид определяется `Calendar`, `Dropdown` и целевым элементом.
 
 ---
 
-## Ключевые особенности реализации
+## Инварианты
 
-### `mouseUsedRef` — отличение мышь vs клавиатура
+- `forwardRef` на компоненте — не убирать. Ref ведёт на корневой `div` и одновременно используется внутри как `containerRef` (позиционирование дропдауна и определение кликов «снаружи»), поэтому менять ref-target нельзя.
+- Публичный API (`DatePickerExtended`, `IDatePickerExtendedProps`, `DatePickerExtendedContext`, `IDatePickerExtendedContext`) экспортируется через `src/components/DatePickerExtended/index.ts` — переименования props и смена их типов недопустимы.
+- **Открыть календарь снаружи можно только через `DatePickerExtendedContext`** — управляемого prop открытости у компонента нет. Контекст экспортируется из barrel, поэтому целевой элемент пишется и внутри библиотеки (`DateField`, `MonthYearField`, `ChipDatePicker`), и в коде потребителя.
+- Форма контекста (`dropdownOpen`, `mouseUsedRef`, `setDropdownOpen`) — часть публичного API и одновременно контракт трёх внутренних потребителей. Её изменение ломает `DateFieldTarget`, `MonthYearFieldTarget` и `ChipDatePickerTarget` — править только вместе с ними.
+- `mouseUsedRef` — флаг «взаимодействие было мышью». Он выставляется на `mousedown` по корневому элементу и сбрасывается при закрытии дропдауна; от него зависят `initialFocus` и `returnFocusOnDeactivate` у `FocusTrap`. Не заменять на state: значение читается во время рендера дропдауна и не должно вызывать перерисовку.
+- `DatePickerExtendedDropdown` в barrel не экспортируется.
+- Размер дропдауна зафиксирован (`EComponentSize.MD`) и наружу не выведен.
+- Компонент не хардкодит текст: подписи кнопок календаря и `aria-label` целевого элемента задаёт потребитель. Библиотека мультиязычная.
+- React 17-совместимость (ветка `release-0`): не переводить на `useId` и другие React 18-only API.
 
-```ts
-const mouseUsedRef = useRef(false);
+---
 
-const handleMouseDown = (event) => {
-    mouseUsedRef.current = true;
-    onMouseDown?.(event);
-};
-```
+## Accessibility
 
-Сбрасывается при закрытии dropdown'а (в `useEffect`, ветка else).
-Используется в `FocusTrap`:
+- Дропдаун имеет `role="dialog"` и `aria-modal="true"`. Доступное имя диалога компонент не задаёт, и передать его через props нельзя: `...restProps` уходят на корневой `div`, а в `DatePickerExtendedDropdown` передаются только явно перечисленные props. Aria-атрибуты, переданные в `DatePickerExtended`, окажутся на корневом элементе, а не на диалоге.
+- Десктопный календарь обёрнут в `FocusTrap` (`focus-trap-react`):
+  - при открытии с клавиатуры фокус уходит внутрь календаря, при закрытии возвращается на целевой элемент;
+  - при открытии мышью (`mouseUsedRef`) фокус не перехватывается и не возвращается — иначе после клика мышью фокус «прыгал» бы в календарь;
+  - `clickOutsideDeactivates: true`; `fallbackFocus` — контейнер календаря внутри ловушки (`tabIndex={-1}`), поэтому при отсутствии tabbable-элементов фокус остаётся внутри диалога. Задаётся ленивой функцией, т.к. на момент рендера ref ещё не заполнен; целевой элемент и `document.body` оставлены запасными вариантами, потому что focus-trap бросает исключение на пустом fallback.
+- `Escape` на корневом элементе закрывает календарь (только когда он открыт), после чего вызывается пользовательский `onKeyDown`.
+- `mousedown` вне корневого элемента и вне дропдауна закрывает календарь; клик внутри календаря — нет.
+- Открытие календаря — ответственность целевого элемента: он же должен нести `aria-haspopup="dialog"` и `aria-expanded` (значение берётся из контекста).
+- Клавиатурная навигация внутри сетки календаря — на стороне `Calendar`.
 
-```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`.
+- `Calendar` — календарная сетка, рендерится внутри дропдауна; её props входят в `IDatePickerExtendedProps`, кроме `adaptiveMode`.
+- `Dropdown` — выпадающее меню; из его props наружу выведен только `alignment`, мобильная версия конфигурируется внутри.
+- `DateField` — поле ввода даты; передаёт `dropdownTargetRef` и открывает календарь из `DateFieldTarget` через контекст.
+- `MonthYearField` — выбор месяца и года; конфигурирует `pickType={ECalendarPickType.MONTH_YEAR}`.
+- `ChipDatePicker` — чип-фильтр с календарём; открывает дропдаун из `ChipDatePickerTarget` через контекст.
+- `DatePickerExtendedContext` — контекст открытости дропдауна для целевого элемента. Экспортируется из barrel вместе с типом `IDatePickerExtendedContext`, отдельного AI.md не имеет.
 
-**`mouseUsedRef` сбрасывается в else-ветке** — при каждом закрытии
-флаг становится `false`, чтобы следующее открытие корректно решало,
-как вести себя с focus trap'ом.
+Внутренние части (в barrel не экспортируются, отдельного AI.md не имеют):
 
-### Esc → закрыть dropdown (локальный onKeyDown)
+- `DatePickerExtendedDropdown` — дропдаун с `FocusTrap` вокруг календаря и мобильной версткой (`DropdownMobileHeader` + `DropdownMobileBody`).
 
-```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. Это компромисс.
+## Stories
 
-### `renderCalendar(adaptiveMode)` — две ветки
+Основные истории: `stories/DatePickerExtended/DatePickerExtended.stories.tsx`
+Файлы примеров: `stories/DatePickerExtended/examples/`
 
-```tsx
-const renderMobileContent = () => (
-    <>
-        <DropdownMobileHeader controlButtons={<DropdownMobileClose onClick={...} />}>
-            {renderHeaderTarget()}
-        </DropdownMobileHeader>
-        <DropdownMobileBody>{renderCalendar(true)}</DropdownMobileBody>
-    </>
-);
-// desktop:
-<FocusTrap ...>
-    <div role="presentation">{renderCalendar(false)}</div>
-</FocusTrap>
-```
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `alignment`, `pickType`, `reversedPick` и кнопок футера |
+| `Default` | `Default.tsx` | Минимальный пример: кнопка-триггер открывает календарь через контекст |
+| `Alignments` | `Alignments.tsx` | Выравнивание дропдауна LEFT / RIGHT |
+| `PickTypes` | `PickTypes.tsx` | Выбор дня (DATE) и месяца с годом (MONTH_YEAR) |
+| `WithMarkedAndDisabledDays` | `WithMarkedAndDisabledDays.tsx` | Отмеченные и недоступные дни, ограничение периода |
+| `WithFooterButtons` | `WithFooterButtons.tsx` | Кнопки футера «Вчера» / «Сегодня» / «Завтра» |
+| `VisualTests` | `VisualTests.tsx` | Скриншот-регрессия: раскрытый календарь с отметками, ограничением периода и футером (на xs — мобильный дропдаун) |
+| `VisualTestsMonthYear` | `VisualTestsMonthYear.tsx` | Скриншот-регрессия: раскрытый календарь в режиме MONTH_YEAR |
+| `VisualTestsAlignmentRight` | `VisualTestsAlignmentRight.tsx` | Скриншот-регрессия: раскрытый календарь с выравниванием RIGHT |
+
+Примеры импортируют `DatePickerExtendedContext` из `@sberbusiness/triplex-next` наравне с самим компонентом — без контекста целевой элемент не может открыть календарь, см. «Инварианты».
 
-**`adaptiveMode=true`** — календарь на мобильном (полноэкранный,
-другие размеры и поведение).
-**`adaptiveMode=false`** — десктопный компактный календарь в dropdown'е.
+---
 
-Calendar сам смотрит на `adaptiveMode` и меняет поведение.
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-08-24 | `DatePickerExtendedContext` и `IDatePickerExtendedContext` экспортируются из barrel — целевой элемент можно написать снаружи библиотеки. `adaptiveMode` исключён из `IDatePickerExtendedProps` (ломающее изменение, затрагивает также `DateField`, `MonthYearField`, `ChipDatePicker`) |
+| 2026-08-20 | Создан документ. AI-рефакторинг, unit-тесты (`__tests__/DatePickerExtended.test.tsx`), stories по modern pattern. Исправлено: `yesterdayButtonProps` / `tomorrowButtonProps` пробрасываются в `Calendar`, `adaptiveMode` больше не попадает в DOM |
+
+---
 
-### `onDateChange` → закрыть dropdown + вызвать внешний
+## Примеры использования
+
+### Default
+
+`stories/DatePickerExtended/examples/Default.tsx`
+
+```tsx
+import React, { useContext, useState } from "react";
+import moment from "moment";
+import {
+    Button,
+    DatePickerExtended,
+    DatePickerExtendedContext,
+    DropdownMobileInput,
+    EButtonTheme,
+    EComponentSize,
+} from "@sberbusiness/triplex-next";
+
+const DATE_FORMAT = "YYYYMMDD";
+const DISPLAY_FORMAT = "DD.MM.YYYY";
+
+interface ITargetProps {
+    /** Отображаемое значение даты. */
+    children: React.ReactNode;
+}
 
-```ts
-const handleChangeDate = (date: moment.Moment) => {
-    setDropdownOpen(false);
-    onDateChange(date);
+const Target = ({ children }: ITargetProps) => {
+    const { dropdownOpen, setDropdownOpen } = useContext(DatePickerExtendedContext);
+
+    return (
+        <Button
+            theme={EButtonTheme.SECONDARY}
+            size={EComponentSize.MD}
+            aria-haspopup="dialog"
+            aria-expanded={dropdownOpen}
+            onClick={() => setDropdownOpen(!dropdownOpen)}
+        >
+            {children}
+        </Button>
+    );
+};
+
+export const Default = () => {
+    const [value, setValue] = useState("19700115");
+    const displayedValue = moment(value, DATE_FORMAT).format(DISPLAY_FORMAT);
+
+    return (
+        <DatePickerExtended
+            pickedDate={value}
+            format={DATE_FORMAT}
+            onDateChange={(date) => setValue(date.format(DATE_FORMAT))}
+            renderTarget={() => <Target>{displayedValue}</Target>}
+            renderDropdownHeaderTarget={() => <DropdownMobileInput value={displayedValue} readOnly />}
+        />
+    );
 };
 ```
 
-Выбор даты → dropdown закрывается автоматически. Это жёсткое
-поведение, потребитель не может отключить. Если нужно "мультидневный
-выбор" — Calendar не подходит, нужен другой компонент.
+### Alignments
 
-### `FocusTrap` с `clickOutsideDeactivates`
+`stories/DatePickerExtended/examples/Alignments.tsx`
 
-```ts
-focusTrapOptions={{
-    clickOutsideDeactivates: true,
-    fallbackFocus: targetRef.current!,
-    ...
-}}
-```
+```tsx
+import React, { useContext, useState } from "react";
+import moment from "moment";
+import {
+    Button,
+    DatePickerExtended,
+    DatePickerExtendedContext,
+    DropdownMobileInput,
+    EButtonTheme,
+    EComponentSize,
+    EDropdownAlignment,
+} from "@sberbusiness/triplex-next";
+
+const DATE_FORMAT = "YYYYMMDD";
+const DISPLAY_FORMAT = "DD.MM.YYYY";
+
+const ALIGNMENTS = Object.values(EDropdownAlignment);
+
+interface ITargetProps {
+    /** Отображаемое значение даты. */
+    children: React.ReactNode;
+}
 
-- `clickOutsideDeactivates` — клик вне → FocusTrap отпускает фокус,
-  но outside-handler всё равно закрывает dropdown. Это **защита**:
-  FocusTrap не борется с outside-handler'ом.
-- `fallbackFocus: targetRef.current!` — если FocusTrap не может найти
-  focusable элемент внутри, поставить фокус на target (non-null
-  assertion обязателен потому что при первой активации targetRef
-  уже mounted).
+const Target = ({ children }: ITargetProps) => {
+    const { dropdownOpen, setDropdownOpen } = useContext(DatePickerExtendedContext);
+
+    return (
+        <Button
+            theme={EButtonTheme.SECONDARY}
+            size={EComponentSize.MD}
+            aria-haspopup="dialog"
+            aria-expanded={dropdownOpen}
+            onClick={() => setDropdownOpen(!dropdownOpen)}
+        >
+            {children}
+        </Button>
+    );
+};
 
-### `role="dialog" aria-modal="true"` на Dropdown
+interface IAlignmentItemProps {
+    /** Выравнивание выпадающего календаря относительно целевого элемента. */
+    alignment: EDropdownAlignment;
+}
 
-Семантика модального диалога для содержимого (календарь). Screen reader
-объявит как модал. **Jарко** (не опционально), `...rest` идёт в
-Dropdown после `role`/`aria-modal`, но `role` и `aria-modal` не
-подлежат перебиванию снаружи потребителя (IDatePickerExtendedProps не
-принимает role).
+const AlignmentItem = ({ alignment }: IAlignmentItemProps) => {
+    const [value, setValue] = useState("19700115");
+    const displayedValue = moment(value, DATE_FORMAT).format(DISPLAY_FORMAT);
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{alignment.toUpperCase()}</div>
+            <DatePickerExtended
+                alignment={alignment}
+                pickedDate={value}
+                format={DATE_FORMAT}
+                onDateChange={(date) => setValue(date.format(DATE_FORMAT))}
+                renderTarget={() => <Target>{displayedValue}</Target>}
+                renderDropdownHeaderTarget={() => <DropdownMobileInput value={displayedValue} readOnly />}
+            />
+        </div>
+    );
+};
 
-### `data-tx={process.env.npm_package_version}` — есть
+export const Alignments = () => (
+    <div style={{ display: "flex", gap: "48px", flexWrap: "wrap" }}>
+        {ALIGNMENTS.map((alignment) => (
+            <AlignmentItem key={alignment} alignment={alignment} />
+        ))}
+    </div>
+);
+```
 
-Стандарт библиотеки. Не удалять.
+### PickTypes
 
-### `setRef` — double-duty ref
+`stories/DatePickerExtended/examples/PickTypes.tsx`
 
-```ts
-const setRef = (node: HTMLDivElement | null) => {
-    containerRef.current = node;
-    if (typeof ref === "function") ref(node);
-    else if (ref) ref.current = node;
+```tsx
+import React, { useContext, useState } from "react";
+import moment from "moment";
+import {
+    Button,
+    DatePickerExtended,
+    DatePickerExtendedContext,
+    DropdownMobileInput,
+    ECalendarPickType,
+    EButtonTheme,
+    EComponentSize,
+} from "@sberbusiness/triplex-next";
+
+const DATE_FORMAT = "YYYYMMDD";
+
+/** Формат отображения даты для каждого варианта выбора. */
+const PICK_TYPE_TO_DISPLAY_FORMAT = {
+    [ECalendarPickType.DATE]: "DD.MM.YYYY",
+    [ECalendarPickType.MONTH_YEAR]: "MMMM YYYY",
 };
-```
 
-Один DOM-узел = target для Dropdown (`targetRef`) + forwarded ref.
+const PICK_TYPES = Object.values(ECalendarPickType);
 
----
+interface ITargetProps {
+    /** Отображаемое значение даты. */
+    children: React.ReactNode;
+}
 
-## Инварианты
+const Target = ({ children }: ITargetProps) => {
+    const { dropdownOpen, setDropdownOpen } = useContext(DatePickerExtendedContext);
+
+    return (
+        <Button
+            theme={EButtonTheme.SECONDARY}
+            size={EComponentSize.MD}
+            aria-haspopup="dialog"
+            aria-expanded={dropdownOpen}
+            onClick={() => setDropdownOpen(!dropdownOpen)}
+        >
+            {children}
+        </Button>
+    );
+};
 
-- **`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.
+interface IPickTypeItemProps {
+    /** Вариант выбора даты. */
+    pickType: ECalendarPickType;
+}
 
----
+const PickTypeItem = ({ pickType }: IPickTypeItemProps) => {
+    const [value, setValue] = useState("19700115");
+    const displayedValue = moment(value, DATE_FORMAT).format(PICK_TYPE_TO_DISPLAY_FORMAT[pickType]);
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{pickType.toUpperCase()}</div>
+            <DatePickerExtended
+                pickType={pickType}
+                pickedDate={value}
+                format={DATE_FORMAT}
+                onDateChange={(date) => setValue(date.format(DATE_FORMAT))}
+                renderTarget={() => <Target>{displayedValue}</Target>}
+                renderDropdownHeaderTarget={() => <DropdownMobileInput value={displayedValue} readOnly />}
+            />
+        </div>
+    );
+};
 
-## Accessibility
+export const PickTypes = () => (
+    <div style={{ display: "flex", gap: "48px", flexWrap: "wrap" }}>
+        {PICK_TYPES.map((pickType) => (
+            <PickTypeItem key={pickType} pickType={pickType} />
+        ))}
+    </div>
+);
+```
 
-- **`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`).
+### WithMarkedAndDisabledDays
 
----
+`stories/DatePickerExtended/examples/WithMarkedAndDisabledDays.tsx`
 
-## Дизайн-токены
+```tsx
+import React, { useContext, useState } from "react";
+import moment from "moment";
+import {
+    Button,
+    DatePickerExtended,
+    DatePickerExtendedContext,
+    DropdownMobileInput,
+    ECalendarDateMarkType,
+    EButtonTheme,
+    EComponentSize,
+} from "@sberbusiness/triplex-next";
+
+const DATE_FORMAT = "YYYYMMDD";
+const DISPLAY_FORMAT = "DD.MM.YYYY";
+
+/** Отмеченные дни: тип отметки задаёт цвет маркера под числом. */
+const MARKED_DAYS = {
+    "19700108": ECalendarDateMarkType.STANDARD,
+    "19700109": ECalendarDateMarkType.ATTENTION,
+    "19700112": ECalendarDateMarkType.CRITICAL,
+};
 
-**Нет собственных.** Dropdown и Calendar — источники всех визуальных
-токенов.
+/** Дни, недоступные для выбора. */
+const DISABLED_DAYS = ["19700120", "19700121"];
 
----
+/** Ограничение выбираемого периода. */
+const LIMIT_RANGE = {
+    dateFrom: moment("19700105", DATE_FORMAT),
+    dateTo: moment("19700125", DATE_FORMAT),
+};
 
-## Связанные компоненты
+interface ITargetProps {
+    /** Отображаемое значение даты. */
+    children: React.ReactNode;
+}
 
-- `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`) — потребитель
-  для месяца/года.
+const Target = ({ children }: ITargetProps) => {
+    const { dropdownOpen, setDropdownOpen } = useContext(DatePickerExtendedContext);
+
+    return (
+        <Button
+            theme={EButtonTheme.SECONDARY}
+            size={EComponentSize.MD}
+            aria-haspopup="dialog"
+            aria-expanded={dropdownOpen}
+            onClick={() => setDropdownOpen(!dropdownOpen)}
+        >
+            {children}
+        </Button>
+    );
+};
 
----
+export const WithMarkedAndDisabledDays = () => {
+    const [value, setValue] = useState("19700115");
+    const displayedValue = moment(value, DATE_FORMAT).format(DISPLAY_FORMAT);
+
+    return (
+        <DatePickerExtended
+            pickedDate={value}
+            format={DATE_FORMAT}
+            limitRange={LIMIT_RANGE}
+            markedDays={MARKED_DAYS}
+            disabledDays={DISABLED_DAYS}
+            onDateChange={(date) => setValue(date.format(DATE_FORMAT))}
+            renderTarget={() => <Target>{displayedValue}</Target>}
+            renderDropdownHeaderTarget={() => <DropdownMobileInput value={displayedValue} readOnly />}
+        />
+    );
+};
+```
 
-## Stories
+### WithFooterButtons
 
-**Нет собственных stories.** Документируется косвенно через
-`DateField`/`DateRange`/`MonthYearField`.
+`stories/DatePickerExtended/examples/WithFooterButtons.tsx`
 
----
+```tsx
+import React, { useContext, useState } from "react";
+import moment from "moment";
+import {
+    Button,
+    DatePickerExtended,
+    DatePickerExtendedContext,
+    DropdownMobileInput,
+    EButtonTheme,
+    EComponentSize,
+} from "@sberbusiness/triplex-next";
+
+const DATE_FORMAT = "YYYYMMDD";
+const DISPLAY_FORMAT = "DD.MM.YYYY";
+
+interface ITargetProps {
+    /** Отображаемое значение даты. */
+    children: React.ReactNode;
+}
 
-## История изменений
+const Target = ({ children }: ITargetProps) => {
+    const { dropdownOpen, setDropdownOpen } = useContext(DatePickerExtendedContext);
+
+    return (
+        <Button
+            theme={EButtonTheme.SECONDARY}
+            size={EComponentSize.MD}
+            aria-haspopup="dialog"
+            aria-expanded={dropdownOpen}
+            onClick={() => setDropdownOpen(!dropdownOpen)}
+        >
+            {children}
+        </Button>
+    );
+};
+
+// Кнопки «Вчера» и «Завтра» календарь показывает только на странице текущего месяца,
+// кнопку «Сегодня» — всегда. Текст кнопок задаёт потребитель.
+export const WithFooterButtons = () => {
+    const [value, setValue] = useState(moment().format(DATE_FORMAT));
+    const displayedValue = moment(value, DATE_FORMAT).format(DISPLAY_FORMAT);
+
+    return (
+        <DatePickerExtended
+            pickedDate={value}
+            format={DATE_FORMAT}
+            yesterdayButtonProps={{ children: "Вчера" }}
+            todayButtonProps={{ children: "Сегодня" }}
+            tomorrowButtonProps={{ children: "Завтра" }}
+            onDateChange={(date) => setValue(date.format(DATE_FORMAT))}
+            renderTarget={() => <Target>{displayedValue}</Target>}
+            renderDropdownHeaderTarget={() => <DropdownMobileInput value={displayedValue} readOnly />}
+        />
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |