# DateRangeField: API

## Пропсы корня

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `value` | `[start: string, end: string]` | — | Нет | Контролируемый диапазон в виде кортежа `[start, end]` из строк `YYYY-MM-DD`. Граница равна `''`, пока она не заполнена; без начала диапазон пуст. |
| `defaultValue` | `[start: string, end: string]` | `['', '']` | Нет | Начальный диапазон для неконтролируемого использования, как у `value`. По умолчанию `['', '']` — пустое поле. |
| `onChangeValue` | `(value: [start: string, end: string]) => void` | — | Нет | Вызывается с диапазоном при его изменении. |
| `format` | `string` | — | Да | Шаблон формата даты для маски ввода и разбора. Определяет порядок сегментов даты. Примеры: "dd.MM.yyyy"; "MM/dd/yyyy"; "yyyy-MM-dd" |
| `separator` | `string` | — | Да | Символ-разделитель сегментов даты в поле. Примеры: "."; "/"; "-" |
| `rangeSeparator` | `string` | `' – '` | Нет | Разделитель между начальной и конечной датами в поле диапазона, по умолчанию — короткое тире между неразрывными пробелами (`'\u00A0–\u00A0'`). Определяет, как две даты визуально и логически разделяются при вводе или отображении диапазона дат. Примеры: " – " → "01.01.2024 – 31.01.2024"; " - " → "01.01.2024 - 31.01.2024"; " to " → "01.01.2024 to 31.01.2024". Если не задан, используется короткое тире между неразрывными пробелами (U+00A0), чтобы диапазон не переносился на разделителе. |
| `min` | `string` | — | Нет | Минимально допустимая дата в виде строки `YYYY-MM-DD`. Даты раньше этого значения нельзя выбрать; при разборе ввода они ограничиваются или отклоняются. |
| `max` | `string` | — | Нет | Максимально допустимая дата в виде строки `YYYY-MM-DD`. Даты позже этого значения нельзя выбрать; при разборе ввода они ограничиваются или отклоняются. |
| `disabledDates` | `CalendarDatesDisabled` | — | Нет | Правила отключения отдельных дат в календаре. Можно использовать, чтобы блокировать диапазоны, дни недели или собственные условия. |
| `disabled` | `boolean` | — | Нет | Отключает поле. Запрещает ввод и взаимодействие и применяет визуальное отключённое состояние. |
| `calendar` | `CalendarSystem` | `gregorianCalendar` | Нет | Календарная система, в которой даты вводятся и выбираются. Значения остаются днями в формате `YYYY-MM-DD`. По умолчанию — григорианский календарь. |
| `locale` | `string` | — | Нет | Локаль BCP 47 всплывающего календаря (названия месяцев и дней, первый день недели), например `de-DE`. Формат ввода по-прежнему задаётся `format`. По умолчанию — локаль среды выполнения, как у `Intl`. |
| `size` | `TextFieldSize` | — | Нет | Визуальный размер текстового поля. Влияет на отступы, размер шрифта и общую высоту. 'sm': компактное поле; 'md': по умолчанию; 'lg': просторная раскладка |
| `ref` | `Ref<HTMLDivElement>` | — | Нет | Ref, передаваемый на элемент-обёртку. Полезен для программного управления, фокуса или интеграции. |
| `error` | `boolean` | — | Нет | Показывает поле ввода в состоянии ошибки. |

Также принимает все атрибуты `<div>`.

## Дочерние части

- `DateRangeFieldInput`: поверхность ввода дат начала и окончания.
- `DateRangeFieldTriggerIconButton`: необязательная кнопка-триггер календаря.
- `DateRangeFieldCalendar`: содержимое календаря, синхронизированное с выбранным диапазоном.

### `DateRangeFieldInput`

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `ref` | `Ref<HTMLInputElement>` | — | Нет | Ref, передаваемый на нижележащий нативный элемент `<input>`. |

Также принимает все атрибуты `<input>`.

### `DateRangeFieldCalendar`

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `max` | `string` | — | Нет | Самая поздняя доступная для выбора дата в виде строки `YYYY-MM-DD`. Месяцы и годы после этой даты становятся недоступны. Пикеры дней, месяцев и годов используют её, чтобы отключать или ограничивать навигацию. |
| `min` | `string` | — | Нет | Самая ранняя доступная для выбора дата в виде строки `YYYY-MM-DD`. Месяцы и годы до этой даты становятся недоступны. Все пикеры учитывают это ограничение при вычислении активных диапазонов. |
| `selection` | `"range"` | — | Нет | Режим выбора. Определяет форму `value`, все даты — строки `YYYY-MM-DD`: 'single' — строка, `''`, когда ничего не выбрано; 'multiple' — массив строк; 'range' — кортеж `[start, end]`, где `start` не позже `end`, а `''` обозначает незаданную границу. По умолчанию: `'single'` |
| `view` | `CalendarView` | — | Нет | Контролируемый видимый вид: 'day' — дни видимого месяца (`CalendarDays`); 'month' — месяцы видимого года (`CalendarMonths`); 'year' — страницы годов (`CalendarYears`) |
| `value` | `[start: string, end: string]` | — | Нет | Контролируемое значение выбора, форма которого зависит от режима `selection`. Некорректные или несуществующие даты считаются невыбранными. |
| `defaultValue` | `[start: string, end: string]` | — | Нет | Неконтролируемое начальное значение выбора, форма которого зависит от режима `selection`. |
| `defaultView` | `CalendarView` | — | Нет | Начальный вид для неконтролируемого использования. По умолчанию: `'day'` |
| `disabled` | `boolean` | — | Нет | Отключает весь календарь: ни одну дату нельзя выбрать, навигация выключена. |
| `disabledDates` | `CalendarDatesDisabled` | — | Нет | Даты, которые нельзя выбрать, в виде строк `YYYY-MM-DD`: одна дата; массив дат; предикат `(date: string) => boolean` |
| `onChangeValue` | `(value: CalendarValue<S>) => void` | — | Нет | Вызывается, когда пользователь меняет выбор. Форма значения зависит от режима `selection`. |
| `onChangeView` | `(view: CalendarView) => void` | — | Нет | Вызывается при изменении видимого вида. |
| `month` | `string` | — | Нет | Контролируемый видимый месяц — строка `YYYY-MM-DD` любого дня этого месяца. |
| `defaultMonth` | `string` | — | Нет | Начальный видимый месяц для неконтролируемого использования — строка `YYYY-MM-DD` любого дня этого месяца. По умолчанию: месяц выбранной даты, иначе текущий месяц |
| `onChangeMonth` | `(month: string) => void` | — | Нет | Вызывается с первым днём видимого месяца в виде строки `YYYY-MM-DD`, когда видимый месяц меняется (например, при прокрутке или через пикеры месяца и года). Это событие отражает навигацию по виду, а не выбор. |
| `calendar` | `CalendarSystem` | — | Нет | Календарная система, в которой показывается календарь. Значения остаются днями в формате `YYYY-MM-DD`. По умолчанию — григорианский календарь. |
| `locale` | `string` | — | Нет | Локаль BCP 47 для названий месяцев и дней и первого дня недели, например `de-DE`. Применяется ко всем частям календаря и задаёт `lang` на корне. По умолчанию — локаль среды выполнения, как у `Intl`. |
| `size` | `CalendarBaseSize` | — | Нет | Общая шкала размера календаря. Через `CalendarBaseContext` влияет на вложенные элементы управления: кнопки навигации, триггеры пикеров и подписи дней недели. |
| `variant` | `CalendarBaseVariant` | — | Нет | Визуальный вариант календаря. Передаётся через `CalendarBaseContext` и используется вложенными элементами управления (кнопками, подписями и т. д.) для единообразной стилизации. |
| `compact` | `boolean` | — | Нет | Флаг плотности для более компактных раскладок. При `true` корневой элемент получает `data-compact="true"`, чтобы стили могли уменьшить отступы, промежутки и высоту элементов управления для более плотного календаря. При `false` или `undefined` календарь использует обычные интервалы. |

Также принимает все атрибуты `<div>`.

### `DateRangeFieldTriggerIconButton`

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `size` | `IconButtonSize` | — | Нет | Размер контейнера кнопки. Управляет отступами и общей кликабельной областью. |
| `asChild` | `boolean` | — | Нет | Если true, рендерит кнопку как дочерний компонент через `Slot` (например, из Radix UI). Включает полиморфный рендер — полезно, чтобы кнопка работала как ссылка или собственный тег. |
| `variant` | `ButtonBaseVariant` | — | Нет | Определяет визуальный стиль кнопки: цветовую схему и акцент. |
| `appearance` | `ButtonBaseAppearance` | — | Нет | Настраивает структурный внешний вид кнопки (фон, рамка и т. д.). |
| `disabled` | `boolean` | — | Нет | Отключает кнопку при true. Запрещает взаимодействие и применяет визуальное отключённое состояние. Не применяется с `asChild`: отключённым состоянием владеет дочерний элемент, например через `aria-disabled` или ссылку без `href`. |
| `className` | `string` | — | Нет | Необязательный собственный CSS-класс для элемента кнопки. Полезен для переопределений дизайн-системы или локальных стилей. |
| `children` | `ReactNode` | — | Нет | Содержимое кнопки — текст, иконка или любой React-узел. |
| `ref` | `Ref<HTMLButtonElement>` | — | Нет | Ref, передаваемый на нативный элемент `<button>`. Даёт прямой доступ к DOM для управления фокусом или измерений. |

Также принимает все атрибуты `<button>`.

## Типы

- `DateRangeFieldProps`
- `DateRangeFieldInputProps`
- `DateRangeFieldTriggerIconButtonProps`
- `DateRangeFieldCalendarProps`

## Модель состояния

- Корень владеет связанной парой дат, а не двумя несвязанными значениями.
- Частичный ввод — обычное дело при редактировании, и его нужно обрабатывать явно.
- Корень принимает `value`, `defaultValue` и `onChangeValue` как кортеж `[start, end]` из дней `YYYY-MM-DD`; `DateRangeFieldInput` показывает его в формате `format` и по-прежнему вызывает собственные `onChange` и `onInput`. Пока дата начала пуста или неполна, диапазон равен `['', '']`; пока неполна только дата окончания, в диапазоне есть только начало. Сброс формы восстанавливает `defaultValue`, если поле не контролируемое.
- При изменении `min` или `max` обе введённые даты снова ограничиваются так же, как при вводе, с вызовом `input`.
- `rangeSeparator` влияет на видимую композицию и ожидания при разборе.
- Пропсы ограничений должны соответствовать реальным правилам формы и отчётности.