DateField

DateField — составной компонент для ввода одной даты, который объединяет ввод с клавиатуры, необязательный выбор в календаре и ограничения на уровне поля в одном элементе управления.

Storybook Исходники

Пропсы корня

Проп	Тип	По умолчанию
`value`	`string`	—
Контролируемая дата в виде строки `YYYY-MM-DD`; `''`, пока в поле нет полной даты.
`defaultValue`	`string`	`''`
Начальная дата для неконтролируемого использования в виде строки `YYYY-MM-DD`. По умолчанию `''` — пустое поле.
`onChangeValue`	`(value: string) => void`	—
Вызывается с датой `YYYY-MM-DD` при её изменении и с `''`, когда текст очищен или не заполнен до конца.
`format`обязательный	`string`	—
Шаблон формата даты для маски ввода и разбора. Определяет порядок сегментов даты. Примеры: "dd.MM.yyyy"; "MM/dd/yyyy"; "yyyy-MM-dd"
`separator`обязательный	`string`	—
Символ-разделитель сегментов даты в поле. Примеры: "."; "/"; "-"
`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>.

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

DateFieldInput: поверхность для ввода.
DateFieldTriggerIconButton: необязательная кнопка-триггер календаря.
DateFieldCalendar: содержимое календаря, синхронизированное со значением поля.

`DateFieldInput`

Проп	Тип	По умолчанию
`ref`	`Ref<HTMLInputElement>`	—
Ref, передаваемый на нижележащий нативный элемент `<input>`.

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

`DateFieldCalendar`

Проп	Тип	По умолчанию
`max`	`string`	—
Самая поздняя доступная для выбора дата в виде строки `YYYY-MM-DD`. Месяцы и годы после этой даты становятся недоступны. Пикеры дней, месяцев и годов используют её, чтобы отключать или ограничивать навигацию.
`min`	`string`	—
Самая ранняя доступная для выбора дата в виде строки `YYYY-MM-DD`. Месяцы и годы до этой даты становятся недоступны. Все пикеры учитывают это ограничение при вычислении активных диапазонов.
`selection`	`"single"`	—
Режим выбора. Определяет форму `value`, все даты — строки `YYYY-MM-DD`: 'single' — строка, `''`, когда ничего не выбрано; 'multiple' — массив строк; 'range' — кортеж `[start, end]`, где `start` не позже `end`, а `''` обозначает незаданную границу. По умолчанию: `'single'`
`view`	`CalendarView`	—
Контролируемый видимый вид: 'day' — дни видимого месяца (`CalendarDays`); 'month' — месяцы видимого года (`CalendarMonths`); 'year' — страницы годов (`CalendarYears`)
`value`	`string`	—
Контролируемое значение выбора, форма которого зависит от режима `selection`. Некорректные или несуществующие даты считаются невыбранными.
`defaultValue`	`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>.

`DateFieldTriggerIconButton`

Проп	Тип	По умолчанию
`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>.

Типы

DateFieldProps
DateFieldInputProps
DateFieldTriggerIconButtonProps
DateFieldCalendarProps

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

Корень владеет общим значением даты, которое используют и ввод с клавиатуры, и выбор в календаре.
Корень принимает value, defaultValue и onChangeValue как день YYYY-MM-DD, как значение нативного <input type="date">; DateFieldInput показывает его в формате format и по-прежнему вызывает собственные onChange и onInput. Пока текст пуст или неполон, значение равно '', и в календаре ничего не выбрано. Сброс формы восстанавливает defaultValue, если поле не контролируемое.
При изменении min или max введённый текст снова ограничивается так же, как при вводе, с событием input.
Разбор и форматирование определяются format и separator.
min, max и disabledDates должны соответствовать валидации продукта, а не только визуальным подсказкам.
Нативная семантика формы берётся от нижележащего текстового input, а не от отдельной скрытой части наподобие select.