0.14.3 • Published 3d ago

@snack-uikit/calendar

Licence

Apache-2.0

Version

0.14.3

Deps

Size

437 kB

Vulns

Weekly

Stars

Summary Dependency Versions

Calendar

Installation

npm i @snack-uikit/calendar

Changelog

Description

Пакет @snack-uikit/calendar предоставляет компоненты для выбора даты, диапазона дат и времени: календарь (Calendar) и отдельный пикер времени (TimePicker).
Компоненты покрывают основные сценарии работы с датой и временем: выбор одной даты, периода, месяца, года или даты с временем, а также точную установку времени по часам, минутам и опционально секундам.
Оба компонента поддерживают локализацию (язык и формат дат), управление фокусом с клавиатуры и подстройку под размер контейнера через fitToContainer, что упрощает их встраивание в сложные интерфейсы.
Для режима диапазона в календаре доступны пресеты быстрого выбора периода (например, «Сегодня», «Неделя», «Месяц»), которые можно настраивать через проп presets.

Calendar

Description

Calendar — основной компонент для выбора дат и периодов: он может работать в режимах date, date-range, month, month-range, year-range, year и date-time (дата и время).
Компонент поддерживает как контролируемый (value + onChangeValue), так и неконтролируемый (defaultValue) режимы и умеет подстраиваться под разные размеры через проп size (s, m, l).
С помощью колбека buildCellProps можно управлять доступностью и подсветкой отдельных ячеек (например, отключить прошлые даты или выделить праздничные дни), а опция showHolidays автоматически раскрашивает выходные.
Проп presets позволяет добавить панель с пресетами для быстрого выбора периода в режиме date-range, в том числе с собственным списком вариантов.
Локаль (locale) задаёт язык подписей и первый день недели, при отсутствии явно переданного значения используется язык браузера пользователя.
Figma: Calendar.

Example

import { Calendar } from '@snack-uikit/calendar';

function CalendarExample() {
  return (
    <>
      {/* Выбор одной даты */}
      <Calendar
        mode='date'
        onChangeValue={(selectedDate: Date) => {
          console.log('Selected date:', selectedDate);
        }}
      />

      {/* Выбор периода c пресетами */}
      <Calendar
        mode='date-range'
        presets={{
          enabled: true,
          title: true,
        }}
        onChangeValue={(selectedRange) => {
          console.log('Selected range:', selectedRange);
        }}
      />

      {/* Выбор даты и времени с отображением секунд */}
      <Calendar
        mode='date-time'
        showSeconds
        onChangeValue={(selectedDateTime: Date) => {
          console.log('Selected date and time:', selectedDateTime);
        }}
      />
    </>
  );
}

TimePicker

Description

TimePicker — компонент для точного выбора времени (часы, минуты и при необходимости секунды) без выбора календарной даты.
Поддерживает контролируемый и неконтролируемый режимы через пропы value, defaultValue и onChangeValue, а результирующее значение представлено объектом TimeValue ({ hours, minutes, seconds }).
Проп today позволяет подсветить «текущее» время (например, рабочее время или время на момент открытия) на основании переданной даты.
Компонент адаптируется под размеры (size — s, m, l) и может растягиваться по контейнеру через fitToContainer, а также поддерживает управление фокусом (onFocusLeave, navigationStartRef) для сложных форм и диалогов.
Figma: TimePicker.

Example

import { TimePicker } from '@snack-uikit/calendar';

function TimePickerExample() {
  return (
    <TimePicker
      showSeconds
      onChangeValue={value => {
        if (!value) {
          return;
        }

        const { hours, minutes, seconds } = value;
        console.log(`Selected time: ${hours}:${minutes}:${seconds}`);
      }}
    />
  );
}

Calendar

Props

name	type	default value	description
mode*	"date" \| "date-time" \| "date-range" \| "month" \| "month-range" \| "year" \| "year-range"	-	Режим работы календаря: - `date` - режим выбора даты - `date-range` - режим выбора периода - `month-range` - режим выбора периода из месяцев - `year-range` - режим выбора периода из лет - `month` - режим выбора месяца - `date-time` - режим выбора даты и времени - `year` - режим выбора года
size	enum Size: `"s"`, `"m"`, `"l"`	m	Размер
today	`number \| Date`	-	Дата сегодняшнего дня
showHolidays	`boolean`	-	Раскрашивает субботу и воскресенье
buildCellProps	`(date: Date, viewMode: ViewMode) => { isDisabled?: boolean; isHoliday?: boolean } ;`	-	Колбек установки свойств ячеек календаря. Вызывается на построение каждой ячейки. Принимает два параметра: `Date` - дата ячейки `ViewMode`: - `month` отображение месяца, каждая ячейка - 1 день - `year` отображение года, каждая ячейка - 1 месяц - `decade` отображение декады, каждая ячейка - 1 год Колбек должен возвращать объект с полями, отвечающими за отключение и подкраску ячейки.
className	`string`	-	CSS-класс контейнера
fitToContainer	`boolean`	true	Отключает предустановленный размер, заставляя компонент подстраиваться к размеру контейнра: (width: 100%, height: 100%).
style	`CSSProperties`	-	Объект со стилями на контейнер.
autofocus	`boolean`	-	Автофокус
locale	`Intl.Locale`	Проставляется в соответствие с языком в настройках браузера	Локаль, в соответствие с которой выставляется язык названий и первый день недели
onFocusLeave	`(direction: FocusDirection) => void`	-	Колбек потери фокуса. Вызывается со значением `next`, когда фокус покидает компонент, передвигаясь вперед, по клавише `tab`. Со значением `prev` - по клавише стрелки вверх или `shift + tab`.
navigationStartRef	`RefObject<{ focus(): void; }>`	-	Ссылка на управление первым элементом навигации
presets	`PresetsOptions`	-	Настройки секции с пресетами быстрого выбора периода. Доступны только при mode === 'date-range' и отсутствии buildCellProps (временно PDS-3139)
value	`Date \| Range`	-	Выбранное значение. - в режиме date тип `Date` - в режиме date-range тип `Range` (`[Date, Date]`) - в режиме month-range тип `Range` (`[Date, Date]`) - в режиме year-range тип `Range` (`[Date, Date]`) - в режиме month тип `Date` - в режиме date-time тип `Date` - в режиме year тип `Date`
defaultValue	`Date \| Range`	-	Значение по-умолчанию для uncontrolled. - в режиме date тип `Date` - в режиме date-range тип `Range` (`[Date, Date]`) - в режиме month-range тип `Range` (`[Date, Date]`) - в режиме year-range тип `Range` (`[Date, Date]`) - в режиме month тип `Date` - в режиме date-time тип `Date` - в режиме year тип `Date`
onChangeValue	`((value: Date) => void) \| ((value: Range) => void) \| ((value: Range) => void) \| ((value: Range) => void) \| ((value: Date) => void) \| ((value: Date) => void) \| ((value: Date) => void)`	-	Колбек выбора значения. - в режиме date принимает тип `Date` - в режиме date-range принимает тип `Range` - в режиме month-range принимает тип `Range` - в режиме year-range принимает тип `Range` - в режиме month принимает тип `Date` - в режиме date-time принимает тип `Date` - в режиме year принимает тип `Date`
showSeconds	`boolean`	-	Показывать ли секунды (только в режиме date-time)

TimePicker

Props

name	type	default value	description
value	`TimeValue`	-	Выбранное значение.
today	`number \| Date`	-	Дата сегодняшнего дня
defaultValue	`TimeValue`	-	Значение по-умолчанию для uncontrolled.
onChangeValue	`(value?: TimeValue) => void`	-	Колбек выбора значения
showSeconds	`boolean`	true	Показывать ли секунды
footerMode	enum TimePickerFooterMode: `"current-time-and-apply"`, `"apply-only"`	current-time-and-apply	Режим футера: кнопка выбора текущего времени («Текущее») и подтверждения выбранного («Применить»), либо только подтверждение («Применить»).
size	enum Size: `"s"`, `"m"`, `"l"`	m	Размер
className	`string`	-	CSS-класс контейнера
fitToContainer	`boolean`	true	Отключает предустановленный размер, заставляя компонент подстраиваться к размеру контейнра: (width: 100%, height: 100%).
onFocusLeave	`(direction: FocusDirection) => void`	-	Колбек потери фокуса. Вызывается со значением `next`, когда фокус покидает компонент, передвигаясь вперед, по клавише `tab`. Со значением `prev` - по клавише стрелки вверх или `shift + tab`.
navigationStartRef	`RefObject<{ focus(): void; }>`	-	Ссылка на управление первым элементом навигации