@astryxdesign/core 0.7.8 → 0.7.9-canary.07992bb

package/src/gestures/nativeScroll.ts

@@ -31,33 +31,18 @@
 import {isRtlElement} from '../hooks/isRtlElement';
 import type {NativeScrollProbe} from './types';
 import {parentAcrossShadow} from '../utils/flatTree';
+import {
+  isInsideScrollView,
+  parseTouchAction,
+  rootOverflow,
+  SCROLLABLE_OVERFLOW as SCROLLABLE,
+  type AllowedPans,
+} from '../utils/scrollView';
 
 export {parentAcrossShadow};
 
-export interface AllowedPans {
-  readonly x: boolean;
-  readonly y: boolean;
-}
-
-/** Which pans a `touch-action` value lets the browser perform. */
-export function parseTouchAction(value: string): AllowedPans {
-  const tokens = value.trim().split(/\s+/);
-  if (tokens.includes('auto') || tokens.includes('manipulation')) {
-    return {x: true, y: true};
-  }
-  if (tokens.includes('none')) {
-    return {x: false, y: false};
-  }
-  return {
-    x: tokens.some(
-      token =>
-        token === 'pan-x' || token === 'pan-left' || token === 'pan-right',
-    ),
-    y: tokens.some(
-      token => token === 'pan-y' || token === 'pan-up' || token === 'pan-down',
-    ),
-  };
-}
+export {parseTouchAction};
+export type {AllowedPans};
 
 interface ChainEntry {
   readonly element: Element;
@@ -66,15 +51,8 @@ interface ChainEntry {
   readonly isRtl: boolean;
   readonly stopsX: boolean;
   readonly stopsY: boolean;
-  /**
-   * The scroller sits beyond a `position: fixed` ancestor of the touch: it
-   * still scrolls under the finger, but it does not carry the touched
-   * element, so the element is not inside a scroll view (spec:AST-094 FR11).
-   */
-  readonly isBeyondFixed: boolean;
 }
 
-const SCROLLABLE = new Set(['auto', 'scroll', 'overlay']);
 const EDGE_TOLERANCE = 1;
 
 interface Chain {
@@ -94,7 +72,6 @@ function buildChain(target: Element, readsTouchAction: boolean): Chain {
   let allowX = true;
   let allowY = true;
   let reachedRoot = false;
-  let isBeyondFixed = false;
   for (
     let node: Node | null = target;
     node != null;
@@ -128,15 +105,11 @@ function buildChain(target: Element, readsTouchAction: boolean): Chain {
         isRtl: isRtlElement(element as HTMLElement),
         stopsX: behaviorX !== 'auto',
         stopsY: behaviorY !== 'auto',
-        isBeyondFixed,
       });
     }
     if (isRoot) {
       break;
     }
-    if (style.position === 'fixed') {
-      isBeyondFixed = true;
-    }
   }
   if (!reachedRoot && root instanceof Element) {
     chain.push({
@@ -146,7 +119,6 @@ function buildChain(target: Element, readsTouchAction: boolean): Chain {
       isRtl: false,
       stopsX: false,
       stopsY: false,
-      isBeyondFixed,
     });
   }
   return {entries: chain, allowsPan: allowX || allowY};
@@ -167,28 +139,6 @@ function overscrollBehavior(style: CSSStyleDeclaration): [string, string] {
   return [x || first, y || second];
 }
 
-/**
- * The viewport scrolls unless the root or the body clips it (a scroll lock
- * sets `overflow: hidden` on one of them).
- */
-function rootOverflow(doc: Document, axis: 'x' | 'y'): string {
-  const view = doc.defaultView;
-  if (view == null) {
-    return 'hidden';
-  }
-  for (const element of [doc.documentElement, doc.body]) {
-    if (element == null) {
-      continue;
-    }
-    const style = view.getComputedStyle(element);
-    const value = axis === 'x' ? style.overflowX : style.overflowY;
-    if (value === 'hidden' || value === 'clip') {
-      return 'hidden';
-    }
-  }
-  return 'auto';
-}
-
 function canMoveY(element: Element, dy: number): boolean {
   if (element.scrollHeight - element.clientHeight <= EDGE_TOLERANCE) {
     return false;
@@ -288,15 +238,9 @@ export function createNativeScrollProbe(
       return chain?.allowsPan === true;
     },
     get isInsideScroller(): boolean {
-      return getChain().some(
-        entry =>
-          !entry.isBeyondFixed &&
-          ((entry.y &&
-            entry.element.scrollHeight - entry.element.clientHeight >
-              EDGE_TOLERANCE) ||
-            (entry.x &&
-              entry.element.scrollWidth - entry.element.clientWidth >
-                EDGE_TOLERANCE)),
+      return (
+        target instanceof Element &&
+        isInsideScrollView(target, {readsTouchAction})
       );
     },
   };

package/src/gestures/wheelSegmenter.ts

@@ -5,6 +5,7 @@
  * @input A wheel stream's deltas along one axis, with their event times
  * @output Exports WheelSegmenter and isBunched. WheelSegmenter splits the
  *   stream into gestures and reads a trackpad's lift (the onset of momentum).
+ *   It keeps a trackpad's late or merged glide wheels in their flick.
  *   isBunched tells one stall's merge from a frame.
  * @position Read by GestureHost.ts's wheel input: the web reports no
  *   trackpad contact or phase, so both are inferred.
@@ -25,6 +26,12 @@ export interface WheelSegment {
   readonly decaying: boolean;
   /** This event came so soon after the one before that it is a merge. */
   readonly bunched: boolean;
+  /**
+   * The signed travel of the late wheel before this one, with any wheel
+   * merged with it. It is handed over when that wheel joined the glide and
+   * this one grows into a new gesture; else 0.
+   */
+  readonly carried: number;
 }
 
 /** Momentum arrives at frame rate: a pause this long ends it. */
@@ -38,6 +45,25 @@ const BUNCHED_MS = 1.5;
 const LIFT_RUN = 4;
 /** And how much of its size the run has lost by then. */
 const LIFT_DECAY = 0.8;
+/** How near a wheel must lie to a sum of the glide's next steps, px. */
+const FIT_PX = 1;
+/** Or as a share of that sum, when the share is larger. */
+const FIT_SHARE = 0.25;
+/** The most glide steps one wheel is read as carrying. */
+const MAX_STEPS = 64;
+/** How near a late or rising wheel must lie to the glide's sum, as a share. */
+const LATE_FIT_SHARE = 0.15;
+/**
+ * How far a wheel may grow past the last unbunched one and still be the
+ * glide, px.
+ */
+const RISE_PX = 0.5;
+/** A stream's frame interval until it shows its own, ms. */
+const FRAME_MS = 16;
+/** The longest frame interval a trackpad reports at: 60 Hz, ms. */
+const SLOWEST_FRAME_MS = 1000 / 60;
+/** The intervals that set a gesture's frame before its window applies. */
+const FIRST_PACES = 3;
 
 /**
  * Whether a wheel `intervalMs` after the one before is one stall's merge, not
@@ -59,6 +85,16 @@ export function isBunched(intervalMs: number): boolean {
  * decay, or a pause of 50 ms starts a new gesture. A bunched wheel is never
  * a jump. The decay reads it by its last step. Momentum never pauses,
  * reverses or grows.
+ *
+ * A stalled page receives a trackpad's glide late, and the engine merges the
+ * wheels it held. In momentum, a trackpad wheel that the glide's decay
+ * explains stays in the flick. It may come after a pause, or rise after more
+ * than a frame. It is at or below the next step, or near the sum of the next
+ * steps its stall spans. After such a wheel, a trackpad wheel that grows
+ * starts a new gesture and takes the late wheel's travel. The decay also
+ * reads a trackpad merge in momentum, by its last step. It reads one in a
+ * shrinking run too, where it explains the merge better than steady steps
+ * do. Other wheels keep the rules above.
  */
 export class WheelSegmenter {
   gesture = 0;
@@ -69,44 +105,137 @@ export class WheelSegmenter {
   private count = 0;
   private run = 0;
   private runStart = 0;
+  /** The decay's step-to-step ratio, from the last two one-step wheels. */
+  private ratio = 1;
+  /** The gesture's last on-pace intervals, ms: their median is its frame. */
+  private paces: number[] = [];
+  /** The intervals in a row that came slower than the frame allows, ms. */
+  private slower: number[] = [];
+  /** When the gesture's last wheel within two frames of the one before came. */
+  private onPace = -Infinity;
+  /** The gesture's last wheel that was not bunched, px. */
+  private paced = 0;
+  /** A wheel joined the glide late: a later one that grows is the fingers'. */
+  private resumed = false;
+  /**
+   * The signed travel of the last wheel that joined the glide late, with any
+   * wheel merged with it.
+   */
+  private joined = 0;
 
-  push(time: number, delta: number, idleMs: number): WheelSegment {
+  /**
+   * Reads one wheel. `continuous` is whether it carries a trackpad's
+   * signature (`scrollTypeOf`). Only those wheels can join a glide late.
+   */
+  push(
+    time: number,
+    delta: number,
+    idleMs: number,
+    continuous = false,
+  ): WheelSegment {
     const size = Math.abs(delta);
     const sign = Math.sign(delta);
     const gap = time - this.last;
     const bunched = this.count > 0 && isBunched(gap);
+    const frame = this.frameMs();
     let boundary: WheelBoundary | null = null;
+    let carriedSteps: number | null = null;
     if (this.count === 0) {
       boundary = this.gesture === 0 ? 'first' : 'idle';
     } else if (this.phase === 'finger' && gap >= idleMs) {
       boundary = 'idle';
     } else if (this.phase === 'momentum') {
+      // A late wheel carries the steps of its whole stall, which began at the
+      // last wheel that came on pace.
+      const frames = Math.round((time - this.onPace) / frame);
+      const late = gap >= MOMENTUM_GAP_MS;
+      const rises = !bunched && size >= 2 && size > this.previous * 1.3 + 0.5;
       if (sign !== 0 && this.sign !== 0 && sign !== this.sign) {
         boundary = 'reversal';
-      } else if (gap >= MOMENTUM_GAP_MS) {
-        boundary = 'gap';
-      } else if (!bunched && size >= 2 && size > this.previous * 1.3 + 0.5) {
+      } else if (late || rises) {
+        // A wheel that rises on pace is the fingers'. One that rises after a
+        // skipped frame may carry the frames its stall held.
+        if (continuous && sign === this.sign && (late || gap >= 1.5 * frame)) {
+          carriedSteps = this.glideSteps(
+            size,
+            Math.max(1, frames),
+            LATE_FIT_SHARE,
+          );
+        }
+        if (carriedSteps == null) {
+          boundary = late ? 'gap' : 'jump';
+        }
+      } else if (
+        continuous &&
+        this.resumed &&
+        !bunched &&
+        size > FIT_PX &&
+        size > this.paced + RISE_PX
+      ) {
+        // A glide only falls, so after a late wheel one that grows is the
+        // fingers'. A whole-pixel glide repeats a step as it slows.
         boundary = 'jump';
       }
     }
+    if (carriedSteps == null && boundary == null && bunched && continuous) {
+      if (this.phase === 'momentum') {
+        carriedSteps = this.glideSteps(size, MAX_STEPS);
+      } else if (this.run > 0) {
+        // In a shrinking run, the decay reads a merge only where it explains
+        // the merge better than steady steps do.
+        const decay = this.glideSteps(size, MAX_STEPS);
+        if (
+          decay != null &&
+          decay > 1 &&
+          Math.abs(size - this.glideSum(decay)) < this.steadyOff(size)
+        ) {
+          carriedSteps = decay;
+        }
+      }
+    }
     // A bunched wheel carries the steps of the frames it merged. The decay
     // goes on from its last step, so the steps after it read as they are.
     const steps =
-      boundary == null && bunched && this.previous > 0
+      carriedSteps ??
+      (boundary == null && bunched && this.previous > 0
         ? Math.max(1, Math.round(size / this.previous))
-        : 1;
+        : 1);
+    // On the decay, a wheel of several steps ends at the decay's own step.
+    const onDecay = carriedSteps != null && carriedSteps > 1;
+    // A bunched wheel is read by its last step, as the decay goes on from it.
+    const step = onDecay ? this.previous * this.ratio ** steps : size / steps;
     if (boundary != null) {
       this.gesture += 1;
       this.phase = 'finger';
       this.count = 0;
       this.run = 0;
+      this.ratio = 1;
+      this.resumed = false;
+      this.paces = [];
+      this.slower = [];
+    }
+    // The late wheel was the fingers' when the next one grows: the new
+    // gesture takes its travel.
+    const carried = boundary === 'jump' ? this.joined : 0;
+    const joinedLate = boundary == null && carriedSteps != null && !bunched;
+    if (joinedLate) {
+      this.resumed = true;
+    }
+    // A wheel merged with the late one is the same dispatch: it adds to it.
+    this.joined = joinedLate
+      ? delta
+      : bunched && boundary == null && this.joined !== 0
+        ? this.joined + delta
+        : 0;
+    if (!bunched) {
+      this.paced = size;
     }
     let liftNow = false;
     let decaying = false;
     if (this.phase === 'finger' && this.count >= 3 && size > 0) {
-      // A bunched wheel is read by its last step, as the decay goes on from it.
-      const step = size / steps;
-      decaying = step <= this.previous * 0.995 && step >= this.previous * 0.5;
+      decaying = onDecay
+        ? this.ratio <= 0.995
+        : step <= this.previous * 0.995 && step >= this.previous * 0.5;
       if (decaying) {
         if (this.run === 0) {
           this.runStart = this.previous;
@@ -120,8 +249,17 @@ export class WheelSegmenter {
         liftNow = true;
       }
     }
+    if (steps === 1 && this.count > 0 && this.previous > 0 && step > 0) {
+      this.ratio = Math.min(1, Math.max(0.5, step / this.previous));
+    }
+    if (!bunched && boundary == null && gap < MOMENTUM_GAP_MS) {
+      this.notePace(gap, frame);
+    }
+    if (boundary != null || (!bunched && gap < 2 * frame)) {
+      this.onPace = time;
+    }
     this.count += 1;
-    this.previous = size / steps;
+    this.previous = step;
     if (sign !== 0) {
       this.sign = sign;
     }
@@ -133,9 +271,104 @@ export class WheelSegmenter {
       liftNow,
       decaying: decaying && !liftNow,
       bunched: boundary == null && bunched,
+      carried,
     };
   }
 
+  /**
+   * Keep an interval for the frame. The gesture's first FIRST_PACES set it.
+   * After them, only an interval within half a frame and one and a half
+   * frames counts: a stall's squeezed wheels come faster. FIRST_PACES slower
+   * intervals in a row set the frame again, so a squeezed start cannot hold
+   * it down.
+   */
+  private notePace(gap: number, frame: number): void {
+    const inWindow = gap >= 0.5 * frame && gap <= 1.5 * frame;
+    if (this.paces.length < FIRST_PACES || inWindow) {
+      this.paces = [...this.paces.slice(-7), gap];
+      this.slower = [];
+      return;
+    }
+    this.slower = gap > 1.5 * frame ? [...this.slower, gap] : [];
+    if (this.slower.length >= FIRST_PACES) {
+      this.paces = this.slower;
+      this.slower = [];
+    }
+  }
+
+  /**
+   * The gesture's frame interval: the median of its last on-pace intervals,
+   * or FRAME_MS before it shows one. A trackpad reports at 60 Hz or faster,
+   * so a longer median is a stall's.
+   */
+  private frameMs(): number {
+    if (this.paces.length === 0) {
+      return FRAME_MS;
+    }
+    const sorted = [...this.paces].sort((a, b) => a - b);
+    const middle = sorted.length >> 1;
+    const median =
+      sorted.length % 2 === 1
+        ? sorted[middle]
+        : (sorted[middle - 1] + sorted[middle]) / 2;
+    return Math.min(median, SLOWEST_FRAME_MS);
+  }
+
+  /** The sum of the decay's next `count` steps from `previous`. */
+  private glideSum(count: number): number {
+    let next = this.previous * this.ratio;
+    let sum = 0;
+    for (let i = 0; i < count; i++) {
+      sum += next;
+      next *= this.ratio;
+    }
+    return sum;
+  }
+
+  /**
+   * How far a merge of `size` lies from whole steps of the run's steady
+   * size, or of its last step, whichever lies nearer.
+   */
+  private steadyOff(size: number): number {
+    return Math.min(
+      ...[this.runStart, this.previous]
+        .filter(step => step > 0)
+        .map(step =>
+          Math.abs(size - Math.max(1, Math.round(size / step)) * step),
+        ),
+    );
+  }
+
+  /**
+   * How many of the decay's next steps a trackpad wheel of `size` carries,
+   * at most `most`. A wheel at or below the next step carries one. A larger
+   * one carries the fewest steps whose sum lies within FIT_PX or `share` of
+   * it. The decay goes on from `previous` at `ratio` a step. Null when
+   * no sum lies that near.
+   */
+  private glideSteps(
+    size: number,
+    most: number,
+    share = FIT_SHARE,
+  ): number | null {
+    if (this.previous <= 0 || size <= 0) {
+      return null;
+    }
+    let next = this.previous * this.ratio;
+    if (size <= next + FIT_PX) {
+      return 1;
+    }
+    let sum = next;
+    for (let count = 2; count <= Math.min(most, MAX_STEPS); count++) {
+      next *= this.ratio;
+      sum += next;
+      if (Math.abs(size - sum) <= Math.max(FIT_PX, sum * share)) {
+        return count;
+      }
+    }
+    return null;
+  }
+
   /** The gesture ended on its own (its timer): the next event starts one. */
   end(): void {
     this.count = 0;

package/src/hooks/StackItemScrollRegion.tsx

@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file StackItemScrollRegion.tsx
+ * @input A scrollable `div` or `span` StackItem's props, ref and children
+ * @output StackItemScrollRegion (internal; not re-exported from
+ *   hooks/index.ts), which renders that element and names it as a group
+ *   while its content overflows
+ * @position Internal client island for StackItem, which itself stays a
+ *   static render. Only a scrollable `div` or `span` item measures its
+ *   overflow, on the client; another element keeps its own role.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Stack/StackItem.tsx
+ * - /packages/core/src/serverSafeComponents.test.ts
+ */
+
+import {createElement, type AriaRole, type ReactNode, type Ref} from 'react';
+import {useMergedRefs} from './useMergedRefs';
+import {useScrollRegionProps} from './useScrollRegionProps';
+
+export interface StackItemScrollRegionProps {
+  as: 'div' | 'span';
+  ref?: Ref<HTMLElement>;
+  elementProps: {
+    role?: AriaRole;
+    'aria-label'?: string;
+    [prop: string]: unknown;
+  };
+  children?: ReactNode;
+}
+
+export function StackItemScrollRegion({
+  as: element,
+  ref,
+  elementProps,
+  children,
+}: StackItemScrollRegionProps) {
+  const region = useScrollRegionProps({
+    isScrollable: true,
+    role: elementProps.role,
+    label: elementProps['aria-label'],
+  });
+  const mergedRef = useMergedRefs(ref, region.ref);
+  return createElement(
+    element,
+    {
+      ...elementProps,
+      ref: mergedRef,
+      role: region.role,
+      'aria-label': region['aria-label'],
+    },
+    children,
+  );
+}