@ankhorage/zora 25.8.11 → 25.8.12

package/src/features/grid-interactions/adapters/inbound/GridInteractions.scrollLock.test.tsx

@@ -0,0 +1,265 @@
+// Drives the native GridInteractions adapter and the real ZORA ScrollView through
+// react-native-web's responder system in a private happy-dom window. The module mocks are
+// process-wide in Bun, so this file relies on the repository's `bun test --isolate` script;
+// DOM globals are restored in afterAll.
+import { afterAll, expect, mock, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import type { GridInteractionIntent } from '../../../../types/grid-interactions';
+
+const browser = new Window();
+const globalKeys = [
+  'window',
+  'document',
+  'Node',
+  'navigator',
+  'ShadowRoot',
+  'IS_REACT_ACT_ENVIRONMENT',
+] as const;
+const previousGlobals = globalKeys.map(
+  (key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)] as const,
+);
+Object.assign(globalThis, {
+  IS_REACT_ACT_ENVIRONMENT: true,
+  Node: browser.Node,
+  ShadowRoot: browser.ShadowRoot,
+  document: browser.document,
+  navigator: browser.navigator,
+  window: browser,
+});
+
+const reactNativeWeb = await import('react-native-web');
+await mock.module('react-native', () => reactNativeWeb);
+// The layout feature only needs these Surface primitives; the real package would load
+// native-only peers, so DOM-capable react-native-web primitives stand in for them.
+await mock.module('@ankhorage/surface', () => ({
+  Divider: reactNativeWeb.View,
+  Grid: reactNativeWeb.View,
+  ScrollView: reactNativeWeb.ScrollView,
+  ThemeScope: ({ children }: { readonly children: React.ReactNode }) => children,
+  View: reactNativeWeb.View,
+  useTheme: () => ({}),
+}));
+const { ScrollView } = await import('../../../layout/public');
+const { GridInteractions } = await import('./GridInteractions');
+const defaultScrollLockModule = await import('./useGridInteractionScrollLock');
+const nativeScrollLockModule = await import('./useGridInteractionScrollLock.native');
+
+afterAll(() => {
+  browser.close();
+  for (const [key, descriptor] of previousGlobals) {
+    if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+    else Reflect.deleteProperty(globalThis, key);
+  }
+});
+
+const viewport = {
+  height: 100,
+  offsetX: 0,
+  offsetY: 0,
+  pixelsPerUnitX: 2,
+  pixelsPerUnitY: 4,
+  width: 100,
+};
+const items = [{ height: 2, id: 'a', width: 3, x: 1, y: 1 }];
+
+type TouchType = 'touchstart' | 'touchmove' | 'touchend' | 'touchcancel';
+interface PageOptions {
+  readonly interactionPolicy?: 'passive';
+  readonly interactions?: boolean;
+  readonly nested?: boolean;
+}
+interface Page {
+  readonly intents: GridInteractionIntent[];
+  readonly render: (options: PageOptions) => Promise<void>;
+  readonly scroll: (testID: string) => Promise<boolean>;
+  readonly startDrag: () => Promise<void>;
+  readonly touch: (type: TouchType, pageY: number) => Promise<void>;
+  readonly unmount: () => Promise<void>;
+}
+
+/*** Mounts ScrollView(s) around a GridInteractions surface and exposes observable page input. */
+function mountPage(): Page {
+  const host = document.createElement('div');
+  document.body.append(host);
+  const root = createRoot(host);
+  const intents: GridInteractionIntent[] = [];
+  const scrolls: string[] = [];
+  const track = (id: string) => () => scrolls.push(id);
+  const touch: Page['touch'] = async (type, pageY) => {
+    const target = host.querySelector<HTMLElement>('[data-testid="surface"]');
+    if (!target) throw new Error('Missing interaction surface');
+    const point = { clientX: 5, clientY: pageY, identifier: 0, pageX: 5, pageY, target };
+    const event = new browser.Event(type, { bubbles: true, cancelable: true });
+    const active = type === 'touchend' || type === 'touchcancel' ? [] : [point];
+    Object.defineProperty(event, 'touches', { value: active });
+    Object.defineProperty(event, 'changedTouches', { value: [point] });
+    await act(() => Promise.resolve().then(() => target.dispatchEvent(event)));
+  };
+  return {
+    intents,
+    render: ({ interactionPolicy, interactions = true, nested = false }) => {
+      const surface = interactions ? (
+        <GridInteractions
+          interactionPolicy={interactionPolicy}
+          items={items}
+          onIntent={(intent) => intents.push(intent)}
+          selectedIds={['a']}
+          testID="surface"
+          viewport={viewport}
+        >
+          <span>slate</span>
+        </GridInteractions>
+      ) : null;
+      const page = (
+        <ScrollView testID="page" onWheel={track('page')}>
+          {nested ? (
+            <ScrollView testID="panel" onWheel={track('panel')}>
+              {surface}
+            </ScrollView>
+          ) : (
+            surface
+          )}
+        </ScrollView>
+      );
+      return act(() => Promise.resolve().then(() => root.render(page)));
+    },
+    // A disabled react-native-web ScrollView stops delivering wheel input to its handlers.
+    scroll: async (testID) => {
+      const target = host.querySelector<HTMLElement>(`[data-testid="${testID}"]`);
+      if (!target) throw new Error(`Missing ${testID}`);
+      const before = scrolls.length;
+      await act(() =>
+        Promise.resolve().then(() =>
+          target.dispatchEvent(new browser.Event('wheel', { bubbles: true })),
+        ),
+      );
+      return scrolls.slice(before).includes(testID);
+    },
+    // Moving after the start only emits intents once the responder system granted ownership.
+    startDrag: async () => {
+      await touch('touchstart', 6);
+      await touch('touchmove', 30);
+      expect(intents.length).toBeGreaterThan(0);
+    },
+    touch,
+    unmount: async () => {
+      await act(() => Promise.resolve().then(() => root.unmount()));
+      host.remove();
+    },
+  };
+}
+
+test('exercises the native scroll-lock hook rather than the web no-op adapter', () => {
+  expect(defaultScrollLockModule.useGridInteractionScrollLock).toBe(
+    nativeScrollLockModule.useGridInteractionScrollLock,
+  );
+});
+
+test('suspends the page scroll for the whole drag and restores it on release', async () => {
+  const page = mountPage();
+  try {
+    await page.render({});
+    expect(await page.scroll('page')).toBe(true);
+
+    await page.startDrag();
+    expect(await page.scroll('page')).toBe(false);
+
+    await page.touch('touchend', 30);
+    expect(await page.scroll('page')).toBe(true);
+  } finally {
+    await page.unmount();
+  }
+});
+
+test('restores the page scroll and ends ownership when the responder gesture is cancelled', async () => {
+  const page = mountPage();
+  try {
+    await page.render({});
+    await page.startDrag();
+    expect(await page.scroll('page')).toBe(false);
+    const intentsBeforeCancel = page.intents.length;
+
+    await page.touch('touchcancel', 30);
+    expect(await page.scroll('page')).toBe(true);
+    await page.touch('touchmove', 60);
+    expect(page.intents).toHaveLength(intentsBeforeCancel);
+  } finally {
+    await page.unmount();
+  }
+});
+
+test('suspends both nested ScrollViews during a drag and restores both together', async () => {
+  const page = mountPage();
+  try {
+    await page.render({ nested: true });
+
+    await page.startDrag();
+    expect(await page.scroll('panel')).toBe(false);
+    expect(await page.scroll('page')).toBe(false);
+
+    await page.touch('touchend', 30);
+    expect(await page.scroll('panel')).toBe(true);
+    expect(await page.scroll('page')).toBe(true);
+  } finally {
+    await page.unmount();
+  }
+});
+
+test('releases the scroll lock when the surface unmounts mid-drag', async () => {
+  const page = mountPage();
+  try {
+    await page.render({});
+    await page.startDrag();
+    expect(await page.scroll('page')).toBe(false);
+
+    await page.render({ interactions: false });
+    expect(await page.scroll('page')).toBe(true);
+  } finally {
+    await page.unmount();
+  }
+});
+
+test('never takes ownership or the page scroll while the interaction policy is passive', async () => {
+  const page = mountPage();
+  try {
+    await page.render({ interactionPolicy: 'passive' });
+
+    await page.touch('touchstart', 6);
+    await page.touch('touchmove', 30);
+    expect(page.intents).toEqual([]);
+    expect(await page.scroll('page')).toBe(true);
+    await page.touch('touchend', 30);
+    expect(await page.scroll('page')).toBe(true);
+  } finally {
+    await page.unmount();
+  }
+});
+
+test('leaves no lock behind when the policy turns passive mid-drag, and locks again once active', async () => {
+  const page = mountPage();
+  try {
+    await page.render({});
+    await page.startDrag();
+    expect(await page.scroll('page')).toBe(false);
+
+    await page.render({ interactionPolicy: 'passive' });
+    await page.touch('touchend', 30);
+    expect(await page.scroll('page')).toBe(true);
+
+    await page.render({});
+    const intentsBeforeSecondDrag = page.intents.length;
+    await page.touch('touchstart', 6);
+    // A different distance, because the controller drops an intent identical to the previous one.
+    await page.touch('touchmove', 40);
+    expect(page.intents.length).toBeGreaterThan(intentsBeforeSecondDrag);
+    expect(await page.scroll('page')).toBe(false);
+
+    await page.touch('touchend', 30);
+    expect(await page.scroll('page')).toBe(true);
+  } finally {
+    await page.unmount();
+  }
+});

package/src/features/grid-interactions/adapters/inbound/GridInteractions.test.tsx

@@ -209,6 +209,70 @@ test('clears the web Space modifier on blur, disable, and unmount', async () =>
   }
 });
 
+test('keeps an active RNW drag when an ancestor scroll container scrolls', async () => {
+  const browser = new Window();
+  const restore = installBrowserGlobals(browser);
+  const host = document.createElement('div');
+  document.body.append(host);
+  const root = createRoot(host);
+  const { GridInteractions } = await loadGridInteractions();
+  const intents: unknown[] = [];
+
+  try {
+    await renderGridInteractions(
+      root,
+      <GridInteractions
+        items={[{ height: 2, id: 'a', width: 3, x: 1, y: 1 }]}
+        onIntent={(intent) => intents.push(intent)}
+        selectedIds={['a']}
+        testID="grid-interactions"
+        viewport={{
+          height: 100,
+          offsetX: 0,
+          offsetY: 0,
+          pixelsPerUnitX: 2,
+          pixelsPerUnitY: 4,
+          width: 100,
+        }}
+      >
+        <span>nested target</span>
+      </GridInteractions>,
+    );
+    const surface = host.querySelector<HTMLElement>('[data-testid="grid-interactions"]');
+    if (!surface) throw new Error('Missing interaction surface');
+
+    await dispatchTouch(browser, surface, 'touchstart', 6);
+    await dispatchTouch(browser, surface, 'touchmove', 30);
+    const intentsBeforeScroll = intents.length;
+    expect(intentsBeforeScroll).toBeGreaterThan(0);
+
+    // A scrolling ancestor must not take the responder from an active drag.
+    await act(() => Promise.resolve().then(() => host.dispatchEvent(new browser.Event('scroll'))));
+    await dispatchTouch(browser, surface, 'touchmove', 60);
+
+    expect(intents.length).toBeGreaterThan(intentsBeforeScroll);
+  } finally {
+    await act(() => Promise.resolve().then(() => root.unmount()));
+    host.remove();
+    browser.close();
+    restore();
+  }
+});
+
+/*** Dispatches one single-finger touch at a fixed horizontal position on the interaction surface. */
+function dispatchTouch(
+  browser: Window,
+  surface: HTMLElement,
+  type: 'touchstart' | 'touchmove',
+  pageY: number,
+) {
+  const touch = { clientX: 5, clientY: pageY, identifier: 0, pageX: 5, pageY, target: surface };
+  const event = new browser.Event(type, { bubbles: true, cancelable: true });
+  Object.defineProperty(event, 'touches', { value: [touch] });
+  Object.defineProperty(event, 'changedTouches', { value: [touch] });
+  return dispatch(surface, event);
+}
+
 /*** Installs the DOM globals that the independently bundled RNW adapter requires. */
 function installBrowserGlobals(browser: Window): () => void {
   const keys = [

package/src/features/grid-interactions/adapters/inbound/GridInteractions.tsx

@@ -9,6 +9,7 @@ import { createGridInteractionsController } from '../../application/createGridIn
 import { createGridInteractionsPointerQueue } from './createGridInteractionsPointerQueue';
 import { GridInteractionsKeyboardProxy } from './GridInteractionsKeyboardProxy';
 import { resolveGridInteractionPointer } from './resolveGridInteractionPointer';
+import { useGridInteractionScrollLock } from './useGridInteractionScrollLock';
 
 /*** Adapts native responder and keyboard events to the controlled grid interaction boundary. */
 export function GridInteractions({
@@ -28,6 +29,7 @@ export function GridInteractions({
   const surfaceRef = React.useRef<View>(null);
   const spaceKeyRef = React.useRef(false);
   const [pointerQueue] = React.useState(() => createGridInteractionsPointerQueue());
+  const scrollLock = useGridInteractionScrollLock();
   React.useLayoutEffect(() => controller.update(controllerProps), [controller, controllerProps]);
   React.useLayoutEffect(() => {
     pointerQueue.activate();
@@ -61,16 +63,22 @@ export function GridInteractions({
       accessibilityRole="adjustable"
       ref={surfaceRef}
       testID={testID}
-      onResponderGrant={(event) =>
-        withPointer(event, (pointer) => controller.begin(pointer, resizeHandle))
-      }
+      onResponderGrant={(event) => {
+        scrollLock.acquire();
+        withPointer(event, (pointer) => controller.begin(pointer, resizeHandle));
+      }}
       onResponderMove={(event) => withPointer(event, controller.move)}
-      onResponderRelease={(event) => withPointer(event, controller.end)}
+      onResponderRelease={(event) => {
+        scrollLock.release();
+        withPointer(event, controller.end);
+      }}
       onResponderTerminate={() => {
+        scrollLock.release();
         setSpaceKey(false);
         pointerQueue.cancel();
         controller.cancel();
       }}
+      onResponderTerminationRequest={() => false}
       onStartShouldSetResponder={() => enabled}
     >
       <GridInteractionsKeyboardProxy

package/src/features/grid-interactions/adapters/inbound/useGridInteractionScrollLock.native.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+
+import type { GridInteractionScrollLock } from '../../../../types/grid-interactions';
+import { useScrollGestureLock } from '../../../layout/public';
+import { createGridInteractionScrollLock } from '../../application/createGridInteractionScrollLock';
+
+/*** Keeps ancestor ZORA scrolling suspended while one native responder gesture owns the surface. */
+export function useGridInteractionScrollLock(): GridInteractionScrollLock {
+  const scrollLock = useScrollGestureLock();
+  const gestureLock = React.useMemo(
+    () => createGridInteractionScrollLock(scrollLock),
+    [scrollLock],
+  );
+  React.useEffect(() => gestureLock.release, [gestureLock]);
+
+  return gestureLock;
+}

package/src/features/grid-interactions/adapters/inbound/useGridInteractionScrollLock.ts

@@ -0,0 +1 @@
+export { useGridInteractionScrollLock } from './useGridInteractionScrollLock.native';

package/src/features/grid-interactions/adapters/inbound/useGridInteractionScrollLock.web.ts

@@ -0,0 +1,11 @@
+import type { GridInteractionScrollLock } from '../../../../types/grid-interactions';
+
+const webScrollLock: GridInteractionScrollLock = {
+  acquire: () => undefined,
+  release: () => undefined,
+};
+
+/*** Leaves browser scrolling to the RNW responder system, which already honors termination requests. */
+export function useGridInteractionScrollLock(): GridInteractionScrollLock {
+  return webScrollLock;
+}

package/src/features/grid-interactions/application/createGridInteractionScrollLock.test.ts

@@ -0,0 +1,41 @@
+import { expect, test } from 'bun:test';
+
+import type { ScrollGestureLock } from '../../../types/layout';
+import { createGridInteractionScrollLock } from './createGridInteractionScrollLock';
+
+/*** Counts held and released ancestor scroll locks. */
+function createCountingScrollLock() {
+  const state = { acquired: 0, released: 0 };
+  const lock: ScrollGestureLock = {
+    acquire: () => {
+      state.acquired += 1;
+      return () => {
+        state.released += 1;
+      };
+    },
+  };
+  return { lock, state };
+}
+
+test('takes the ancestor scroll lock once per gesture even when grant repeats', () => {
+  const { lock, state } = createCountingScrollLock();
+  const gesture = createGridInteractionScrollLock(lock);
+
+  gesture.acquire();
+  gesture.acquire();
+
+  expect(state).toEqual({ acquired: 1, released: 0 });
+});
+
+test('releases on release or termination and can lock again for the next gesture', () => {
+  const { lock, state } = createCountingScrollLock();
+  const gesture = createGridInteractionScrollLock(lock);
+
+  gesture.acquire();
+  gesture.release();
+  gesture.release();
+  gesture.acquire();
+  gesture.release();
+
+  expect(state).toEqual({ acquired: 2, released: 2 });
+});

package/src/features/grid-interactions/application/createGridInteractionScrollLock.ts

@@ -0,0 +1,18 @@
+import type { GridInteractionScrollLock } from '../../../types/grid-interactions';
+import type { ScrollGestureLock } from '../../../types/layout';
+
+/*** Holds at most one ancestor scroll lock for the active responder gesture of an interaction surface. */
+export function createGridInteractionScrollLock(
+  scrollLock: ScrollGestureLock,
+): GridInteractionScrollLock {
+  let releaseScrollLock: (() => void) | undefined;
+  return {
+    acquire: () => {
+      releaseScrollLock ??= scrollLock.acquire();
+    },
+    release: () => {
+      releaseScrollLock?.();
+      releaseScrollLock = undefined;
+    },
+  };
+}

package/src/features/grid-view/adapters/inbound/GridView.nativeScrollSync.test.tsx

@@ -0,0 +1,186 @@
+import type { GridRectItem, GridViewport } from '@ankhorage/grid-view';
+import { afterAll, afterEach, beforeEach, expect, jest, mock, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+
+import type { GridScrollAxis } from '../../../../types/grid-view';
+
+type NativeScrollEvent = Readonly<{
+  nativeEvent: Readonly<{ contentOffset: { x: number; y: number } }>;
+}>;
+type NativeScrollProps = Readonly<{
+  onMomentumScrollEnd?: (event: NativeScrollEvent) => void;
+  onScroll?: (event: NativeScrollEvent) => void;
+  testID?: string;
+}>;
+type ScrollRequest = Readonly<{ animated?: boolean; x?: number; y?: number }>;
+
+const browser = new Window();
+const globalKeys = ['window', 'document', 'Node', 'navigator', 'IS_REACT_ACT_ENVIRONMENT'] as const;
+const previousGlobals = globalKeys.map(
+  (key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)] as const,
+);
+Object.assign(globalThis, {
+  IS_REACT_ACT_ENVIRONMENT: true,
+  Node: browser.Node,
+  document: browser.document,
+  navigator: browser.navigator,
+  window: browser,
+});
+
+const scrollHandlers = new Map<string, NativeScrollProps>();
+const nativeRequests: (readonly [GridScrollAxis, number, boolean])[] = [];
+const ScrollView = React.forwardRef<
+  { scrollTo: (request: ScrollRequest) => void },
+  React.PropsWithChildren<NativeScrollProps>
+>(function ScrollView({ children, onMomentumScrollEnd, onScroll, testID }, ref) {
+  React.useEffect(() => {
+    if (testID !== undefined) scrollHandlers.set(testID, { onMomentumScrollEnd, onScroll, testID });
+    return () => {
+      if (testID !== undefined) scrollHandlers.delete(testID);
+    };
+  }, [onMomentumScrollEnd, onScroll, testID]);
+  React.useImperativeHandle(ref, () => ({
+    scrollTo: ({ animated = false, x, y }) => {
+      if (x !== undefined) nativeRequests.push(['x', x, animated]);
+      if (y !== undefined) nativeRequests.push(['y', y, animated]);
+    },
+  }));
+  return <div data-testid={testID}>{children}</div>;
+});
+
+const View = React.forwardRef<
+  { measureInWindow: (callback: (x: number, y: number) => void) => void },
+  React.PropsWithChildren<{ testID?: string }>
+>(function View({ children, testID }, ref) {
+  React.useImperativeHandle(ref, () => ({ measureInWindow: (callback) => callback(0, 0) }));
+  return <div data-testid={testID}>{children}</div>;
+});
+
+await mock.module('react-native', () => ({
+  Pressable: ({ children }: React.PropsWithChildren) => <button>{children}</button>,
+  ScrollView,
+  Text: ({ children }: React.PropsWithChildren) => <span>{children}</span>,
+  View,
+}));
+
+const { GridView } = await import('./GridView');
+
+beforeEach(() => {
+  jest.useFakeTimers();
+  nativeRequests.length = 0;
+  scrollHandlers.clear();
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+afterAll(() => {
+  browser.close();
+  for (const [key, descriptor] of previousGlobals) {
+    if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+    else Reflect.deleteProperty(globalThis, key);
+  }
+});
+
+test('reconciles the published viewport with late native animation frames after watchdog fallback', async () => {
+  const host = document.createElement('div');
+  document.body.append(host);
+  const root = createRoot(host);
+  const published: GridViewport[] = [];
+  const physicalOffsets: number[] = [];
+  const items: readonly GridRectItem[] = [{ height: 20, id: 'far', width: 20, x: 10, y: 272 }];
+
+  function Consumer() {
+    return (
+      <GridView
+        contentHeight={1000}
+        contentWidth={1000}
+        focusedItemId="far"
+        height={100}
+        items={items}
+        onViewportChange={(next) => {
+          published.push(next);
+        }}
+        renderItem={() => null}
+        testID="grid"
+        viewportConstraints={{ world: { height: 1000, width: 1000, x: 0, y: 0 } }}
+        width={100}
+      />
+    );
+  }
+
+  try {
+    await React.act(() =>
+      Promise.resolve().then(() => {
+        root.render(<Consumer />);
+      }),
+    );
+    expect(nativeRequests).toEqual([['y', 200, true]]);
+    expect(published.map((viewport) => viewport.offsetY)).toEqual([200]);
+
+    await dispatchNativeScrollAsync('grid-vertical-scroll', 40, physicalOffsets);
+    await React.act(() =>
+      Promise.resolve().then(() => {
+        jest.advanceTimersByTime(700);
+      }),
+    );
+    expect(published.map((viewport) => viewport.offsetY)).toEqual([200, 40]);
+
+    await dispatchNativeScrollAsync('grid-vertical-scroll', 100, physicalOffsets);
+    await dispatchNativeScrollAsync('grid-vertical-scroll', 200, physicalOffsets);
+    await dispatchNativeScrollEndAsync('grid-vertical-scroll', 200, physicalOffsets);
+
+    expect(physicalOffsets).toEqual([40, 100, 200, 200]);
+    expect(published.map((viewport) => viewport.offsetY)).toEqual([200, 40, 100, 200]);
+    expect(published.at(-1)?.offsetY).toBe(physicalOffsets.at(-1));
+    expect(nativeRequests).toEqual([['y', 200, true]]);
+    expect(jest.getTimerCount()).toBe(0);
+  } finally {
+    await React.act(() =>
+      Promise.resolve().then(() => {
+        root.unmount();
+      }),
+    );
+    host.remove();
+  }
+});
+
+/*** Delivers one physical native scroll frame through the mounted GridView boundary. */
+async function dispatchNativeScrollAsync(
+  testID: string,
+  offset: number,
+  physicalOffsets: number[],
+): Promise<void> {
+  const handler = scrollHandlers.get(testID)?.onScroll;
+  if (!handler) throw new Error(`Missing native scroll handler for ${testID}.`);
+  physicalOffsets.push(offset);
+  await React.act(() =>
+    Promise.resolve().then(() => {
+      handler(createNativeScrollEvent(offset));
+    }),
+  );
+}
+
+/*** Delivers the native momentum-end signal after the final physical offset is observed. */
+async function dispatchNativeScrollEndAsync(
+  testID: string,
+  offset: number,
+  physicalOffsets: number[],
+): Promise<void> {
+  const handler = scrollHandlers.get(testID)?.onMomentumScrollEnd;
+  if (!handler) throw new Error(`Missing native scroll-end handler for ${testID}.`);
+  physicalOffsets.push(offset);
+  await React.act(() =>
+    Promise.resolve().then(() => {
+      handler(createNativeScrollEvent(offset));
+    }),
+  );
+}
+
+/*** Builds the native event shape GridView receives from either scroll axis. */
+function createNativeScrollEvent(offset: number): NativeScrollEvent {
+  return { nativeEvent: { contentOffset: { x: 0, y: offset } } };
+}