Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
5.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file wheelOptions.ts
 * @input Nothing; types, the row height and pure functions
 * @output WheelOption, WheelProps, WheelHandle, WHEEL_ROW_HEIGHT, canSpinTo,
 *   nearestEnabledIndex, steppedIndex and endIndex: what both wheels share
 * @position Internal; read by Wheel.tsx (which re-exports all of it) and
 *   PickerWheel.tsx
 *
 * SYNC: When modified, update:
 * - /packages/core/src/DateInput/Wheel.tsx
 * - /packages/core/src/DateInput/PickerWheel.tsx
 */

import type {Ref} from 'react';

/**
 * The row height, px (`dateInputTouchSizes.wheelItemSize`): the pitch of both
 * columns' rows, and the unit of the touch wheel's offset.
 */
export const WHEEL_ROW_HEIGHT = 28;

export interface WheelOption {
  /** Stable numeric identity of the row (a month 1-12, or a year). */
  value: number;
  /** Row text. */
  label: string;
  /**
   * Rows outside min/max stay visible but cannot be committed: a wheel that
   * stops on one travels on to the nearest enabled row.
   */
  isDisabled?: boolean;
  /**
   * Where the row falls when a key steps the wheel; without it, rows step in
   * list order. A 12-hour hour column sets the full hour, so 12 PM comes before
   * 1 PM.
   */
  order?: number;
}

/** What a Wheel's `ref` exposes. */
export interface WheelHandle {
  /**
   * Turn the wheel onto `index` (an index into `options`) on the tap spin, then
   * commit it as a rest would. Resolves true once that row is the committed
   * one, false if a finger or another turn interrupted it or the wheel went
   * away first. An index outside `options` or a disabled row resolves false at
   * once, and nothing turns. Under a fine pointer the row commits at once. The
   * column then scrolls to it as for any new value, on the same rule.
   */
  spinTo(index: number): Promise<boolean>;
}

export interface WheelProps {
  /** Accessible name for the column, e.g. "Month". */
  label: string;
  /** Rows, top to bottom. */
  options: ReadonlyArray<WheelOption>;
  /** Committed value; must match one option's `value`. */
  value: number;
  /** Fired when the wheel comes to rest on a different, enabled row. */
  onChange: (value: number) => void;
  /**
   * False while the wheel is hidden. The scrolling column then waits to listen
   * and scroll, because a hidden scroller's offsets mean nothing. The touch
   * wheel turns its gestures off, and shows a value set from outside without
   * motion.
   */
  isActive?: boolean;
  /** Programmatic turns: `spinTo(index)`. */
  ref?: Ref<WheelHandle>;
}

/**
 * Whether `spinTo(index)` may turn onto `index`: an enabled row of `options`.
 * The touch wheel and the scrolling column answer a spin by the same rule.
 */
export function canSpinTo(
  options: ReadonlyArray<WheelOption>,
  index: number,
): boolean {
  const option = options[index];
  return option != null && !option.isDisabled;
}

/**
 * The enabled row nearest `index`: `index` itself when it is enabled,
 * otherwise the closest enabled row on either side. A tie goes to the side of
 * `towardIndex` (the committed row), and a wheel with no enabled row stays on
 * `towardIndex`.
 *
 * @example
 * ```
 * // Hours 0-23 with 09:00-17:00 bounds: stopping on 7 rests on 9.
 * nearestEnabledIndex(hourOptions, 7, 10); // 9
 * ```
 */
export function nearestEnabledIndex(
  options: ReadonlyArray<WheelOption>,
  index: number,
  towardIndex: number,
): number {
  const isEnabled = (i: number) =>
    i >= 0 && i < options.length && !options[i].isDisabled;
  if (isEnabled(index)) {
    return index;
  }
  for (let distance = 1; distance < options.length; distance++) {
    const below = index - distance;
    const above = index + distance;
    const isBelowEnabled = isEnabled(below);
    const isAboveEnabled = isEnabled(above);
    if (isBelowEnabled && isAboveEnabled) {
      return towardIndex < index ? below : above;
    }
    if (isBelowEnabled) {
      return below;
    }
    if (isAboveEnabled) {
      return above;
    }
  }
  return towardIndex;
}

/** The rows' indices in the order keys step them: by `order`, else list order. */
function inKeyOrder(options: ReadonlyArray<WheelOption>): number[] {
  const indices = options.map((_, index) => index);
  if (options.every(option => option.order == null)) {
    return indices;
  }
  return indices.sort(
    (a, b) => (options[a].order ?? a) - (options[b].order ?? b),
  );
}

/**
 * The row a key moves a wheel to from `from` by `delta` rows, in key order. It
 * is the next enabled row from the target in the key's direction. Past the
 * last enabled row, it is the last enabled row before the target. Null when no
 * enabled row lies in that direction, so the key commits nothing.
 */
export function steppedIndex(
  options: ReadonlyArray<WheelOption>,
  from: number,
  delta: number,
): number | null {
  const count = options.length;
  if (count === 0 || delta === 0) {
    return null;
  }
  const rows = inKeyOrder(options);
  const start = Math.max(0, rows.indexOf(from));
  const isEnabled = (position: number) => !options[rows[position]].isDisabled;
  const step = Math.sign(delta);
  const target = Math.min(count - 1, Math.max(0, start + delta));
  for (
    let position = target;
    position >= 0 && position < count;
    position += step
  ) {
    if (isEnabled(position)) {
      return position === start ? null : rows[position];
    }
  }
  for (let position = target; position !== start; position -= step) {
    if (isEnabled(position)) {
      return rows[position];
    }
  }
  return null;
}

/** The first or the last enabled row in key order: where Home or End moves a wheel. */
export function endIndex(
  options: ReadonlyArray<WheelOption>,
  end: 'first' | 'last',
): number | null {
  const enabled = inKeyOrder(options).filter(
    index => !options[index].isDisabled,
  );
  return (end === 'first' ? enabled[0] : enabled[enabled.length - 1]) ?? null;
}