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

package/src/DateInput/wheelStrip.ts

@@ -0,0 +1,341 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file wheelStrip.ts
+ * @input The touch wheel's strip (its flat rows in one element), its layout,
+ *   and curves from wheelPhysics.ts
+ * @output createWheelStrip: the one owner of a wheel's offset. It writes a
+ *   drag's frames, plays and stops curves, ticks, and reports the nearest row
+ * @position Glue of the touch picker wheel (PickerWheel.tsx) over the shared
+ *   animator (motion/animator.ts)
+ *
+ * The strip is the one element that moves, on `translate`, so a motion plays
+ * on the compositor with no layout or paint per frame.
+ *
+ * SYNC: When modified, update wheelStrip.test.ts and PickerWheel.tsx.
+ */
+
+import {canVibrate, playHaptic} from '../gestures/haptics';
+import {createMotionAnimator, type MotionCurve} from '../motion/animator';
+import {reducedMotionFade} from '../motion/reducedMotion';
+import {picker} from '../motion/uikit/picker';
+import {
+  nearestIndex,
+  reachesRow,
+  tickTimes,
+  type WheelCurve,
+  type WheelLayout,
+} from './wheelPhysics';
+
+/** How a motion ended: arrived on its row, or stopped before. */
+export type WheelMotionOutcome = 'arrived' | 'stopped';
+
+/** Options for one motion. */
+export interface PlayOptions {
+  /** Tick as rows reach the band (a drag's release); a tap's spin does not. */
+  ticks?: boolean;
+  /** Called once when the motion ends, either way. */
+  onEnd?: (outcome: WheelMotionOutcome, offset: number) => void;
+  /** Started by a touch drag's release, which cross-fades under Reduce Motion. */
+  touchRelease?: boolean;
+  /**
+   * The momentum that continues a throw: a coast, and its bounce at an end.
+   * It is direct movement, so it plays under Reduce Motion too, as scrolling
+   * keeps decelerating under iOS Reduce Motion.
+   */
+  momentum?: boolean;
+}
+
+/** One picker column's offset and everything that moves it. */
+export interface WheelStrip {
+  /** The strip the offset moves (null detaches it). */
+  attach(strip: HTMLElement | null): void;
+  /** Update the rows (a new option list); keeps the offset. */
+  setLayout(layout: WheelLayout): void;
+  /**
+   * Tell `listener` the position of the row nearest the band whenever it
+   * changes. That is on a drag frame, where a motion stops or ends, and at
+   * rest. A cross-fade's landing counts as an end. A motion itself reports
+   * nothing until it ends, so the compositor plays it without the main thread
+   * painting a mark per row.
+   */
+  onNearestChange(listener: ((position: number) => void) | null): void;
+  /** Whether a motion is playing. */
+  isMoving(): boolean;
+  /**
+   * The offset on screen at `time` (ms, the document timeline's clock; default
+   * now). It is the animator's presentation value. So a motion that has not
+   * started on screen yet shows its start.
+   */
+  offset(time?: number): number;
+  /** Where the wheel will be at rest: the motion's end, or the offset now. */
+  target(): number;
+  /**
+   * Show `offset` at once, stopping any motion: a drag frame or a park. A drag
+   * frame passes `ticks`, which also keeps the strip on its own compositing
+   * layer for the frames that follow.
+   */
+  setOffset(offset: number, options?: {ticks?: boolean}): void;
+  /** Forget the previous drag frame (a new gesture starts). */
+  resetDrag(): void;
+  /**
+   * Stop the motion where it was on screen at `time` (a finger landing on a
+   * spinning wheel: its touch-down time). Returns that offset.
+   */
+  stop(time?: number): number;
+  /** Play `curve` from the current offset; the strip ends at `curve.to`. */
+  play(curve: WheelCurve, options?: PlayOptions): void;
+  /**
+   * Forget the row last reported nearest the band, so the next report names it
+   * again even unchanged. A caller that clears its mark as a motion starts then
+   * gets it back. That happens when the motion ends on the row it began on.
+   */
+  forgetNearest(): void;
+  /** Stop everything; a motion still running ends as stopped. */
+  dispose(): void;
+}
+
+interface Running {
+  readonly curve: WheelCurve;
+  readonly onEnd?: (outcome: WheelMotionOutcome, offset: number) => void;
+  readonly timers: ReturnType<typeof setTimeout>[];
+}
+
+function now(): number {
+  const time =
+    typeof document !== 'undefined'
+      ? (document.timeline?.currentTime as number | null | undefined)
+      : null;
+  return typeof time === 'number' ? time : performance.now();
+}
+
+/**
+ * Creates a wheel's strip on a fresh animator. It uses the internal animator
+ * for three jobs the public handle lacks:
+ *
+ * - It plays a closed-form curve on the compositor: a coast onto a row, a
+ *   snap, a spin.
+ * - It times haptic ticks on that curve's clock.
+ * - It substitutes Reduce Motion's cross-fade for a move.
+ *
+ * A release's coast and its bounce at an end are momentum (`decay`), so they
+ * keep their motion under Reduce Motion. Every other curve is a transition
+ * (`play`). Under Reduce Motion the animator cross-fades it after a touch or
+ * on a coarse pointer. Otherwise it lands at once.
+ *
+ * @example
+ * ```
+ * const strip = createWheelStrip({rowHeight: 28, rowCount: 60});
+ * strip.attach(element);
+ * strip.setOffset(30 * 28);
+ * strip.play(planRelease(strip.offset(), 900, layout).curve, {ticks: true, momentum: true});
+ * ```
+ */
+export function createWheelStrip(initialLayout: WheelLayout): WheelStrip {
+  const animator = createMotionAnimator(null);
+  let layout = initialLayout;
+  let running: Running | null = null;
+  let nearestListener: ((position: number) => void) | null = null;
+  let lastNearest: number | null = null;
+  let lastTick = -Infinity;
+  /** Last offset a drag frame showed, for its ticks. */
+  let dragPrevious: number | null = null;
+
+  const shown = (time?: number): number =>
+    // The strip's top sits on the band's row: offset `o` is `translate` −o.
+    -animator.get('y', time);
+
+  const reportNearest = (offset: number): void => {
+    const position = nearestIndex(offset, layout);
+    if (position === lastNearest) {
+      return;
+    }
+    lastNearest = position;
+    nearestListener?.(position);
+  };
+
+  const tick = (time: number): void => {
+    if (time - lastTick < picker.selectionTick.minimumIntervalMs) {
+      return;
+    }
+    lastTick = time;
+    playHaptic('selection');
+  };
+
+  const clear = (motion: Running): void => {
+    for (const timer of motion.timers) {
+      clearTimeout(timer);
+    }
+    motion.timers.length = 0;
+    if (running === motion) {
+      running = null;
+    }
+  };
+
+  /**
+   * The motion's timers, from `origin` (when it started on screen): its
+   * ticks, a cross-fade's landing, and its end.
+   */
+  const schedule = (
+    motion: Running,
+    origin: number,
+    {
+      endMs,
+      ticks,
+      landingMs,
+    }: {endMs: number; ticks: boolean; landingMs: number | null},
+  ): void => {
+    for (const timer of motion.timers) {
+      clearTimeout(timer);
+    }
+    motion.timers.length = 0;
+    const elapsed = now() - origin;
+    if (ticks) {
+      for (const t of tickTimes(motion.curve, layout.rowHeight)) {
+        motion.timers.push(
+          setTimeout(
+            () => {
+              if (running === motion) {
+                tick(now());
+              }
+            },
+            Math.max(0, t * 1000 - elapsed),
+          ),
+        );
+      }
+    }
+    if (landingMs != null) {
+      motion.timers.push(
+        setTimeout(
+          () => {
+            if (running === motion) {
+              reportNearest(motion.curve.to);
+            }
+          },
+          Math.max(0, landingMs - elapsed),
+        ),
+      );
+    }
+    motion.timers.push(
+      setTimeout(
+        () => {
+          if (running !== motion) {
+            return;
+          }
+          clear(motion);
+          reportNearest(motion.curve.to);
+          motion.onEnd?.('arrived', motion.curve.to);
+        },
+        Math.max(0, endMs - elapsed),
+      ),
+    );
+  };
+
+  const stop = (time?: number): number => {
+    const motion = running;
+    if (motion == null) {
+      return shown();
+    }
+    const offset = shown(time);
+    clear(motion);
+    // `set` ends the strip's animation and puts it where it was shown.
+    animator.set({y: -offset});
+    reportNearest(offset);
+    motion.onEnd?.('stopped', offset);
+    return offset;
+  };
+
+  return {
+    attach(strip) {
+      animator.attach(strip);
+    },
+    setLayout(next) {
+      layout = next;
+    },
+    onNearestChange(listener) {
+      nearestListener = listener;
+      lastNearest = null;
+    },
+    isMoving() {
+      return running != null;
+    },
+    offset(time) {
+      return shown(time);
+    },
+    target() {
+      return running?.curve.to ?? shown();
+    },
+    setOffset(offset, {ticks = false} = {}) {
+      if (running != null) {
+        stop();
+      }
+      if (
+        ticks &&
+        dragPrevious != null &&
+        canVibrate() &&
+        reachesRow(dragPrevious, offset, layout.rowHeight)
+      ) {
+        tick(now());
+      }
+      dragPrevious = offset;
+      // A park is a one-off write: no layer for a strip at rest.
+      animator.set({y: -offset}, {promote: ticks});
+      reportNearest(offset);
+    },
+    resetDrag() {
+      dragPrevious = null;
+    },
+    stop,
+    play(
+      curve,
+      {ticks = false, onEnd, touchRelease = false, momentum = false} = {},
+    ) {
+      stop();
+      dragPrevious = null;
+      const element = animator.element;
+      // What Reduce Motion makes of a transition: null while motion plays.
+      // Momentum is never substituted.
+      const fade = momentum ? null : reducedMotionFade(element, {touchRelease});
+      const endMs = fade == null ? curve.duration * 1000 : fade.duration;
+      if (!(endMs > 0)) {
+        animator.set({y: -curve.to});
+        reportNearest(curve.to);
+        onEnd?.('arrived', curve.to);
+        return;
+      }
+      const motionCurve: MotionCurve = {
+        duration: curve.duration,
+        at: t => -curve.value(t),
+        velocity: t => -curve.velocity(t),
+      };
+      const handle = momentum
+        ? animator.decay({y: motionCurve}, {touchRelease})
+        : animator.play({y: motionCurve}, {touchRelease});
+      const motion: Running = {curve, onEnd, timers: []};
+      running = motion;
+      const plan = {
+        endMs,
+        // A cross-fade has no travel to tick through.
+        ticks: ticks && fade == null && canVibrate(),
+        // A cross-fade lands its rows at its midpoint, faded out.
+        landingMs: fade == null ? null : endMs / 2,
+      };
+      schedule(motion, now(), plan);
+      // A busy main thread can hold a motion's first frame: its timers then
+      // follow the start the browser gives it. The animator's start promise
+      // only resolves, so nothing here waits on a rejection.
+      void handle.started.then(start => {
+        if (running === motion) {
+          schedule(motion, start, plan);
+        }
+      });
+    },
+    forgetNearest() {
+      lastNearest = null;
+    },
+    dispose() {
+      stop();
+      animator.dispose();
+    },
+  };
+}

package/src/DateTimeInput/TouchDateTimeField.tsx

@@ -881,6 +881,8 @@ export function TouchDateTimeField({
       return {
         value: hour,
         label: String(hour),
+        // Keys step in time order: 12 PM comes before 1 PM.
+        order: hour24,
         isDisabled: !rangeOverlaps(
           hour24 * 3600,
           hour24 * 3600 + 3599,

package/src/Dialog/Dialog.tsx

@@ -81,7 +81,10 @@ import {themeProps} from '../utils/themeProps';
 import type {DialogVariantMap} from './index';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useInteractionModalityTracking} from '../utils/interactionModality';
-import {focusForLastInput, isFocusLost} from '../utils/focusReturn';
+import {
+  focusForLastInput,
+  prepareFocusReturnOnRemoval,
+} from '../utils/focusReturn';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
@@ -603,7 +606,8 @@ export function Dialog({
   const allowEscape = purpose !== 'required';
   const allowBackdropClick = purpose === 'info';
 
-  // Handle open/close state — skip for inline rendering
+  // Syncs the native dialog with `isOpen` through `showModal()` and `close()`.
+  // An inline dialog is not in the top layer, so it skips this.
   useEffect(() => {
     if (isInline) {
       return;
@@ -653,39 +657,15 @@ export function Dialog({
   }, [isOpen, isInline]);
 
   // A dialog that unmounts while open (rendered only while open, or removed
-  // with the rest of a view) never runs the close branch above, and removing a
-  // <dialog> does not run the browser's own focus return. Focus left inside
-  // it, or dropped to the body by the removal, goes back to the opener.
+  // with the rest of a view) never runs the close branch above. Focus the
+  // removal lost goes back to the opener.
   useEffect(() => {
-    if (isInline) {
+    const dialog = dialogRef.current;
+    if (isInline || dialog == null) {
       return;
     }
-    const dialog = dialogRef.current;
-    // Read now: a removed iframe's document has no window, so its frame
-    // element can no longer be found once the dialog is gone.
-    const host = dialog?.ownerDocument.defaultView?.frameElement ?? null;
-    return () => {
-      const trigger = triggerElementRef.current;
-      if (dialog == null || trigger == null) {
-        return;
-      }
-      // Checked once the commit has finished: StrictMode's simulated unmount
-      // leaves the dialog in the document, and only a real removal returns
-      // focus.
-      queueMicrotask(() => {
-        if (dialog.isConnected || !trigger.isConnected) {
-          return;
-        }
-        // isFocusLost reads the dialog's own document. For a dialog in an
-        // iframe, the document that hosts the frame must also have lost focus
-        // or keep it on that frame, wherever the opener is: a control the
-        // user pressed outside the frame to remove the dialog, or the frame
-        // itself, keeps its focus.
-        if (isFocusLost(dialog) && (host == null || isFocusLost(host))) {
-          focusForLastInput(trigger);
-        }
-      });
-    };
+    const returnFocusOnRemoval = prepareFocusReturnOnRemoval(dialog);
+    return () => returnFocusOnRemoval(triggerElementRef.current);
   }, [isInline]);
 
   // Host app-global surfaces (toasts) inside this modal while it is open, so

package/src/Drawer/useDrawerDialogPresence.ts

@@ -131,6 +131,8 @@ export function useDrawerDialogPresence({
   // Element focused when the drawer opened — restored on close.
   const triggerElementRef = useRef<HTMLElement | null>(null);
 
+  // Syncs the drawer's native host with `isOpen`. It shows or hides the
+  // top-layer host, keeps the opener, waits for the exit, and returns focus.
   useEffect(() => {
     const dialog = dialogRef.current;
     if (!dialog) {

package/src/DropdownMenu/useMenuOverflow.ts

@@ -63,6 +63,8 @@ export function useMenuOverflow(
     );
   }, [menuRef]);
 
+  // Syncs the overflow measurement with the open menu. It measures, then
+  // observes resize, DOM changes and window resize.
   useIsomorphicLayoutEffect(() => {
     if (!isOpen) {
       return;
@@ -98,6 +100,7 @@ export function useMenuOverflow(
     };
   }, [isOpen, measureOverflow, menuRef]);
 
+  // Measures overflow again after the content changes while the menu is open.
   useIsomorphicLayoutEffect(() => {
     if (isOpen) {
       measureOverflow();

package/src/Field/Field.tsx

@@ -25,11 +25,11 @@ import {FieldStatus} from '../FieldStatus/FieldStatus';
 import {useFieldStatusAnnouncement} from '../FieldStatus/useFieldStatusAnnouncement';
 import {spacingVars, borderVars, sizeVars} from '../theme/tokens.stylex';
 import type {IconType} from '../Icon';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
 import {Text} from '../Text/Text';
-import {VisuallyHidden} from '../VisuallyHidden';
+import {VisuallyHidden} from '../VisuallyHidden/VisuallyHidden';
 import {themeProps} from '../utils/themeProps';
 import type {FieldStatusPlacement} from './fieldStatusPlacement';
 

package/src/FieldStatus/useFieldStatusAnnouncement.ts

@@ -36,6 +36,7 @@ export function useFieldStatusAnnouncement(
   type: InputStatusType | undefined,
 ): void {
   const announce = useAnnounce();
+  // Syncs the live region with the status message.
   useEffect(() => {
     if (message) {
       announce(message, type === 'error' ? 'assertive' : 'polite');