@astryxdesign/core 0.7.7 → 0.7.8-canary.0d54fd3

package/src/DateInput/TouchDateField.tsx

@@ -108,8 +108,6 @@ import {
   formatSharedDate,
   plainDateFromISO,
   plainDateToday,
-  plainDateFormat,
-  DATE_FORMAT_WEEKDAY_ONLY,
   type ISODateString,
 } from '../utils';
 import {plainDateFormatStandaloneMonthYear} from '../utils/plainDate';
@@ -117,6 +115,7 @@ import {chainEventHandlers} from '../utils/chainEventHandlers';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
 import {normalizeDayOfWeek} from '../utils/dateTypes';
+import {getWeekdayHeaders} from '../Calendar/getWeekdayHeaderNames';
 import {MonthScroller, type MonthScrollerHandle} from './MonthScroller';
 import {MonthYearWheels} from './MonthYearWheels';
 import {
@@ -676,6 +675,7 @@ export function TouchDateField({
   const scrollerHandleRef = useRef<MonthScrollerHandle | null>(null);
   // Pending focus handoff from the clear button; see handleClear.
   const clearFocusTimerRef = useRef<number | null>(null);
+  // Releases the focus timer on unmount.
   useEffect(
     () => () => {
       if (clearFocusTimerRef.current != null) {
@@ -720,34 +720,8 @@ export function TouchDateField({
 
   const {year, month} = fromMonthIndex(monthIndex);
 
-  /**
-   * Three-letter weekday names — "Sun", not Calendar's "Su".
-   *
-   * The sheet is full width and the columns are ~51px, so there is room for
-   * the form people actually read, and a picker operated by thumb should not
-   * make anyone decode "Tu" against "Th".
-   *
-   * This is CLDR's `abbreviated` width, which `Intl` produces natively — no
-   * truncation, so the 28 non-English locales stay correct rather than being
-   * sliced to three characters. (Verified against the CLDR tables for all 30
-   * locales in the catalog.) Calendar's 2-letter row is CLDR's *short* width,
-   * which `Intl` cannot express, which is exactly why that surface needs a
-   * generated table and this one does not.
-   *
-   * Built here rather than taken from `useCalendarDays`, which supplies the
-   * short form for Calendar's own header. The rotation matches: day 4 of
-   * January 1970 was a Sunday, so offsetting from it by `weekStartsOn` walks
-   * the week in the same order the panes lay out their columns.
-   */
-  const dayNames = useMemo(
-    () =>
-      Array.from({length: 7}, (_, offset) =>
-        plainDateFormat(
-          {year: 1970, month: 1, day: 4 + ((weekStartsOn + offset) % 7)},
-          DATE_FORMAT_WEEKDAY_ONLY,
-          locale,
-        ),
-      ),
+  const weekdayHeaders = useMemo(
+    () => getWeekdayHeaders(locale, weekStartsOn),
     [locale, weekStartsOn],
   );
   const monthYearLabel = plainDateFormatStandaloneMonthYear(
@@ -1107,8 +1081,8 @@ export function TouchDateField({
           styles.weekdays,
           isWheelOpen && styles.weekdaysHidden,
         )}>
-        {dayNames.map(name => (
-          <div key={name} {...stylex.props(styles.weekday)}>
+        {weekdayHeaders.map(({dayOfWeek, name}) => (
+          <div key={dayOfWeek} {...stylex.props(styles.weekday)}>
             {name}
           </div>
         ))}

package/src/DateInput/Wheel.tsx

@@ -4,41 +4,30 @@
 
 /**
  * @file Wheel.tsx
- * @input Option list, selected value, change callback
- * @output Exports Wheel — a snap-scrolling picker column
- * @position Internal component; consumed by MonthYearWheels.tsx
+ * @input Option list, selected value and change callback
+ * @output Exports Wheel (one picker column), ScrollWheel (the scrolling
+ *   column) and the shared types of wheelOptions.ts
+ * @position Internal component; consumed by MonthYearWheels.tsx,
+ *   TouchTimeField.tsx and TouchDateTimeField.tsx
  *
- * A wheel is a scroll container, not a custom gesture surface. Momentum,
- * rubber-banding, and the settle animation are the platform's; all this adds
- * is `scroll-snap-align: center` on each option, half a viewport of padding at
- * each end so the first and last option can reach the middle, and a commit
- * when the scrolling stops and no finger or mouse drag still holds it.
+ * Wheel picks its column by the primary pointer. Under a finger it is
+ * PickerWheel.tsx, the touch layer, imported here alone. Under a fine pointer
+ * it is the snap-scrolling column below.
  *
- * The falloff (rows fading and tipping away from the centre) is a CSS
- * scroll-driven animation on a `view()` timeline — the browser interpolates it
- * against each row's own position in the scrollport, so it stays glued to the
- * finger with no JS in the frame loop. It is guarded by `@supports`, because a
- * browser that does not understand `animation-timeline` would otherwise run
- * the same keyframes on the document timeline and simply play them once.
- *
- * Under Reduce Motion, the wheel's own scrolls (a step from a key or a click,
- * the travel to the nearest enabled row) land without travel. They cross-fade
- * on a touch screen and land at once otherwise. A finger's scroll and its
- * momentum stay the platform's.
- *
- * Accessibility: this is a listbox, not a novel widget. It is one tab stop
- * with arrow/Home/End/PageUp/PageDown keys, `aria-activedescendant` tracking
- * the active row, and every row reachable by tap — none of which depends on
- * the scroll-driven decoration.
+ * The scrolling column is a scroll container: momentum, rubber-banding and the
+ * settle are the platform's. Its rows fade and tip on a CSS `view()` timeline,
+ * behind `@supports`. Under Reduce Motion its own scrolls land without travel.
  *
  * SYNC: When modified, update:
+ * - /packages/core/src/DateInput/PickerWheel.tsx (the touch column)
+ * - /packages/core/src/DateInput/wheelOptions.ts
  * - /packages/core/src/DateInput/TouchDateField.tsx
  * - /packages/core/src/DateTimeInput/TouchDateTimeField.tsx
  * - /packages/core/src/DateInput/DateInput.doc.mjs
  * - /packages/core/src/DateInput/DateInputTouch.test.tsx
  */
 
-import {useCallback, useEffect, useId, useRef, useState} from 'react';
+import {useCallback, useEffect, useRef, useState} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -54,10 +43,25 @@ import {
   reducedMotionFade,
   type ReducedMotionDip,
 } from '../motion/reducedMotion';
+import {useTouchPresentation} from '../utils/touchPresentation';
+import {PickerWheel} from './PickerWheel';
 import {dateInputTouchSizes, dateInputTouchGeometry} from './tokens.stylex';
 import {useOwnScrollGesture} from './useOwnScrollGesture';
 import {usePointerDragScroll} from './usePointerDragScroll';
 import {useScrollSettle} from './useScrollSettle';
+import {useWheelListbox} from './useWheelListbox';
+import {
+  endIndex,
+  nearestEnabledIndex,
+  steppedIndex,
+  type WheelProps,
+} from './wheelOptions';
+
+export {
+  nearestEnabledIndex,
+  type WheelOption,
+  type WheelProps,
+} from './wheelOptions';
 
 const ITEM_BLOCK_SIZE = dateInputTouchSizes.wheelItemSize;
 
@@ -214,80 +218,35 @@ const styles = stylex.create({
   },
 });
 
-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;
-}
-
-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 — scroll offsets of a display:none
-   * scroller are meaningless, so listeners and the initial scroll wait.
-   */
-  isActive?: boolean;
-}
-
 /**
- * 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`.
+ * One picker column: UIPickerView's motion with flat rows under a finger, the
+ * snap-scrolling column under a fine pointer.
  *
  * @example
  * ```
- * // Hours 0-23 with 09:00-17:00 bounds: stopping on 7 rests on 9.
- * nearestEnabledIndex(hourOptions, 7, 10); // 9
+ * <Wheel
+ *   label="Month"
+ *   options={monthOptions}
+ *   value={month}
+ *   onChange={setMonth}
+ * />
  * ```
  */
-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;
+export function Wheel(props: WheelProps) {
+  // One touch model on every touch device: a finger gets UIPickerView's motion
+  // with flat rows, a fine pointer the scrolling column.
+  const {isTouch} = useTouchPresentation();
+  return isTouch ? <PickerWheel {...props} /> : <ScrollWheel {...props} />;
 }
 
+Wheel.displayName = 'Wheel';
+
 /**
- * One snap-scrolling picker column.
+ * One snap-scrolling picker column, under a fine pointer.
  *
  * @example
  * ```
- * <Wheel
+ * <ScrollWheel
  *   label="Month"
  *   options={monthOptions}
  *   value={month}
@@ -295,14 +254,13 @@ export function nearestEnabledIndex(
  * />
  * ```
  */
-export function Wheel({
+export function ScrollWheel({
   label,
   options,
   value,
   onChange,
   isActive = true,
 }: WheelProps) {
-  const id = useId();
   const scrollerRef = useRef<HTMLDivElement | null>(null);
   const selectedIndex = Math.max(
     0,
@@ -462,6 +420,8 @@ export function Wheel({
   // useScrollSettle. The settle handler re-checks the position afterwards, so
   // a correction that is genuinely needed still happens, just at rest.
   const parkedRef = useRef(false);
+  // Syncs the wheel's scroll position with the selected index while the wheel
+  // is active.
   useEffect(() => {
     if (!isActive) {
       parkedRef.current = false;
@@ -492,6 +452,8 @@ export function Wheel({
   // Highlight follows the finger. rAF-throttled: a scroll can fire far more
   // often than the display refreshes, and this only feeds a repaint.
   const frameRef = useRef<number | undefined>(undefined);
+  // Syncs a scroll listener with the active wheel. It updates the highlighted
+  // row.
   useEffect(() => {
     const scroller = scrollerRef.current;
     if (scroller == null || !isActive) {
@@ -531,69 +493,64 @@ export function Wheel({
   // there is no way to share — it takes every touch that lands on it.
   useOwnScrollGesture(scrollerRef, 'all', {isEnabled: isActive});
 
-  const moveBy = useCallback(
-    (delta: number) => {
-      const next = Math.min(
-        options.length - 1,
-        Math.max(0, activeIndex + delta),
-      );
-      const option = options[next];
-      if (option == null || option.isDisabled) {
+  // A key commits the row it moves to and scrolls the column there.
+  const moveTo = useCallback(
+    (row: number | null) => {
+      const option = row == null ? undefined : options[row];
+      if (row == null || option == null || option.isDisabled) {
         return;
       }
-      setActiveIndex(next);
-      scrollToIndex(next, 'smooth');
+      setActiveIndex(row);
+      scrollToIndex(row, 'smooth');
       if (option.value !== value) {
         onChange(option.value);
       }
     },
-    [activeIndex, options, scrollToIndex, value, onChange],
+    [options, scrollToIndex, value, onChange],
+  );
+
+  const moveBy = useCallback(
+    (delta: number) => moveTo(steppedIndex(options, activeIndex, delta)),
+    [moveTo, options, activeIndex],
   );
 
-  const handleKeyDown = useCallback(
-    (event: React.KeyboardEvent) => {
-      switch (event.key) {
-        case 'ArrowDown':
-          event.preventDefault();
-          moveBy(1);
-          break;
-        case 'ArrowUp':
-          event.preventDefault();
-          moveBy(-1);
-          break;
-        case 'PageDown':
-          event.preventDefault();
-          moveBy(10);
-          break;
-        case 'PageUp':
-          event.preventDefault();
-          moveBy(-10);
-          break;
-        case 'Home':
-          event.preventDefault();
-          moveBy(-activeIndex);
-          break;
-        case 'End':
-          event.preventDefault();
-          moveBy(options.length - 1 - activeIndex);
-          break;
-        default:
-          break;
+  // Home and End: the first and the last enabled row.
+  const toEnd = useCallback(
+    (end: 'first' | 'last') => moveTo(endIndex(options, end)),
+    [moveTo, options],
+  );
+
+  const activate = useCallback(
+    (index: number) => {
+      const option = options[index];
+      if (option == null || option.isDisabled) {
+        return;
+      }
+      setActiveIndex(index);
+      scrollToIndex(index, 'smooth');
+      if (option.value !== value) {
+        onChange(option.value);
       }
     },
-    [moveBy, activeIndex, options.length],
+    [options, scrollToIndex, value, onChange],
   );
 
+  const {listboxProps, optionProps} = useWheelListbox({
+    label,
+    options,
+    value,
+    activeIndex,
+    stepBy: moveBy,
+    toEnd,
+    activate,
+  });
+
   return (
     <div {...stylex.props(styles.column)}>
       <div aria-hidden="true" {...stylex.props(styles.band)} />
       <div
         ref={scrollerRef}
-        role="listbox"
-        aria-label={label}
-        aria-activedescendant={`${id}-${options[activeIndex]?.value}`}
-        tabIndex={0}
-        onKeyDown={handleKeyDown}
+        {...listboxProps}
         // Read in the capture phase. usePointerDragScroll stops a primary
         // mouse press from bubbling, so that it does not reach BottomSheet's
         // drag. A bubbling handler would never see a mouse, and would keep the
@@ -608,20 +565,7 @@ export function Wheel({
         {options.map((option, index) => (
           <div
             key={option.value}
-            id={`${id}-${option.value}`}
-            role="option"
-            aria-selected={option.value === value}
-            aria-disabled={option.isDisabled || undefined}
-            onClick={() => {
-              if (option.isDisabled) {
-                return;
-              }
-              setActiveIndex(index);
-              scrollToIndex(index, 'smooth');
-              if (option.value !== value) {
-                onChange(option.value);
-              }
-            }}
+            {...optionProps(option, index)}
             {...stylex.props(
               styles.item,
               index === activeIndex && styles.itemActive,
@@ -635,4 +579,4 @@ export function Wheel({
   );
 }
 
-Wheel.displayName = 'Wheel';
+ScrollWheel.displayName = 'ScrollWheel';

package/src/DateInput/useOwnScrollGesture.ts

@@ -6,7 +6,8 @@
  * @file useOwnScrollGesture.ts
  * @input A scroll container ref and which axis it owns
  * @output Stops touch gestures on that container from reaching an ancestor
- * @position Internal behavior hook; consumed by Wheel.tsx and MonthScroller.tsx
+ * @position Internal behavior hook; consumed by Wheel.tsx, PickerWheel.tsx and
+ *   MonthScroller.tsx
  *
  * Lets a nested scroller keep the finger that lands on it.
  *
@@ -114,6 +115,16 @@ export type OwnScrollGestureOptions = {
    * so momentum and snapping are never second-guessed.
    */
   onSwipe?: (direction: 1 | -1) => void;
+  /**
+   * Also keep the pointer a touch lands with, for an `'all'` scroller that pans
+   * through the gesture system rather than natively. A sheet arms its pull-down
+   * on its body's `pointerdown`, and counts on a native pan to cancel a touch
+   * pointer. A pan of the gesture system never cancels it. Without this, the
+   * sheet follows the first 8 px of a downward drag before the scroller's own
+   * pan takes over. The gesture host and the shared modality tracker listen in
+   * the capture phase, before this.
+   */
+  isPointerKept?: boolean;
 };
 
 /**
@@ -130,13 +141,15 @@ export function useOwnScrollGesture(
   axis: OwnedAxis = 'all',
   options: OwnScrollGestureOptions = {},
 ): void {
-  const {isEnabled = true, onSwipe} = options;
+  const {isEnabled = true, onSwipe, isPointerKept = false} = options;
 
   // Read through a ref so a caller need not memoize the callback: re-running
   // this effect would tear the listeners off mid-gesture.
   const onSwipeRef = useRef(onSwipe);
   onSwipeRef.current = onSwipe;
 
+  // Syncs touch listeners on the element with `isEnabled`. They decide which
+  // gesture owns a horizontal scroll.
   useEffect(() => {
     const element = ref.current;
     if (element == null || !isEnabled) {
@@ -213,15 +226,24 @@ export function useOwnScrollGesture(
       claimed = null;
     };
 
+    const keepPointer = (event: PointerEvent) => event.stopPropagation();
+    const isKeepingPointer = axis === 'all' && isPointerKept;
+
     element.addEventListener('touchstart', onStart, {passive: true});
     element.addEventListener('touchmove', onMove, {passive: true});
     element.addEventListener('touchend', onEnd, {passive: true});
     element.addEventListener('touchcancel', onEnd, {passive: true});
+    if (isKeepingPointer) {
+      element.addEventListener('pointerdown', keepPointer);
+    }
     return () => {
       element.removeEventListener('touchstart', onStart);
       element.removeEventListener('touchmove', onMove);
       element.removeEventListener('touchend', onEnd);
       element.removeEventListener('touchcancel', onEnd);
+      if (isKeepingPointer) {
+        element.removeEventListener('pointerdown', keepPointer);
+      }
     };
-  }, [ref, axis, isEnabled]);
+  }, [ref, axis, isEnabled, isPointerKept]);
 }

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),
+    }),
+  };
+}