@ankhorage/zora 25.8.11 → 25.8.13

package/src/features/grid-view/application/createGridScrollSync.test.ts

@@ -0,0 +1,292 @@
+import { afterEach, beforeEach, expect, jest, test } from 'bun:test';
+
+import type { GridScrollAxis } from '../../../types/grid-view';
+import { createGridScrollSync } from './createGridScrollSync';
+
+type ScrollRequest = readonly [axis: GridScrollAxis, offset: number, animated: boolean];
+type UserScroll = readonly [axis: GridScrollAxis, displacement: number];
+
+let clock = 0;
+
+beforeEach(() => {
+  clock = 0;
+  jest.useFakeTimers();
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+/*** Advances the injected clock and the fake timers together. */
+function advance(milliseconds: number) {
+  clock += milliseconds;
+  jest.advanceTimersByTime(milliseconds);
+}
+
+/*** Creates a controller whose native requests and user scrolls are recorded. */
+function createRecordedSync() {
+  const programmaticScrolls: UserScroll[] = [];
+  const requests: ScrollRequest[] = [];
+  const userScrolls: UserScroll[] = [];
+  const sync = createGridScrollSync({
+    now: () => clock,
+    onProgrammaticScroll: (axis, displacement) => programmaticScrolls.push([axis, displacement]),
+    onUserScroll: (axis, displacement) => userScrolls.push([axis, displacement]),
+    scrollTo: (axis, offset, animated) => requests.push([axis, offset, animated]),
+  });
+  return { programmaticScrolls, requests, sync, userScrolls };
+}
+
+test('adopts native scrolling as user input when nothing was requested', () => {
+  const { sync, userScrolls } = createRecordedSync();
+
+  sync.scrolled('y', 30);
+  sync.scrolled('y', 45);
+
+  expect(userScrolls).toEqual([
+    ['y', 30],
+    ['y', 15],
+  ]);
+});
+
+test('requests only axes that moved beyond the native tolerance', () => {
+  const { requests, sync } = createRecordedSync();
+
+  sync.request({ x: 0.4, y: 200 }, true);
+
+  expect(requests).toEqual([['y', 200, true]]);
+  expect(sync.isCurrent({ x: 0.9, y: 200.5 })).toBe(true);
+  expect(sync.isCurrent({ x: 0, y: 202 })).toBe(false);
+});
+
+test('ignores animation frames and the settled echo of a programmatic scroll', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 0, y: 200 }, true);
+
+  advance(16);
+  sync.scrolled('y', 60);
+  advance(16);
+  sync.scrolled('y', 140);
+  advance(16);
+  sync.scrolled('y', 200.4);
+  advance(500);
+
+  expect(userScrolls).toEqual([]);
+  expect(jest.getTimerCount()).toBe(0);
+  sync.scrolled('y', 230);
+  expect(userScrolls).toEqual([['y', 30]]);
+});
+
+test('keeps delayed animated frames from becoming user pans after a 120ms quiet period', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 0, y: 200 }, true);
+
+  advance(16);
+  sync.scrolled('y', 40);
+  advance(150);
+  expect(userScrolls).toEqual([]);
+  sync.scrolled('y', 100);
+  advance(150);
+  sync.scrolled('y', 200);
+  advance(400);
+
+  expect(userScrolls).toEqual([]);
+  expect(jest.getTimerCount()).toBe(0);
+  sync.scrolled('y', 230);
+  expect(userScrolls).toEqual([['y', 30]]);
+});
+
+test('ignores a first native animation frame arriving after the initial request deadline', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 300, y: 0 }, true);
+
+  advance(800);
+  sync.scrolled('x', 100);
+  sync.scrolled('x', 299.7);
+
+  expect(userScrolls).toEqual([]);
+  expect(jest.getTimerCount()).toBe(0);
+  sync.scrolled('x', 320);
+  expect(userScrolls).toEqual([['x', 20]]);
+});
+
+test('keeps the axes independent: settling vertical leaves a pending horizontal scroll alone', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 300, y: 200 }, true);
+
+  sync.scrolled('y', 40);
+  advance(150);
+  expect(userScrolls).toEqual([]);
+  sync.scrollEnded('y', 40);
+  expect(userScrolls).toEqual([['y', -160]]);
+
+  sync.scrolled('x', 100);
+  sync.scrolled('x', 299.6);
+  expect(userScrolls).toEqual([['y', -160]]);
+  expect(jest.getTimerCount()).toBe(0);
+});
+
+test('keeps a vertical animation pending while the user drags horizontally', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 300, y: 200 }, true);
+
+  sync.dragBegan('x', 120);
+  sync.scrolled('y', 80);
+  sync.scrolled('y', 199.7);
+
+  expect(userScrolls).toEqual([['x', -180]]);
+});
+
+test('adopts the native offset reported when a drag interrupts an animation', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 0, y: 200 }, true);
+  sync.scrolled('y', 40);
+
+  sync.dragBegan('y', 55);
+
+  expect(userScrolls).toEqual([['y', -145]]);
+  expect(jest.getTimerCount()).toBe(0);
+  sync.scrolled('y', 70);
+  expect(userScrolls).toEqual([
+    ['y', -145],
+    ['y', 15],
+  ]);
+});
+
+test('adopts the final native offset when an unreachable animation ends short', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 0, y: 500 }, true);
+  sync.scrolled('y', 120);
+
+  sync.scrollEnded('y', 180);
+
+  expect(userScrolls).toEqual([['y', -320]]);
+  expect(jest.getTimerCount()).toBe(0);
+});
+
+test('reconciles a stalled animation at its request deadline instead of the quiet interval', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 0, y: 200 }, true);
+  sync.scrolled('y', 40);
+  sync.scrolled('y', 60);
+
+  advance(120);
+  expect(userScrolls).toEqual([]);
+  advance(579);
+  expect(userScrolls).toEqual([]);
+  advance(1);
+
+  expect(userScrolls).toEqual([['y', -140]]);
+});
+
+test('suppresses late animation echoes even after fallback reconciles a stalled axis', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 0, y: 200 }, true);
+  sync.scrolled('y', 40);
+
+  advance(700);
+  expect(userScrolls).toEqual([['y', -160]]);
+
+  // A delayed native animation may resume after the request deadline.
+  sync.scrolled('y', 100);
+  sync.scrolled('y', 200);
+  expect(userScrolls).toEqual([['y', -160]]);
+
+  // A real drag explicitly takes ownership and adopts the current physical offset.
+  sync.dragBegan('y', 200);
+  sync.scrolled('y', 230);
+  expect(userScrolls).toEqual([
+    ['y', -160],
+    ['y', 30],
+  ]);
+});
+
+test('converges the logical position when a delayed animation resumes after fallback', () => {
+  const { programmaticScrolls, sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 0, y: 200 }, true);
+  sync.scrolled('y', 40);
+
+  advance(700);
+  sync.scrolled('y', 100);
+  sync.scrolled('y', 200);
+  expect(sync.isCurrent({ x: 0, y: 200 })).toBe(true);
+  sync.scrollEnded('y', 200);
+
+  expect(userScrolls).toEqual([['y', -160]]);
+  expect(programmaticScrolls).toEqual([
+    ['y', 60],
+    ['y', 100],
+  ]);
+});
+
+test('retargeting discards residual echo ownership from an earlier animation', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 0, y: 200 }, true);
+  sync.scrolled('y', 40);
+  advance(700);
+
+  sync.request({ x: 0, y: 400 }, true);
+  sync.scrolled('y', 100);
+  advance(700);
+
+  expect(userScrolls).toEqual([
+    ['y', -160],
+    ['y', -300],
+  ]);
+  expect(sync.isCurrent({ x: 0, y: 100 })).toBe(true);
+});
+
+test('a genuine reversal after a stalled animation exits residual echo suppression', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 0, y: 200 }, true);
+  sync.scrolled('y', 40);
+  advance(700);
+
+  sync.scrolled('y', 100);
+  sync.scrolled('y', 20);
+  expect(userScrolls).toEqual([
+    ['y', -160],
+    ['y', -80],
+  ]);
+});
+
+test('discards stale in-flight offsets and timers when a scroll is retargeted', () => {
+  const { requests, sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 0, y: 200 }, true);
+  sync.scrolled('y', 40);
+
+  sync.request({ x: 0, y: 400 }, true);
+  expect(jest.getTimerCount()).toBe(0);
+  advance(500);
+  sync.scrolled('y', 399.5);
+
+  expect(requests).toEqual([
+    ['y', 200, true],
+    ['y', 400, true],
+  ]);
+  expect(userScrolls).toEqual([]);
+});
+
+test('returns control to the user once the programmatic scroll window expires', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 0, y: 200 }, false);
+
+  advance(121);
+  sync.scrolled('y', 90);
+
+  expect(userScrolls).toEqual([['y', -110]]);
+});
+
+test('cancels every pending settle timer on dispose', () => {
+  const { sync, userScrolls } = createRecordedSync();
+  sync.request({ x: 300, y: 200 }, true);
+  sync.scrolled('x', 20);
+  sync.scrolled('y', 40);
+  expect(jest.getTimerCount()).toBe(2);
+
+  sync.dispose();
+  advance(1000);
+
+  expect(jest.getTimerCount()).toBe(0);
+  expect(userScrolls).toEqual([]);
+});

package/src/features/grid-view/application/createGridScrollSync.ts

@@ -0,0 +1,169 @@
+import type {
+  GridPendingScroll,
+  GridScrollAxis,
+  GridScrollPosition,
+  GridScrollSync,
+  GridScrollSyncOptions,
+} from '../../../types/grid-view';
+import {
+  ANIMATED_SCROLL_WINDOW_MS,
+  IMMEDIATE_SCROLL_WINDOW_MS,
+  SCROLL_POSITION_TOLERANCE,
+} from '../constants/scroll';
+import { resolveScrollEventSource } from './resolveScrollEventSource';
+
+const AXES: readonly GridScrollAxis[] = ['x', 'y'];
+interface EchoTail {
+  lastOffset: number;
+  target: number;
+}
+
+/***
+ * Arbitrates each native scroll axis between programmatic requests and the user,
+ * so echoes of GridView's own scrollTo calls never become viewport pans.
+ */
+export function createGridScrollSync({
+  scrollTo,
+  onUserScroll,
+  onProgrammaticScroll,
+  now = Date.now,
+  schedule = setTimeout,
+  cancel = clearTimeout,
+}: GridScrollSyncOptions): GridScrollSync {
+  let position: GridScrollPosition = { x: 0, y: 0 };
+  const pending = new Map<GridScrollAxis, GridPendingScroll>();
+  const inFlight = new Map<GridScrollAxis, number>();
+  // Keep ownership of late frames even after a stalled animation is reconciled.
+  const echoTails = new Map<GridScrollAxis, EchoTail>();
+  const timers = new Map<GridScrollAxis, ReturnType<typeof setTimeout>>();
+
+  const clearTimer = (axis: GridScrollAxis) => {
+    const timer = timers.get(axis);
+    if (timer !== undefined) cancel(timer);
+    timers.delete(axis);
+  };
+  const release = (axis: GridScrollAxis) => {
+    clearTimer(axis);
+    pending.delete(axis);
+    inFlight.delete(axis);
+  };
+  const adopt = (axis: GridScrollAxis, offset: number) => {
+    const displacement = offset - readAxis(position, axis);
+    position = withAxis(position, axis, offset);
+    if (displacement !== 0) onUserScroll(axis, displacement);
+  };
+  const settle = (axis: GridScrollAxis, finalOffset?: number) => {
+    const pendingScroll = pending.get(axis);
+    const offset = finalOffset ?? inFlight.get(axis);
+    release(axis);
+    if (offset !== undefined) {
+      if (
+        finalOffset === undefined &&
+        pendingScroll?.animated &&
+        !isSameOffset(offset, pendingScroll.target)
+      ) {
+        echoTails.set(axis, { lastOffset: offset, target: pendingScroll.target });
+      } else {
+        echoTails.delete(axis);
+      }
+      adopt(axis, offset);
+    }
+  };
+  const scrolled = (axis: GridScrollAxis, offset: number) => {
+    const tail = echoTails.get(axis);
+    if (tail) {
+      if (isContinuingProgrammaticEcho(tail, offset)) {
+        const displacement = offset - readAxis(position, axis);
+        position = withAxis(position, axis, offset);
+        if (displacement !== 0) onProgrammaticScroll(axis, displacement);
+        if (isSameOffset(offset, tail.target)) echoTails.delete(axis);
+        else tail.lastOffset = offset;
+        return;
+      }
+      echoTails.delete(axis);
+    }
+    let pendingScroll = pending.get(axis);
+    if (pendingScroll?.animated && now() > pendingScroll.expiresAt) {
+      // A native scroll may deliver its first frame after the initial deadline.
+      // Without an explicit drag/end, that is still an echo of our scrollTo.
+      pendingScroll = { ...pendingScroll, expiresAt: now() + ANIMATED_SCROLL_WINDOW_MS };
+      pending.set(axis, pendingScroll);
+    }
+    const source = resolveScrollEventSource(pendingScroll, offset, now());
+    if (source === 'in-flight' && pendingScroll) {
+      clearTimer(axis);
+      inFlight.set(axis, offset);
+      // Native animation frames can pause longer than 120ms; only reconcile at the
+      // original request deadline, or earlier on an explicit drag/end/target echo.
+      timers.set(
+        axis,
+        schedule(() => settle(axis), Math.max(0, pendingScroll.expiresAt - now())),
+      );
+      return;
+    }
+    release(axis);
+    if (source === 'user') adopt(axis, offset);
+  };
+
+  return {
+    isCurrent: (next) =>
+      AXES.every((axis) => isSameOffset(readAxis(position, axis), readAxis(next, axis))),
+    request: (next, animated) => {
+      const windowMs = animated ? ANIMATED_SCROLL_WINDOW_MS : IMMEDIATE_SCROLL_WINDOW_MS;
+      const expiresAt = now() + windowMs;
+      for (const axis of AXES) {
+        const target = readAxis(next, axis);
+        if (isSameOffset(readAxis(position, axis), target)) continue;
+        release(axis);
+        echoTails.delete(axis);
+        pending.set(axis, { animated, expiresAt, target });
+        scrollTo(axis, target, animated);
+      }
+      position = next;
+    },
+    scrolled,
+    dragBegan: (axis, offset) => {
+      const hadTail = echoTails.delete(axis);
+      if (pending.has(axis) || inFlight.has(axis)) settle(axis, offset);
+      else if (hadTail) adopt(axis, offset);
+    },
+    scrollEnded: (axis, offset) => {
+      scrolled(axis, offset);
+      echoTails.delete(axis);
+      if (pending.has(axis)) settle(axis, offset);
+    },
+    dispose: () => {
+      for (const axis of AXES) release(axis);
+      echoTails.clear();
+    },
+  };
+}
+
+/*** Suppresses delayed monotonic frames toward the old programmatic target until an actual drag/end. */
+function isContinuingProgrammaticEcho({ lastOffset, target }: EchoTail, offset: number): boolean {
+  const step = offset - lastOffset;
+  if (Math.abs(step) <= SCROLL_POSITION_TOLERANCE) return true;
+  return (
+    Math.sign(step) === Math.sign(target - lastOffset) &&
+    Math.abs(target - offset) <= Math.abs(target - lastOffset) + SCROLL_POSITION_TOLERANCE
+  );
+}
+
+/*** Reads one axis of a physical scroll position. */
+function readAxis(value: GridScrollPosition, axis: GridScrollAxis): number {
+  return axis === 'x' ? value.x : value.y;
+}
+
+/*** Replaces one axis of a physical scroll position. */
+function withAxis(
+  value: GridScrollPosition,
+  axis: GridScrollAxis,
+  offset: number,
+): GridScrollPosition {
+  return axis === 'x' ? { ...value, x: offset } : { ...value, y: offset };
+}
+
+/*** Treats offsets within the native positioning tolerance as the same scroll offset. */
+function isSameOffset(left: number, right: number): boolean {
+  return Math.abs(left - right) <= SCROLL_POSITION_TOLERANCE;
+}

package/src/features/grid-view/application/resolveScrollEventSource.test.ts

@@ -0,0 +1,19 @@
+import { expect, test } from 'bun:test';
+
+import { resolveScrollEventSource } from './resolveScrollEventSource';
+
+const pending = { animated: true, expiresAt: 1000, target: 100 };
+
+test('treats every offset as user input when no programmatic scroll is pending', () => {
+  expect(resolveScrollEventSource(undefined, 40, 0)).toBe('user');
+});
+
+test('keeps intermediate animation frames separate from user input until the target is reached', () => {
+  expect(resolveScrollEventSource(pending, 10, 500)).toBe('in-flight');
+  expect(resolveScrollEventSource(pending, 99.4, 500)).toBe('settled');
+  expect(resolveScrollEventSource(pending, 100.9, 500)).toBe('settled');
+});
+
+test('returns control to the user once the programmatic scroll window has expired', () => {
+  expect(resolveScrollEventSource(pending, 10, 1001)).toBe('user');
+});

package/src/features/grid-view/application/resolveScrollEventSource.ts

@@ -0,0 +1,12 @@
+import type { GridPendingScroll } from '../../../types/grid-view';
+import { SCROLL_POSITION_TOLERANCE } from '../constants/scroll';
+
+/*** Classifies a native scroll offset as a user gesture, the settled echo of a programmatic scroll, or an in-flight frame of one. */
+export function resolveScrollEventSource(
+  pending: GridPendingScroll | undefined,
+  offset: number,
+  now: number,
+): 'in-flight' | 'settled' | 'user' {
+  if (pending === undefined || now > pending.expiresAt) return 'user';
+  return Math.abs(offset - pending.target) <= SCROLL_POSITION_TOLERANCE ? 'settled' : 'in-flight';
+}

package/src/features/grid-view/constants/scroll.ts

@@ -0,0 +1,8 @@
+/** Largest native-versus-requested scroll offset difference, in pixels, still treated as the same position. */
+export const SCROLL_POSITION_TOLERANCE = 1;
+
+/** Upper bound for a native animated `scrollTo` to deliver its settled offset. */
+export const ANIMATED_SCROLL_WINDOW_MS = 700;
+
+/** Upper bound for an immediate `scrollTo` to deliver its settled offset. */
+export const IMMEDIATE_SCROLL_WINDOW_MS = 120;

package/src/features/layout/adapters/inbound/ScrollGestureLockContext.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+
+import type { ScrollGestureLock } from '../../../../types/layout';
+
+/*** Carries the nearest ZORA ScrollView gesture lock to descendant gesture surfaces. */
+export const ScrollGestureLockContext = React.createContext<ScrollGestureLock | undefined>(
+  undefined,
+);