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

package/bundle/components/ChipDatePicker.md

@@ -0,0 +1,332 @@
+---
+component: ChipDatePicker
+category: Chips
+related: [Chip, ChipDatePickerTarget, ChipMonthYearPicker, DateField, DatePickerExtended, Puller]
+tokens: []
+stories: stories/Chips/ChipDatePicker.stories.tsx
+version: "1.0"
+---
+
+# ChipDatePicker
+
+## Назначение
+
+Управляемый выбор даты в виде чипса-фильтра. Показывает название фильтра либо
+выбранную дату, открывает календарь и позволяет очистить выбор. В мобильном
+дропдауне дополнительно доступен ручной ввод даты с маской.
+
+Используй когда: в панели фильтров нужна конкретная дата, а выбранное значение
+должно читаться прямо на чипсе. Размещай в `ChipGroup` для общих отступов и переноса.
+Не используй когда: нужен месяц без дня (`ChipMonthYearPicker`), диапазон дат
+(`DateRange`) или поле формы со статусом валидации (`DateField`).
+
+Публичное подключение: `import { ChipDatePicker } from "@sberbusiness/triplex-next"`.
+Потребитель хранит `value` и обновляет его в `onChange`.
+
+---
+
+## Варианты и props
+
+`IChipDatePickerProps` наследует `IDateFieldProps` без `status` и `invalidDateHint`,
+добавляет `type` / `disabled` от `IChipProps` и обязательный `label`.
+Точные типы и полный список календарных props находятся в исходниках этих интерфейсов.
+
+### Значение и отображение
+
+| Prop | По умолчанию | Назначение и ограничения |
+|---|---|---|
+| `value` | Обязателен | Строка в формате `format`; `""` означает отсутствие выбора |
+| `onChange` | Обязателен | Получает дату в формате `format` или `""` при очистке. Выбор календаря вызывает его сразу, ручной ввод — при закрытии дропдауна |
+| `label` | Обязателен | `React.ReactNode` в невыбранном состоянии |
+| `displayedValue` | — | Заменяет текст выбранной даты. При пустом или недоступном `value` игнорируется; `0` и `""` сохраняются, так как используется `??` |
+| `format` | `"YYYYMMDD"` | Транспортный формат `value` и аргумента `onChange`. Отображение и мобильный ввод используют `"DD.MM.YYYY"` (`inputDateFormat`) |
+| `placeholderMask` | — | Заполнение пустых позиций маски мобильного поля; не является подписью чипса |
+
+Значение разбирается строго: невозможная дата, несовпадение с `format`, выход за
+`limitRange` или попадание в `disabledDays` превращают его в невыбранное состояние.
+Вместо ошибки показывается `label`, а справа — стрелка раскрытия. При выбранной
+дате справа отображается кнопка очистки.
+
+### Внешний вид и календарь
+
+| Prop или группа | По умолчанию | Назначение и ограничения |
+|---|---|---|
+| `size` | `EComponentSize.MD` | SM / MD / LG; размер чипса, стрелки и кнопки очистки |
+| `type` | `EChipType.TYPE_1` | TYPE_1 / TYPE_2; фон чипса |
+| `disabled` | `false` | Визуальное отключение чипса и исключение его из tab-порядка; ограничения описаны в Accessibility |
+| `limitRange` | `globalLimitRange` | Границы выбора: 1900-01-01 … 2199-12-31 по умолчанию |
+| `disabledDays` | — | Недоступные дни в транспортном формате, проверяются и для `value`, и для ручного ввода |
+| `alignment` | `EDropdownAlignment.LEFT` | Выравнивание дропдауна |
+| `defaultViewDate`, `markedDays`, `reversedPick`, `pickType` | От `Calendar` | Настройка календаря через `DatePickerExtended`. `pickType` по умолчанию `DATE`, в отличие от `ChipMonthYearPicker` не зафиксирован |
+| `onViewChange`, `onPageChange`, `dayHtmlAttributes`, `monthHtmlAttributes`, `yearHtmlAttributes` | — | События навигации и атрибуты ячеек календаря |
+| `prevButtonProps`, `nextButtonProps`, `viewButtonProps`, `yesterdayButtonProps`, `todayButtonProps`, `tomorrowButtonProps` | — | Кнопки управления и футер календаря |
+| `onDropdownOpen`, `onDropdownClose` | — | Уведомления о переходах открытости; при закрытии сначала обрабатывается мобильный ввод, затем вызывается `onDropdownClose` |
+| `focusTrapProps` | От `DatePickerExtended` | Настройка десктопной ловушки фокуса |
+
+### Передача атрибутов
+
+`className`, `id`, `data-*`, `aria-*` и обработчики `<div>` из `...rest` уходят
+на корневой `<div>` `DatePickerExtended`, а не на чипс-таргет и не на мобильное поле.
+В текущей реализации пользовательский `className` переопределяет `.chipGroupItem`
+корня из-за порядка spread; его слияние изменило бы существующее поведение.
+
+Унаследованные `onClear` и `targetProps` присутствуют в типе, но не подключены к
+`ChipDatePickerTarget`: они не настраивают очистку и внутренний таргет.
+Очистка всегда сообщает `onChange("")`. Удалять эти props при рефакторинге нельзя.
+
+### Незавершённый мобильный ввод
+
+- Открытый чипс сохраняет последнее значение из внешних props; промежуточный
+  ввод меняет мобильное поле и выбранный день календаря, а не подпись чипса.
+- При закрытии полная допустимая дата коммитится через `onChange`; пустой ввод
+  очищает ранее выбранную дату. Повторная передача того же значения не нужна.
+- Неполная, невозможная, запрещённая или выходящая за границы дата откатывается
+  к последнему значению из props без вызова `onChange`.
+- Выбор в календаре закрывает дропдаун и сообщает дату один раз: флаг
+  `dropdownClosedByCalendarRef` предотвращает дополнительный коммит ручного ввода.
+- Изменение `value`, `format`, `limitRange` или `disabledDays` синхронизирует поле
+  с внешними props. Эффект намеренно не зависит от промежуточного `pickerValues`,
+  иначе каждый введённый символ затирался бы прежним `value`.
+
+---
+
+## Дизайн-токены
+
+Собственных токенов нет: используемый самим компонентом `.chipGroupItem` из
+`styles/Chip.module.less` задаёт только `display: inline-block`, поэтому
+frontmatter содержит `tokens: []`.
+
+Внешний вид композиции задают зависимости: `Chip` (фон, цвет, фокус, selected и
+disabled), `Calendar` (календарь) и `Dropdown` (выпадающий блок). Их токены описаны
+в соответствующих AI.md; например, фон обычного чипса — `Chip.Background_Type1_Default`,
+фокус — `Chip.Shadow_Focus`, фон календаря — `Calendar.Background`.
+
+Порядок переопределения токенов описан в
+[ThemeProvider-ai.md](../ThemeProvider/ThemeProvider-ai.md#как-переопределять-токены).
+
+---
+
+## Инварианты
+
+- `forwardRef<HTMLDivElement>` сохраняется: ссылка указывает на корневой
+  `<div>` `DatePickerExtended`, а не на `<span>` чипса или `<input>`.
+- `value` / `onChange` — управляемый контракт, очистка передаёт пустую строку.
+  `format` не меняет `inputDateFormat` и видимую маску.
+- Нельзя добавлять промежуточные значения поля в зависимости эффекта
+  синхронизации с props либо терять разграничение ввода и выбора календаря.
+- `DateFieldUtils` и `inputDateFormat` импортируются из внутренних модулей
+  `DateField`; изменения их логики или сигнатур требуют проверки обоих компонентов.
+- `IChipDatePickerProps`, `ChipDatePicker`, `ChipDatePickerTarget` и его props
+  экспортируются через `src/components/Chip/index.ts` и вложенный barrel; сохранять
+  имена, типы и экспорты. Контракт таргета описан в [ChipDatePickerTarget-ai.md](./ChipDatePickerTarget-ai.md).
+- Story ids `chips-chipdatepicker--*` используются существующими baseline-файлами
+  xs / xl, поэтому их нельзя переименовывать без обновления visual-проверок.
+
+---
+
+## Accessibility
+
+- Таргет — `Chip` с `<span role="button">`, фокусируемый через `tabIndex={0}`.
+  Доступное имя берётся из `label` или отображаемого значения; `aria-expanded`
+  отражает состояние календаря. Enter / Space переключают дропдаун с
+  `preventDefault()`, Escape из корня или портала закрывает его.
+- Десктопный календарь находится в `role="dialog"` с `aria-modal` и `FocusTrap`.
+  При открытии с клавиатуры фокус переходит внутрь и возвращается на таргет при
+  закрытии; открытие мышью не перехватывает фокус. Настройки делегированы
+  `DatePickerExtended`.
+- В мобильном режиме шапка содержит редактируемое маскированное поле с
+  `autoFocus`, изменение коммитится при закрытии. `aria-label` корня не
+  пробрасывается этому полю: отдельного prop для его настройки сейчас нет.
+- `disabled` даёт классу `Chip` `pointer-events: none` и `tabIndex={-1}`,
+  но не является нативным `disabled`. `ChipDatePickerTarget` пока не блокирует
+  программно отправленные клики и клавиши, а кнопка очистки не получает
+  `disabled`; на такое отключение нельзя полагаться как на защиту обработчиков.
+- Кнопка очистки останавливает всплытие клика, чтобы не открывать календарь.
+  Доступное имя ей пока нельзя передать через `ChipDatePicker`: собственного
+  `clearButtonProps` нет, а `targetProps` не подключён. Это существующее ограничение,
+  связанное с задачами `ChipClearButton` / `ChipDatePickerTarget`, а не требование
+  добавлять локализованную строку внутрь библиотеки.
+
+---
+
+## Связанные компоненты
+
+- `Chip` — база таргета и источник визуальных состояний; родитель семейства.
+- [ChipDatePickerTarget](./ChipDatePickerTarget-ai.md) — публичный таргет со своим контекстным и клавиатурным
+  контрактом: читает `DatePickerExtendedContext`, переключает дропдаун, выбирает
+  между `ChipClearButton` и `ChipDropdownArrow`.
+- `ChipMonthYearPicker` — альтернатива для выбора месяца без дня и ручного ввода.
+- `DateField` — альтернатива в форме; источник унаследованного интерфейса,
+  `DateFieldUtils` и `inputDateFormat`.
+- `DatePickerExtended` — рендерится внутри, владеет календарём, дропдауном,
+  открытостью и корневым DOM-элементом.
+- `Puller` — мобильная шторка календаря; в её шапке рендерится `PullerMaskedInput` —
+  обёртка над `FormFieldMaskedInput`, общие props поля и маски описаны в `FormField`.
+- `ChipGroup` — рекомендуемый контейнер для ряда фильтров.
+
+---
+
+## Stories
+
+Основные истории: `stories/Chips/ChipDatePicker.stories.tsx`
+Файлы примеров: `stories/Chips/examples/ChipDatePicker/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Управляемый выбор с контролами type, size, label, displayedValue, disabled |
+| `Default` | `DefaultExample.tsx` | Минимальный управляемый фильтр value / onChange |
+| `Types` | `TypesExample.tsx` | TYPE_1 / TYPE_2 |
+| `Sizes` | `SizesExample.tsx` | SM / MD / LG |
+| `WithCustomDisplayedValue` | `WithCustomDisplayedValueExample.tsx` | Подмена текста выбранного значения |
+| `VisualTests` | `VisualTestsExample.tsx` | Три размера с фиксированной датой 19700101; play открывает последний календарь |
+
+Для всех пяти не-Playground историй существуют baseline-скриншоты xs / xl в
+`__screenshots__/`. Stories и их идентификаторы в TRI-136 сохранены.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-10-19 | Создан документ; подтверждены контракт управляемой даты, мобильного ввода и существующие ограничения. Лениво инициализировано состояние и дополнены unit-тесты (TRI-136) |
+| 2026-10-21 | Добавлена ссылка на отдельную AI-документацию ChipDatePickerTarget |
+| 2026-10-21 | Переход на `Puller` (TRIPLEX-961): мобильный ввод даты — `PullerMaskedInput` (бывший `DropdownMobileMaskedInput`). |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Chips/examples/ChipDatePicker/DefaultExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipDatePicker, EComponentSize, EDropdownAlignment } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => {
+    const [value, setValue] = useState("");
+    return (
+        <ChipDatePicker
+            value={value}
+            label="Date label"
+            onChange={setValue}
+            alignment={EDropdownAlignment.LEFT}
+            size={EComponentSize.MD}
+        />
+    );
+};
+```
+
+### Types
+
+`stories/Chips/examples/ChipDatePicker/TypesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipDatePicker, EChipType, EDropdownAlignment } from "@sberbusiness/triplex-next";
+
+type TypeItemProps = {
+    type: EChipType;
+    label: string;
+};
+
+const TypeItem = ({ type, label }: TypeItemProps) => {
+    const [value, setValue] = useState("");
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{label}</div>
+            <ChipDatePicker
+                value={value}
+                label="Date label"
+                type={type}
+                alignment={EDropdownAlignment.LEFT}
+                onChange={setValue}
+            />
+        </div>
+    );
+};
+
+const typeOptions = Object.values(EChipType).map((type) => ({
+    value: type,
+    label: type.toUpperCase(),
+}));
+
+export const TypesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {typeOptions.map(({ value, label }) => (
+            <TypeItem key={value} type={value} label={label} />
+        ))}
+    </div>
+);
+```
+
+### Sizes
+
+`stories/Chips/examples/ChipDatePicker/SizesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipDatePicker, EComponentSize, EDropdownAlignment } from "@sberbusiness/triplex-next";
+
+type SizeItemProps = {
+    size: EComponentSize;
+    label: string;
+};
+
+const SizeItem = ({ size, label }: SizeItemProps) => {
+    const [value, setValue] = useState("");
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{label}</div>
+            <ChipDatePicker
+                size={size}
+                alignment={EDropdownAlignment.LEFT}
+                value={value}
+                label="Date label"
+                onChange={setValue}
+            />
+        </div>
+    );
+};
+
+const sizeOptions = Object.values(EComponentSize).map((size) => ({
+    value: size,
+    label: size.toUpperCase(),
+}));
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {sizeOptions.map(({ value, label }) => (
+            <SizeItem key={value} size={value} label={label} />
+        ))}
+    </div>
+);
+```
+
+### WithCustomDisplayedValue
+
+`stories/Chips/examples/ChipDatePicker/WithCustomDisplayedValueExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipDatePicker, EComponentSize, EDropdownAlignment } from "@sberbusiness/triplex-next";
+
+export const WithCustomDisplayedValueExample = () => {
+    const [value, setValue] = useState("");
+    return (
+        <ChipDatePicker
+            value={value}
+            label="Date label"
+            onChange={setValue}
+            alignment={EDropdownAlignment.LEFT}
+            size={EComponentSize.MD}
+            displayedValue="Date value"
+        />
+    );
+};
+```
+

package/bundle/components/ChipDatePickerTarget.md

@@ -0,0 +1,316 @@
+---
+component: ChipDatePickerTarget
+category: Chips
+related: [ChipDatePicker, Chip, DatePickerExtended]
+tokens: []
+stories: stories/Chips/ChipDatePicker.stories.tsx
+version: "1.0"
+---
+
+# ChipDatePickerTarget
+
+## Назначение
+
+Публичный target для выбора даты в виде `Chip`: переключает выпадающий календарь
+через `DatePickerExtendedContext`, показывает стрелку либо кнопку очистки.
+Сам не хранит дату и не форматирует `children`.
+
+Используй когда: нужна своя композиция `DatePickerExtended.renderTarget`
+с чипсом, собственным контентом, `prefix` или `postfix`.
+Не используй когда: достаточно готового управляемого фильтра `ChipDatePicker`
+с `value`, `onChange` и мобильным вводом даты.
+
+Публичное подключение:
+
+```tsx
+import { ChipDatePickerTarget, type IChipDatePickerTargetProps } from "@sberbusiness/triplex-next";
+```
+
+Возвращай target из `DatePickerExtended.renderTarget`: там он получает рабочий
+контекст. Вне provider используется значение контекста по умолчанию
+(`dropdownOpen: false`, пустой setter), поэтому самостоятельный target не открывает
+календарь. Создавать свой `Context.Provider` для обычной композиции не требуется.
+
+Минимальная управляемая композиция:
+
+```tsx
+const [pickedDate, setPickedDate] = useState<string | null>(null);
+
+<DatePickerExtended
+    pickedDate={pickedDate}
+    onDateChange={(date) => setPickedDate(date.format("YYYYMMDD"))}
+    renderTarget={() => (
+        <ChipDatePickerTarget selected={pickedDate !== null} onClear={() => setPickedDate(null)}>
+            {pickedDate ? moment(pickedDate, "YYYYMMDD").format("DD.MM.YYYY") : "Выберите дату"}
+        </ChipDatePickerTarget>
+    )}
+    renderDropdownHeaderTarget={() => <span>Выберите дату</span>}
+/>;
+```
+
+---
+
+## Варианты и props
+
+`IChipDatePickerTargetProps` наследует `IChipProps` целиком и добавляет обязательный
+`onClear`. Точные типы унаследованных атрибутов находятся в исходниках `Chip`.
+
+### Значение и callbacks
+
+| Prop | По умолчанию | Назначение и ограничения |
+|---|---|---|
+| `onClear` | Обязателен | Вызывается без аргументов по клику встроенной кнопки очистки; потребитель сбрасывает свою дату и `selected` |
+| `selected` | `false` | Управляемое визуальное состояние; при `true` вместо стрелки рендерится `ChipClearButton` |
+| `children` | — | Подпись фильтра или выбранная дата; форматирует потребитель |
+| `onClick` | — | Получает исходное событие после вызова `setDropdownOpen(!dropdownOpen)` |
+| `onKeyDown` | — | Получает событие только для `event.code` Enter / Space, после `preventDefault()` и переключения контекста; для остальных клавиш не вызывается |
+
+`onClear` не закрывает открытый календарь и не меняет `selected` автоматически.
+Клик встроенной кнопки вызывает `stopPropagation()`, поэтому не переключает
+календарь и не вызывает `onClick` target.
+
+### Внешний вид и унаследованные атрибуты
+
+| Prop или группа | По умолчанию | Назначение и ограничения |
+|---|---|---|
+| `size` | `EComponentSize.MD` | SM / MD / LG; передаётся в `Chip`, стрелку и встроенную кнопку очистки |
+| `type` | `EChipType.TYPE_1` | TYPE_1 / TYPE_2; визуальная тема `Chip` |
+| `disabled` | `false` | CSS-блокировка указателя и `tabIndex={-1}` у `Chip`; ограничения ниже |
+| `prefix` | — | Контент перед подписью через слот `Chip` |
+| `postfix` | Автоматическая стрелка или очистка | Переданное значение переопределяет автоматический postfix, включая явно переданный `undefined`; обработчики пользовательского слота задаёт потребитель |
+| `showNotificationIcon` | `false` | Значок `Badge.Dot` через `Chip` |
+| `className`, `style`, `id`, `data-*`, `aria-*`, прочие span-атрибуты | — | Передаются в корневой `<span>` `Chip`; `className` объединяется с его классами |
+
+`...restProps` расположен после `postfix` и `aria-expanded`, поэтому потребитель
+может переопределить их, а также унаследованные `role` и `tabIndex`. Сохраняй
+согласованность ARIA с реальной открытостью календаря. Для необязательных слотов
+учитывай правила `Chip`: явный `null` / `false` оставляет класс отступов без контента.
+
+---
+
+## Дизайн-токены
+
+Собственных стилей и токенов нет: frontmatter содержит `tokens: []`.
+Внешний вид задают зависимости: `Chip` (например, `Chip.Background_Type1_Default`,
+`Chip.Background_Selected_Default`, `Chip.Color_Disabled`, `Chip.Shadow_Focus`)
+и `ChipClearButton` (фокус использует `Chip.Shadow_Focus`). Стрелка использует
+палитру иконок, отдельных токенов target не добавляет.
+
+Полный набор — в [Chip-ai.md](./Chip-ai.md#дизайн-токены); значения по умолчанию —
+`src/components/DesignTokens/components/Chip.ts`. Переопределение через
+`ThemeProvider.tokens` описано в
+[ThemeProvider-ai.md](../ThemeProvider/ThemeProvider-ai.md#как-переопределять-токены).
+
+---
+
+## Инварианты
+
+- `forwardRef<HTMLSpanElement>` сохраняется: ref указывает на корневой `<span>`
+  `Chip`, а не на кнопку очистки, календарь или корень `DatePickerExtended`.
+- `ChipDatePickerTarget` и `IChipDatePickerTargetProps` экспортируются именованно
+  через `src/components/Chip/ChipDatePicker/index.ts` и `src/components/Chip/index.ts`;
+  имена, типы props и barrel-экспорты сохраняются.
+- Открытость читается из `DatePickerExtendedContext`; не добавлять локальную копию
+  состояния, иначе стрелка и `aria-expanded` разойдутся с календарём.
+- `selected` приходит от потребителя, `onClear` получает ноль аргументов. Не
+  подменять его DOM-событием или изменением даты внутри target.
+- Клик target сначала вызывает setter контекста, затем `onClick`. Enter / Space
+  сначала отменяют действие браузера, переключают контекст, затем вызывают
+  пользовательский `onKeyDown` внутри той же ветки.
+- Порядок spread сохраняет переопределение `postfix` и `aria-expanded` через props.
+- Корневой элемент, CSS-контракт `Chip` и ref-target не меняются при AI-рефакторинге.
+
+---
+
+## Accessibility
+
+- По умолчанию это `<span role="button" tabIndex={0}>`; имя задаётся текстом
+  `children` или переданным `aria-label`. `selected` сам не добавляет `aria-pressed`.
+- `aria-expanded` берётся из контекста. `aria-haspopup` и `aria-controls`
+  автоматически не задаются: нужные атрибуты и ID-связи передаёт потребитель.
+- Enter / Space распознаются по `event.code`, переключают календарь и вызывают
+  `preventDefault()`. Остальные клавиши не передаются в пользовательский
+  `onKeyDown` target. Escape, ловушка фокуса и возврат фокуса принадлежат
+  `DatePickerExtended`, а навигация по датам — `Calendar`.
+- `disabled` у `Chip` означает `pointer-events: none` и `tabIndex={-1}`,
+  а не нативное отключение `<span>`; программно отправленные события
+  обработчики не блокируют. Встроенная кнопка очистки не получает `disabled`.
+- Встроенная очистка останавливает только всплытие клика. Её Enter / Space
+  всплывают в target: обработчик target вызывает `preventDefault()`, отменяя
+  нативную активацию кнопки, и переключает календарь. Поэтому встроенную
+  кнопку нельзя нажать с клавиатуры — `onClear` не вызывается. Доступное имя
+  из props target кнопке не передаётся, `clearButtonProps` у компонента нет.
+  Это существующие ограничения, а не желаемое поведение.
+- Для клавиатурно доступной именованной очистки передай свою кнопку в `postfix`:
+  `aria-label`, остановка всплытия клика и Enter / Space; локализованный текст
+  остаётся у потребителя.
+
+```tsx
+const handleClearClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    event.stopPropagation();
+    setPickedDate(null);
+};
+
+// Не даём Enter / Space дойти до target: нативная активация кнопки вызовет click.
+const handleClearKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
+    if (event.code === "Enter" || event.code === "Space") {
+        event.stopPropagation();
+    }
+};
+
+// postfix передаётся только при выборе: явный postfix={undefined} убрал бы автоматическую стрелку.
+const postfixProps =
+    pickedDate !== null
+        ? {
+              postfix: (
+                  <ChipClearButton aria-label="Очистить дату" onClick={handleClearClick} onKeyDown={handleClearKeyDown} />
+              ),
+          }
+        : {};
+
+<ChipDatePickerTarget selected={pickedDate !== null} onClear={() => setPickedDate(null)} {...postfixProps}>
+    {label}
+</ChipDatePickerTarget>;
+```
+
+---
+
+## Связанные компоненты
+
+- [ChipDatePicker](./ChipDatePicker-ai.md) — готовый родитель: вычисляет `selected`
+  и подпись, передаёт `onClear`, рендерит target внутри `DatePickerExtended`.
+- [Chip](./Chip-ai.md) — рендерится внутри target, источник унаследованных props,
+  визуальных состояний и span-семантики.
+- [DatePickerExtended](../DatePickerExtended/DatePickerExtended-ai.md) — владеет
+  календарём и контекстом открытости; публичная точка композиции — `renderTarget`.
+- `ChipClearButton` — встроенный postfix для `selected`; отдельная публичная
+  кнопка принимает `aria-label` и остальные props `ButtonIcon`.
+- `ChipDropdownArrow` — встроенный postfix без выбора; `rotated` повторяет
+  открытость контекста.
+
+---
+
+## Stories
+
+Основные истории: `stories/Chips/ChipDatePicker.stories.tsx`
+Файлы примеров: `stories/Chips/examples/ChipDatePicker/`
+
+Используются существующие истории родителя: `ChipDatePicker` рендерит этот target.
+Отдельный stories-файл атому не требуется. Примеры ручной композиции через
+`renderTarget` приведены выше в этом документе.
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Target с контролами type, size, disabled; выбор даты включает `selected` и кнопку очистки |
+| `Types` | `TypesExample.tsx` | TYPE_1 / TYPE_2 target без выбора, со стрелкой |
+| `Sizes` | `SizesExample.tsx` | SM / MD / LG target без выбора, со стрелкой |
+| `VisualTests` | `VisualTestsExample.tsx` | Selected target трёх размеров с кнопкой очистки; play раскрывает календарь последнего |
+
+Состояния `disabled`, hover, focus и prefix/postfix-слоты отрисовывает `Chip`;
+они покрыты stories `stories/Chips/Chip.stories.tsx`.
+
+Контракт target покрывает `src/components/Chip/__tests__/ChipDatePickerTarget.test.tsx`;
+календарный выбор и связь с датой — существующие тесты `ChipDatePicker` и
+`DatePickerExtended`. Ограничения встроенной очистки и disabled не закрепляются
+новыми тестами как желаемое поведение.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-10-21 | Создан документ; добавлены JSDoc и focused тесты target без изменения API и поведения |
+
+---
+
+## Примеры использования
+
+### Types
+
+`stories/Chips/examples/ChipDatePicker/TypesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipDatePicker, EChipType, EDropdownAlignment } from "@sberbusiness/triplex-next";
+
+type TypeItemProps = {
+    type: EChipType;
+    label: string;
+};
+
+const TypeItem = ({ type, label }: TypeItemProps) => {
+    const [value, setValue] = useState("");
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{label}</div>
+            <ChipDatePicker
+                value={value}
+                label="Date label"
+                type={type}
+                alignment={EDropdownAlignment.LEFT}
+                onChange={setValue}
+            />
+        </div>
+    );
+};
+
+const typeOptions = Object.values(EChipType).map((type) => ({
+    value: type,
+    label: type.toUpperCase(),
+}));
+
+export const TypesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {typeOptions.map(({ value, label }) => (
+            <TypeItem key={value} type={value} label={label} />
+        ))}
+    </div>
+);
+```
+
+### Sizes
+
+`stories/Chips/examples/ChipDatePicker/SizesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ChipDatePicker, EComponentSize, EDropdownAlignment } from "@sberbusiness/triplex-next";
+
+type SizeItemProps = {
+    size: EComponentSize;
+    label: string;
+};
+
+const SizeItem = ({ size, label }: SizeItemProps) => {
+    const [value, setValue] = useState("");
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{label}</div>
+            <ChipDatePicker
+                size={size}
+                alignment={EDropdownAlignment.LEFT}
+                value={value}
+                label="Date label"
+                onChange={setValue}
+            />
+        </div>
+    );
+};
+
+const sizeOptions = Object.values(EComponentSize).map((size) => ({
+    value: size,
+    label: size.toUpperCase(),
+}));
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {sizeOptions.map(({ value, label }) => (
+            <SizeItem key={value} size={value} label={label} />
+        ))}
+    </div>
+);
+```
+