@ankhorage/zora 25.7.0 → 25.8.1

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,229 @@
+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 }] },
+    ]);
+  });
+
+  test('does not compound controlled move previews or reapply the release endpoint', () => {
+    const intents: unknown[] = [];
+    const initialItems = [{ id: 'a', x: 40, y: 40, width: 20, height: 20 }];
+    const controller = createGridInteractionsController({
+      viewport,
+      items: initialItems,
+      onIntent: (intent) => intents.push(intent),
+    });
+
+    controller.begin({ x: 80, y: 160 });
+    controller.move({ x: 100, y: 160 });
+    controller.update({
+      viewport,
+      items: [{ id: 'a', x: 50, y: 40, width: 20, height: 20 }],
+      onIntent: (intent) => intents.push(intent),
+    });
+    controller.move({ x: 120, y: 160 });
+    controller.update({
+      viewport,
+      items: [{ id: 'a', x: 60, y: 40, width: 20, height: 20 }],
+      onIntent: (intent) => intents.push(intent),
+    });
+    controller.end({ x: 120, y: 160 });
+
+    expect(intents).toEqual([
+      { type: 'move', itemIds: ['a'], rects: [{ id: 'a', x: 50, y: 40, width: 20, height: 20 }] },
+      { type: 'move', itemIds: ['a'], rects: [{ id: 'a', x: 60, y: 40, width: 20, height: 20 }] },
+    ]);
+  });
+
+  test('keeps controlled resize, negative multi-item movement, cancel, and pan non-compounding', () => {
+    const resizeIntents: unknown[] = [];
+    const resizeController = createGridInteractionsController({
+      viewport,
+      items: [{ id: 'a', x: 40, y: 40, width: 20, height: 20 }],
+      onIntent: (intent) => resizeIntents.push(intent),
+    });
+
+    resizeController.begin({ x: 120, y: 240 }, 'bottom-right');
+    resizeController.move({ x: 140, y: 280 });
+    resizeController.update({
+      viewport,
+      items: [{ id: 'a', x: 40, y: 40, width: 30, height: 30 }],
+      onIntent: (intent) => resizeIntents.push(intent),
+    });
+    resizeController.move({ x: 160, y: 320 });
+    resizeController.update({
+      viewport,
+      items: [{ id: 'a', x: 40, y: 40, width: 40, height: 40 }],
+      onIntent: (intent) => resizeIntents.push(intent),
+    });
+    resizeController.end({ x: 160, y: 320 });
+
+    const moveIntents: unknown[] = [];
+    const moveController = createGridInteractionsController({
+      viewport,
+      items: [
+        { id: 'a', x: 40, y: 40, width: 20, height: 20 },
+        { id: 'b', x: 80, y: 40, width: 20, height: 20 },
+      ],
+      selectedIds: ['a', 'b'],
+      onIntent: (intent) => moveIntents.push(intent),
+    });
+
+    moveController.begin({ x: 80, y: 160 });
+    moveController.move({ x: 60, y: 120 });
+    moveController.cancel();
+    moveController.end({ x: 40, y: 80 });
+
+    const panIntents: unknown[] = [];
+    const panController = createGridInteractionsController({
+      viewport,
+      items: [],
+      onIntent: (intent) => panIntents.push(intent),
+    });
+
+    panController.begin({ x: 20, y: 40, spaceKey: true });
+    panController.move({ x: 40, y: 80 });
+    panController.update({
+      viewport: { ...viewport, offsetX: 5, offsetY: 2.5 },
+      items: [],
+      onIntent: (intent) => panIntents.push(intent),
+    });
+    panController.move({ x: 60, y: 120 });
+    panController.end({ x: 60, y: 120 });
+
+    expect(resizeIntents).toEqual([
+      { type: 'resize', itemIds: ['a'], rects: [{ id: 'a', x: 40, y: 40, width: 30, height: 30 }] },
+      { type: 'resize', itemIds: ['a'], rects: [{ id: 'a', x: 40, y: 40, width: 40, height: 40 }] },
+    ]);
+    expect(moveIntents).toEqual([
+      {
+        type: 'move',
+        itemIds: ['a', 'b'],
+        rects: [
+          { id: 'a', x: 30, y: 30, width: 20, height: 20 },
+          { id: 'b', x: 70, y: 30, width: 20, height: 20 },
+        ],
+      },
+    ]);
+    expect(panIntents).toEqual([
+      {
+        type: 'pan',
+        itemIds: [],
+        viewport: { ...viewport, offsetX: 5, offsetY: 2.5 },
+      },
+      {
+        type: 'pan',
+        itemIds: [],
+        viewport: { ...viewport, offsetX: 10, offsetY: 5 },
+      },
+    ]);
+  });
+});

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

@@ -0,0 +1,248 @@
+import {
+  type GridPoint,
+  type GridRect,
+  type GridResizeHandle,
+  type GridViewport,
+  hitTestWorldRects,
+  moveWorldRects,
+  panViewport,
+  resizeWorldRect,
+  resolveWorldSnapCandidate,
+  selectWorldRects,
+  viewportToWorld,
+} from '@ankhorage/grid-view';
+
+import type {
+  GridInteractionIntent,
+  GridInteractionItem,
+  GridInteractionPointer,
+  GridInteractionsController,
+  GridInteractionsControllerProps,
+} from '../../../types/grid-interactions';
+
+type InteractionState =
+  | { readonly kind: 'idle' }
+  | { readonly kind: 'marquee'; readonly start: GridPoint; readonly viewport: GridViewport }
+  | { readonly kind: 'pan'; readonly start: GridPoint; readonly viewport: GridViewport }
+  | {
+      readonly kind: 'move';
+      readonly start: GridPoint;
+      readonly viewport: GridViewport;
+      readonly itemIds: readonly string[];
+      readonly items: readonly GridInteractionItem[];
+    }
+  | {
+      readonly kind: 'resize';
+      readonly start: GridPoint;
+      readonly viewport: GridViewport;
+      readonly item: GridInteractionItem;
+      readonly handle: GridResizeHandle;
+    };
+
+/*** Create a platform-neutral controlled interaction controller using grid-view geometry only. */
+export function createGridInteractionsController(
+  props: GridInteractionsControllerProps,
+): GridInteractionsController {
+  let currentProps = props;
+  let state: InteractionState = { kind: 'idle' };
+  let previousIntent: GridInteractionIntent | undefined;
+  const point = (pointer: GridInteractionPointer, viewport = currentProps.viewport) =>
+    Number.isFinite(pointer.x) && Number.isFinite(pointer.y)
+      ? viewportToWorld(pointer, viewport)
+      : undefined;
+  const emit = (intent: GridInteractionIntent) => {
+    if (JSON.stringify(previousIntent) === JSON.stringify(intent)) return;
+    previousIntent = intent;
+    currentProps.onIntent(intent);
+  };
+
+  return {
+    begin: (pointer, handle) => {
+      if (!canEdit(currentProps)) return;
+      const start = point(pointer);
+      if (start === undefined) return;
+      if (pointer.spaceKey === true || pointer.altKey === true) {
+        state = { kind: 'pan', start, viewport: currentProps.viewport };
+        return;
+      }
+      const target = hitTestWorldRects(currentProps.items, start);
+      if (target === undefined || isProtected(target)) {
+        state = { kind: 'marquee', start, viewport: currentProps.viewport };
+        return;
+      }
+      if (handle !== undefined && target.resizable !== false) {
+        state = { kind: 'resize', start, viewport: currentProps.viewport, item: target, handle };
+        return;
+      }
+      const itemIds =
+        currentProps.selectedIds?.includes(target.id) === true
+          ? currentProps.selectedIds
+          : [target.id];
+      state = {
+        kind: 'move',
+        start,
+        viewport: currentProps.viewport,
+        itemIds,
+        items: currentProps.items.filter((item) => itemIds.includes(item.id)),
+      };
+    },
+    move: (pointer) => {
+      if (!canEdit(currentProps)) return;
+      const current = point(pointer, viewportForState(state, currentProps.viewport));
+      if (current !== undefined) emitPreview(state, current, currentProps, emit);
+    },
+    end: (pointer) => {
+      if (!canEdit(currentProps)) {
+        state = { kind: 'idle' };
+        return;
+      }
+      const current = point(pointer, viewportForState(state, currentProps.viewport));
+      if (current !== undefined) emitPreview(state, current, currentProps, emit);
+      state = { kind: 'idle' };
+    },
+    cancel: () => {
+      state = { kind: 'idle' };
+    },
+    keyDown: (key, pointer = { x: 0, y: 0 }) => {
+      if (!canEdit(currentProps)) return false;
+      const focusedId = currentProps.selectedIds?.at(-1);
+      const focused = currentProps.items.find((item) => item.id === focusedId);
+      if (!focused || isProtected(focused)) return false;
+      const increment = pointer.shiftKey === true ? 10 : 1;
+      const delta = keyToDelta(key, increment);
+      if (delta === undefined) return false;
+      if (pointer.altKey === true) {
+        emit({
+          type: 'resize',
+          itemIds: [focused.id],
+          rects: [resizeWorldRect(focused, resizeHandleForDelta(delta), delta)],
+        });
+        return true;
+      }
+      emit({ type: 'move', itemIds: [focused.id], rects: moveWorldRects([focused], delta) });
+      return true;
+    },
+    update: (nextProps) => {
+      currentProps = nextProps;
+    },
+  };
+}
+
+/*** Determines whether the component-wide interaction policy permits edit intents. */
+function canEdit(props: GridInteractionsControllerProps): boolean {
+  return props.interactionPolicy !== 'passive';
+}
+
+/*** Emit one controlled preview/intention without retaining or mutating caller-owned item data. */
+function emitPreview(
+  state: InteractionState,
+  current: GridPoint,
+  props: GridInteractionsControllerProps,
+  emit: (intent: GridInteractionIntent) => void,
+) {
+  if (state.kind === 'idle') return;
+  if (state.kind === 'pan') {
+    emit({
+      type: 'pan',
+      itemIds: [],
+      viewport: panViewport(state.viewport, {
+        x: state.start.x - current.x,
+        y: state.start.y - current.y,
+      }),
+    });
+    return;
+  }
+  if (state.kind === 'marquee') {
+    const marquee = normalizeRect(state.start, current);
+    const itemIds = selectWorldRects(props.items, marquee, {
+      mode: props.marqueeMode ?? 'intersect',
+    }).filter((id) => {
+      const item = props.items.find((candidate) => candidate.id === id);
+      return item !== undefined && !isProtected(item);
+    });
+    emit({ type: 'marquee', itemIds, marquee });
+    return;
+  }
+  const delta = resolveSnapDelta(state, current, props);
+  if (state.kind === 'move') {
+    emit({ type: 'move', itemIds: state.itemIds, rects: moveWorldRects(state.items, delta) });
+    return;
+  }
+  emit({
+    type: 'resize',
+    itemIds: [state.item.id],
+    rects: [resizeWorldRect(state.item, state.handle, delta)],
+  });
+}
+
+/*** Resolve explicit per-axis candidate snapping without inventing geometry outside grid-view. */
+function resolveSnapDelta(
+  state: InteractionState,
+  current: GridPoint,
+  props: GridInteractionsControllerProps,
+): GridPoint {
+  if (state.kind === 'idle' || state.kind === 'marquee' || state.kind === 'pan') {
+    return { x: 0, y: 0 };
+  }
+  const raw = { x: current.x - state.start.x, y: current.y - state.start.y };
+  if (props.snap?.enabled !== true) return raw;
+  const anchor = state.kind === 'resize' ? state.item : state.items.at(0);
+  if (anchor === undefined) return raw;
+  const options = {
+    enabled: true,
+    tolerancePixels: props.snap.tolerancePixels,
+    priorities: props.snap.priorities,
+  };
+  return {
+    x:
+      resolveWorldSnapCandidate(anchor.x + raw.x, props.snap.x ?? [], {
+        ...options,
+        pixelsPerUnit: props.viewport.pixelsPerUnitX,
+      }) - anchor.x,
+    y:
+      resolveWorldSnapCandidate(anchor.y + raw.y, props.snap.y ?? [], {
+        ...options,
+        pixelsPerUnit: props.viewport.pixelsPerUnitY,
+      }) - anchor.y,
+  };
+}
+
+/*** Keep pointer coordinates in the original gesture coordinate space across controlled updates. */
+function viewportForState(state: InteractionState, fallback: GridViewport): GridViewport {
+  return state.kind === 'idle' ? fallback : state.viewport;
+}
+
+/*** Keep all caller-declared protected items out of selection and edit intents. */
+function isProtected(item: GridInteractionItem): boolean {
+  return (
+    item.disabled === true ||
+    item.locked === true ||
+    item.readOnly === true ||
+    item.passive === true
+  );
+}
+
+/*** Normalize an arbitrary-direction drag into the world rectangle expected by grid-view selection. */
+function normalizeRect(start: GridPoint, end: GridPoint): GridRect {
+  return {
+    x: Math.min(start.x, end.x),
+    y: Math.min(start.y, end.y),
+    width: Math.abs(end.x - start.x),
+    height: Math.abs(end.y - start.y),
+  };
+}
+
+/** Maps accessible arrow keys to caller-controlled world-space edit increments. */
+function keyToDelta(key: string, increment: number): GridPoint | undefined {
+  if (key === 'ArrowUp') return { x: 0, y: -increment };
+  if (key === 'ArrowRight') return { x: increment, y: 0 };
+  if (key === 'ArrowDown') return { x: 0, y: increment };
+  if (key === 'ArrowLeft') return { x: -increment, y: 0 };
+  return undefined;
+}
+
+/** Chooses the physical edge matching an accessible resize direction. */
+function resizeHandleForDelta(delta: GridPoint): GridResizeHandle {
+  if (delta.x < 0) return delta.y < 0 ? 'top-left' : delta.y > 0 ? 'bottom-left' : 'left';
+  return delta.y < 0 ? 'top-right' : delta.y > 0 ? 'bottom-right' : 'right';
+}

package/src/features/grid-interactions/meta.ts

@@ -0,0 +1,12 @@
+import type { ZoraComponentMeta } from '../../types/authoring';
+
+/** Grid input is a code composition boundary because it accepts live geometry and callbacks. */
+export const gridInteractionsMeta = {
+  name: 'GridInteractions',
+  category: 'foundation',
+  description: 'Maps native and web input to controlled world-space grid interaction intents.',
+  directManifestNode: false,
+  note: 'Requires live viewport geometry, item data, and an executable intent callback; available through code APIs only.',
+  allowedChildren: [],
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/features/grid-interactions/public.ts

@@ -0,0 +1,11 @@
+export type {
+  GridInteractionIntent,
+  GridInteractionItem,
+  GridInteractionPointer,
+  GridInteractionsController,
+  GridInteractionsControllerProps,
+  GridInteractionSnap,
+  GridInteractionsProps,
+} from '../../types/grid-interactions';
+export { GridInteractions } from './adapters/inbound/GridInteractions';
+export { createGridInteractionsController } from './application/createGridInteractionsController';