@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/DateInput/usePointerDragScroll.ts

@@ -87,6 +87,7 @@ export function usePointerDragScroll(
 ): PointerDragScrollState {
   const isDraggingRef = useRef(false);
 
+  // Syncs pointer listeners with `isEnabled`. A mouse drag scrolls the element.
   useEffect(() => {
     const element = ref.current;
     if (element == null || !isEnabled) {

package/src/DateInput/useScrollSettle.ts

@@ -98,6 +98,8 @@ export function useScrollSettle(
 
   const isAtRestRef = useRef(true);
 
+  // Syncs scroll, touch and pointer listeners with `isEnabled`. They find when
+  // scrolling stops.
   useEffect(() => {
     const element = ref.current;
     if (element == null || !isEnabled) {

package/src/DateInput/useWheelListbox.ts

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useWheelListbox.ts
+ * @input A wheel's label, options, committed value and active row, and its
+ *   presentation's three moves: a step, an end, a row
+ * @output useWheelListbox: the listbox and option props both wheels share
+ * @position Internal hook of ScrollWheel (Wheel.tsx) and PickerWheel.tsx
+ *
+ * A wheel is a listbox: one tab stop, with Arrow, Page, Home and End keys.
+ * Each presentation decides what its keys and clicks do to its own column.
+ *
+ * SYNC: When modified, update Wheel.tsx and PickerWheel.tsx.
+ */
+
+import {useCallback, useId, type KeyboardEvent} from 'react';
+import type {WheelOption} from './wheelOptions';
+
+/** Rows a Page Up or Page Down key moves. */
+const PAGE_ROWS = 10;
+
+export interface WheelListboxProps {
+  /** Accessible name for the column. */
+  label: string;
+  /** Rows, top to bottom. */
+  options: ReadonlyArray<WheelOption>;
+  /** Committed value. */
+  value: number;
+  /** The row `aria-activedescendant` names. */
+  activeIndex: number;
+  /** An Arrow or Page key: a step of `delta` rows. */
+  stepBy: (delta: number) => void;
+  /** Home or End. */
+  toEnd: (end: 'first' | 'last') => void;
+  /** A click on row `index`. */
+  activate: (index: number) => void;
+}
+
+/**
+ * The listbox and option props of one wheel column: ids, ARIA, the keys and
+ * a click on a row. `aria-activedescendant` marks the active row, and a click
+ * reaches every row. The scrolling column steps from the row under its band. The
+ * touch column steps from the row it is heading to.
+ *
+ * @example
+ * ```
+ * const {listboxProps, optionProps} = useWheelListbox({label, options, value, activeIndex, stepBy, toEnd, activate});
+ * <div {...listboxProps}>{options.map((option, index) => <div key={option.value} {...optionProps(option, index)} />)}</div>
+ * ```
+ */
+export function useWheelListbox({
+  label,
+  options,
+  value,
+  activeIndex,
+  stepBy,
+  toEnd,
+  activate,
+}: WheelListboxProps) {
+  const id = useId();
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      switch (event.key) {
+        case 'ArrowDown':
+          event.preventDefault();
+          stepBy(1);
+          break;
+        case 'ArrowUp':
+          event.preventDefault();
+          stepBy(-1);
+          break;
+        case 'PageDown':
+          event.preventDefault();
+          stepBy(PAGE_ROWS);
+          break;
+        case 'PageUp':
+          event.preventDefault();
+          stepBy(-PAGE_ROWS);
+          break;
+        case 'Home':
+          event.preventDefault();
+          toEnd('first');
+          break;
+        case 'End':
+          event.preventDefault();
+          toEnd('last');
+          break;
+        default:
+          break;
+      }
+    },
+    [stepBy, toEnd],
+  );
+  return {
+    listboxProps: {
+      role: 'listbox' as const,
+      'aria-label': label,
+      'aria-activedescendant': `${id}-${options[activeIndex]?.value}`,
+      tabIndex: 0,
+      onKeyDown,
+    },
+    optionProps: (option: WheelOption, index: number) => ({
+      id: `${id}-${option.value}`,
+      role: 'option' as const,
+      'aria-selected': option.value === value,
+      'aria-disabled': option.isDisabled || undefined,
+      onClick: () => activate(index),
+    }),
+  };
+}

package/src/DateInput/wheelOptions.ts

@@ -0,0 +1,184 @@
+// 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;
+}