@ankhorage/zora 25.3.0 → 25.4.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"spatial-grid.d.ts","sourceRoot":"","sources":["../../src/types/spatial-grid.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,iGAAiG;AACjG,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,sGAAsG;IACtG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,qFAAqF;IACrF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,qDAAqD;AACrD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,+FAA+F;AAC/F,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;IAC7D,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IACnE,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,oBAAoB,KAAK,KAAK,CAAC,SAAS,CAAC;CAC9F"}

package/dist/types/spatial-grid.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=spatial-grid.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spatial-grid.js","sourceRoot":"","sources":["../../src/types/spatial-grid.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/** A free-positioned item retains the grid-view world rectangle and adds presentation policy. */\nexport interface SpatialGridItem extends GridRectItem {\n  /** Higher values are painted and hit-tested above lower values; equal values preserve input order. */\n  readonly zIndex?: number;\n  /** Accessible name for the item; defaults to a stable ID-derived board-item name. */\n  readonly accessibilityLabel?: string;\n  /** Prevents selection and activation for this item while keeping it visible. */\n  readonly disabled?: boolean;\n}\n\n/** State supplied to the code-only item renderer. */\nexport interface SpatialGridItemState {\n  readonly selected: boolean;\n  readonly focused: boolean;\n  readonly disabled: boolean;\n}\n\n/** Props for the virtualized, free-placement presentation over canonical GridView geometry. */\nexport interface SpatialGridProps extends ZoraBaseProps {\n  readonly items: readonly SpatialGridItem[];\n  readonly contentWidth: number;\n  readonly contentHeight: number;\n  readonly width: number;\n  readonly height: number;\n  readonly zoom?: number;\n  readonly overscanPixels?: number;\n  readonly selectedItemId?: string;\n  readonly focusedItemId?: string;\n  readonly revealPaddingPixels?: number;\n  readonly disabled?: boolean;\n  /** Prevents selection and activation while retaining focus and viewport navigation. */\n  readonly readOnly?: boolean;\n  readonly onSelectionChange?: (id: string) => void;\n  readonly onActivation?: (id: string) => void;\n  readonly onFocusChange?: (id: string) => void;\n  readonly onViewportChange?: (viewport: GridViewport) => void;\n  readonly onVisibleItemIdsChange?: (ids: readonly string[]) => void;\n  readonly renderItem: (item: SpatialGridItem, state: SpatialGridItemState) => React.ReactNode;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "25.3.0",
+  "version": "25.4.0",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {
@@ -44,7 +44,7 @@
     "@ankhorage/color-theory": "^0.3.1",
     "@ankhorage/contracts": "^24.2.1",
     "@ankhorage/game": "^0.1.2",
-    "@ankhorage/grid-view": "^0.3.0",
+    "@ankhorage/grid-view": "^0.5.0",
     "@ankhorage/reader": "^0.1.0",
     "@ankhorage/runtime": "^4.0.7",
     "@ankhorage/surface": "^9.4.2",
@@ -132,7 +132,7 @@
     "version-packages": "ankhorage-changeset version"
   },
   "devDependencies": {
-    "@ankhorage/devtools": "^2.3.9",
+    "@ankhorage/devtools": "^2.3.10",
     "@ankhorage/paradox": "^0.3.1",
     "@react-native-vector-icons/fontawesome": "^13.1.4",
     "@react-native-vector-icons/fontawesome5": "^13.1.4",

package/src/features/registry/ZORA_COMPONENT_REGISTRY.ts

@@ -66,6 +66,7 @@ import { BarcodeScannerView, CameraPermissionView, ScanOverlay } from '../scanne
 import { ScreenSection, SectionHeader } from '../section/public';
 import { SelectableItem } from '../selection/public';
 import { Skeleton, SkeletonCard, SkeletonList, SkeletonText } from '../skeleton/public';
+import { SpatialGrid } from '../spatial-grid/public';
 import { Surface } from '../surface/public';
 import {
   CardBack,
@@ -215,6 +216,7 @@ const _ZORA_COMPONENT_REGISTRY = {
   ScanOverlay,
   SectionHeader,
   SelectableItem,
+  SpatialGrid,
   PaletteItem,
   CardBack,
   CardHand,

package/src/features/registry/componentMeta.ts

@@ -85,6 +85,7 @@ import {
   skeletonMeta,
   skeletonTextMeta,
 } from '../skeleton/skeletonMeta';
+import { spatialGridMeta } from '../spatial-grid/meta';
 import { surfaceMeta } from '../surface/surfaceMeta';
 import {
   cardBackMeta,
@@ -218,6 +219,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   ScanOverlay: scanOverlayMeta,
   SectionHeader: sectionHeaderMeta,
   SelectableItem: selectableItemMeta,
+  SpatialGrid: spatialGridMeta,
   SelectionProvider: selectionProviderMeta,
   PaletteItem: paletteItemMeta,
   Timeline: timelineMeta,

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/index.ts

@@ -416,6 +416,12 @@ export {
   SkeletonText,
   type SkeletonTextProps,
 } from './features/skeleton/public';
+export type {
+  SpatialGridItem,
+  SpatialGridItemState,
+  SpatialGridProps,
+} from './features/spatial-grid/public';
+export { SpatialGrid } from './features/spatial-grid/public';
 export type { SurfaceProps, SurfaceVariant } from './features/surface/public';
 export { Surface } from './features/surface/public';
 export type {

package/src/types/spatial-grid.ts

@@ -0,0 +1,44 @@
+import type { GridRectItem, GridViewport } from '@ankhorage/grid-view';
+import type React from 'react';
+
+import type { ZoraBaseProps } from './base';
+
+/** A free-positioned item retains the grid-view world rectangle and adds presentation policy. */
+export interface SpatialGridItem extends GridRectItem {
+  /** Higher values are painted and hit-tested above lower values; equal values preserve input order. */
+  readonly zIndex?: number;
+  /** Accessible name for the item; defaults to a stable ID-derived board-item name. */
+  readonly accessibilityLabel?: string;
+  /** Prevents selection and activation for this item while keeping it visible. */
+  readonly disabled?: boolean;
+}
+
+/** State supplied to the code-only item renderer. */
+export interface SpatialGridItemState {
+  readonly selected: boolean;
+  readonly focused: boolean;
+  readonly disabled: boolean;
+}
+
+/** Props for the virtualized, free-placement presentation over canonical GridView geometry. */
+export interface SpatialGridProps extends ZoraBaseProps {
+  readonly items: readonly SpatialGridItem[];
+  readonly contentWidth: number;
+  readonly contentHeight: number;
+  readonly width: number;
+  readonly height: number;
+  readonly zoom?: number;
+  readonly overscanPixels?: number;
+  readonly selectedItemId?: string;
+  readonly focusedItemId?: string;
+  readonly revealPaddingPixels?: number;
+  readonly disabled?: boolean;
+  /** Prevents selection and activation while retaining focus and viewport navigation. */
+  readonly readOnly?: boolean;
+  readonly onSelectionChange?: (id: string) => void;
+  readonly onActivation?: (id: string) => void;
+  readonly onFocusChange?: (id: string) => void;
+  readonly onViewportChange?: (viewport: GridViewport) => void;
+  readonly onVisibleItemIdsChange?: (ids: readonly string[]) => void;
+  readonly renderItem: (item: SpatialGridItem, state: SpatialGridItemState) => React.ReactNode;
+}

package/web-dist/chunks/{Accordion-e9ewv367.js → Accordion-60wn9xn9.js}

@@ -6,7 +6,7 @@ import {
   getAxisCategoryTicks,
   getAxisTicks,
   worldToViewport
-} from "./Accordion-e6ddpz5v.js";
+} from "./Accordion-r2w86rwv.js";
 import {
   useZoraTheme2
 } from "./Accordion-srjya6dz.js";

package/web-dist/chunks/{Accordion-q2z00p5r.js → Accordion-nxsda1my.js}

@@ -3,7 +3,7 @@ import {
   getVisibleGridItems,
   revealWorldRect,
   worldToViewport
-} from "./Accordion-e6ddpz5v.js";
+} from "./Accordion-r2w86rwv.js";
 import {
   require_cjs
 } from "./Accordion-xgpzh4wq.js";

package/web-dist/chunks/{Accordion-689w7frk.js → Accordion-s3d6g59s.js}

@@ -1,7 +1,7 @@
 'use client';
 import {
   TileGrid2
-} from "./Accordion-q2z00p5r.js";
+} from "./Accordion-nxsda1my.js";
 import {
   withZoraThemeScope
 } from "./Accordion-42jfy1a1.js";

package/web-dist/components/explorer/Explorer.js

@@ -1,5 +1,5 @@
 'use client';
-import"../../chunks/Accordion-q2z00p5r.js";
+import"../../chunks/Accordion-nxsda1my.js";
 import"../../chunks/Accordion-bfzeab9x.js";
 import"../../chunks/Accordion-6wrr910w.js";
 import"../../chunks/Accordion-8f0nekwe.js";
@@ -14,7 +14,7 @@ import {
   Explorer2,
   FileExplorer2,
   MediaExplorer2
-} from "../../chunks/Accordion-689w7frk.js";
+} from "../../chunks/Accordion-s3d6g59s.js";
 import"../../chunks/Accordion-bff0p3x4.js";
 import"../../chunks/Accordion-srjya6dz.js";
 import"../../chunks/Accordion-184r2r82.js";

package/web-dist/components/file-explorer/FileExplorer.js

@@ -1,5 +1,5 @@
 'use client';
-import"../../chunks/Accordion-q2z00p5r.js";
+import"../../chunks/Accordion-nxsda1my.js";
 import"../../chunks/Accordion-bfzeab9x.js";
 import"../../chunks/Accordion-6wrr910w.js";
 import"../../chunks/Accordion-8f0nekwe.js";
@@ -14,7 +14,7 @@ import {
   Explorer2,
   FileExplorer2,
   MediaExplorer2
-} from "../../chunks/Accordion-689w7frk.js";
+} from "../../chunks/Accordion-s3d6g59s.js";
 import"../../chunks/Accordion-bff0p3x4.js";
 import"../../chunks/Accordion-srjya6dz.js";
 import"../../chunks/Accordion-184r2r82.js";

package/web-dist/components/grid-line-overlay/GridLineOverlay.js

@@ -4,7 +4,7 @@ import"../../chunks/Accordion-42jfy1a1.js";
 import {
   GridLineOverlay2,
   GridRuler2
-} from "../../chunks/Accordion-e9ewv367.js";
+} from "../../chunks/Accordion-60wn9xn9.js";
 import"../../chunks/Accordion-srjya6dz.js";
 import"../../chunks/Accordion-xgpzh4wq.js";
 export {

package/web-dist/components/grid-ruler/GridRuler.js

@@ -4,7 +4,7 @@ import"../../chunks/Accordion-42jfy1a1.js";
 import {
   GridLineOverlay2,
   GridRuler2
-} from "../../chunks/Accordion-e9ewv367.js";
+} from "../../chunks/Accordion-60wn9xn9.js";
 import"../../chunks/Accordion-srjya6dz.js";
 import"../../chunks/Accordion-xgpzh4wq.js";
 export {

package/web-dist/components/grid-view/GridView.js

@@ -2,7 +2,7 @@
 import {
   GridView2,
   TileGrid2
-} from "../../chunks/Accordion-q2z00p5r.js";
+} from "../../chunks/Accordion-nxsda1my.js";
 import"../../chunks/Accordion-xgpzh4wq.js";
 export {
   GridView2 as GridView,