@ankhorage/zora 25.5.0 → 25.6.0

package/dist/types/grid-view.d.ts

@@ -1,4 +1,4 @@
-import type { GridRectItem, GridViewport } from '@ankhorage/grid-view';
+import type { GridRectItem, GridViewport, GridViewportConstraints, GridZoomLimits } from '@ankhorage/grid-view';
 import type React from 'react';
 import type { ZoraBaseProps } from './base';
 /** The renderer owns presentation only; world geometry comes from grid-view. */
@@ -8,6 +8,18 @@ export interface GridViewProps extends ZoraBaseProps {
     contentHeight: number;
     width: number;
     height: number;
+    /**
+     * Canonical controlled world viewport. Supplying this value makes `onViewportChange`
+     * report interaction proposals without mutating renderer-owned state.
+     */
+    viewport?: GridViewport;
+    /** Initial world position and independent axis scales for uncontrolled rendering. */
+    defaultViewport?: Partial<Pick<GridViewport, 'offsetX' | 'offsetY' | 'pixelsPerUnitX' | 'pixelsPerUnitY'>>;
+    /** Finite world bounds and optional overscroll for panning and focused-item reveal. */
+    viewportConstraints?: GridViewportConstraints;
+    /** Independent X/Y scale limits applied to focal-point zoom interactions. */
+    zoomLimits?: GridZoomLimits;
+    /** @deprecated Use `defaultViewport` for new code. */
     zoom?: number;
     overscanPixels?: number;
     /** Stable item identity that must be scrolled into view without duplicating viewport geometry. */
@@ -30,11 +42,16 @@ export interface TileGridProps extends ZoraBaseProps {
     tileSize?: number;
     gap?: number;
     zoom?: number;
+    viewport?: GridViewport;
+    defaultViewport?: Partial<Pick<GridViewport, 'offsetX' | 'offsetY' | 'pixelsPerUnitX' | 'pixelsPerUnitY'>>;
+    viewportConstraints?: GridViewportConstraints;
+    zoomLimits?: GridZoomLimits;
     overscanPixels?: number;
     focusedItemId?: string;
     revealPaddingPixels?: number;
     /** Reports the same measured column count used to position tiles. */
     onColumnsChange?: (columns: number) => void;
+    onViewportChange?: (viewport: GridViewport) => void;
     onVisibleItemIdsChange?: (ids: readonly string[]) => void;
     renderItem: (item: TileGridItem) => React.ReactNode;
 }

package/dist/types/grid-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grid-view.d.ts","sourceRoot":"","sources":["../../src/types/grid-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,gFAAgF;AAChF,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kGAAkG;IAClG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;IACpD,sBAAsB,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IAC1D,UAAU,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,KAAK,CAAC,SAAS,CAAC;CACrD;AAED,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,sBAAsB,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IAC1D,UAAU,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,KAAK,CAAC,SAAS,CAAC;CACrD"}
+{"version":3,"file":"grid-view.d.ts","sourceRoot":"","sources":["../../src/types/grid-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,uBAAuB,EACvB,cAAc,EACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,gFAAgF;AAChF,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,qFAAqF;IACrF,eAAe,CAAC,EAAE,OAAO,CACvB,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,SAAS,GAAG,gBAAgB,GAAG,gBAAgB,CAAC,CAChF,CAAC;IACF,uFAAuF;IACvF,mBAAmB,CAAC,EAAE,uBAAuB,CAAC;IAC9C,6EAA6E;IAC7E,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kGAAkG;IAClG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;IACpD,sBAAsB,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IAC1D,UAAU,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,KAAK,CAAC,SAAS,CAAC;CACrD;AAED,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CACvB,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,SAAS,GAAG,gBAAgB,GAAG,gBAAgB,CAAC,CAChF,CAAC;IACF,mBAAmB,CAAC,EAAE,uBAAuB,CAAC;IAC9C,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;IACpD,sBAAsB,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IAC1D,UAAU,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,KAAK,CAAC,SAAS,CAAC;CACrD"}

package/dist/types/grid-view.js.map

@@ -1 +1 @@
-{"version":3,"file":"grid-view.js","sourceRoot":"","sources":["../../src/types/grid-view.ts"],"names":[],"mappings":"","sourcesContent":["import type { GridRectItem, GridViewport } from '@ankhorage/grid-view';\nimport type React from 'react';\n\nimport type { ZoraBaseProps } from './base';\n\n/** The renderer owns presentation only; world geometry comes from grid-view. */\nexport interface GridViewProps extends ZoraBaseProps {\n  items: readonly GridRectItem[];\n  contentWidth: number;\n  contentHeight: number;\n  width: number;\n  height: number;\n  zoom?: number;\n  overscanPixels?: number;\n  /** Stable item identity that must be scrolled into view without duplicating viewport geometry. */\n  focusedItemId?: string;\n  /** Pixel inset retained around a revealed focused item. */\n  revealPaddingPixels?: number;\n  onViewportChange?: (viewport: GridViewport) => void;\n  onVisibleItemIdsChange?: (ids: readonly string[]) => void;\n  renderItem: (item: GridRectItem) => React.ReactNode;\n}\n\n/** An item needs a stable ID; visual positioning belongs to the TileGrid composition. */\nexport interface TileGridItem {\n  readonly id: string;\n}\n\n/** Reusable tile presentation based on the generic world/viewport engine. */\nexport interface TileGridProps extends ZoraBaseProps {\n  items: readonly TileGridItem[];\n  width?: number;\n  height?: number;\n  tileSize?: number;\n  gap?: number;\n  zoom?: number;\n  overscanPixels?: number;\n  focusedItemId?: string;\n  revealPaddingPixels?: number;\n  /** Reports the same measured column count used to position tiles. */\n  onColumnsChange?: (columns: number) => void;\n  onVisibleItemIdsChange?: (ids: readonly string[]) => void;\n  renderItem: (item: TileGridItem) => React.ReactNode;\n}\n"]}
+{"version":3,"file":"grid-view.js","sourceRoot":"","sources":["../../src/types/grid-view.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  GridRectItem,\n  GridViewport,\n  GridViewportConstraints,\n  GridZoomLimits,\n} from '@ankhorage/grid-view';\nimport type React from 'react';\n\nimport type { ZoraBaseProps } from './base';\n\n/** The renderer owns presentation only; world geometry comes from grid-view. */\nexport interface GridViewProps extends ZoraBaseProps {\n  items: readonly GridRectItem[];\n  contentWidth: number;\n  contentHeight: number;\n  width: number;\n  height: number;\n  /**\n   * Canonical controlled world viewport. Supplying this value makes `onViewportChange`\n   * report interaction proposals without mutating renderer-owned state.\n   */\n  viewport?: GridViewport;\n  /** Initial world position and independent axis scales for uncontrolled rendering. */\n  defaultViewport?: Partial<\n    Pick<GridViewport, 'offsetX' | 'offsetY' | 'pixelsPerUnitX' | 'pixelsPerUnitY'>\n  >;\n  /** Finite world bounds and optional overscroll for panning and focused-item reveal. */\n  viewportConstraints?: GridViewportConstraints;\n  /** Independent X/Y scale limits applied to focal-point zoom interactions. */\n  zoomLimits?: GridZoomLimits;\n  /** @deprecated Use `defaultViewport` for new code. */\n  zoom?: number;\n  overscanPixels?: number;\n  /** Stable item identity that must be scrolled into view without duplicating viewport geometry. */\n  focusedItemId?: string;\n  /** Pixel inset retained around a revealed focused item. */\n  revealPaddingPixels?: number;\n  onViewportChange?: (viewport: GridViewport) => void;\n  onVisibleItemIdsChange?: (ids: readonly string[]) => void;\n  renderItem: (item: GridRectItem) => React.ReactNode;\n}\n\n/** An item needs a stable ID; visual positioning belongs to the TileGrid composition. */\nexport interface TileGridItem {\n  readonly id: string;\n}\n\n/** Reusable tile presentation based on the generic world/viewport engine. */\nexport interface TileGridProps extends ZoraBaseProps {\n  items: readonly TileGridItem[];\n  width?: number;\n  height?: number;\n  tileSize?: number;\n  gap?: number;\n  zoom?: number;\n  viewport?: GridViewport;\n  defaultViewport?: Partial<\n    Pick<GridViewport, 'offsetX' | 'offsetY' | 'pixelsPerUnitX' | 'pixelsPerUnitY'>\n  >;\n  viewportConstraints?: GridViewportConstraints;\n  zoomLimits?: GridZoomLimits;\n  overscanPixels?: number;\n  focusedItemId?: string;\n  revealPaddingPixels?: number;\n  /** Reports the same measured column count used to position tiles. */\n  onColumnsChange?: (columns: number) => void;\n  onViewportChange?: (viewport: GridViewport) => void;\n  onVisibleItemIdsChange?: (ids: readonly string[]) => void;\n  renderItem: (item: TileGridItem) => React.ReactNode;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "25.5.0",
+  "version": "25.6.0",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {

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

@@ -0,0 +1,585 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type { GridRectItem, GridViewport } from '@ankhorage/grid-view';
+import { expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import type { GridView as GridViewComponent } from './GridView';
+import type { TileGrid as TileGridComponent } from './TileGrid';
+
+const webDistRoot = join(import.meta.dir, '../../../../../web-dist');
+const load = () => import(pathToFileURL(join(webDistRoot, 'components/grid-view/index.js')).href);
+const items: readonly GridRectItem[] = [
+  { height: 20, id: 'near', width: 20, x: 10, y: 10 },
+  { height: 20, id: 'far', width: 20, x: 300, y: 300 },
+  { height: 20, id: 'far-other', width: 20, x: 600, y: 600 },
+];
+const constraints = { world: { height: 1000, width: 1000, x: 0, y: 0 } };
+
+test('supports accessible pan and zoom controls and native scrolling without feedback proposals', async () => {
+  const { GridView } = (await load()) as { GridView: typeof GridViewComponent };
+  await withBrowserAsync(async (browserWindow, host) => {
+    const changes: GridViewport[] = [];
+    const root = createRoot(host);
+    try {
+      await interactAsync(() =>
+        root.render(
+          <GridView
+            contentHeight={1000}
+            contentWidth={1000}
+            height={100}
+            items={items}
+            onViewportChange={(viewport) => changes.push(viewport)}
+            renderItem={(item) => <span data-grid-item={item.id}>{item.id}</span>}
+            testID="grid"
+            viewportConstraints={constraints}
+            width={100}
+          />,
+        ),
+      );
+      const horizontal = host.querySelector<HTMLElement>('[data-testid="grid-horizontal-scroll"]');
+      const panRight = host.querySelector<HTMLButtonElement>('[aria-label="Pan right"]');
+      const zoomIn = host.querySelector<HTMLButtonElement>('[aria-label="Zoom in"]');
+      if (!horizontal || !panRight || !zoomIn) throw new Error('Missing interactive grid controls');
+
+      expect(host.querySelectorAll('[role="button"]')).toHaveLength(6);
+      horizontal.scrollLeft = 25;
+      await interactAsync(() =>
+        horizontal.dispatchEvent(new browserWindow.Event('scroll', { bubbles: true })),
+      );
+      expect(changes).toHaveLength(1);
+      expect(changes.at(-1)?.offsetX).toBe(25);
+
+      await interactAsync(() => panRight.click());
+      await interactAsync(() => zoomIn.click());
+      expect(changes).toHaveLength(3);
+    } finally {
+      await interactAsync(() => root.unmount());
+    }
+  });
+});
+
+test('deduplicates a controlled focus-reveal veto while allowing accepted movement and focus changes', async () => {
+  const { GridView } = (await load()) as { GridView: typeof GridViewComponent };
+  await withBrowserAsync(async (_browserWindow, host) => {
+    const controlledChanges: GridViewport[] = [];
+    const root = createRoot(host);
+    const controlledViewport = createViewport();
+    try {
+      await interactAsync(() =>
+        root.render(
+          <GridView
+            contentHeight={1000}
+            contentWidth={1000}
+            focusedItemId="far"
+            height={100}
+            items={[...items]}
+            onViewportChange={(viewport) => controlledChanges.push(viewport)}
+            renderItem={(item) => <span>{item.id}</span>}
+            viewport={controlledViewport}
+            viewportConstraints={constraints}
+            width={100}
+          />,
+        ),
+      );
+      await interactAsync(() =>
+        root.render(
+          <GridView
+            contentHeight={1000}
+            contentWidth={1000}
+            focusedItemId="far"
+            height={100}
+            items={[...items]}
+            onViewportChange={(viewport) => controlledChanges.push(viewport)}
+            renderItem={(item) => <span>{item.id}</span>}
+            viewport={{ ...controlledViewport }}
+            viewportConstraints={constraints}
+            width={100}
+          />,
+        ),
+      );
+      expect(controlledChanges).toHaveLength(1);
+
+      await interactAsync(() =>
+        root.render(
+          <GridView
+            contentHeight={1000}
+            contentWidth={1000}
+            focusedItemId="far"
+            height={100}
+            items={[...items]}
+            onViewportChange={(viewport) => controlledChanges.push(viewport)}
+            renderItem={(item) => <span>{item.id}</span>}
+            viewport={controlledChanges[0]}
+            viewportConstraints={constraints}
+            width={100}
+          />,
+        ),
+      );
+      expect(controlledChanges).toHaveLength(1);
+
+      await interactAsync(() =>
+        root.render(
+          <GridView
+            contentHeight={1000}
+            contentWidth={1000}
+            focusedItemId="far"
+            height={100}
+            items={[...items]}
+            onViewportChange={(viewport) => controlledChanges.push(viewport)}
+            renderItem={(item) => <span>{item.id}</span>}
+            viewport={controlledViewport}
+            viewportConstraints={constraints}
+            width={100}
+          />,
+        ),
+      );
+      expect(controlledChanges).toHaveLength(1);
+
+      await interactAsync(() =>
+        root.render(
+          <GridView
+            contentHeight={1000}
+            contentWidth={1000}
+            focusedItemId="far-other"
+            height={100}
+            items={[...items]}
+            onViewportChange={(viewport) => controlledChanges.push(viewport)}
+            renderItem={(item) => <span>{item.id}</span>}
+            viewport={controlledChanges.at(-1)}
+            viewportConstraints={constraints}
+            width={100}
+          />,
+        ),
+      );
+      expect(controlledChanges).toHaveLength(2);
+
+      const uncontrolledChanges: GridViewport[] = [];
+      await interactAsync(() =>
+        root.render(
+          <GridView
+            contentHeight={1000}
+            contentWidth={1000}
+            focusedItemId="far"
+            height={100}
+            items={items}
+            onViewportChange={(viewport) => uncontrolledChanges.push(viewport)}
+            renderItem={(item) => <span>{item.id}</span>}
+            viewportConstraints={constraints}
+            width={100}
+          />,
+        ),
+      );
+      expect(uncontrolledChanges).toHaveLength(1);
+    } finally {
+      await interactAsync(() => root.unmount());
+    }
+  });
+});
+
+test('maps centered bounds and overscroll to native positions and preserves a local pinch focal world point', async () => {
+  const { GridView } = (await load()) as { GridView: typeof GridViewComponent };
+  await withBrowserAsync(async (browserWindow, host) => {
+    const changes: GridViewport[] = [];
+    const root = createRoot(host);
+    try {
+      await interactAsync(() =>
+        root.render(
+          <GridView
+            contentHeight={50}
+            contentWidth={50}
+            height={600}
+            items={[{ height: 50, id: 'small', width: 50, x: 0, y: 0 }]}
+            renderItem={(item) => <span data-grid-item={item.id}>{item.id}</span>}
+            testID="grid"
+            viewportConstraints={{ world: { height: 50, width: 50, x: 0, y: 0 } }}
+            width={800}
+          />,
+        ),
+      );
+      expect(host.querySelector('[data-grid-item="small"]')?.parentElement?.style.left).toBe(
+        '375px',
+      );
+      expect(host.querySelector('[data-grid-item="small"]')?.parentElement?.style.top).toBe(
+        '275px',
+      );
+
+      await interactAsync(() =>
+        root.render(
+          <GridView
+            contentHeight={1000}
+            contentWidth={1000}
+            height={100}
+            items={items}
+            onViewportChange={(viewport) => changes.push(viewport)}
+            renderItem={(item) => <span data-grid-item={item.id}>{item.id}</span>}
+            testID="grid"
+            viewport={createViewport({ offsetX: -20, offsetY: -20 })}
+            viewportConstraints={{
+              overscrollX: 20,
+              overscrollY: 20,
+              world: { height: 1000, width: 1000, x: 0, y: 0 },
+            }}
+            width={100}
+          />,
+        ),
+      );
+      const horizontal = host.querySelector<HTMLElement>('[data-testid="grid-horizontal-scroll"]');
+      if (!horizontal) throw new Error('Missing horizontal scroll view');
+      expect(horizontal.firstElementChild?.firstElementChild?.getAttribute('style')).toContain(
+        'width: 1040px',
+      );
+
+      const grid = host.querySelector<HTMLElement>('[data-testid="grid"]');
+      if (!grid) throw new Error('Missing grid viewport');
+      Object.defineProperty(grid, 'getBoundingClientRect', {
+        value: () => ({ left: 200, top: 200 }),
+      });
+      Object.defineProperty(grid, 'measureInWindow', {
+        value: (callback: (x: number, y: number) => void) => callback(200, 200),
+      });
+      await dispatchTouchesAsync(browserWindow, grid, 'touchstart', [
+        { locationX: 8, locationY: 12, pageX: 220, pageY: 250 },
+        { locationX: 72, locationY: 88, pageX: 280, pageY: 250 },
+      ]);
+      await dispatchTouchesAsync(browserWindow, grid, 'touchmove', [
+        { locationX: 1, locationY: 99, pageX: 190, pageY: 250 },
+        { locationX: 99, locationY: 1, pageX: 310, pageY: 250 },
+      ]);
+      expect(changes.at(-1)?.pixelsPerUnitX).toBe(2);
+      expect(changes.at(-1)?.offsetX).toBe(5);
+    } finally {
+      await interactAsync(() => root.unmount());
+    }
+  });
+});
+
+test('uses default viewport scale when laying out TileGrid columns', async () => {
+  const { TileGrid } = (await load()) as { TileGrid: typeof TileGridComponent };
+  await withBrowserAsync(async (_browserWindow, host) => {
+    const root = createRoot(host);
+    try {
+      await interactAsync(() =>
+        root.render(
+          <TileGrid
+            defaultViewport={{ pixelsPerUnitX: 2, pixelsPerUnitY: 2 }}
+            height={300}
+            items={[{ id: 'a' }, { id: 'b' }, { id: 'c' }, { id: 'd' }]}
+            renderItem={(item) => <span data-tile={item.id}>{item.id}</span>}
+            tileSize={100}
+            width={500}
+          />,
+        ),
+      );
+      expect(host.querySelector('[data-tile="c"]')?.parentElement?.style.top).toBe('224px');
+    } finally {
+      await interactAsync(() => root.unmount());
+    }
+  });
+});
+
+test('keeps TileGrid placement synchronized with uncontrolled and controlled GridView zoom', async () => {
+  const { TileGrid } = (await load()) as { TileGrid: typeof TileGridComponent };
+  const tileItems = ['a', 'b', 'c', 'd', 'e'].map((id) => ({ id }));
+  await withBrowserAsync(async (_browserWindow, host) => {
+    const uncontrolledColumns: number[] = [];
+    const root = createRoot(host);
+    try {
+      await interactAsync(() =>
+        root.render(
+          <TileGrid
+            height={300}
+            items={tileItems}
+            onColumnsChange={(columns) => uncontrolledColumns.push(columns)}
+            renderItem={(item) => <span data-tile={item.id}>{item.id}</span>}
+            tileSize={100}
+            width={500}
+          />,
+        ),
+      );
+      const zoomIn = host.querySelector<HTMLButtonElement>('[aria-label="Zoom in"]');
+      if (!zoomIn) throw new Error('Missing uncontrolled TileGrid zoom control');
+      await interactAsync(() => zoomIn.click());
+      expect(uncontrolledColumns).toEqual([4, 3]);
+      expect(host.querySelector('[data-tile="d"]')?.parentElement?.style.top).not.toBe(
+        host.querySelector('[data-tile="a"]')?.parentElement?.style.top,
+      );
+
+      const controlledChanges: GridViewport[] = [];
+      const controlledViewport = createViewport({ height: 300, width: 500 });
+      await interactAsync(() =>
+        root.render(
+          <TileGrid
+            height={300}
+            items={tileItems}
+            onViewportChange={(nextViewport) => controlledChanges.push(nextViewport)}
+            renderItem={(item) => <span data-tile={item.id}>{item.id}</span>}
+            tileSize={100}
+            viewport={controlledViewport}
+            width={500}
+          />,
+        ),
+      );
+      const controlledZoomIn = host.querySelector<HTMLButtonElement>('[aria-label="Zoom in"]');
+      if (!controlledZoomIn) throw new Error('Missing controlled TileGrid zoom control');
+      await interactAsync(() => controlledZoomIn.click());
+      expect(controlledChanges).toHaveLength(1);
+      await interactAsync(() =>
+        root.render(
+          <TileGrid
+            height={300}
+            items={tileItems}
+            onViewportChange={(nextViewport) => controlledChanges.push(nextViewport)}
+            renderItem={(item) => <span data-tile={item.id}>{item.id}</span>}
+            tileSize={100}
+            viewport={controlledChanges[0]}
+            width={500}
+          />,
+        ),
+      );
+      expect(host.querySelector('[data-tile="d"]')?.parentElement?.style.top).not.toBe(
+        host.querySelector('[data-tile="a"]')?.parentElement?.style.top,
+      );
+    } finally {
+      await interactAsync(() => root.unmount());
+    }
+  });
+});
+
+test('waits for the newest asynchronous viewport measurement before continuous pinch zoom', async () => {
+  const { GridView } = (await load()) as { GridView: typeof GridViewComponent };
+  await withBrowserAsync(async (browserWindow, host) => {
+    const changes: GridViewport[] = [];
+    const measurements: ((x: number, y: number) => void)[] = [];
+    const root = createRoot(host);
+    try {
+      await interactAsync(() =>
+        root.render(
+          <GridView
+            contentHeight={1000}
+            contentWidth={1000}
+            height={100}
+            items={items}
+            onViewportChange={(viewport) => changes.push(viewport)}
+            renderItem={(item) => <span>{item.id}</span>}
+            testID="grid"
+            viewportConstraints={constraints}
+            width={100}
+          />,
+        ),
+      );
+      const grid = host.querySelector<HTMLElement>('[data-testid="grid"]');
+      if (!grid) throw new Error('Missing grid viewport');
+      Object.defineProperty(grid, 'measureInWindow', {
+        value: (callback: (x: number, y: number) => void) => measurements.push(callback),
+      });
+      await dispatchTouchesAsync(browserWindow, grid, 'touchstart', [
+        { pageX: 210, pageY: 170 },
+        { pageX: 290, pageY: 170 },
+      ]);
+      await dispatchTouchesAsync(browserWindow, grid, 'touchmove', [
+        { pageX: 200, pageY: 170 },
+        { pageX: 300, pageY: 170 },
+      ]);
+      await interactAsync(() => measurements[0]?.(20, 20));
+      await interactAsync(() => measurements[1]?.(200, 150));
+      await dispatchTouchesAsync(browserWindow, grid, 'touchmove', [
+        { pageX: 190, pageY: 170 },
+        { pageX: 310, pageY: 170 },
+      ]);
+      await interactAsync(() => measurements[2]?.(200, 150));
+      expect(changes).toHaveLength(1);
+      expect(changes[0]?.pixelsPerUnitX).toBe(1.2);
+      expect(changes[0]?.offsetX).toBeCloseTo(8.333333333333343);
+      expect(changes[0]?.offsetY).toBeCloseTo(3.333333333333332);
+    } finally {
+      await interactAsync(() => root.unmount());
+    }
+  });
+});
+
+test('invalidates delayed pinch measurements after touch lifecycle completion', async () => {
+  const { GridView } = (await load()) as { GridView: typeof GridViewComponent };
+  await withBrowserAsync(async (browserWindow, host) => {
+    const changes: GridViewport[] = [];
+    const measurements: ((x: number, y: number) => void)[] = [];
+    const root = createRoot(host);
+    try {
+      await interactAsync(() =>
+        root.render(
+          <GridView
+            contentHeight={1000}
+            contentWidth={1000}
+            height={100}
+            items={items}
+            onViewportChange={(viewport) => changes.push(viewport)}
+            renderItem={(item) => <span>{item.id}</span>}
+            testID="grid"
+            viewportConstraints={constraints}
+            width={100}
+          />,
+        ),
+      );
+      const grid = host.querySelector<HTMLElement>('[data-testid="grid"]');
+      const horizontal = host.querySelector<HTMLElement>('[data-testid="grid-horizontal-scroll"]');
+      const vertical = host.querySelector<HTMLElement>('[data-testid="grid-vertical-scroll"]');
+      if (!grid || !horizontal || !vertical) throw new Error('Missing grid scroll surfaces');
+      Object.defineProperty(grid, 'measureInWindow', {
+        value: (callback: (x: number, y: number) => void) => measurements.push(callback),
+      });
+
+      await dispatchTouchesAsync(browserWindow, grid, 'touchstart', [
+        { pageX: 10, pageY: 50 },
+        { pageX: 90, pageY: 50 },
+      ]);
+      await dispatchTouchesAsync(browserWindow, grid, 'touchend', []);
+      await interactAsync(() => measurements[0]?.(200, 150));
+      expect(changes).toHaveLength(0);
+      expect(horizontal.style.overflowX).not.toBe('hidden');
+      expect(vertical.style.overflowY).not.toBe('hidden');
+
+      horizontal.scrollLeft = 20;
+      await interactAsync(() =>
+        horizontal.dispatchEvent(new browserWindow.Event('scroll', { bubbles: true })),
+      );
+      expect(changes).toHaveLength(1);
+
+      await dispatchTouchesAsync(browserWindow, grid, 'touchstart', [
+        { pageX: 10, pageY: 50 },
+        { pageX: 90, pageY: 50 },
+      ]);
+      await dispatchTouchesAsync(browserWindow, grid, 'touchcancel', []);
+      await interactAsync(() => measurements[1]?.(200, 150));
+      expect(changes).toHaveLength(1);
+      expect(horizontal.style.overflowX).not.toBe('hidden');
+      expect(vertical.style.overflowY).not.toBe('hidden');
+
+      await dispatchTouchesAsync(browserWindow, grid, 'touchstart', [
+        { pageX: 10, pageY: 50 },
+        { pageX: 90, pageY: 50 },
+      ]);
+      await dispatchTouchesAsync(browserWindow, grid, 'touchend', []);
+      await dispatchTouchesAsync(browserWindow, grid, 'touchstart', [
+        { pageX: 10, pageY: 50 },
+        { pageX: 90, pageY: 50 },
+      ]);
+      await interactAsync(() => measurements[2]?.(200, 150));
+      await dispatchTouchesAsync(browserWindow, grid, 'touchend', []);
+      await interactAsync(() => measurements[3]?.(200, 150));
+      expect(changes).toHaveLength(1);
+      expect(horizontal.style.overflowX).not.toBe('hidden');
+      expect(vertical.style.overflowY).not.toBe('hidden');
+    } finally {
+      await interactAsync(() => root.unmount());
+    }
+  });
+});
+
+test('invalidates a pending pinch update when GridView unmounts', async () => {
+  const { GridView } = (await load()) as { GridView: typeof GridViewComponent };
+  await withBrowserAsync(async (browserWindow, host) => {
+    const changes: GridViewport[] = [];
+    const measurements: ((x: number, y: number) => void)[] = [];
+    const root = createRoot(host);
+    await interactAsync(() =>
+      root.render(
+        <GridView
+          contentHeight={1000}
+          contentWidth={1000}
+          height={100}
+          items={items}
+          onViewportChange={(viewport) => changes.push(viewport)}
+          renderItem={(item) => <span>{item.id}</span>}
+          testID="grid"
+          viewportConstraints={constraints}
+          width={100}
+        />,
+      ),
+    );
+    const grid = host.querySelector<HTMLElement>('[data-testid="grid"]');
+    if (!grid) throw new Error('Missing grid viewport');
+    Object.defineProperty(grid, 'measureInWindow', {
+      value: (callback: (x: number, y: number) => void) => measurements.push(callback),
+    });
+
+    await dispatchTouchesAsync(browserWindow, grid, 'touchstart', [
+      { pageX: 10, pageY: 50 },
+      { pageX: 90, pageY: 50 },
+    ]);
+    await interactAsync(() => measurements[0]?.(0, 0));
+    await dispatchTouchesAsync(browserWindow, grid, 'touchmove', [
+      { pageX: 0, pageY: 50 },
+      { pageX: 100, pageY: 50 },
+    ]);
+    await interactAsync(() => root.unmount());
+    await interactAsync(() => measurements[1]?.(0, 0));
+    expect(changes).toHaveLength(0);
+  });
+});
+
+/*** Provides a stable controlled viewport for component interaction tests. */
+function createViewport(overrides: Partial<GridViewport> = {}): GridViewport {
+  return {
+    height: 100,
+    offsetX: 0,
+    offsetY: 0,
+    pixelsPerUnitX: 1,
+    pixelsPerUnitY: 1,
+    width: 100,
+    ...overrides,
+  };
+}
+
+/*** Executes a React interaction after the renderer has a chance to flush effects. */
+function interactAsync(action: () => void): Promise<void> {
+  return act(() => Promise.resolve().then(action));
+}
+
+/*** Mounts an isolated browser surface and restores global DOM bindings after a test. */
+async function withBrowserAsync(
+  test: (browserWindow: Window, host: HTMLElement) => Promise<void>,
+): Promise<void> {
+  const browserWindow = new Window();
+  const keys = ['window', 'document', 'Node', 'navigator', 'IS_REACT_ACT_ENVIRONMENT'] as const;
+  const previous = keys.map(
+    (key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)] as const,
+  );
+  Object.assign(globalThis, {
+    IS_REACT_ACT_ENVIRONMENT: true,
+    window: browserWindow,
+    document: browserWindow.document,
+    Node: browserWindow.Node,
+    navigator: browserWindow.navigator,
+  });
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  try {
+    await test(browserWindow, host);
+  } finally {
+    browserWindow.close();
+    for (const [key, descriptor] of previous) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  }
+}
+
+/*** Dispatches touches whose target-local values may differ while page coordinates stay global. */
+function dispatchTouchesAsync(
+  browserWindow: Window,
+  target: HTMLElement,
+  type: 'touchcancel' | 'touchend' | 'touchstart' | 'touchmove',
+  touches: readonly Readonly<{
+    locationX?: number;
+    locationY?: number;
+    pageX: number;
+    pageY: number;
+  }>[],
+): Promise<void> {
+  const event = new browserWindow.Event(type, { bubbles: true });
+  Object.defineProperty(event, 'touches', { value: touches });
+  return interactAsync(() => target.dispatchEvent(event));
+}