@cloud-ru/ds-calendar 1.0.0

package/src/helperComponents/TimePickerDrum/TimePickerDrumWheelColumn.tsx

@@ -0,0 +1,344 @@
+import { isBrowser } from '@cloud-ru/ds-utils';
+import cn from 'classnames';
+import {
+  CSSProperties,
+  forwardRef,
+  PointerEvent,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import { ROW_REL } from './constants';
+import styles from './styles.module.scss';
+import { mod, nearestInSortedValues } from './utils';
+
+/** Инерция барабана (iOS-подобный «доворот»): затухание скорости за мс и пороги остановки/запуска. */
+const MOMENTUM_DECAY_PER_MS = 0.9966;
+/** Ниже этой |скорости| (px/ms) инерция останавливается и колонка доводится до ближайшего значения. */
+const MOMENTUM_STOP_VELOCITY = 0.02;
+/** Минимальная |скорость| отпускания (px/ms), запускающая инерцию; ниже — сразу snap. */
+const MOMENTUM_MIN_FLING_VELOCITY = 0.05;
+
+export type TimePickerDrumWheelColumnProps = {
+  /**
+   * Допустимые значения колонки: отсортированный по возрастанию список без дубликатов.
+   * Циклическая прокрутка выполняется только по индексам этого массива.
+   */
+  options: number[];
+  /** Текущее выбранное значение; должно входить в `options` (иначе для отображения берётся ближайшее из списка). */
+  value: number;
+  /** Вызывается при смене значения после жеста (отпускание / `lostpointercapture`) или после паузы при прокрутке колесом. */
+  onChange(value: number): void;
+  /** Высота одной строки барабана в пикселях (шаг дискретизации при перетаскивании и колесе). */
+  itemHeight: number;
+  /** Высота видимой области колонки («окна») в пикселях. */
+  height: number;
+  /** Форматирование подписи в ячейке (например с ведущим нулём для минут). */
+  formatLabel(value: number): string;
+  /** Дополнительный CSS-класс корневого элемента колонки (обёртка с обработчиками указателя). */
+  className?: string;
+  /** Идентификатор для автотестов на корневом элементе колонки. */
+  'data-test-id'?: string;
+};
+
+/** Императивный интерфейс колонки: форсит «оседание» незавершённого жеста (инерция/колесо) в `onChange`. */
+export type TimePickerDrumWheelColumnHandle = {
+  /**
+   * Синхронно завершает незакоммиченный жест (инерцию и/или колесо), вызывая `onChange` немедленно,
+   * и возвращает итоговое значение колонки. Нужен, чтобы быстрое закрытие/переход не терял значение,
+   * которое иначе закоммитилось бы только после доворота (см. FF-8654, комментарий #2).
+   */
+  flush(): number;
+};
+
+/**
+ * Колонка «барабана»: 5 строк в DOM, значения по кругу в пределах `options`.
+ */
+export const TimePickerDrumWheelColumn = forwardRef<TimePickerDrumWheelColumnHandle, TimePickerDrumWheelColumnProps>(
+  function TimePickerDrumWheelColumn(
+    { options, value, onChange, itemHeight, height, formatLabel, className, 'data-test-id': dataTestId },
+    ref,
+  ) {
+    const n = options.length;
+
+    const [dragOffset, setDragOffset] = useState(0);
+    const dragOffsetRef = useRef(0);
+    const valueRef = useRef(value);
+    const optionsRef = useRef(options);
+    const startY = useRef(0);
+    const startOffset = useRef(0);
+    const wheelAccum = useRef(0);
+    const wheelTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+    const viewportRef = useRef<HTMLDivElement>(null);
+    // Инерция: скорость отпускания (px/ms), отметка последнего move и хэндл rAF-цикла доворота.
+    const velocityRef = useRef(0);
+    const lastMoveRef = useRef<{ y: number; t: number }>({ y: 0, t: 0 });
+    const momentumRaf = useRef(0);
+
+    useEffect(() => {
+      dragOffsetRef.current = dragOffset;
+    }, [dragOffset]);
+
+    useEffect(() => {
+      valueRef.current = value;
+    }, [value]);
+
+    useEffect(() => {
+      optionsRef.current = options;
+    }, [options]);
+
+    useEffect(() => {
+      setDragOffset(0);
+    }, [value, options]);
+
+    const valueIdx = useMemo(() => {
+      const i = options.indexOf(value);
+      if (i >= 0) {
+        return i;
+      }
+      return options.indexOf(nearestInSortedValues(options, value));
+    }, [options, value]);
+
+    const stepsRounded = Math.round(dragOffset / itemHeight);
+    const previewIndex = n > 0 ? mod(valueIdx - stepsRounded, n) : 0;
+    const dragRemainderPx = dragOffset - stepsRounded * itemHeight;
+
+    const resolveIndex = useCallback((list: number[], raw: number) => {
+      let idx = list.indexOf(raw);
+      if (idx >= 0) {
+        return idx;
+      }
+      idx = list.indexOf(nearestInSortedValues(list, raw));
+      return idx >= 0 ? idx : 0;
+    }, []);
+
+    const commitDrag = useCallback((): number | null => {
+      const list = optionsRef.current;
+      const len = list.length;
+      if (len === 0) {
+        setDragOffset(0);
+        return null;
+      }
+
+      const off = dragOffsetRef.current;
+      const steps = Math.round(off / itemHeight);
+      let committed: number | null = null;
+      if (steps !== 0) {
+        const idx = resolveIndex(list, valueRef.current);
+        committed = list[mod(idx - steps, len)];
+        onChange(committed);
+      }
+      setDragOffset(0);
+      return committed;
+    }, [itemHeight, onChange, resolveIndex]);
+
+    const cancelMomentum = useCallback(() => {
+      if (momentumRaf.current) {
+        cancelAnimationFrame(momentumRaf.current);
+        momentumRaf.current = 0;
+      }
+    }, []);
+
+    /**
+     * Инерционный «доворот» после отпускания (iOS-подобный): колонка продолжает крутиться по скорости
+     * жеста с экспоненциальным затуханием, затем доводится до ближайшего значения (`commitDrag`).
+     * При скорости ниже порога снап происходит сразу. Использует timestamp из rAF (без `performance.now`).
+     */
+    const startMomentum = useCallback(() => {
+      const v0 = velocityRef.current;
+      velocityRef.current = 0;
+
+      if (!isBrowser() || !Number.isFinite(v0) || Math.abs(v0) < MOMENTUM_MIN_FLING_VELOCITY) {
+        commitDrag();
+        return;
+      }
+
+      let velocity = v0;
+      let last = 0;
+      const tick = (now: number) => {
+        if (last === 0) {
+          last = now;
+          if (isBrowser()) {
+            momentumRaf.current = requestAnimationFrame(tick);
+          }
+          return;
+        }
+        const dt = Math.max(1, now - last);
+        last = now;
+
+        dragOffsetRef.current += velocity * dt;
+        setDragOffset(dragOffsetRef.current);
+        velocity *= MOMENTUM_DECAY_PER_MS ** dt;
+
+        if (Math.abs(velocity) < MOMENTUM_STOP_VELOCITY) {
+          momentumRaf.current = 0;
+          commitDrag();
+          return;
+        }
+        if (isBrowser()) {
+          momentumRaf.current = requestAnimationFrame(tick);
+        }
+      };
+      if (isBrowser()) {
+        momentumRaf.current = requestAnimationFrame(tick);
+      }
+    }, [commitDrag]);
+
+    const flushWheel = useCallback((): number | null => {
+      const list = optionsRef.current;
+      const len = list.length;
+      if (len === 0) {
+        return null;
+      }
+
+      const steps = Math.round(wheelAccum.current / itemHeight);
+      wheelAccum.current = 0;
+      if (steps !== 0) {
+        const idx = resolveIndex(list, valueRef.current);
+        const committed = list[mod(idx - steps, len)];
+        onChange(committed);
+        return committed;
+      }
+      return null;
+    }, [itemHeight, onChange, resolveIndex]);
+
+    // Форсит завершение незакоммиченного жеста (инерция + колесо) синхронно и возвращает итоговое значение.
+    const flush = useCallback((): number => {
+      cancelMomentum();
+      const wheeled = flushWheel();
+      const dragged = commitDrag();
+      return dragged ?? wheeled ?? valueRef.current;
+    }, [cancelMomentum, commitDrag, flushWheel]);
+
+    useImperativeHandle(ref, () => ({ flush }), [flush]);
+
+    useEffect(() => {
+      const el = viewportRef.current;
+      if (!el) {
+        return;
+      }
+
+      const onWheelNative = (event: WheelEvent) => {
+        if (event.cancelable) {
+          event.preventDefault();
+        }
+        let delta = event.deltaY * 0.12;
+        if (Math.abs(delta) < itemHeight * 0.25) {
+          delta = itemHeight * 0.35 * Math.sign(event.deltaY);
+        }
+        wheelAccum.current += delta;
+        window.clearTimeout(wheelTimer.current);
+        wheelTimer.current = setTimeout(() => {
+          flushWheel();
+        }, 180);
+      };
+
+      el.addEventListener('wheel', onWheelNative, { passive: false });
+      return () => {
+        el.removeEventListener('wheel', onWheelNative);
+      };
+    }, [flushWheel, itemHeight]);
+
+    useEffect(
+      () => () => {
+        window.clearTimeout(wheelTimer.current);
+        cancelMomentum();
+      },
+      [cancelMomentum],
+    );
+
+    const onPointerDown = useCallback(
+      (event: PointerEvent<HTMLDivElement>) => {
+        cancelMomentum();
+        event.currentTarget.setPointerCapture(event.pointerId);
+        startY.current = event.clientY;
+        startOffset.current = dragOffsetRef.current;
+        velocityRef.current = 0;
+        lastMoveRef.current = { y: event.clientY, t: event.timeStamp };
+      },
+      [cancelMomentum],
+    );
+
+    const onPointerMove = useCallback((event: PointerEvent<HTMLDivElement>) => {
+      if (!event.currentTarget.hasPointerCapture(event.pointerId)) {
+        return;
+      }
+      const dt = event.timeStamp - lastMoveRef.current.t;
+      if (dt > 0) {
+        velocityRef.current = (event.clientY - lastMoveRef.current.y) / dt;
+      }
+      lastMoveRef.current = { y: event.clientY, t: event.timeStamp };
+      setDragOffset(startOffset.current + (event.clientY - startY.current));
+    }, []);
+
+    const onPointerUp = useCallback((event: PointerEvent<HTMLDivElement>) => {
+      if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+        event.currentTarget.releasePointerCapture(event.pointerId);
+      }
+    }, []);
+
+    const onPointerCancel = useCallback((event: PointerEvent<HTMLDivElement>) => {
+      if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+        event.currentTarget.releasePointerCapture(event.pointerId);
+      }
+    }, []);
+
+    const trackTranslate = height / 2 - itemHeight / 2 - 2 * itemHeight + dragRemainderPx;
+
+    if (n === 0) {
+      return null;
+    }
+
+    return (
+      <div
+        className={cn(className)}
+        data-test-id={dataTestId}
+        onLostPointerCapture={startMomentum}
+        onPointerCancel={onPointerCancel}
+        onPointerDown={onPointerDown}
+        onPointerMove={onPointerMove}
+        onPointerUp={onPointerUp}
+      >
+        <div
+          ref={viewportRef}
+          className={styles.wheelViewport}
+          style={
+            {
+              height,
+              '--wheel-item': `${itemHeight}px`,
+            } as CSSProperties
+          }
+        >
+          <div className={styles.wheelFadingWrapper}>
+            <div className={styles.wheelTrack} style={{ '--wheel-translate': `${trackTranslate}px` }}>
+              {ROW_REL.map(rel => {
+                const cellValue = options[mod(previewIndex + rel, n)];
+                const selected = rel === 0;
+                return (
+                  <div
+                    key={rel}
+                    className={cn(styles.wheelRow, styles.itemCell, selected && styles.itemCellSelected)}
+                    style={{ '--wheel-item': `${itemHeight}px` }}
+                  >
+                    <span aria-hidden className={styles.stateLayer} data-state='emptyNeutralOnBackground' />
+                    <span className={styles.itemLabel}>{formatLabel(cellValue)}</span>
+                  </div>
+                );
+              })}
+            </div>
+            <div className={styles.wheelFadeTop} aria-hidden />
+            <div className={styles.wheelFadeBottom} aria-hidden />
+            <div className={styles.wheelSlotLines} aria-hidden>
+              <span className={styles.wheelSlotLine} />
+              <span className={styles.wheelSlotLine} />
+            </div>
+          </div>
+        </div>
+      </div>
+    );
+  },
+);

package/src/helperComponents/TimePickerDrum/constants.ts

@@ -0,0 +1,13 @@
+export const TEST_IDS = {
+  root: 'time-picker-drum',
+  selectedDate: 'time-picker-drum__selected-date',
+  selectedTime: 'time-picker-drum__selected-time',
+  drum: 'time-picker-drum__drum',
+  hoursColumn: 'time-picker-drum__hours',
+  minutesColumn: 'time-picker-drum__minutes',
+  secondsColumn: 'time-picker-drum__seconds',
+} as const;
+
+export const ROW_REL = [-2, -1, 0, 1, 2] as const;
+
+export const noop = () => {};

package/src/helperComponents/TimePickerDrum/index.ts

@@ -0,0 +1,3 @@
+export * from './TimePickerDrum';
+export { TEST_IDS } from './constants';
+export * from './types';

package/src/helperComponents/TimePickerDrum/styles.module.scss

@@ -0,0 +1,277 @@
+@use '@cloud-ru/ds-figma-variables/build/scss/styles/styles.module' as base;
+@use '@cloud-ru/ds-figma-variables/build/scss/components/calendar.module' as calendar;
+
+$sizes: 's', 'm', 'l';
+
+$labelTypography: (
+  's': base.$sn-regular-label-s,
+  'm': base.$sn-regular-label-m,
+  'l': base.$sn-regular-label-l,
+);
+
+$displayTypography: (
+  's': base.$sn-regular-display-s,
+  'm': base.$sn-regular-display-m,
+  'l': base.$sn-regular-display-l,
+);
+
+$bodyTypography: (
+  's': base.$sn-regular-body-s,
+  'm': base.$sn-regular-body-m,
+  'l': base.$sn-regular-body-l,
+);
+
+.root {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+
+  box-sizing: border-box;
+  width: 100%;
+
+  @each $size in $sizes {
+    &[data-size='#{$size}'] {
+      gap: base.simple-var(calendar.$calendar, 'anatomy', 'size', $size, 'timePicker', 'gap');
+      padding: base.simple-var(calendar.$calendar, 'anatomy', 'size', $size, 'timePicker', 'padding');
+    }
+  }
+}
+
+.selectedTime {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+@each $size in $sizes {
+  .root[data-size='#{$size}'] .selectedTime {
+    gap: base.simple-var(calendar.$calendar, 'anatomy', 'size', $size, 'timePicker', 'selectedTime', 'gap');
+  }
+}
+
+.dateLabel {
+  color: base.$sn-theme-color-available-version-textDisabled;
+  text-align: center;
+
+  @each $size in $sizes {
+    .root[data-size='#{$size}'] & {
+      @include base.composite-var($labelTypography, $size);
+    }
+  }
+}
+
+.timeRow {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.timeMain {
+  color: base.$sn-theme-color-available-version-textDisabled;
+
+  @each $size in $sizes {
+    .root[data-size='#{$size}'] & {
+      @include base.composite-var($displayTypography, $size);
+    }
+  }
+}
+
+.timeSeconds {
+  color: base.$sn-theme-color-available-version-textDisabled;
+
+  @each $size in $sizes {
+    .root[data-size='#{$size}'] & {
+      @include base.composite-var($displayTypography, $size);
+    }
+  }
+}
+
+.drum {
+  display: flex;
+  flex-direction: row;
+  align-items: stretch;
+  width: 100%;
+
+  @each $size in $sizes {
+    .root[data-size='#{$size}'] & {
+      max-width: base.simple-var(calendar.$calendar, 'anatomy', 'size', $size, 'timePicker', 'drum', 'max-width');
+    }
+  }
+}
+
+.column {
+  /* Не даём подсветить цифры при перетаскивании / колесе мыши */
+  user-select: none;
+  flex: 1 1 0%;
+  min-width: 0;
+
+  -webkit-touch-callout: none;
+}
+
+.wheelViewport {
+  touch-action: none;
+
+  position: relative;
+
+  overflow: hidden;
+
+  box-sizing: border-box;
+  width: 100%;
+}
+
+/* Как fadingWrapper в макете: градиенты не участвуют в hit-testing (`pointer-events: none`). */
+.wheelFadingWrapper {
+  position: relative;
+  overflow: hidden;
+  width: 100%;
+  height: 100%;
+}
+
+.wheelFadeTop,
+.wheelFadeBottom {
+  pointer-events: none;
+
+  position: absolute;
+  z-index: 2;
+  right: 0;
+  left: 0;
+
+  height: 40%;
+}
+
+.wheelFadeTop {
+  top: 0;
+  background: linear-gradient(
+    to bottom,
+    base.$sn-theme-color-neutral-background1Level 0%,
+    color-mix(in srgb, base.$sn-theme-color-neutral-background1Level 45%, transparent) 52%,
+    transparent 100%
+  );
+}
+
+.wheelFadeBottom {
+  bottom: 0;
+  background: linear-gradient(
+    to top,
+    base.$sn-theme-color-neutral-background1Level 0%,
+    color-mix(in srgb, base.$sn-theme-color-neutral-background1Level 45%, transparent) 52%,
+    transparent 100%
+  );
+}
+
+.wheelSlotLines {
+  pointer-events: none;
+
+  position: absolute;
+  z-index: 3;
+  top: 50%;
+  right: 0;
+  left: 0;
+  transform: translateY(-50%);
+
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+
+  height: var(--wheel-item, 40px);
+}
+
+.wheelSlotLine {
+  height: 0;
+  border-top: base.$sn-primitive-strokeWeight-strokeRegular solid base.$sn-theme-color-available-borderColor;
+}
+
+.wheelTrack {
+  will-change: transform;
+  position: relative;
+  z-index: 0;
+  transform: translate3d(0, var(--wheel-translate), 0);
+}
+
+.wheelRow {
+  flex-shrink: 0;
+  width: 100%;
+  height: var(--wheel-item);
+}
+
+.itemCell {
+  position: relative;
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  box-sizing: border-box;
+  width: 100%;
+  margin: 0;
+
+  @each $size in $sizes {
+    .root[data-size='#{$size}'] & {
+      min-width: base.simple-var(calendar.$calendar, 'anatomy', 'size', $size, 'itemCalendar', 'min-width');
+      min-height: base.simple-var(calendar.$calendar, 'anatomy', 'size', $size, 'itemCalendar', 'min-height');
+      padding-right: base.simple-var(
+        calendar.$calendar,
+        'anatomy',
+        'size',
+        $size,
+        'itemCalendar',
+        'container',
+        'labelWrapper',
+        'padding-right'
+      );
+      padding-left: base.simple-var(
+        calendar.$calendar,
+        'anatomy',
+        'size',
+        $size,
+        'itemCalendar',
+        'container',
+        'labelWrapper',
+        'padding-left'
+      );
+      border-radius: base.simple-var(
+        calendar.$calendar,
+        'anatomy',
+        'size',
+        $size,
+        'itemCalendar',
+        'container',
+        'border-radius'
+      );
+    }
+  }
+}
+
+.stateLayer {
+  pointer-events: none;
+
+  position: absolute;
+  inset: 0;
+
+  border-radius: inherit;
+
+  visibility: initial;
+
+  &[data-state='emptyNeutralOnBackground'] {
+    background: base.$sn-theme-color-material-stateLayer-neutral-onBackground-defaultEmpty-filled;
+  }
+}
+
+.itemLabel {
+  position: relative;
+  text-align: center;
+
+  @each $size in $sizes {
+    .root[data-size='#{$size}'] .itemCell & {
+      @include base.composite-var($bodyTypography, $size);
+    }
+  }
+
+  .itemCellSelected & {
+    color: base.$sn-theme-color-available-version-textMain;
+  }
+
+  .itemCell:not(.itemCellSelected) & {
+    color: base.$sn-theme-color-available-version-textTertiary;
+  }
+}

package/src/helperComponents/TimePickerDrum/types.ts

@@ -0,0 +1,62 @@
+import { WithSupportProps } from '@cloud-ru/ds-utils';
+
+import { Size } from '../../types';
+
+/**
+ * Ограничения допустимых значений в колонках барабана времени.
+ * Приоритет: непустой whitelist `allowed*` для соответствующей колонки; иначе — нижняя граница `min*`; иначе — полный диапазон.
+ */
+export type TimePickerDrumCustomOptions = {
+  /** Whitelist часов (0–23): в колонке часов доступны только перечисленные значения. */
+  allowedHours?: number[];
+  /** Whitelist минут (0–59): в колонке минут доступны только перечисленные значения. */
+  allowedMinutes?: number[];
+  /** Whitelist секунд (0–59): в колонке секунд доступны только перечисленные значения. */
+  allowedSeconds?: number[];
+  /** Нижняя граница часов: доступны значения от этого часа до 23 включительно. */
+  minHour?: number;
+  /** Нижняя граница минут: доступны значения от этой минуты до 59 включительно. */
+  minMinute?: number;
+  /** Нижняя граница секунд: доступны значения от этой секунды до 59 включительно. */
+  minSecond?: number;
+};
+
+export type TimePickerDrumProps = WithSupportProps<{
+  /** Размер по оси Figma `size` календаря (высота строк барабана и отступы). */
+  size?: Size;
+  /** Показывать третью колонку секунд (`secondsList` в макете). Если `false`, колонка скрыта и `onSecondsChange` не используется. */
+  showSeconds?: boolean;
+  /** Текст даты над дисплеем времени (локализуется снаружи). В подписи выводится только дата; время — в `timeRow`. Допускается ISO или строка, распознаваемая `Date.parse`. */
+  selectedDateLabel?: string;
+  /** Текущий выбранный час (0–23), контролируемое значение колонки часов. */
+  hours: number;
+  /** Текущая выбранная минута (0–59), контролируемое значение колонки минут. */
+  minutes: number;
+  /** Текущая выбранная секунда (0–59), контролируемое значение колонки секунд. Учитывается при `showSeconds === true`. */
+  seconds?: number;
+  /**
+   * Вызывается при смене часа после жеста (отпускание указателя / `lostpointercapture`) или после паузы при прокрутке колесом,
+   * а также при автоподгонке под `customOptions`. В контролируемом режиме обработчик обязан записать переданный `value` в состояние,
+   * иначе эффект подгонки может вызываться на каждом рендере.
+   */
+  onHoursChange(value: number): void;
+  /**
+   * Вызывается при смене минуты после жеста или после паузы при прокрутке колесом, а также при автоподгонке под `customOptions`.
+   * В контролируемом режиме обработчик обязан записать переданный `value` в состояние, иначе эффект подгонки может вызываться на каждом рендере.
+   */
+  onMinutesChange(value: number): void;
+  /**
+   * Вызывается при смене секунды после жеста или после паузы при прокрутке колесом, а также при автоподгонке под `customOptions`.
+   * Нужен при `showSeconds === true`. В контролируемом режиме обработчик обязан записать переданный `value` в состояние,
+   * иначе эффект подгонки может вызываться на каждом рендере.
+   */
+  onSecondsChange?(value: number): void;
+  /**
+   * Ограничение допустимых значений в колонках: whitelist (`allowed*`) или нижняя граница (`min*`).
+   * Если задан непустой `allowed*` после нормализации, для этой колонки используется только он; иначе при наличии `min*` — диапазон от `min` до максимума (часы 0–23, минуты и секунды 0–59).
+   * При несовпадении текущего `hours` / `minutes` / `seconds` с допустимым набором компонент подставит ближайшее допустимое значение через соответствующий `on*Change`.
+   */
+  customOptions?: TimePickerDrumCustomOptions;
+  /** Дополнительный CSS-класс корневого контейнера барабана. */
+  className?: string;
+}>;