@ankhorage/zora 25.6.2 → 25.8.0

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

@@ -0,0 +1,143 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import type { GridInteractions as GridInteractionsComponent } from './GridInteractions';
+
+const webDistRoot = join(import.meta.dir, '../../../../../web-dist');
+
+/*** Loads the independently bundled RNW interaction adapter through its public artifact path. */
+function loadGridInteractions() {
+  return import(
+    pathToFileURL(join(webDistRoot, 'components/grid-interactions/index.js')).href
+  ) as Promise<{ GridInteractions: typeof GridInteractionsComponent }>;
+}
+
+test('keeps a mounted RNW keyboard boundary current across parent rerenders', 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 firstIntents: unknown[] = [];
+  const secondIntents: unknown[] = [];
+  const render = (
+    onIntent: (intent: unknown) => void,
+    interactionPolicy?: 'passive',
+    resizeHandle?: 'bottom-right',
+  ) => (
+    <GridInteractions
+      interactionPolicy={interactionPolicy}
+      items={[{ height: 2, id: 'a', width: 3, x: 1, y: 1 }]}
+      onIntent={onIntent}
+      selectedIds={['a']}
+      testID="grid-interactions"
+      resizeHandle={resizeHandle}
+      viewport={{
+        height: 100,
+        offsetX: 0,
+        offsetY: 0,
+        pixelsPerUnitX: 2,
+        pixelsPerUnitY: 4,
+        width: 100,
+      }}
+    >
+      <span>nested target</span>
+    </GridInteractions>
+  );
+
+  try {
+    await renderGridInteractions(
+      root,
+      render((intent) => firstIntents.push(intent)),
+    );
+    await renderGridInteractions(
+      root,
+      render((intent) => secondIntents.push(intent)),
+    );
+
+    const keyboard = host.querySelector<HTMLElement>(
+      '[aria-label="Grid interaction keyboard controls"]',
+    );
+    if (!keyboard) throw new Error('Missing keyboard interaction proxy');
+    const resize = new browser.KeyboardEvent('keydown', {
+      altKey: true,
+      bubbles: true,
+      cancelable: true,
+      key: 'ArrowRight',
+    });
+    await dispatch(keyboard, resize);
+    const acceleratedMove = new browser.KeyboardEvent('keydown', {
+      bubbles: true,
+      cancelable: true,
+      key: 'ArrowDown',
+      shiftKey: true,
+    });
+    await dispatch(keyboard, acceleratedMove);
+    await renderGridInteractions(
+      root,
+      render((intent) => secondIntents.push(intent), 'passive'),
+    );
+    const passiveKey = new browser.KeyboardEvent('keydown', { bubbles: true, key: 'ArrowLeft' });
+    await dispatch(keyboard, passiveKey);
+    expect(keyboard.getAttribute('tabindex')).toBe('-1');
+
+    expect(firstIntents).toEqual([]);
+    expect(secondIntents).toEqual([
+      { type: 'resize', itemIds: ['a'], rects: [{ height: 2, id: 'a', width: 4, x: 1, y: 1 }] },
+      { type: 'move', itemIds: ['a'], rects: [{ height: 2, id: 'a', width: 3, x: 1, y: 11 }] },
+    ]);
+    expect(resize.defaultPrevented).toBe(true);
+    expect(acceleratedMove.defaultPrevented).toBe(true);
+    expect(passiveKey.defaultPrevented).toBe(false);
+  } finally {
+    await act(() => Promise.resolve().then(() => root.unmount()));
+    host.remove();
+    browser.close();
+    restore();
+  }
+});
+
+/*** Installs the DOM globals that the independently bundled RNW adapter requires. */
+function installBrowserGlobals(browser: Window): () => void {
+  const keys = [
+    'window',
+    'document',
+    'Node',
+    'navigator',
+    'ShadowRoot',
+    '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,
+    Node: browser.Node,
+    ShadowRoot: browser.ShadowRoot,
+    document: browser.document,
+    navigator: browser.navigator,
+    window: browser,
+  });
+  return () => {
+    for (const [key, descriptor] of previous) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  };
+}
+
+/*** Flushes one mounted RNW render before the next synthetic input event. */
+function renderGridInteractions(root: ReturnType<typeof createRoot>, component: React.ReactNode) {
+  return act(() => Promise.resolve().then(() => root.render(component)));
+}
+
+/*** Dispatches one browser input event through React's RNW adapter boundary. */
+function dispatch(target: HTMLElement, event: Event) {
+  return act(() => Promise.resolve().then(() => target.dispatchEvent(event)));
+}

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

@@ -0,0 +1,79 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import type {
+  GridInteractionsController,
+  GridInteractionsProps,
+} from '../../../../types/grid-interactions';
+import { createGridInteractionsController } from '../../application/createGridInteractionsController';
+import { createGridInteractionsPointerQueue } from './createGridInteractionsPointerQueue';
+import { GridInteractionsKeyboardProxy } from './GridInteractionsKeyboardProxy';
+import { resolveGridInteractionPointer } from './resolveGridInteractionPointer';
+
+/*** Adapts native responder and keyboard events to the controlled grid interaction boundary. */
+export function GridInteractions({
+  children,
+  interactionPolicy,
+  resizeHandle,
+  testID,
+  ...props
+}: GridInteractionsProps) {
+  const controllerProps = React.useMemo(
+    () => ({ ...props, interactionPolicy }),
+    [interactionPolicy, props],
+  );
+  const [controller] = React.useState<GridInteractionsController>(() =>
+    createGridInteractionsController(controllerProps),
+  );
+  const surfaceRef = React.useRef<View>(null);
+  const [pointerQueue] = React.useState(() => createGridInteractionsPointerQueue());
+  React.useLayoutEffect(() => controller.update(controllerProps), [controller, controllerProps]);
+  React.useLayoutEffect(() => {
+    pointerQueue.activate();
+    return () => {
+      pointerQueue.dispose();
+      controller.cancel();
+    };
+  }, [controller, pointerQueue]);
+  const withPointer = (
+    event: Parameters<typeof resolveGridInteractionPointer>[0],
+    handlePointer: (pointer: ReturnType<typeof resolveGridInteractionPointer>) => void,
+  ) => {
+    const surface = surfaceRef.current;
+    if (!surface) return;
+    const eventSnapshot = { nativeEvent: { ...event.nativeEvent } };
+    pointerQueue.enqueue(surface, (origin) =>
+      handlePointer(resolveGridInteractionPointer(eventSnapshot, origin)),
+    );
+  };
+  const enabled = interactionPolicy !== 'passive';
+
+  return (
+    <View
+      accessible
+      accessibilityLabel="Grid interaction surface"
+      accessibilityRole="adjustable"
+      ref={surfaceRef}
+      testID={testID}
+      onResponderGrant={(event) =>
+        withPointer(event, (pointer) => controller.begin(pointer, resizeHandle))
+      }
+      onResponderMove={(event) => withPointer(event, controller.move)}
+      onResponderRelease={(event) => withPointer(event, controller.end)}
+      onResponderTerminate={() => {
+        pointerQueue.cancel();
+        controller.cancel();
+      }}
+      onStartShouldSetResponder={() => enabled}
+    >
+      <GridInteractionsKeyboardProxy
+        enabled={enabled}
+        onKeyDown={(key, keyPointer) => {
+          return controller.keyDown(key, keyPointer);
+        }}
+      >
+        {children}
+      </GridInteractionsKeyboardProxy>
+    </View>
+  );
+}

package/src/features/grid-interactions/adapters/inbound/GridInteractionsKeyboardProxy.native.tsx

@@ -0,0 +1,14 @@
+import type React from 'react';
+
+import type { GridInteractionPointer } from '../../../../types/grid-interactions';
+
+/*** Leaves native accessibility focus untouched where browser keyboard events are unavailable. */
+export function GridInteractionsKeyboardProxy({ children }: GridInteractionsKeyboardProxyProps) {
+  return <>{children}</>;
+}
+
+interface GridInteractionsKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly enabled: boolean;
+  readonly onKeyDown: (key: string, pointer: GridInteractionPointer) => boolean;
+}

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

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

package/src/features/grid-interactions/adapters/inbound/GridInteractionsKeyboardProxy.web.tsx

@@ -0,0 +1,41 @@
+import type React from 'react';
+
+import type { GridInteractionPointer } from '../../../../types/grid-interactions';
+
+/*** Adapts web keyboard movement and resize commands without changing native responder behavior. */
+export function GridInteractionsKeyboardProxy({
+  children,
+  enabled,
+  onKeyDown,
+}: GridInteractionsKeyboardProxyProps) {
+  return (
+    <div
+      aria-label="Grid interaction keyboard controls"
+      onKeyDown={(event) => {
+        if (!enabled) return;
+        if (
+          onKeyDown(event.key, {
+            altKey: event.altKey,
+            ctrlKey: event.ctrlKey,
+            metaKey: event.metaKey,
+            shiftKey: event.shiftKey,
+            x: 0,
+            y: 0,
+          })
+        ) {
+          event.preventDefault();
+        }
+      }}
+      style={{ display: 'contents' }}
+      tabIndex={enabled ? 0 : -1}
+    >
+      {children}
+    </div>
+  );
+}
+
+interface GridInteractionsKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly enabled: boolean;
+  readonly onKeyDown: (key: string, pointer: GridInteractionPointer) => boolean;
+}

package/src/features/grid-interactions/adapters/inbound/createGridInteractionsPointerQueue.test.ts

@@ -0,0 +1,98 @@
+import { expect, test } from 'bun:test';
+
+import { createGridInteractionsPointerQueue } from './createGridInteractionsPointerQueue';
+import { resolveGridInteractionPointer } from './resolveGridInteractionPointer';
+
+test('invalidates pending native responder callbacks after cancellation', () => {
+  const callbacks: ((x: number, y: number) => void)[] = [];
+  const origins: unknown[] = [];
+  const queue = createGridInteractionsPointerQueue();
+  const surface = {
+    measureInWindow: (callback: (x: number, y: number) => void) => callbacks.push(callback),
+  };
+
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  queue.cancel();
+  callbacks[0]?.(10, 20);
+
+  expect(origins).toEqual([]);
+  expect(callbacks).toHaveLength(1);
+});
+
+test('invalidates an active native responder measurement across unmount and remount', () => {
+  const callbacks: ((x: number, y: number) => void)[] = [];
+  const origins: unknown[] = [];
+  const queue = createGridInteractionsPointerQueue();
+  const surface = {
+    measureInWindow: (callback: (x: number, y: number) => void) => callbacks.push(callback),
+  };
+
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  queue.dispose();
+  queue.activate();
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  callbacks[1]?.(30, 40);
+  callbacks[0]?.(10, 20);
+
+  expect(origins).toEqual([{ x: 30, y: 40 }]);
+});
+
+test('retires a canceled measurement slot without waiting for its callback', () => {
+  const callbacks: ((x: number, y: number) => void)[] = [];
+  const origins: unknown[] = [];
+  const queue = createGridInteractionsPointerQueue();
+  const surface = {
+    measureInWindow: (callback: (x: number, y: number) => void) => callbacks.push(callback),
+  };
+
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  queue.cancel();
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  callbacks[1]?.(30, 40);
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  callbacks[0]?.(10, 20);
+  callbacks[2]?.(50, 60);
+
+  expect(origins).toEqual([
+    { x: 30, y: 40 },
+    { x: 50, y: 60 },
+  ]);
+});
+
+test('uses the latest RNW surface origin for each serialized pointer', () => {
+  const origins = [
+    { left: 10, top: 20 },
+    { left: 15, top: 25 },
+  ];
+  const resolvedOrigins: unknown[] = [];
+  const queue = createGridInteractionsPointerQueue();
+  const surface = {
+    getBoundingClientRect: () => origins.shift(),
+  };
+
+  queue.enqueue(surface, (origin) => resolvedOrigins.push(origin));
+  queue.enqueue(surface, (origin) => resolvedOrigins.push(origin));
+
+  expect(resolvedOrigins).toEqual([
+    { x: 10, y: 20 },
+    { x: 15, y: 25 },
+  ]);
+});
+
+test('preserves native responder-local coordinates while measuring asynchronously', () => {
+  const callbacks: ((x: number, y: number) => void)[] = [];
+  const pointers: unknown[] = [];
+  const queue = createGridInteractionsPointerQueue();
+  const surface = {
+    measureInWindow: (callback: (x: number, y: number) => void) => callbacks.push(callback),
+  };
+  const event = { nativeEvent: { locationX: 7, locationY: 9 } };
+
+  queue.enqueue(surface, (origin) => {
+    pointers.push(resolveGridInteractionPointer(event, origin));
+  });
+  callbacks[0]?.(10, 20);
+
+  expect(pointers).toEqual([{ x: 7, y: 9 }]);
+});

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

@@ -0,0 +1,94 @@
+/*** Serializes native responder measurements and invalidates work from canceled interaction lifecycles. */
+export function createGridInteractionsPointerQueue() {
+  let active = true;
+  let generation = 0;
+  let measuring = false;
+  let measurementId = 0;
+  let activeMeasurementId: number | undefined;
+  let pending: readonly GridInteractionPointerWork[] = [];
+
+  const processNext = () => {
+    if (measuring) return;
+    const pointerWork = pending.at(0);
+    if (pointerWork === undefined) return;
+    pending = pending.slice(1);
+    measuring = true;
+    const currentMeasurementId = ++measurementId;
+    activeMeasurementId = currentMeasurementId;
+    let settled = false;
+    measureSurfaceOrigin(pointerWork.surface, (origin) => {
+      if (settled) return;
+      settled = true;
+      if (activeMeasurementId !== currentMeasurementId) return;
+      try {
+        if (active && pointerWork.generation === generation) {
+          pointerWork.handleOrigin(origin);
+        }
+      } finally {
+        activeMeasurementId = undefined;
+        measuring = false;
+        processNext();
+      }
+    });
+  };
+
+  return {
+    activate: () => {
+      active = true;
+    },
+    enqueue: (
+      surface: GridInteractionSurface,
+      handleOrigin: (origin: GridInteractionSurfaceOrigin) => void,
+    ) => {
+      if (!active) return;
+      pending = [...pending, { generation, handleOrigin, surface }];
+      processNext();
+    },
+    cancel: () => {
+      generation += 1;
+      pending = [];
+      activeMeasurementId = undefined;
+      measuring = false;
+    },
+    dispose: () => {
+      active = false;
+      generation += 1;
+      pending = [];
+      activeMeasurementId = undefined;
+      measuring = false;
+    },
+  };
+}
+
+interface GridInteractionPointerWork {
+  readonly generation: number;
+  readonly handleOrigin: (origin: GridInteractionSurfaceOrigin) => void;
+  readonly surface: GridInteractionSurface;
+}
+
+interface GridInteractionSurface {
+  readonly getBoundingClientRect?: () => Pick<DOMRect, 'left' | 'top'>;
+  readonly measureInWindow?: (callback: (x: number, y: number) => void) => void;
+}
+
+interface GridInteractionSurfaceOrigin {
+  readonly x: number;
+  readonly y: number;
+}
+
+/*** Resolves the current surface origin through RNW DOM geometry or native asynchronous measurement. */
+function measureSurfaceOrigin(
+  surface: GridInteractionSurface,
+  onOrigin: (origin: GridInteractionSurfaceOrigin) => void,
+) {
+  const rect = surface.getBoundingClientRect?.();
+  if (rect) {
+    onOrigin({ x: rect.left, y: rect.top });
+    return;
+  }
+  if (surface.measureInWindow !== undefined) {
+    surface.measureInWindow((x, y) => onOrigin({ x, y }));
+    return;
+  }
+  onOrigin({ x: 0, y: 0 });
+}

package/src/features/grid-interactions/adapters/inbound/resolveGridInteractionPointer.test.ts

@@ -0,0 +1,33 @@
+import { expect, test } from 'bun:test';
+
+import { resolveGridInteractionPointer } from './resolveGridInteractionPointer';
+
+test('normalizes nested responder coordinates against the interaction surface origin', () => {
+  expect(
+    resolveGridInteractionPointer(
+      {
+        nativeEvent: {
+          locationX: 4,
+          locationY: 6,
+          pageX: 124,
+          pageY: 86,
+        },
+      },
+      { x: 120, y: 80 },
+    ),
+  ).toEqual({ x: 4, y: 6 });
+});
+
+test('uses responder-local coordinates when page coordinates are unavailable on native', () => {
+  expect(
+    resolveGridInteractionPointer(
+      {
+        nativeEvent: {
+          locationX: 4,
+          locationY: 6,
+        },
+      },
+      { x: 120, y: 80 },
+    ),
+  ).toEqual({ x: 4, y: 6 });
+});

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

@@ -0,0 +1,45 @@
+import type { GridInteractionPointer } from '../../../../types/grid-interactions';
+
+/*** Converts a responder event into coordinates local to the interaction surface. */
+export function resolveGridInteractionPointer(
+  event: GridInteractionNativePointerEvent,
+  surfaceOrigin: GridInteractionSurfaceOrigin,
+): GridInteractionPointer {
+  const { nativeEvent } = event;
+  const { pageX, pageY } = nativeEvent;
+  const x =
+    typeof pageX === 'number' && Number.isFinite(pageX)
+      ? pageX - surfaceOrigin.x
+      : nativeEvent.locationX;
+  const y =
+    typeof pageY === 'number' && Number.isFinite(pageY)
+      ? pageY - surfaceOrigin.y
+      : nativeEvent.locationY;
+
+  return {
+    altKey: nativeEvent.altKey,
+    ctrlKey: nativeEvent.ctrlKey,
+    metaKey: nativeEvent.metaKey,
+    shiftKey: nativeEvent.shiftKey,
+    x,
+    y,
+  };
+}
+
+interface GridInteractionNativePointerEvent {
+  readonly nativeEvent: {
+    readonly altKey?: boolean;
+    readonly ctrlKey?: boolean;
+    readonly locationX: number;
+    readonly locationY: number;
+    readonly metaKey?: boolean;
+    readonly pageX?: number;
+    readonly pageY?: number;
+    readonly shiftKey?: boolean;
+  };
+}
+
+interface GridInteractionSurfaceOrigin {
+  readonly x: number;
+  readonly y: number;
+}

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

@@ -0,0 +1,115 @@
+import { describe, expect, test } from 'bun:test';
+
+import { createGridInteractionsController } from './createGridInteractionsController';
+
+const viewport = {
+  width: 100,
+  height: 100,
+  offsetX: 0,
+  offsetY: 0,
+  pixelsPerUnitX: 2,
+  pixelsPerUnitY: 4,
+};
+const items = [
+  { id: 'a', x: 1, y: 1, width: 3, height: 2 },
+  { id: 'locked', x: 10, y: 1, width: 2, height: 2, locked: true },
+];
+
+describe('createGridInteractionsController', () => {
+  test('maps independent viewport scales to a move preview without mutating items', () => {
+    const intents: unknown[] = [];
+    const controller = createGridInteractionsController({
+      viewport,
+      items,
+      onIntent: (intent) => intents.push(intent),
+    });
+    controller.begin({ x: 3, y: 5 });
+    controller.move({ x: 7, y: 13 });
+    expect(intents).toEqual([
+      { type: 'move', itemIds: ['a'], rects: [{ id: 'a', x: 3, y: 3, width: 3, height: 2 }] },
+    ]);
+    expect(items[0]).toEqual({ id: 'a', x: 1, y: 1, width: 3, height: 2 });
+  });
+
+  test('normalizes negative marquee drags and protects locked items', () => {
+    const intents: unknown[] = [];
+    const controller = createGridInteractionsController({
+      viewport,
+      items,
+      marqueeMode: 'intersect',
+      onIntent: (intent) => intents.push(intent),
+    });
+    controller.begin({ x: 24, y: 12 });
+    controller.end({ x: 0, y: 0 });
+    expect(intents).toEqual([
+      { type: 'marquee', itemIds: ['a'], marquee: { x: 0, y: 0, width: 12, height: 3 } },
+    ]);
+  });
+
+  test('keeps an active gesture while updating controlled props after a parent rerender', () => {
+    const initialIntents: unknown[] = [];
+    const rerenderedIntents: unknown[] = [];
+    const controller = createGridInteractionsController({
+      viewport,
+      items,
+      onIntent: (intent) => initialIntents.push(intent),
+    });
+
+    controller.begin({ x: 3, y: 5 });
+    controller.update({
+      viewport,
+      items,
+      onIntent: (intent) => rerenderedIntents.push(intent),
+    });
+    controller.end({ x: 7, y: 13 });
+
+    expect(initialIntents).toEqual([]);
+    expect(rerenderedIntents).toEqual([
+      { type: 'move', itemIds: ['a'], rects: [{ id: 'a', x: 3, y: 3, width: 3, height: 2 }] },
+    ]);
+  });
+
+  test('emits keyboard resize and accelerated movement only while interaction is enabled', () => {
+    const intents: unknown[] = [];
+    const controller = createGridInteractionsController({
+      viewport,
+      items,
+      onIntent: (intent) => intents.push(intent),
+      selectedIds: ['a'],
+    });
+
+    expect(controller.keyDown('ArrowRight', { x: 0, y: 0, altKey: true })).toBe(true);
+    expect(controller.keyDown('ArrowDown', { x: 0, y: 0, shiftKey: true })).toBe(true);
+    controller.update({
+      interactionPolicy: 'passive',
+      viewport,
+      items,
+      onIntent: (intent) => intents.push(intent),
+      selectedIds: ['a'],
+    });
+    expect(controller.keyDown('ArrowLeft', { x: 0, y: 0 })).toBe(false);
+    controller.begin({ x: 3, y: 5 });
+    controller.end({ x: 7, y: 13 });
+
+    expect(intents).toEqual([
+      { type: 'resize', itemIds: ['a'], rects: [{ id: 'a', x: 1, y: 1, width: 4, height: 2 }] },
+      { type: 'move', itemIds: ['a'], rects: [{ id: 'a', x: 1, y: 11, width: 3, height: 2 }] },
+    ]);
+  });
+
+  test('emits handle-driven resize intents for a pointer gesture', () => {
+    const intents: unknown[] = [];
+    const controller = createGridInteractionsController({
+      viewport,
+      items,
+      onIntent: (intent) => intents.push(intent),
+    });
+
+    controller.begin({ x: 3, y: 5 }, 'bottom-right');
+    controller.end({ x: 7, y: 13 });
+
+    expect(intents).toEqual([
+      { type: 'resize', itemIds: ['a'], rects: [{ id: 'a', x: 1, y: 1, width: 5, height: 4 }] },
+    ]);
+  });
+});