@ankhorage/zora 25.5.0 → 25.6.2

package/src/features/grid-view/adapters/inbound/TileGrid.tsx

@@ -1,3 +1,4 @@
+import type { GridViewport } from '@ankhorage/grid-view';
 import React from 'react';
 import { View as NativeView } from 'react-native';
 
@@ -13,20 +14,29 @@ export function TileGrid({
   tileSize = 120,
   gap = 12,
   zoom = 1,
+  viewport,
+  defaultViewport,
+  viewportConstraints,
+  zoomLimits,
   overscanPixels,
   focusedItemId,
   revealPaddingPixels,
   onColumnsChange,
+  onViewportChange,
   onVisibleItemIdsChange,
   renderItem,
   interactionPolicy,
   testID,
 }: TileGridProps) {
   const [measuredWidth, setMeasuredWidth] = React.useState(0);
+  const [uncontrolledPixelsPerUnitX, setUncontrolledPixelsPerUnitX] = React.useState(
+    () => defaultViewport?.pixelsPerUnitX ?? zoom,
+  );
   const resolvedWidth = width ?? measuredWidth;
+  const pixelsPerUnitX = viewport?.pixelsPerUnitX ?? uncontrolledPixelsPerUnitX;
   const layout = React.useMemo(
-    () => layoutTileGrid(items, resolvedWidth, tileSize, gap, zoom),
-    [items, resolvedWidth, tileSize, gap, zoom],
+    () => layoutTileGrid(items, resolvedWidth, tileSize, gap, pixelsPerUnitX),
+    [gap, items, pixelsPerUnitX, resolvedWidth, tileSize],
   );
   const itemLookup = React.useMemo(() => new Map(items.map((item) => [item.id, item])), [items]);
 
@@ -34,6 +44,14 @@ export function TileGrid({
     if (resolvedWidth > 0) onColumnsChange?.(layout.columns);
   }, [layout.columns, onColumnsChange, resolvedWidth]);
 
+  const handleViewportChange = React.useCallback(
+    (nextViewport: GridViewport) => {
+      if (viewport === undefined) setUncontrolledPixelsPerUnitX(nextViewport.pixelsPerUnitX);
+      onViewportChange?.(nextViewport);
+    },
+    [onViewportChange, viewport],
+  );
+
   return (
     <NativeView
       onLayout={(event) => setMeasuredWidth(event.nativeEvent.layout.width)}
@@ -43,12 +61,14 @@ export function TileGrid({
       {resolvedWidth > 0 ? (
         <GridView
           contentHeight={layout.height}
-          contentWidth={Math.max(resolvedWidth / zoom, layout.width)}
+          contentWidth={Math.max(resolvedWidth / pixelsPerUnitX, layout.width)}
+          defaultViewport={defaultViewport}
           height={height}
           focusedItemId={focusedItemId}
           interactionPolicy={interactionPolicy}
           items={layout.items}
           onVisibleItemIdsChange={onVisibleItemIdsChange}
+          onViewportChange={handleViewportChange}
           overscanPixels={overscanPixels}
           renderItem={(item) => {
             const source = itemLookup.get(item.id);
@@ -56,6 +76,9 @@ export function TileGrid({
           }}
           revealPaddingPixels={revealPaddingPixels}
           width={resolvedWidth}
+          viewport={viewport}
+          viewportConstraints={viewportConstraints}
+          zoomLimits={zoomLimits}
           zoom={zoom}
         />
       ) : null}

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

@@ -0,0 +1,232 @@
+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';
+
+const browserKeys = [
+  'window',
+  'document',
+  'Node',
+  'navigator',
+  'ShadowRoot',
+  'IS_REACT_ACT_ENVIRONMENT',
+] as const;
+const webDistRoot = join(import.meta.dir, '../../../../../web-dist');
+const load = (path: string) => import(pathToFileURL(join(webDistRoot, path)).href);
+
+/*** Mount MatrixGrid through React Native Web and restore the ambient DOM after each assertion. */
+async function withMatrixDom(assertion: (host: HTMLElement, browser: Window) => Promise<void>) {
+  const browser = new Window();
+  const previous = browserKeys.map(
+    (key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)] as const,
+  );
+  Object.assign(globalThis, {
+    IS_REACT_ACT_ENVIRONMENT: true,
+    window: browser,
+    document: browser.document,
+    Node: browser.Node,
+    navigator: browser.navigator,
+    ShadowRoot: browser.ShadowRoot,
+  });
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  try {
+    await assertion(host, browser);
+  } finally {
+    browser.close();
+    for (const [key, descriptor] of previous) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  }
+}
+
+const layout = {
+  columns: Array.from({ length: 100 }, (_, index) => ({
+    id: `column-${index}`,
+    size: 10 + (index % 3),
+  })),
+  rows: Array.from({ length: 100 }, (_, index) => ({ id: `row-${index}`, size: 8 + (index % 4) })),
+};
+
+const cells = layout.rows.flatMap((row) =>
+  layout.columns.map((column) => ({
+    id: `${row.id}-${column.id}`,
+    rowId: row.id,
+    columnId: column.id,
+  })),
+);
+
+type MatrixGridComponent = React.ComponentType<{
+  readonly cells: typeof cells;
+  readonly height: number;
+  readonly layout: typeof layout;
+  readonly onSelectionChange?: (ids: readonly string[]) => void;
+  readonly onViewportChange?: (viewport: unknown) => void;
+  readonly renderCell: (cell: { readonly id: string }) => React.ReactNode;
+  readonly selectedCellIds?: readonly string[];
+  readonly selectionMode?: 'multi';
+  readonly testID: string;
+  readonly viewport?: {
+    readonly height: number;
+    readonly offsetX: number;
+    readonly offsetY: number;
+    readonly pixelsPerUnitX: number;
+    readonly pixelsPerUnitY: number;
+    readonly width: number;
+  };
+  readonly width: number;
+  readonly zoomX?: number;
+  readonly zoomY?: number;
+}>;
+
+type ZoraProviderComponent = React.ComponentType<{ readonly children: React.ReactNode }>;
+
+test('mounts only visible sparse cells with independent axis zoom and preserves native-web selection', async () => {
+  await withMatrixDom(async (host, browser) => {
+    const selected: (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;
+    };
+    try {
+      act(() =>
+        root.render(
+          <ZoraProvider>
+            <MatrixGrid
+              cells={cells}
+              height={96}
+              layout={layout}
+              selectedCellIds={[]}
+              selectionMode="multi"
+              testID="matrix"
+              viewport={{
+                height: 96,
+                offsetX: 0,
+                offsetY: 0,
+                pixelsPerUnitX: 2,
+                pixelsPerUnitY: 3,
+                width: 120,
+              }}
+              width={120}
+              onSelectionChange={(ids) => selected.push(ids)}
+              renderCell={(cell) => <span>{cell.id}</span>}
+            />
+          </ZoraProvider>,
+        ),
+      );
+      const mountedCells = host.querySelectorAll('[data-testid^="matrix-cell-"]');
+      expect(cells).toHaveLength(10_000);
+      expect(mountedCells.length).toBeGreaterThan(1);
+      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');
+      void act(() => target?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true })));
+      expect(selected).toEqual([['row-1-column-1']]);
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});
+
+test('does not propose controlled viewports on mount or fresh parent callback identities', async () => {
+  await withMatrixDom(async (host) => {
+    const proposals: unknown[] = [];
+    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 render = () => (
+      <ZoraProvider>
+        <MatrixGrid
+          cells={cells}
+          height={96}
+          layout={layout}
+          testID="controlled-matrix"
+          viewport={{
+            height: 96,
+            offsetX: 0,
+            offsetY: 0,
+            pixelsPerUnitX: 2,
+            pixelsPerUnitY: 3,
+            width: 120,
+          }}
+          width={120}
+          onViewportChange={(proposal) => proposals.push(proposal)}
+          renderCell={(cell) => <span>{cell.id}</span>}
+        />
+      </ZoraProvider>
+    );
+    try {
+      act(() => root.render(render()));
+      act(() => root.render(render()));
+      expect(proposals).toEqual([]);
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});
+
+test('proposes an uncontrolled horizontal pan in world units while retaining independent axis zoom', async () => {
+  await withMatrixDom(async (host, browser) => {
+    const proposals: unknown[] = [];
+    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;
+    };
+    try {
+      act(() =>
+        root.render(
+          <ZoraProvider>
+            <MatrixGrid
+              cells={cells}
+              height={96}
+              layout={layout}
+              testID="uncontrolled-matrix"
+              width={120}
+              zoomX={2}
+              zoomY={3}
+              onViewportChange={(proposal) => proposals.push(proposal)}
+              renderCell={(cell) => <span>{cell.id}</span>}
+            />
+          </ZoraProvider>,
+        ),
+      );
+      const horizontalScroll = host.querySelector(
+        '[data-testid="uncontrolled-matrix-horizontal-scroll"]',
+      );
+      if (!horizontalScroll) throw new Error('Missing MatrixGrid horizontal scroll viewport.');
+      horizontalScroll.scrollLeft = 40;
+      await act(async () => {
+        horizontalScroll.dispatchEvent(new browser.Event('scroll', { bubbles: true }));
+        await new Promise<void>((resolve) => browser.setTimeout(resolve, 200));
+      });
+      expect(proposals).toEqual([
+        {
+          height: 96,
+          offsetX: 20,
+          offsetY: 0,
+          pixelsPerUnitX: 2,
+          pixelsPerUnitY: 3,
+          width: 120,
+        },
+      ]);
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});

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

@@ -0,0 +1,142 @@
+import {
+  getVisibleMatrixCells,
+  type GridMatrixCellPlacement,
+  type GridViewport,
+} from '@ankhorage/grid-view';
+import { Pressable } from '@ankhorage/surface';
+import React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import type { MatrixGridProps } from '../../../../types/matrix-grid';
+import { GridView } from '../../../grid-view/public';
+import { resolveSelectionEventIntent } from '../../../selection/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
+import { resolveMatrixGridContentSize } from '../../application/resolveMatrixGridContentSize';
+import { resolveMatrixGridSelection } from '../../application/resolveMatrixGridSelection';
+
+/*** Compose the canonical GridView around released sparse matrix placement and culling geometry. */
+function MatrixGridInner({
+  accessibilityLabel = 'Matrix grid',
+  cells,
+  height,
+  interactionPolicy,
+  layout,
+  onSelectionChange,
+  onViewportChange,
+  overscanPixels = 160,
+  renderCell,
+  selectedCellIds = [],
+  selectionMode = 'single',
+  testID,
+  viewport: controlledViewport,
+  width,
+  zoomX = 1,
+  zoomY = 1,
+}: MatrixGridProps) {
+  const { theme } = useZoraTheme();
+  const contentSize = React.useMemo(() => resolveMatrixGridContentSize(layout), [layout]);
+  const initialViewport = React.useMemo<GridViewport>(
+    () => ({ height, offsetX: 0, offsetY: 0, pixelsPerUnitX: zoomX, pixelsPerUnitY: zoomY, width }),
+    [height, width, zoomX, zoomY],
+  );
+  const [uncontrolledViewport, setUncontrolledViewport] = React.useState(initialViewport);
+  const viewport = controlledViewport ?? uncontrolledViewport;
+  const visibleCells = React.useMemo(
+    () => getVisibleMatrixCells(layout, cells, viewport, overscanPixels),
+    [cells, layout, overscanPixels, viewport],
+  );
+
+  const visibleCellById = React.useMemo(
+    () => new Map(visibleCells.map((cell) => [cell.id, cell])),
+    [visibleCells],
+  );
+
+  const handleViewportChange = React.useCallback(
+    (proposal: GridViewport) => {
+      if (controlledViewport === undefined) setUncontrolledViewport(proposal);
+      onViewportChange?.(proposal);
+    },
+    [controlledViewport, onViewportChange],
+  );
+
+  const activateCell = React.useCallback(
+    (cell: GridMatrixCellPlacement, event: unknown) => {
+      if (interactionPolicy === 'passive') return;
+      const intent = resolveSelectionEventIntent(event, 'pointer');
+      onSelectionChange?.(
+        resolveMatrixGridSelection(selectedCellIds, cell.id, intent, selectionMode),
+      );
+    },
+    [interactionPolicy, onSelectionChange, selectedCellIds, selectionMode],
+  );
+  return (
+    <View accessibilityLabel={accessibilityLabel}>
+      <GridView
+        contentHeight={contentSize.height}
+        contentWidth={contentSize.width}
+        height={height}
+        interactionPolicy={interactionPolicy}
+        items={visibleCells}
+        overscanPixels={0}
+        renderItem={(item) => {
+          const cell = visibleCellById.get(item.id);
+          if (!cell) return null;
+          return renderMatrixCell(
+            cell,
+            selectedCellIds,
+            theme.semantics.neutral.divider,
+            theme.colors.primary,
+            renderCell,
+            activateCell,
+            testID,
+          );
+        }}
+        testID={testID}
+        viewport={viewport}
+        width={width}
+        onViewportChange={handleViewportChange}
+      />
+    </View>
+  );
+}
+
+/*** Render one positioned sparse cell with native/web accessible selection semantics. */
+function renderMatrixCell(
+  cell: GridMatrixCellPlacement,
+  selectedCellIds: readonly string[],
+  dividerColor: string,
+  selectedColor: string,
+  renderCell: MatrixGridProps['renderCell'],
+  activateCell: (cell: GridMatrixCellPlacement, event: unknown) => void,
+  testID: string | undefined,
+) {
+  const selected = selectedCellIds.includes(cell.id);
+  return (
+    <Pressable
+      key={cell.id}
+      accessibilityLabel={`Cell ${cell.id}`}
+      accessibilityRole="button"
+      accessibilityState={{ selected }}
+      style={[
+        styles.cell,
+        {
+          borderColor: selected ? selectedColor : dividerColor,
+          height: '100%',
+          width: '100%',
+        },
+      ]}
+      testID={testID === undefined ? undefined : `${testID}-cell-${cell.id}`}
+      onPress={(event) => activateCell(cell, event)}
+    >
+      {renderCell(cell)}
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  cell: { borderWidth: 1, height: '100%', overflow: 'hidden', width: '100%' },
+});
+
+/*** A code-first generic sparse matrix grid; formulas and domain vocabulary remain external. */
+export const MatrixGrid = withZoraThemeScope(MatrixGridInner);

package/src/features/matrix-grid/application/resolveMatrixGridContentSize.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveMatrixGridContentSize } from './resolveMatrixGridContentSize';
+
+describe('resolveMatrixGridContentSize', () => {
+  test('sums variable matrix axes without materializing logical cells', () => {
+    expect(
+      resolveMatrixGridContentSize({
+        columns: [
+          { id: 'beat', size: 40 },
+          { id: 'bar', size: 60 },
+        ],
+        rows: [
+          { id: 'bass', size: 24 },
+          { id: 'lead', size: 36 },
+        ],
+      }),
+    ).toEqual({ height: 60, width: 100 });
+  });
+
+  test('rejects non-finite cumulative axis geometry through the published grid-view contract', () => {
+    expect(() =>
+      resolveMatrixGridContentSize({
+        columns: [
+          { id: 'left', size: Number.MAX_VALUE },
+          { id: 'right', size: Number.MAX_VALUE },
+        ],
+        rows: [{ id: 'row', size: 1 }],
+      }),
+    ).toThrow('Layout axis cumulative world coordinates must be finite.');
+  });
+});

package/src/features/matrix-grid/application/resolveMatrixGridContentSize.ts

@@ -0,0 +1,28 @@
+import {
+  getMatrixCellPlacement,
+  getVisibleMatrixCells,
+  type GridMatrixLayout,
+} from '@ankhorage/grid-view';
+
+/*** Resolve total sparse-matrix world extents without expanding its logical cells. */
+export function resolveMatrixGridContentSize(layout: GridMatrixLayout) {
+  const finalRow = layout.rows.at(-1);
+  const finalColumn = layout.columns.at(-1);
+  if (!finalRow || !finalColumn) {
+    getVisibleMatrixCells(layout, [], {
+      height: 1,
+      offsetX: 0,
+      offsetY: 0,
+      pixelsPerUnitX: 1,
+      pixelsPerUnitY: 1,
+      width: 1,
+    });
+    return { height: 0, width: 0 };
+  }
+  const finalCell = getMatrixCellPlacement(layout, {
+    id: 'matrix-grid-content-boundary',
+    rowId: finalRow.id,
+    columnId: finalColumn.id,
+  });
+  return { height: finalCell.y + finalCell.height, width: finalCell.x + finalCell.width };
+}

package/src/features/matrix-grid/application/resolveMatrixGridSelection.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveMatrixGridSelection } from './resolveMatrixGridSelection';
+
+describe('resolveMatrixGridSelection', () => {
+  test('preserves the canonical single and multi selection intent rules', () => {
+    expect(resolveMatrixGridSelection(['a'], 'b', 'toggle', 'single')).toEqual(['b']);
+    expect(resolveMatrixGridSelection(['a'], 'b', 'toggle', 'multi')).toEqual(['a', 'b']);
+  });
+});

package/src/features/matrix-grid/application/resolveMatrixGridSelection.ts

@@ -0,0 +1,15 @@
+import { applySelectionIntent, type SelectionIntent } from '@ankhorage/utility/selection';
+
+import type { SelectionMode } from '../../../types/selection';
+
+/*** Apply ZORA's canonical selection intent while retaining the configured selection mode. */
+export function resolveMatrixGridSelection(
+  selectedIds: readonly string[],
+  cellId: string,
+  intent: SelectionIntent,
+  mode: SelectionMode,
+): readonly string[] {
+  return mode === 'single'
+    ? applySelectionIntent(selectedIds, cellId, 'replace')
+    : applySelectionIntent(selectedIds, cellId, intent);
+}

package/src/features/matrix-grid/application/resolveMatrixGridVisibleCells.test.ts

@@ -0,0 +1,35 @@
+import { getMatrixCellPlacement, getVisibleMatrixCells } from '@ankhorage/grid-view';
+import { describe, expect, test } from 'bun:test';
+
+describe('MatrixGrid sparse geometry', () => {
+  test('culls a 10k sparse cell catalogue in a million-cell logical matrix', () => {
+    const layout = {
+      columns: Array.from({ length: 1000 }, (_, index) => ({ id: `column-${index}`, size: 20 })),
+      rows: Array.from({ length: 1000 }, (_, index) => ({
+        id: `row-${index}`,
+        size: index % 2 === 0 ? 16 : 24,
+      })),
+    };
+    const cells = Array.from({ length: 10001 }, (_, index) => ({
+      columnId: `column-${(index * 37) % 1000}`,
+      id: `cell-${index}`,
+      rowId: `row-${(index * 91) % 1000}`,
+    }));
+
+    const firstCell = cells.at(0);
+    if (!firstCell) throw new Error('The sparse test catalogue must contain a first cell.');
+    const first = getMatrixCellPlacement(layout, firstCell);
+    const visible = getVisibleMatrixCells(layout, cells, {
+      height: 120,
+      offsetX: first.x,
+      offsetY: first.y,
+      pixelsPerUnitX: 1,
+      pixelsPerUnitY: 1,
+      width: 120,
+    });
+
+    expect(first).toMatchObject({ id: 'cell-0', width: 20 });
+    expect(visible.length).toBeLessThan(cells.length);
+    expect(visible.every((cell) => cell.width === 20 && cell.height > 0)).toBe(true);
+  });
+});

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

@@ -0,0 +1,12 @@
+import type { ZoraComponentMeta } from '../../types/authoring';
+
+/** Code-only rendering and non-serializable cell callbacks stay outside manifest authoring. */
+export const matrixGridMeta = {
+  name: 'MatrixGrid',
+  category: 'foundation',
+  description: 'Virtualized sparse matrix renderer for executable code APIs.',
+  directManifestNode: false,
+  note: 'Requires a renderCell callback and is intentionally code-only.',
+  allowedChildren: [],
+  props: {},
+} as const satisfies ZoraComponentMeta;

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

@@ -0,0 +1,3 @@
+export type { MatrixGridProps } from '../../types/matrix-grid';
+export { MatrixGrid } from './adapters/inbound/MatrixGrid';
+export { resolveMatrixGridContentSize } from './application/resolveMatrixGridContentSize';

package/src/features/registry/ZORA_COMPONENT_REGISTRY.ts

@@ -55,6 +55,7 @@ import { Image } from '../image/public';
 import { KeyboardAvoidingView } from '../keyboard-avoiding-view/public';
 import { AppShell, Divider, Grid, Screen, ScrollView, View } from '../layout/public';
 import { FlatList, List, ListItem, ListSection, SectionList } from '../list/public';
+import { MatrixGrid } from '../matrix-grid/public';
 import { MissingElement } from '../missing-element/public';
 import { Pagination } from '../pagination/public';
 import { PaletteItem } from '../palette-item/public';
@@ -202,6 +203,7 @@ const _ZORA_COMPONENT_REGISTRY = {
   GridView,
   TileGrid,
   TimeGrid,
+  MatrixGrid,
   MediaExplorer,
   Hero,
   List,

package/src/features/registry/componentMeta.ts

@@ -68,6 +68,7 @@ import { viewMeta } from '../layout/viewMeta';
 import { flatListMeta } from '../list/flatListMeta';
 import { listItemMeta, listMeta, listSectionMeta } from '../list/meta';
 import { sectionListMeta } from '../list/sectionListMeta';
+import { matrixGridMeta } from '../matrix-grid/meta';
 import { missingElementMeta } from '../missing-element/missingElementMeta';
 import { paginationMeta } from '../pagination/paginationMeta';
 import { paletteItemMeta } from '../palette-item/paletteItemMeta';
@@ -206,6 +207,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   GridView: gridViewMeta,
   TileGrid: tileGridMeta,
   TimeGrid: timeGridMeta,
+  MatrixGrid: matrixGridMeta,
   Hero: heroMeta,
   List: listMeta,
   ListItem: listItemMeta,