@ankhorage/zora 25.3.0 → 25.5.0

package/src/features/spatial-grid/adapters/inbound/SpatialGrid.test.tsx

@@ -0,0 +1,248 @@
+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 { renderToStaticMarkup } from 'react-dom/server';
+
+import type { SpatialGrid as SpatialGridComponent } from './SpatialGrid';
+
+const webDistRoot = join(import.meta.dir, '../../../../../web-dist');
+
+/** Loads the independently bundled React Native Web component through its public artifact path. */
+function loadSpatialGrid() {
+  return import(
+    pathToFileURL(join(webDistRoot, 'components/spatial-grid/index.js')).href
+  ) as Promise<{
+    SpatialGrid: typeof SpatialGridComponent;
+  }>;
+}
+
+test('renders a bounded, accessible 10k free-placement catalog in deterministic overlap order', async () => {
+  const items = [
+    { height: 30, id: 'back', width: 30, x: 0, y: 0, zIndex: -1 },
+    { height: 30, id: 'front', width: 30, x: 0, y: 0, zIndex: 1 },
+    ...Array.from({ length: 9998 }, (_, index) => ({
+      height: 20,
+      id: `item-${index}`,
+      width: 20,
+      x: 1000 + (index % 100) * 100,
+      y: 1000 + Math.floor(index / 100) * 100,
+    })),
+  ];
+  await withBrowserRoot(async (browserWindow) => {
+    const { SpatialGrid } = await loadSpatialGrid();
+    browserWindow.document.body.innerHTML = renderToStaticMarkup(
+      <SpatialGrid
+        contentHeight={11000}
+        contentWidth={11000}
+        height={100}
+        items={items}
+        selectedItemId="front"
+        testID="board"
+        width={100}
+        zoom={2}
+        renderItem={(item) => <span>{item.id}</span>}
+      />,
+    );
+    const mounted = [...browserWindow.document.querySelectorAll('[data-testid^="board-item-"]')];
+
+    expect(mounted).toHaveLength(2);
+    expect(mounted.map((element) => element.getAttribute('data-testid'))).toEqual([
+      'board-item-back',
+      'board-item-front',
+    ]);
+    expect(
+      browserWindow.document
+        .querySelector('[data-testid="board-item-front"]')
+        ?.getAttribute('role'),
+    ).toBe('button');
+    expect(
+      browserWindow.document
+        .querySelector('[data-testid="board-item-front"]')
+        ?.getAttribute('tabindex'),
+    ).toBe('0');
+    expect(
+      browserWindow.document
+        .querySelector('[data-testid="board-item-front"]')
+        ?.getAttribute('aria-label'),
+    ).toBe('Spatial grid item front');
+  });
+});
+
+test('activates the topmost overlapping item by pointer and keyboard', async () => {
+  const { SpatialGrid } = await loadSpatialGrid();
+  const selection: string[] = [];
+  const activation: string[] = [];
+  await withBrowserRoot(async (browserWindow, host, root) => {
+    await renderSpatialGrid(
+      root,
+      <SpatialGrid
+        contentHeight={100}
+        contentWidth={100}
+        height={100}
+        items={[
+          { height: 50, id: 'back', width: 50, x: 10, y: 20, zIndex: -1 },
+          { height: 50, id: 'front', width: 50, x: 10, y: 20, zIndex: 1 },
+        ]}
+        testID="interactive-board"
+        width={100}
+        onActivation={(id) => activation.push(id)}
+        onSelectionChange={(id) => selection.push(id)}
+        renderItem={(item) => <span>{item.id}</span>}
+      />,
+    );
+    const front = requireItem(host, 'interactive-board-item-front');
+    await dispatch(front, new browserWindow.MouseEvent('click', { bubbles: true }));
+    await dispatch(
+      front,
+      new browserWindow.KeyboardEvent('keydown', { bubbles: true, key: 'Enter' }),
+    );
+    await dispatch(
+      front,
+      new browserWindow.KeyboardEvent('keyup', { bubbles: true, key: 'Enter' }),
+    );
+    // happy-dom does not synthesize the browser click dispatched for an activated button.
+    await dispatch(front, new browserWindow.MouseEvent('click', { bubbles: true }));
+    expect(selection).toEqual(['front', 'front']);
+    expect(activation).toEqual(['front', 'front']);
+  });
+});
+
+test('separates disabled, read-only, and passive interaction behavior', async () => {
+  const { SpatialGrid } = await loadSpatialGrid();
+  const selection: string[] = [];
+  const activation: string[] = [];
+  const focus: string[] = [];
+  await withBrowserRoot(async (browserWindow, host, root) => {
+    const render = (
+      props: Pick<
+        React.ComponentProps<typeof SpatialGrid>,
+        'disabled' | 'readOnly' | 'interactionPolicy'
+      >,
+    ) => (
+      <SpatialGrid
+        contentHeight={100}
+        contentWidth={100}
+        height={100}
+        items={[{ height: 50, id: 'node', width: 50, x: 10, y: 20 }]}
+        testID="interactive-board"
+        width={100}
+        onActivation={(id) => activation.push(id)}
+        onFocusChange={(id) => focus.push(id)}
+        onSelectionChange={(id) => selection.push(id)}
+        renderItem={(item) => <span>{item.id}</span>}
+        {...props}
+      />
+    );
+    for (const props of [
+      { disabled: true },
+      { readOnly: true },
+      { interactionPolicy: 'passive' as const },
+    ]) {
+      await renderSpatialGrid(root, render(props));
+      const item = requireItem(host, 'interactive-board-item-node');
+      await dispatch(item, new browserWindow.FocusEvent('focusin', { bubbles: true }));
+      await dispatch(item, new browserWindow.MouseEvent('click', { bubbles: true }));
+    }
+
+    expect(selection).toEqual([]);
+    expect(activation).toEqual([]);
+    expect(focus).toEqual(['node']);
+  });
+});
+
+test('reveals a focused offscreen item through the composed GridView viewport', async () => {
+  const { SpatialGrid } = await loadSpatialGrid();
+  await withBrowserRoot(async (_browserWindow, host, root) => {
+    const scrollCalls: unknown[] = [];
+    const render = (focusedItemId?: string) => (
+      <SpatialGrid
+        contentHeight={1000}
+        contentWidth={1000}
+        focusedItemId={focusedItemId}
+        height={100}
+        items={[{ height: 20, id: 'distant', width: 20, x: 400, y: 500 }]}
+        revealPaddingPixels={10}
+        width={100}
+        renderItem={(item) => <span>{item.id}</span>}
+      />
+    );
+    await renderSpatialGrid(root, render());
+    const scrollableNodes = [...host.querySelectorAll('div')] as HTMLElement[];
+    for (const node of scrollableNodes) {
+      node.scrollTo = (options: unknown) => scrollCalls.push(options);
+    }
+    await renderSpatialGrid(root, render('distant'));
+
+    expect(scrollCalls).toContainEqual({ animated: true, x: 330 });
+    expect(scrollCalls).toContainEqual({ animated: true, y: 430 });
+  });
+});
+
+/** Runs a mounted RNW test with its DOM globals restored after the assertion. */
+async function withBrowserRoot(
+  callback: (
+    browserWindow: Window,
+    host: HTMLDivElement,
+    root: ReturnType<typeof createRoot>,
+  ) => Promise<void>,
+) {
+  const browserWindow = new Window();
+  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,
+    window: browserWindow,
+    document: browserWindow.document,
+    Node: browserWindow.Node,
+    navigator: browserWindow.navigator,
+    ShadowRoot: browserWindow.ShadowRoot,
+  });
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  const root = createRoot(host);
+
+  try {
+    await callback(browserWindow, host, root);
+  } finally {
+    await act(() => Promise.resolve().then(() => root.unmount()));
+    browserWindow.close();
+    for (const [key, descriptor] of previous) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  }
+}
+
+/** Renders a component through React's mounted interaction boundary. */
+function renderSpatialGrid(root: ReturnType<typeof createRoot>, component: React.ReactNode) {
+  return act(() => Promise.resolve().then(() => root.render(component)));
+}
+
+/** Retrieves one mounted item by its stable test identifier. */
+function requireItem(host: HTMLDivElement, testID: string): HTMLElement {
+  const item = host.querySelector(`[data-testid="${testID}"]`);
+  if (!item) throw new Error(`SpatialGrid did not render ${testID}.`);
+  return item as HTMLElement;
+}
+
+/** Dispatches one mounted native-web event through React's synthetic event boundary. */
+function dispatch(target: EventTarget, event: Event) {
+  return act(() =>
+    Promise.resolve().then(() => {
+      target.dispatchEvent(event);
+    }),
+  );
+}

package/src/features/spatial-grid/adapters/inbound/SpatialGrid.tsx

@@ -0,0 +1,112 @@
+import React from 'react';
+import { Pressable as NativePressable, View as NativeView } from 'react-native';
+
+import type { SpatialGridItem, SpatialGridProps } from '../../../../types/spatial-grid';
+import { GridView } from '../../../grid-view/public';
+import { sortSpatialGridItems } from '../../application/sortSpatialGridItems';
+
+/** Renders virtualized free-placement items without owning geometry, pan, zoom, or drag orchestration. */
+export function SpatialGrid({
+  items,
+  contentWidth,
+  contentHeight,
+  width,
+  height,
+  zoom,
+  overscanPixels,
+  selectedItemId,
+  focusedItemId,
+  revealPaddingPixels,
+  disabled = false,
+  readOnly = false,
+  interactionPolicy,
+  onSelectionChange,
+  onActivation,
+  onFocusChange,
+  onViewportChange,
+  onVisibleItemIdsChange,
+  renderItem,
+  testID,
+}: SpatialGridProps) {
+  const orderedItems = React.useMemo(() => sortSpatialGridItems(items), [items]);
+  const itemLookup = React.useMemo(
+    () => new Map(orderedItems.map((item) => [item.id, item])),
+    [orderedItems],
+  );
+  const interactionBlocked = disabled || interactionPolicy === 'passive';
+
+  return (
+    <NativeView style={{ height, overflow: 'hidden', width }} testID={testID}>
+      <GridView
+        contentHeight={contentHeight}
+        contentWidth={contentWidth}
+        focusedItemId={focusedItemId ?? selectedItemId}
+        height={height}
+        interactionPolicy={interactionPolicy}
+        items={orderedItems}
+        onViewportChange={onViewportChange}
+        onVisibleItemIdsChange={onVisibleItemIdsChange}
+        overscanPixels={overscanPixels}
+        renderItem={(gridItem) => {
+          const item = itemLookup.get(gridItem.id);
+          if (!item) return null;
+          return renderSpatialGridItem(
+            item,
+            item.id === selectedItemId,
+            item.id === focusedItemId,
+            interactionBlocked,
+            readOnly,
+            onSelectionChange,
+            onActivation,
+            onFocusChange,
+            renderItem,
+            testID,
+          );
+        }}
+        revealPaddingPixels={revealPaddingPixels}
+        width={width}
+        zoom={zoom}
+      />
+    </NativeView>
+  );
+}
+
+/** Adds serializable selection, activation, and focus boundaries around a caller-rendered item. */
+function renderSpatialGridItem(
+  item: SpatialGridItem,
+  selected: boolean,
+  focused: boolean,
+  interactionBlocked: boolean,
+  readOnly: boolean,
+  onSelectionChange: SpatialGridProps['onSelectionChange'],
+  onActivation: SpatialGridProps['onActivation'],
+  onFocusChange: SpatialGridProps['onFocusChange'],
+  renderItem: SpatialGridProps['renderItem'],
+  testID: string | undefined,
+) {
+  const interactionDisabled = interactionBlocked || item.disabled === true;
+  const editingDisabled = interactionDisabled || readOnly;
+  return (
+    <NativePressable
+      accessibilityLabel={item.accessibilityLabel ?? `Spatial grid item ${item.id}`}
+      accessibilityRole="button"
+      accessibilityState={{ disabled: editingDisabled, selected }}
+      disabled={interactionDisabled}
+      style={{ height: '100%', width: '100%' }}
+      testID={testID === undefined ? undefined : `${testID}-item-${item.id}`}
+      onFocus={() => {
+        if (!interactionDisabled) onFocusChange?.(item.id);
+      }}
+      onLongPress={() => {
+        if (!editingDisabled) onActivation?.(item.id);
+      }}
+      onPress={() => {
+        if (editingDisabled) return;
+        onSelectionChange?.(item.id);
+        onActivation?.(item.id);
+      }}
+    >
+      {renderItem(item, { disabled: editingDisabled, focused, selected })}
+    </NativePressable>
+  );
+}

package/src/features/spatial-grid/application/sortSpatialGridItems.test.ts

@@ -0,0 +1,42 @@
+import { getVisibleGridItems } from '@ankhorage/grid-view';
+import { describe, expect, test } from 'bun:test';
+
+import { sortSpatialGridItems } from './sortSpatialGridItems';
+
+describe('SpatialGrid presentation', () => {
+  test('preserves free world rectangles and establishes deterministic overlap hit order', () => {
+    const ordered = sortSpatialGridItems([
+      { height: 40, id: 'middle', width: 40, x: 24, y: 18 },
+      { height: 30, id: 'back', width: 30, x: 16, y: 12, zIndex: -1 },
+      { height: 20, id: 'front', width: 20, x: 24, y: 18, zIndex: 2 },
+      { height: 10, id: 'front-later', width: 10, x: 24, y: 18, zIndex: 2 },
+    ]);
+
+    expect(ordered.map((item) => item.id)).toEqual(['back', 'middle', 'front', 'front-later']);
+    expect(ordered[1]).toMatchObject({ height: 40, width: 40, x: 24, y: 18 });
+  });
+
+  test('keeps a 10k free-placement catalogue bounded to the viewport subset', () => {
+    const items = sortSpatialGridItems(
+      Array.from({ length: 10000 }, (_, index) => ({
+        height: 20,
+        id: `item-${index}`,
+        width: 20,
+        x: (index % 100) * 100,
+        y: Math.floor(index / 100) * 100,
+      })),
+    );
+
+    const visible = getVisibleGridItems(items, {
+      height: 160,
+      offsetX: 0,
+      offsetY: 0,
+      pixelsPerUnitX: 1,
+      pixelsPerUnitY: 1,
+      width: 160,
+    });
+
+    expect(visible).toHaveLength(4);
+    expect(visible.map((item) => item.id)).toEqual(['item-0', 'item-1', 'item-100', 'item-101']);
+  });
+});

package/src/features/spatial-grid/application/sortSpatialGridItems.ts

@@ -0,0 +1,14 @@
+import type { SpatialGridItem } from '../../../types/spatial-grid';
+
+/** Orders free-placement items for deterministic paint and overlap hit-testing. */
+export function sortSpatialGridItems(
+  items: readonly SpatialGridItem[],
+): readonly SpatialGridItem[] {
+  return [...items]
+    .map((item, index) => ({ index, item }))
+    .sort(
+      (left, right) =>
+        (left.item.zIndex ?? 0) - (right.item.zIndex ?? 0) || left.index - right.index,
+    )
+    .map(({ item }) => item);
+}

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

@@ -0,0 +1,12 @@
+import type { ZoraComponentMeta } from '../../types/authoring';
+
+/** Free-placement rendering requires a caller-owned React renderer and is therefore code-only. */
+export const spatialGridMeta = {
+  name: 'SpatialGrid',
+  category: 'foundation',
+  description: 'Virtualized free-placement board. Item rendering belongs to the code API.',
+  directManifestNode: false,
+  note: 'SpatialGrid requires a caller-owned React item renderer and cannot be serialized as a manifest node.',
+  allowedChildren: [],
+  props: {},
+} as const satisfies ZoraComponentMeta;

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

@@ -0,0 +1,6 @@
+export type {
+  SpatialGridItem,
+  SpatialGridItemState,
+  SpatialGridProps,
+} from '../../types/spatial-grid';
+export { SpatialGrid } from './adapters/inbound/SpatialGrid';

package/src/features/time-grid/adapters/inbound/TimeGrid.test.tsx

@@ -0,0 +1,131 @@
+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 { TimeGridProps } from '../../../../types/time-grid';
+
+const webDistRoot = join(import.meta.dir, '../../../../../web-dist');
+
+function load(path: string) {
+  return import(pathToFileURL(join(webDistRoot, path)).href);
+}
+
+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);
+    }
+  };
+}
+
+test('keeps mounted interval and virtualized variable-height lane labels synchronized with GridView scrolling', async () => {
+  const browser = new Window();
+  const restore = installBrowserGlobals(browser);
+  const host = document.createElement('div');
+  document.body.append(host);
+  const root = createRoot(host);
+  const { TimeGrid } = (await load('components/time-grid/TimeGrid.js')) as {
+    TimeGrid: React.ComponentType<TimeGridProps>;
+  };
+  const focusedIds: string[] = [];
+  const viewportOffsets: number[] = [];
+
+  try {
+    act(() => {
+      root.render(
+        <TimeGrid
+          contentWidth={100}
+          focusedIntervalId="drums"
+          height={30}
+          intervals={[
+            { extent: 10, id: 'drums', laneId: 'drums', start: 0 },
+            { extent: 10, id: 'strings', laneId: 'strings', start: 0 },
+          ]}
+          lanes={[
+            { height: 20, id: 'drums' },
+            { height: 40, id: 'bass' },
+            { height: 30, id: 'strings' },
+          ]}
+          onFocusedIntervalIdChange={(id) => focusedIds.push(id)}
+          onViewportChange={(viewport) => viewportOffsets.push(viewport.offsetY)}
+          overscanPixels={0}
+          renderInterval={(interval, selected) => (
+            <span data-selected={selected}>{interval.id}</span>
+          )}
+          renderLaneLabel={(lane) => <span>{lane.id}</span>}
+          selectedIntervalIds={['drums']}
+          testID="time-grid"
+          width={100}
+          zoom={2}
+        />,
+      );
+    });
+
+    expect(host.querySelector('[data-testid="time-grid-interval-drums"]')?.textContent).toBe(
+      'drums',
+    );
+    expect(host.querySelector('[data-testid="time-grid-interval-strings"]')).toBeNull();
+    expect(
+      host.querySelector('[data-testid="time-grid-lane-label-drums"]')?.getAttribute('style'),
+    ).toContain('height: 40px');
+    expect(host.querySelector('[data-testid="time-grid-lane-label-bass"]')).toBeNull();
+
+    const interval = host.querySelector<HTMLElement>('[data-testid="time-grid-interval-drums"]');
+    if (!interval) throw new Error('Missing mounted interval');
+    const arrowDown = new browser.KeyboardEvent('keydown', {
+      bubbles: true,
+      cancelable: true,
+      key: 'ArrowDown',
+    });
+    void act(() => interval.dispatchEvent(arrowDown));
+    expect(arrowDown.defaultPrevented).toBe(true);
+    expect(focusedIds).toEqual(['strings']);
+
+    const verticalScroller = Array.from(host.querySelectorAll<HTMLElement>('div')).find(
+      (element) =>
+        element.getAttribute('style') === 'width: 200px; height: 30px;' &&
+        Array.from(element.querySelectorAll('div')).some(
+          (child) => child.getAttribute('style') === 'width: 200px; height: 180px;',
+        ),
+    );
+    if (!verticalScroller) throw new Error('Missing GridView vertical scroller');
+    Object.defineProperty(verticalScroller, 'scrollTop', { configurable: true, value: 60 });
+    void act(() => verticalScroller.dispatchEvent(new browser.Event('scroll', { bubbles: true })));
+
+    expect(viewportOffsets).toContain(30);
+    expect(host.querySelector('[data-testid="time-grid-lane-label-drums"]')).toBeNull();
+    expect(
+      host.querySelector('[data-testid="time-grid-lane-label-bass"]')?.getAttribute('style'),
+    ).toContain('top: -20px');
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  } finally {
+    act(() => root.unmount());
+    host.remove();
+    browser.close();
+    restore();
+  }
+});