@cloud-ru/ds-calendar 1.0.0

package/src/hooks/useOpenTrigger.tsx

@@ -0,0 +1,35 @@
+import { cloneElement, isValidElement, KeyboardEvent, MouseEvent, ReactNode } from 'react';
+
+type TriggerProps = { onClick?(event: MouseEvent<HTMLElement>): void };
+
+/** Триггер открытия mobile-dropdown'а: valid element клонируется с onClick, остальное — span с Enter/Space. */
+export function useOpenTrigger(children: ReactNode, onOpen: () => void): ReactNode {
+  if (isValidElement<TriggerProps>(children)) {
+    return cloneElement(children, {
+      onClick: (event: MouseEvent<HTMLElement>) => {
+        children.props.onClick?.(event);
+        onOpen();
+      },
+    });
+  }
+
+  if (children == null) {
+    return null;
+  }
+
+  return (
+    <span
+      role='button'
+      tabIndex={0}
+      onClick={onOpen}
+      onKeyDown={(event: KeyboardEvent<HTMLSpanElement>) => {
+        if (event.key === 'Enter' || event.key === ' ') {
+          event.preventDefault();
+          onOpen();
+        }
+      }}
+    >
+      {children}
+    </span>
+  );
+}

package/src/hooks/useTimeDrumHandlers.ts

@@ -0,0 +1,35 @@
+import { useCallback } from 'react';
+
+import { DateAndTime, TimeValue } from '../types';
+
+type TimePart = 'hours' | 'minutes' | 'seconds';
+
+export type TimeDrumHandlers = {
+  onHoursChange(next: number): void;
+  onMinutesChange(next: number): void;
+  onSecondsChange(next: number): void;
+};
+
+/** Обработчики колонок `TimePickerDrum`: меняют одну часть в `dateAndTime`, остальные сохраняют. */
+export function useTimeDrumHandlers(
+  dateAndTime: DateAndTime | undefined,
+  onTimeChange: (value: TimeValue | Date) => void,
+): TimeDrumHandlers {
+  const getTimeChangeHandler = useCallback(
+    (part: TimePart) => (next: number) => {
+      onTimeChange({
+        hours: dateAndTime?.hours ?? 0,
+        minutes: dateAndTime?.minutes ?? 0,
+        seconds: dateAndTime?.seconds ?? 0,
+        [part]: next ?? dateAndTime?.[part] ?? 0,
+      });
+    },
+    [dateAndTime, onTimeChange],
+  );
+
+  return {
+    onHoursChange: getTimeChangeHandler('hours'),
+    onMinutesChange: getTimeChangeHandler('minutes'),
+    onSecondsChange: getTimeChangeHandler('seconds'),
+  };
+}

package/src/hooks/useTimePickerValueBridge.ts

@@ -0,0 +1,125 @@
+import { useEventHandler, useUncontrolledProp } from '@cloud-ru/ds-utils';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { Range, TimeValue } from '../types';
+import { isTimePortionComplete, timeValuesEqual } from '../utils';
+import { useDateAndTime } from './useDateAndTime';
+
+export type UseTimePickerValueBridgeParams = {
+  value?: TimeValue;
+  defaultValue?: TimeValue;
+  onChangeValue?(value: TimeValue): void;
+  showSeconds: boolean;
+};
+
+export type TimePickerValueBridge = {
+  /** Контролируемое/неконтролируемое значение времени (наружу). */
+  value?: TimeValue;
+  /** Внутреннее `Range`-представление выбранного времени для `CalendarContext.value`. */
+  internalValue?: Range;
+  /** `CalendarContext.setValue` — принимает `Range`, обновляет `internalValue`. */
+  setValue(dates: Range): void;
+} & Pick<
+  ReturnType<typeof useDateAndTime>,
+  | 'dateAndTime'
+  | 'onTimeChange'
+  | 'onDateChange'
+  | 'onDateAndTimeChange'
+  | 'isDateFilled'
+  | 'isTimeFilled'
+  | 'isDateAndTimeFilled'
+>;
+
+/**
+ * Мост значения для time-picker'ов (desktop popover и mobile bottom sheet): связывает публичное `TimeValue`
+ * с внутренним `dateAndTime` через `Range`-буфер `internalValue`, с защитой от цикла обновлений при внешней
+ * смене `value` (см. `lastValueKeyRef`). Выделен из `TimePickerDropdown`, чтобы обе поверхности шарили логику.
+ */
+export function useTimePickerValueBridge({
+  value: valueProp,
+  defaultValue,
+  onChangeValue,
+  showSeconds,
+}: UseTimePickerValueBridgeParams): TimePickerValueBridge {
+  const [value, setValueState] = useUncontrolledProp<TimeValue | undefined>(valueProp, defaultValue, onChangeValue);
+  const setValueEventHandler = useEventHandler(setValueState);
+  const [internalValue, setInternalValue] = useState<Range | undefined>();
+  const previousValueRef = useRef(value);
+
+  useEffect(() => {
+    if (!internalValue?.[0]) {
+      return;
+    }
+
+    const hours = internalValue[0].getHours();
+    const minutes = internalValue[0].getMinutes();
+    const seconds = internalValue[0].getSeconds();
+
+    setValueEventHandler({ hours, minutes, seconds });
+  }, [internalValue, setValueEventHandler]);
+
+  const setValue = useCallback((dates: Range) => {
+    const newDate = dates[0];
+    setInternalValue([newDate, newDate]);
+  }, []);
+
+  const {
+    dateAndTime,
+    onTimeChange,
+    onDateChange,
+    onDateAndTimeChange,
+    isDateFilled,
+    isTimeFilled,
+    isDateAndTimeFilled,
+  } = useDateAndTime({ showSeconds, value });
+
+  // Этот эффект распространяет правки времени из пикера (dateAndTime) → value. Внешнее изменение
+  // `value` синхронизируется в dateAndTime ОТДЕЛЬНЫМ эффектом (useDateAndTime), который отрабатывает
+  // на рендер позже. Без guard'а в цикле внешней смены value этот эффект видит УСТАРЕВШИЙ dateAndTime
+  // и эмитит его обратно, откатывая внешнее значение → бесконечный ре-рендер. Поэтому в цикл, где
+  // value изменился извне, эмит пропускаем и даём dateAndTime догнаться.
+  const lastValueKeyRef = useRef<string | null>(null);
+  useEffect(() => {
+    const wasValueCleared = value === undefined && previousValueRef.current !== undefined;
+    previousValueRef.current = value;
+
+    // Ключ внешнего value: если он изменился с прошлого рендера, значит value пришёл извне,
+    // а dateAndTime ещё не догнался — эмит в этом цикле пропускаем.
+    const valueKey = value ? `${value.hours}:${value.minutes}:${value.seconds}` : null;
+    const externalValueChanged = valueKey !== lastValueKeyRef.current;
+    lastValueKeyRef.current = valueKey;
+
+    if (wasValueCleared) {
+      return;
+    }
+
+    if (!isTimePortionComplete(dateAndTime, showSeconds)) {
+      return;
+    }
+
+    const next: TimeValue = {
+      hours: dateAndTime.hours ?? 0,
+      minutes: dateAndTime.minutes ?? 0,
+      seconds: dateAndTime.seconds ?? 0,
+    };
+
+    if (timeValuesEqual(value, next) || externalValueChanged) {
+      return;
+    }
+
+    setValueEventHandler(next);
+  }, [dateAndTime, showSeconds, setValueEventHandler, value]);
+
+  return {
+    value,
+    internalValue,
+    setValue,
+    dateAndTime,
+    onTimeChange,
+    onDateChange,
+    onDateAndTimeChange,
+    isDateFilled,
+    isTimeFilled,
+    isDateAndTimeFilled,
+  };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './components';
+export * from './constants';
+export * from './types';
+export * from './locale';

package/src/locale/index.ts

@@ -0,0 +1,53 @@
+import { defineLocale, defineMessages } from '@cloud-ru/ds-locale';
+
+const CALENDAR_MESSAGES = defineMessages({
+  'en-GB': {
+    current: 'Current',
+    apply: 'Apply',
+    time: 'Time',
+    presets: 'Presets',
+    selected: 'Selected:',
+    prevPeriodMonth: 'Previous month',
+    nextPeriodMonth: 'Next month',
+    prevPeriodYear: 'Previous year',
+    nextPeriodYear: 'Next year',
+    prevPeriodDecade: 'Previous decade',
+    nextPeriodDecade: 'Next decade',
+    defaultPresets: {
+      lastWeek: 'Last 7 days',
+      lastTwoWeeks: 'Last 14 days',
+      lastMonth: 'Last 30 days',
+      lastQuarter: 'Last 90 days',
+      lastThird: 'Last 120 days',
+      lastYear: 'Last 1 year',
+      lastTwoYears: 'Last 2 years',
+    },
+  },
+  'ru-RU': {
+    current: 'Сейчас',
+    apply: 'Применить',
+    time: 'Время',
+    presets: 'Пресеты',
+    selected: 'Выбрано:',
+    prevPeriodMonth: 'Предыдущий месяц',
+    nextPeriodMonth: 'Следующий месяц',
+    prevPeriodYear: 'Предыдущий год',
+    nextPeriodYear: 'Следующий год',
+    prevPeriodDecade: 'Предыдущее десятилетие',
+    nextPeriodDecade: 'Следующее десятилетие',
+    defaultPresets: {
+      lastWeek: 'Последние 7 дней',
+      lastTwoWeeks: 'Последние 14 дней',
+      lastMonth: 'Последние 30 дней',
+      lastQuarter: 'Последние 90 дней',
+      lastThird: 'Последние 120 дней',
+      lastYear: 'Последний 1 год',
+      lastTwoYears: 'Последние 2 года',
+    },
+  },
+});
+
+export type CalendarMessages = (typeof CALENDAR_MESSAGES)['en-GB'];
+
+/** locale компонента Calendar: `calendarLocale.useTranslations()` в коде, `calendarLocale.extend(...)` в сервисе. */
+export const calendarLocale = defineLocale('@cloud-ru/ds-calendar', CALENDAR_MESSAGES);

package/src/types.ts

@@ -0,0 +1,88 @@
+import { ValueOf } from '@cloud-ru/ds-utils';
+import { KeyboardEventHandler } from 'react';
+
+import { CALENDAR_MODE, RANGE_POSITION, SIZE, VIEW_MODE } from './constants';
+
+export type RangePosition = ValueOf<typeof RANGE_POSITION>;
+
+export type ViewMode = ValueOf<typeof VIEW_MODE>;
+
+export type Size = ValueOf<typeof SIZE>;
+
+export type CalendarMode = ValueOf<typeof CALENDAR_MODE>;
+
+export type Range = [Date, Date];
+
+export type BaseGridItem = { date: Date; address: [number, number] };
+
+export type BaseGrid = BaseGridItem[][];
+
+export type Cell = {
+  /** Дата ячейки (для колбэков выбора) */
+  date: Date;
+  /** Адрес ячейки в сетке — синхронизация фокуса и клавиатуры */
+  address: [number, number];
+  /** Значение */
+  label: string;
+  /** Является ли сегодняшним днем */
+  current: boolean;
+  /** Выбран ли элемент */
+  checked: boolean;
+  /** Деактивирован ли */
+  disabled?: boolean;
+  /** Является ли выходным/праздником */
+  holiday?: boolean;
+  /**
+   * Относится ли к иному периоду (не к просматриваемому в данный момент)
+   */
+  another: boolean;
+  /**
+   * Является ли частью range
+   * @default out
+   */
+  rangePosition: RangePosition;
+  /** Индекс фокуса кнопки */
+  tabIndex: -1 | 0;
+  onSelect?(date: Date): void;
+  onPreselect?(date: Date): void;
+  onLeave?(): void;
+  onKeyDown?: KeyboardEventHandler;
+};
+
+export type FocusDirection = 'prev' | 'next';
+
+export type BuildCellProps = { isDisabled?: boolean; isHoliday?: boolean };
+export type BuildCellPropsFunction = (date: Date, viewMode: ViewMode) => BuildCellProps;
+
+export type TimeValue = {
+  hours?: number;
+  minutes?: number;
+  seconds?: number;
+};
+
+export type DateAndTime = TimeValue & {
+  year?: number;
+  month?: number;
+  day?: number;
+};
+
+export type PresetItem = {
+  /** Лейбл пресета */
+  label: string;
+  /** ID периода */
+  id: string;
+  /** Период */
+  range: Range;
+};
+
+export type PresetsOptions = {
+  /**
+   * Включение отображения секции с пресетами
+   * @default false
+   */
+  enabled?: boolean;
+  /** Кастомные пресеты быстрого выбора периода относительно текущего момента */
+  items?: PresetItem[];
+};
+
+export type OnKeyDownGetter = (id: number) => KeyboardEventHandler;

package/src/utils.ts

@@ -0,0 +1,151 @@
+import { Lang } from '@cloud-ru/ds-locale';
+import { isBrowser } from '@cloud-ru/ds-utils';
+import { getWeekStartByLocale } from 'weekstart';
+
+import { CALENDAR_MODE, RANGE_POSITION, VIEW_MODE } from './constants';
+import { CalendarMode, DateAndTime, Range, RangePosition, TimeValue, ViewMode } from './types';
+
+export const isTheSameDecade = (date1: Date, date2: Date) =>
+  Math.floor(date1.getFullYear() / 10) === Math.floor(date2.getFullYear() / 10);
+
+export const isTheSameYear = (date1: Date, date2: Date): boolean => date1.getFullYear() === date2.getFullYear();
+
+export const isTheSameMonth = (date1: Date, date2: Date): boolean =>
+  isTheSameYear(date1, date2) && date1.getMonth() === date2.getMonth();
+
+export function isTheSameDate(date1: Date, date2: Date): boolean {
+  return isTheSameMonth(date1, date2) && date1.getDate() === date2.getDate();
+}
+
+export function timeValuesEqual(current: TimeValue | undefined, next: TimeValue): boolean {
+  if (current === undefined) {
+    return false;
+  }
+
+  return (
+    (current.hours ?? 0) === (next.hours ?? 0) &&
+    (current.minutes ?? 0) === (next.minutes ?? 0) &&
+    (current.seconds ?? 0) === (next.seconds ?? 0)
+  );
+}
+
+export const capitalize = (str: string) => str.substring(0, 1).toUpperCase() + str.substring(1);
+
+export const getMonthName = (date: Date, locale?: Intl.Locale): string => {
+  const monthName = date.toLocaleString(locale, { month: 'long' });
+  return capitalize(monthName);
+};
+
+export const getDateLabel = (date: Date) => date.getDate().toString();
+
+export const getYearLabel = (date: Date) => date.getFullYear().toString();
+
+export const getMonthShift = (today: Date, targetDate: Date) => {
+  const overYearDiff = (targetDate.getFullYear() - today.getFullYear()) * 12;
+  const monthsDiff = targetDate.getMonth() - today.getMonth();
+  return overYearDiff + monthsDiff;
+};
+
+export const getYearShift = (today: Date, targetDate: Date) => targetDate.getFullYear() - today.getFullYear();
+
+export const getDecadeShift = (today: Date, targetDate: Date) =>
+  Math.trunc((targetDate.getFullYear() - today.getFullYear()) / 10);
+
+export const isTheSameItem = (viewMode: ViewMode, date1: Date, date2: Date): boolean => {
+  switch (viewMode) {
+    case VIEW_MODE.Month:
+      return isTheSameDate(date1, date2);
+    case VIEW_MODE.Year:
+      return isTheSameMonth(date1, date2);
+    case VIEW_MODE.Decade:
+      return isTheSameYear(date1, date2);
+    default:
+      return false;
+  }
+};
+
+export const sortDates = (dates: Date[]): Date[] => [...dates].sort((d1, d2) => d1.valueOf() - d2.valueOf());
+
+export const getInRangePosition = (date: Date, viewMode: ViewMode, range?: Range): RangePosition => {
+  if (!range) {
+    return RANGE_POSITION.Out;
+  }
+
+  const [startDate, endDate] = sortDates(range);
+
+  const isStart = isTheSameItem(viewMode, date, startDate);
+  const isEnd = isTheSameItem(viewMode, date, endDate);
+
+  if (isStart && isEnd) {
+    return RANGE_POSITION.StartEnd;
+  }
+
+  if (isStart) {
+    return RANGE_POSITION.Start;
+  }
+
+  if (isEnd) {
+    return RANGE_POSITION.End;
+  }
+
+  const [start, end] = [startDate.valueOf(), endDate.valueOf()];
+
+  return date.valueOf() >= start && date.valueOf() <= end ? RANGE_POSITION.In : RANGE_POSITION.Out;
+};
+
+export const getEndOfTheDay = (date: Date) =>
+  new Date(new Date(date.getFullYear(), date.getMonth(), date.getDate() + 1).valueOf() - 1);
+
+export const getStartOfTheMonth = (date: Date) => new Date(new Date(date.getFullYear(), date.getMonth(), 1).valueOf());
+
+export const getEndOfTheMonth = (date: Date) =>
+  new Date(new Date(date.getFullYear(), date.getMonth() + 1, 1).valueOf() - 1);
+
+export const getStartOfTheYear = (date: Date) => new Date(new Date(date.getFullYear(), 0, 1).valueOf());
+
+export const getEndOfTheYear = (date: Date) => new Date(new Date(date.getFullYear() + 1, 0, 1).valueOf() - 1);
+
+/**
+ * Нормализует выбранный период под границы режима (`setValue` десктопа и мобайла дают одинаковый результат):
+ * month/month-range — границы месяца, year/year-range — границы года, иначе — конец дня для верхней границы.
+ */
+export function normalizeRangeForMode(mode: CalendarMode | 'time', dates: Range): Range {
+  const [first, last] = sortDates(dates) as Range;
+
+  switch (mode) {
+    case CALENDAR_MODE.Month:
+    case CALENDAR_MODE.MonthRange:
+      return [getStartOfTheMonth(first), getEndOfTheMonth(last)];
+    case CALENDAR_MODE.Year:
+    case CALENDAR_MODE.YearRange:
+      return [getStartOfTheYear(first), getEndOfTheYear(last)];
+    default:
+      return [first, getEndOfTheDay(last)];
+  }
+}
+
+export const getTestIdBuilder = (testId?: string) => (prefix: string) => (testId ? `${prefix}-${testId}` : undefined);
+
+const getNavigatorLocale = () => (isBrowser() ? (navigator?.language ?? 'ru-RU') : 'ru-RU');
+
+export const getLocale = ({ localeProp, ctxLang }: { localeProp?: Intl.Locale; ctxLang?: Lang } = {}) =>
+  localeProp || new Intl.Locale(ctxLang ? ctxLang.replace('_', '-') : getNavigatorLocale());
+
+export const getStartOfWeek = (locale: Intl.Locale) => getWeekStartByLocale(locale.language);
+
+export const isWeekend = (date: Date, viewMode: ViewMode) => {
+  if (viewMode === 'month') {
+    return date.getDay() === 0 || date.getDay() === 6;
+  }
+  return false;
+};
+
+export function isTimePortionComplete(
+  dateAndTime: Pick<DateAndTime, 'hours' | 'minutes' | 'seconds'>,
+  showSeconds?: boolean,
+): boolean {
+  const { hours, minutes, seconds } = dateAndTime;
+  return [hours, minutes, ...(showSeconds ? [seconds] : [])].every(v => v !== undefined);
+}
+
+export const stringifyAddress = (address: [number, number]): string => address.join('-');