@ankhorage/zora 25.6.2 → 25.8.0

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

@@ -0,0 +1,231 @@
+import {
+  type GridPoint,
+  type GridRect,
+  type GridResizeHandle,
+  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 kind: 'pan'; readonly start: GridPoint }
+  | { readonly kind: 'move'; readonly start: GridPoint; readonly itemIds: readonly string[] }
+  | {
+      readonly kind: 'resize';
+      readonly start: GridPoint;
+      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) =>
+    Number.isFinite(pointer.x) && Number.isFinite(pointer.y)
+      ? viewportToWorld(pointer, currentProps.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 };
+        return;
+      }
+      const target = hitTestWorldRects(currentProps.items, start);
+      if (target === undefined || isProtected(target)) {
+        state = { kind: 'marquee', start };
+        return;
+      }
+      if (handle !== undefined && target.resizable !== false) {
+        state = { kind: 'resize', start, item: target, handle };
+        return;
+      }
+      const itemIds =
+        currentProps.selectedIds?.includes(target.id) === true
+          ? currentProps.selectedIds
+          : [target.id];
+      state = { kind: 'move', start, itemIds };
+    },
+    move: (pointer) => {
+      if (!canEdit(currentProps)) return;
+      const current = point(pointer);
+      if (current !== undefined) emitPreview(state, current, currentProps, emit);
+    },
+    end: (pointer) => {
+      if (!canEdit(currentProps)) {
+        state = { kind: 'idle' };
+        return;
+      }
+      const current = point(pointer);
+      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(props.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') {
+    const selected = props.items.filter((item) => state.itemIds.includes(item.id));
+    emit({ type: 'move', itemIds: state.itemIds, rects: moveWorldRects(selected, 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 : props.items.find((item) => item.id === state.itemIds[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 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';

package/src/features/matrix-grid/adapters/inbound/MatrixGrid.test.tsx

@@ -63,10 +63,12 @@ const cells = layout.rows.flatMap((row) =>
 type MatrixGridComponent = React.ComponentType<{
   readonly cells: typeof cells;
   readonly height: number;
+  readonly interactionPolicy?: 'passive';
   readonly layout: typeof layout;
   readonly onSelectionChange?: (ids: readonly string[]) => void;
   readonly onViewportChange?: (viewport: unknown) => void;
   readonly renderCell: (cell: { readonly id: string }) => React.ReactNode;
+  readonly readOnly?: boolean;
   readonly selectedCellIds?: readonly string[];
   readonly selectionMode?: 'multi';
   readonly testID: string;
@@ -127,8 +129,8 @@ test('mounts only visible sparse cells with independent axis zoom and preserves
       expect(mountedCells.length).toBeLessThan(100);
       const target = host.querySelector('[data-testid="matrix-cell-row-1-column-1"]');
       expect(target).not.toBeNull();
-      expect(target?.parentElement?.getAttribute('style')).toContain('left: 20px');
-      expect(target?.parentElement?.getAttribute('style')).toContain('top: 24px');
+      expect(target?.parentElement?.parentElement?.getAttribute('style')).toContain('left: 20px');
+      expect(target?.parentElement?.parentElement?.getAttribute('style')).toContain('top: 24px');
       void act(() => target?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true })));
       expect(selected).toEqual([['row-1-column-1']]);
     } finally {
@@ -230,3 +232,279 @@ test('proposes an uncontrolled horizontal pan in world units while retaining ind
     }
   });
 });
+
+test('navigates sparse cells by keyboard and applies range and modifier selection intents', async () => {
+  await withMatrixDom(async (host, browser) => {
+    const selections: (readonly string[])[] = [];
+    const root = createRoot(host);
+    const { MatrixGrid } = (await load('components/matrix-grid/MatrixGrid.js')) as {
+      MatrixGrid: MatrixGridComponent;
+    };
+    const { ZoraProvider } = (await load('runtime/ZoraProvider.js')) as {
+      ZoraProvider: ZoraProviderComponent;
+    };
+    const sparseLayout = {
+      columns: [
+        { id: 'column-0', size: 20 },
+        { id: 'column-1', size: 20 },
+        { id: 'column-2', size: 20 },
+      ],
+      rows: [
+        { id: 'row-0', size: 20 },
+        { id: 'row-1', size: 20 },
+        { id: 'row-2', size: 20 },
+      ],
+    };
+    const sparseCells = [
+      { columnId: 'column-0', id: 'a1', rowId: 'row-0' },
+      { columnId: 'column-2', id: 'c1', rowId: 'row-0' },
+      { columnId: 'column-0', id: 'a3', rowId: 'row-2' },
+      { columnId: 'column-2', id: 'c3', rowId: 'row-2' },
+    ];
+
+    function KeyboardMatrix() {
+      const [selectedIds, setSelectedIds] = React.useState<readonly string[]>(['a1']);
+      return (
+        <ZoraProvider>
+          <MatrixGrid
+            cells={sparseCells}
+            height={80}
+            layout={sparseLayout}
+            selectedCellIds={selectedIds}
+            selectionMode="multi"
+            testID="keyboard-matrix"
+            width={80}
+            onSelectionChange={(ids) => {
+              selections.push(ids);
+              setSelectedIds(ids);
+            }}
+            renderCell={(cell) => <span>{cell.id}</span>}
+          />
+        </ZoraProvider>
+      );
+    }
+
+    try {
+      act(() => root.render(<KeyboardMatrix />));
+      const a1 = host.querySelector<HTMLElement>('[data-testid="keyboard-matrix-cell-a1"]');
+      if (!a1) throw new Error('Missing initial sparse matrix cell.');
+      act(() => a1.focus());
+      act(() => {
+        void a1.dispatchEvent(
+          new browser.KeyboardEvent('keydown', { bubbles: true, key: 'ArrowRight' }),
+        );
+      });
+      const c1 = host.querySelector<HTMLElement>('[data-testid="keyboard-matrix-cell-c1"]');
+      expect(c1).not.toBeNull();
+      expect(document.activeElement).toBe(c1);
+      act(() => {
+        void c1?.dispatchEvent(
+          new browser.KeyboardEvent('keydown', { bubbles: true, key: 'ArrowDown', shiftKey: true }),
+        );
+      });
+      expect(selections).toEqual([['a1', 'c1', 'a3', 'c3']]);
+      const c3 = host.querySelector<HTMLElement>('[data-testid="keyboard-matrix-cell-c3"]');
+      act(() => {
+        void c3?.dispatchEvent(
+          new browser.KeyboardEvent('keydown', { bubbles: true, ctrlKey: true, key: 'Enter' }),
+        );
+      });
+      expect(selections.at(-1)).toEqual(['a1', 'c1', 'a3']);
+      act(() => {
+        void c3?.dispatchEvent(new browser.KeyboardEvent('keydown', { bubbles: true, key: ' ' }));
+      });
+      expect(selections.at(-1)).toEqual(['c3']);
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});
+
+test('does not capture keyboard input from interactive cell content and respects read-only selection', async () => {
+  await withMatrixDom(async (host, browser) => {
+    const selections: (readonly string[])[] = [];
+    const root = createRoot(host);
+    const { MatrixGrid } = (await load('components/matrix-grid/MatrixGrid.js')) as {
+      MatrixGrid: MatrixGridComponent;
+    };
+    const { ZoraProvider } = (await load('runtime/ZoraProvider.js')) as {
+      ZoraProvider: ZoraProviderComponent;
+    };
+    const oneCellLayout = {
+      columns: [{ id: 'column-0', size: 20 }],
+      rows: [{ id: 'row-0', size: 20 }],
+    };
+    const oneCell = [{ columnId: 'column-0', id: 'a1', rowId: 'row-0' }];
+
+    try {
+      act(() =>
+        root.render(
+          <ZoraProvider>
+            <MatrixGrid
+              cells={oneCell}
+              height={40}
+              layout={oneCellLayout}
+              readOnly
+              testID="interactive-matrix"
+              width={40}
+              onSelectionChange={(ids) => selections.push(ids)}
+              renderCell={() => <input data-testid="matrix-editor" />}
+            />
+          </ZoraProvider>,
+        ),
+      );
+      const editor = host.querySelector<HTMLInputElement>('[data-testid="matrix-editor"]');
+      const cell = host.querySelector<HTMLElement>('[data-testid="interactive-matrix-cell-a1"]');
+      if (!editor) throw new Error('Missing embedded matrix editor.');
+      if (!cell) throw new Error('Missing read-only matrix cell.');
+      act(() => {
+        void cell.dispatchEvent(new browser.MouseEvent('click', { bubbles: true }));
+      });
+      act(() => editor.focus());
+      act(() => {
+        void editor.dispatchEvent(
+          new browser.KeyboardEvent('keydown', { bubbles: true, key: 'ArrowRight' }),
+        );
+        void editor.dispatchEvent(
+          new browser.KeyboardEvent('keydown', { bubbles: true, key: 'Enter' }),
+        );
+        void editor.dispatchEvent(
+          new browser.KeyboardEvent('keydown', { bubbles: true, key: ' ' }),
+        );
+      });
+      expect(document.activeElement).toBe(editor);
+      expect(selections).toEqual([]);
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});
+
+test('suppresses selection from passive matrix cells', async () => {
+  await withMatrixDom(async (host, browser) => {
+    const selections: (readonly string[])[] = [];
+    const root = createRoot(host);
+    const { MatrixGrid } = (await load('components/matrix-grid/MatrixGrid.js')) as {
+      MatrixGrid: MatrixGridComponent;
+    };
+    const { ZoraProvider } = (await load('runtime/ZoraProvider.js')) as {
+      ZoraProvider: ZoraProviderComponent;
+    };
+    const oneCellLayout = {
+      columns: [{ id: 'column-0', size: 20 }],
+      rows: [{ id: 'row-0', size: 20 }],
+    };
+    const oneCell = [{ columnId: 'column-0', id: 'a1', rowId: 'row-0' }];
+
+    try {
+      act(() =>
+        root.render(
+          <ZoraProvider>
+            <MatrixGrid
+              cells={oneCell}
+              height={40}
+              interactionPolicy="passive"
+              layout={oneCellLayout}
+              testID="passive-matrix"
+              width={40}
+              onSelectionChange={(ids) => selections.push(ids)}
+              renderCell={(cell) => <span>{cell.id}</span>}
+            />
+          </ZoraProvider>,
+        ),
+      );
+      const cell = host.querySelector<HTMLElement>('[data-testid="passive-matrix-cell-a1"]');
+      if (!cell) throw new Error('Missing passive matrix cell.');
+      act(() => {
+        void cell.dispatchEvent(new browser.MouseEvent('click', { bubbles: true }));
+        void cell.dispatchEvent(
+          new browser.KeyboardEvent('keydown', { bubbles: true, key: 'ArrowRight' }),
+        );
+      });
+      expect(selections).toEqual([]);
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});
+
+test('reveals an offscreen keyboard target through a controlled viewport with independent axis zoom', async () => {
+  await withMatrixDom(async (host, browser) => {
+    const root = createRoot(host);
+    const { MatrixGrid } = (await load('components/matrix-grid/MatrixGrid.js')) as {
+      MatrixGrid: MatrixGridComponent;
+    };
+    const { ZoraProvider } = (await load('runtime/ZoraProvider.js')) as {
+      ZoraProvider: ZoraProviderComponent;
+    };
+    const sparseLayout = {
+      columns: [
+        { id: 'column-0', size: 20 },
+        { id: 'column-1', size: 20 },
+        { id: 'column-2', size: 20 },
+      ],
+      rows: [{ id: 'row-0', size: 20 }],
+    };
+    const sparseCells = [
+      { columnId: 'column-0', id: 'a1', rowId: 'row-0' },
+      { columnId: 'column-2', id: 'c1', rowId: 'row-0' },
+    ];
+    function ControlledMatrix() {
+      const [viewport, setViewport] = React.useState<MatrixGridViewport>({
+        height: 20,
+        offsetX: 0,
+        offsetY: 0,
+        pixelsPerUnitX: 2,
+        pixelsPerUnitY: 3,
+        width: 20,
+      });
+      return (
+        <MatrixGrid
+          cells={sparseCells}
+          height={20}
+          layout={sparseLayout}
+          overscanPixels={0}
+          testID="controlled-keyboard-matrix"
+          viewport={viewport}
+          width={20}
+          onViewportChange={(proposal) => {
+            const nextViewport = proposal as MatrixGridViewport;
+            setViewport(nextViewport);
+          }}
+          renderCell={(cell) => <span>{cell.id}</span>}
+        />
+      );
+    }
+
+    try {
+      act(() =>
+        root.render(
+          <ZoraProvider>
+            <ControlledMatrix />
+          </ZoraProvider>,
+        ),
+      );
+      const a1 = host.querySelector<HTMLElement>(
+        '[data-testid="controlled-keyboard-matrix-cell-a1"]',
+      );
+      if (!a1) throw new Error('Missing controlled focus origin.');
+      await act(async () => {
+        await new Promise<void>((resolve) => browser.setTimeout(resolve, 0));
+        a1.focus();
+        void a1.dispatchEvent(
+          new browser.KeyboardEvent('keydown', { bubbles: true, key: 'ArrowRight' }),
+        );
+        await new Promise<void>((resolve) => browser.setTimeout(resolve, 20));
+      });
+      const c1 = host.querySelector<HTMLElement>(
+        '[data-testid="controlled-keyboard-matrix-cell-c1"]',
+      );
+      expect(c1).not.toBeNull();
+      expect(document.activeElement).toBe(c1);
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});
+
+type MatrixGridViewport = NonNullable<React.ComponentProps<MatrixGridComponent>['viewport']>;