@ankhorage/zora 25.6.2 → 25.8.0

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

@@ -1,19 +1,23 @@
 import {
+  getMatrixCellPlacement,
   getVisibleMatrixCells,
   type GridMatrixCellPlacement,
   type GridViewport,
 } from '@ankhorage/grid-view';
-import { Pressable } from '@ankhorage/surface';
+import { isRecord } from '@ankhorage/utility/object';
 import React from 'react';
-import { StyleSheet, View } from 'react-native';
+import { Platform, Pressable as NativePressable, 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 { createMatrixGridSparseIndex } from '../../application/createMatrixGridSparseIndex';
 import { resolveMatrixGridContentSize } from '../../application/resolveMatrixGridContentSize';
 import { resolveMatrixGridSelection } from '../../application/resolveMatrixGridSelection';
+import { MatrixGridKeyboardProxy } from './MatrixGridKeyboardProxy';
+import { useMatrixGridKeyboardFocus } from './useMatrixGridKeyboardFocus';
 
 /*** Compose the canonical GridView around released sparse matrix placement and culling geometry. */
 function MatrixGridInner({
@@ -25,6 +29,7 @@ function MatrixGridInner({
   onSelectionChange,
   onViewportChange,
   overscanPixels = 160,
+  readOnly = false,
   renderCell,
   selectedCellIds = [],
   selectionMode = 'single',
@@ -42,15 +47,16 @@ function MatrixGridInner({
   );
   const [uncontrolledViewport, setUncontrolledViewport] = React.useState(initialViewport);
   const viewport = controlledViewport ?? uncontrolledViewport;
-  const visibleCells = React.useMemo(
+  const sparseIndex = React.useMemo(
+    () => createMatrixGridSparseIndex(layout, cells),
+    [cells, layout],
+  );
+  const cellPlacements = 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 [visibleIds, setVisibleIds] = React.useState<readonly string[]>([]);
+  const anchorId = React.useRef<string | null>(null);
 
   const handleViewportChange = React.useCallback(
     (proposal: GridViewport) => {
@@ -62,14 +68,63 @@ function MatrixGridInner({
 
   const activateCell = React.useCallback(
     (cell: GridMatrixCellPlacement, event: unknown) => {
-      if (interactionPolicy === 'passive') return;
-      const intent = resolveSelectionEventIntent(event, 'pointer');
+      if (interactionPolicy === 'passive' || readOnly) return;
+      const intent = isRangeSelectionEvent(event)
+        ? 'range'
+        : resolveSelectionEventIntent(event, 'pointer');
       onSelectionChange?.(
-        resolveMatrixGridSelection(selectedCellIds, cell.id, intent, selectionMode),
+        resolveMatrixGridSelection(
+          sparseIndex.entries,
+          selectedCellIds,
+          cell.id,
+          anchorId.current,
+          intent,
+          selectionMode,
+        ),
       );
+      if (intent !== 'range') anchorId.current = cell.id;
     },
-    [interactionPolicy, onSelectionChange, selectedCellIds, selectionMode],
+    [
+      interactionPolicy,
+      onSelectionChange,
+      readOnly,
+      selectedCellIds,
+      selectionMode,
+      sparseIndex.entries,
+    ],
+  );
+  const handleKeyboardNavigation = React.useCallback(
+    (targetId: string, originId: string, shiftKey: boolean) => {
+      anchorId.current ??= originId;
+      if (!shiftKey) return;
+      const cell = sparseIndex.cellById.get(targetId);
+      if (cell) activateCell(getMatrixCellPlacement(layout, cell), { shiftKey: true });
+    },
+    [activateCell, layout, sparseIndex],
+  );
+  const keyboard = useMatrixGridKeyboardFocus(
+    sparseIndex,
+    interactionPolicy === 'passive',
+    visibleIds,
+    handleKeyboardNavigation,
+  );
+  const focusedPlacement = React.useMemo(() => {
+    const focusedCell =
+      keyboard.focusedId === null ? undefined : sparseIndex.cellById.get(keyboard.focusedId);
+    return focusedCell ? getMatrixCellPlacement(layout, focusedCell) : undefined;
+  }, [keyboard.focusedId, layout, sparseIndex.cellById]);
+  const gridItems = React.useMemo(
+    () =>
+      focusedPlacement && !cellPlacements.some((cell) => cell.id === focusedPlacement.id)
+        ? [...cellPlacements, focusedPlacement]
+        : cellPlacements,
+    [cellPlacements, focusedPlacement],
   );
+  const cellById = React.useMemo(
+    () => new Map(gridItems.map((cell) => [cell.id, cell])),
+    [gridItems],
+  );
+
   return (
     <View accessibilityLabel={accessibilityLabel}>
       <GridView
@@ -77,10 +132,12 @@ function MatrixGridInner({
         contentWidth={contentSize.width}
         height={height}
         interactionPolicy={interactionPolicy}
-        items={visibleCells}
+        items={gridItems}
+        focusedItemId={keyboard.focusedId ?? undefined}
         overscanPixels={0}
+        onVisibleItemIdsChange={setVisibleIds}
         renderItem={(item) => {
-          const cell = visibleCellById.get(item.id);
+          const cell = cellById.get(item.id);
           if (!cell) return null;
           return renderMatrixCell(
             cell,
@@ -89,6 +146,9 @@ function MatrixGridInner({
             theme.colors.primary,
             renderCell,
             activateCell,
+            keyboard,
+            interactionPolicy === 'passive',
+            readOnly,
             testID,
           );
         }}
@@ -109,28 +169,58 @@ function renderMatrixCell(
   selectedColor: string,
   renderCell: MatrixGridProps['renderCell'],
   activateCell: (cell: GridMatrixCellPlacement, event: unknown) => void,
+  keyboard: ReturnType<typeof useMatrixGridKeyboardFocus>,
+  passive: boolean,
+  readOnly: boolean,
   testID: string | undefined,
 ) {
   const selected = selectedCellIds.includes(cell.id);
+  const canInteract = keyboard.tabStopId === 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)}
+    <MatrixGridKeyboardProxy
+      onKeyDown={(event) => {
+        if (keyboard.onKeyDown(cell.id, event.key, event.shiftKey)) return true;
+        if (!['Enter', ' '].includes(event.key)) return false;
+        if (passive || readOnly) return false;
+        activateCell(cell, event);
+        return true;
+      }}
     >
-      {renderCell(cell)}
-    </Pressable>
+      <NativePressable
+        key={cell.id}
+        accessibilityActions={[{ name: 'activate' }]}
+        accessibilityLabel={`Cell ${cell.id}`}
+        accessibilityRole="button"
+        accessibilityState={{ disabled: passive, selected }}
+        disabled={passive}
+        focusable={Platform.OS !== 'web' || canInteract}
+        style={[
+          styles.cell,
+          {
+            borderColor: selected || keyboard.focusedId === cell.id ? selectedColor : dividerColor,
+            height: '100%',
+            width: '100%',
+          },
+        ]}
+        testID={testID === undefined ? undefined : `${testID}-cell-${cell.id}`}
+        onAccessibilityAction={() => activateCell(cell, {})}
+        onFocus={() => keyboard.onFocus(cell.id)}
+        onPress={(event) => activateCell(cell, event)}
+        ref={(node) => keyboard.registerCell(cell.id, node)}
+      >
+        {renderCell(cell)}
+      </NativePressable>
+    </MatrixGridKeyboardProxy>
+  );
+}
+
+/*** Recognize range intent without changing the shared replace-or-toggle selection contract. */
+function isRangeSelectionEvent(event: unknown): boolean {
+  if (!isRecord(event)) return false;
+  if (event.shiftKey === true) return true;
+  return (
+    (isRecord(event.nativeEvent) && event.nativeEvent.shiftKey === true) ||
+    (isRecord(event.originalEvent) && event.originalEvent.shiftKey === true)
   );
 }
 

package/src/features/matrix-grid/adapters/inbound/MatrixGridKeyboardProxy.native.tsx

@@ -0,0 +1,11 @@
+import type React from 'react';
+
+/*** Retain native accessibility focus while physical-key dispatch remains a web host concern. */
+export function MatrixGridKeyboardProxy({ children }: MatrixGridKeyboardProxyProps) {
+  return <>{children}</>;
+}
+
+interface MatrixGridKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => boolean;
+}

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

@@ -0,0 +1,11 @@
+import type React from 'react';
+
+/*** Provides the native fallback type surface; RNW resolves the web adapter at runtime. */
+export function MatrixGridKeyboardProxy({ children }: MatrixGridKeyboardProxyProps) {
+  return <>{children}</>;
+}
+
+interface MatrixGridKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => boolean;
+}

package/src/features/matrix-grid/adapters/inbound/MatrixGridKeyboardProxy.web.tsx

@@ -0,0 +1,43 @@
+import type React from 'react';
+
+/*** Bridge browser keyboard events into the matrix's platform-neutral focus policy. */
+export function MatrixGridKeyboardProxy({ children, onKeyDown }: MatrixGridKeyboardProxyProps) {
+  return (
+    <div
+      onKeyDownCapture={(event) => {
+        if (isNestedInteractiveElement(event.target, event.currentTarget)) return;
+        if (onKeyDown(event)) event.preventDefault();
+      }}
+      style={{ display: 'flex', flex: 1 }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/*** Leave editable and independently interactive cell content in control of its own keyboard events. */
+function isNestedInteractiveElement(target: EventTarget, boundary: EventTarget): boolean {
+  if (target === boundary || !hasClosest(target)) return false;
+  const interactiveElement = target.closest(interactiveSelector);
+  return interactiveElement !== null && interactiveElement !== getFirstElementChild(boundary);
+}
+
+/*** Recognize the browser-only closest capability without leaking DOM globals into shared code. */
+function hasClosest(
+  target: EventTarget,
+): target is EventTarget & { closest: (selector: string) => unknown } {
+  return 'closest' in target && typeof target.closest === 'function';
+}
+
+/*** Exempt the cell's own Pressable while preserving keyboard ownership for nested controls. */
+function getFirstElementChild(boundary: EventTarget): unknown {
+  return 'firstElementChild' in boundary ? boundary.firstElementChild : undefined;
+}
+
+const interactiveSelector =
+  'a, button, input, select, textarea, [contenteditable="true"], [role="button"], [role="checkbox"], [role="combobox"], [role="link"], [role="menuitem"], [role="option"], [role="slider"], [role="spinbutton"], [role="switch"], [role="tab"]';
+
+interface MatrixGridKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => boolean;
+}

package/src/features/matrix-grid/adapters/inbound/useMatrixGridKeyboardFocus.ts

@@ -0,0 +1,70 @@
+import React from 'react';
+
+import type { MatrixGridSparseIndex } from '../../application/createMatrixGridSparseIndex';
+import { getMatrixGridNextFocusId } from '../../application/getMatrixGridNextFocusId';
+
+/*** Keep one roving focus target and restore it after GridView virtualizes a sparse cell. */
+export function useMatrixGridKeyboardFocus(
+  index: MatrixGridSparseIndex,
+  disabled: boolean,
+  visibleIds: readonly string[],
+  onNavigate: (targetId: string, originId: string, shiftKey: boolean) => void,
+) {
+  const [focusedId, setFocusedId] = React.useState<string | null>(null);
+  const focusedRef = React.useRef<string | null>(null);
+  const pendingFocusRef = React.useRef<string | null>(null);
+  const cellRefs = React.useRef(new Map<string, FocusableCell>());
+  const visibleIdSet = React.useMemo(() => new Set(visibleIds), [visibleIds]);
+  const tabStopId =
+    focusedId !== null && visibleIdSet.has(focusedId)
+      ? focusedId
+      : visibleIds.find((id) => index.positionById.has(id));
+
+  const onFocus = React.useCallback((id: string) => {
+    pendingFocusRef.current = null;
+    focusedRef.current = id;
+    setFocusedId(id);
+  }, []);
+
+  const registerCell = React.useCallback((id: string, node: FocusableCell | null) => {
+    if (node === null) {
+      cellRefs.current.delete(id);
+      return;
+    }
+    cellRefs.current.set(id, node);
+    if (pendingFocusRef.current === id) {
+      pendingFocusRef.current = null;
+      node.focus();
+    }
+  }, []);
+
+  const onKeyDown = React.useCallback(
+    (id: string, key: string, shiftKey: boolean): boolean => {
+      if (disabled || !['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'].includes(key)) {
+        return false;
+      }
+      const originId = focusedRef.current ?? id;
+      const nextId = getMatrixGridNextFocusId(index, originId, key);
+      if (nextId === null || nextId === originId) return true;
+
+      focusedRef.current = nextId;
+      pendingFocusRef.current = nextId;
+      setFocusedId(nextId);
+      onNavigate(nextId, originId, shiftKey);
+
+      const mounted = cellRefs.current.get(nextId);
+      if (mounted) {
+        pendingFocusRef.current = null;
+        mounted.focus();
+      }
+      return true;
+    },
+    [disabled, index, onNavigate],
+  );
+
+  return { focusedId, onFocus, onKeyDown, registerCell, tabStopId };
+}
+
+interface FocusableCell {
+  focus: () => void;
+}

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

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'bun:test';
+
+import { createMatrixGridSparseIndex } from './createMatrixGridSparseIndex';
+import { getMatrixGridNextFocusId } from './getMatrixGridNextFocusId';
+
+describe('createMatrixGridSparseIndex', () => {
+  test('indexes more than 10k sparse cells without creating placement rectangles', () => {
+    const layout = {
+      columns: Array.from({ length: 1_000 }, (_, index) => ({ id: `column-${index}`, size: 10 })),
+      rows: Array.from({ length: 1_000 }, (_, index) => ({ id: `row-${index}`, size: 10 })),
+    };
+    const cells = layout.rows.flatMap((row) =>
+      layout.columns.slice(0, 10).map((column) => ({
+        columnId: column.id,
+        id: `${row.id}-${column.id}`,
+        rowId: row.id,
+      })),
+    );
+    const index = createMatrixGridSparseIndex(layout, [...cells].reverse());
+
+    expect(index.entries).toHaveLength(10_000);
+    expect(index.entries[0]).toEqual({
+      cell: cells.at(-1),
+      columnIndex: 9,
+      id: 'row-999-column-9',
+      rowIndex: 999,
+    });
+    expect(getMatrixGridNextFocusId(index, 'row-500-column-5', 'ArrowRight')).toBe(
+      'row-500-column-6',
+    );
+    expect(getMatrixGridNextFocusId(index, 'row-500-column-5', 'ArrowDown')).toBe(
+      'row-501-column-5',
+    );
+  });
+});

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

@@ -0,0 +1,105 @@
+import type { GridMatrixCell, GridMatrixLayout } from '@ankhorage/grid-view';
+
+/*** Build a geometry-independent lookup for sparse matrix navigation, selection, and focus recovery. */
+export function createMatrixGridSparseIndex(
+  layout: GridMatrixLayout,
+  cells: readonly GridMatrixCell[],
+): MatrixGridSparseIndex {
+  const rowIndexes = new Map(layout.rows.map((row, index) => [row.id, index]));
+  const columnIndexes = new Map(layout.columns.map((column, index) => [column.id, index]));
+  const entries = cells.map((cell) => createSparseEntry(cell, rowIndexes, columnIndexes));
+  const entriesByRow = groupEntries(entries, 'columnIndex');
+  const entriesByColumn = groupEntries(entries, 'rowIndex');
+  const orderedEntries = [...entries].sort(compareRowThenColumn);
+
+  return {
+    cellById: new Map(entries.map((entry) => [entry.id, entry.cell])),
+    entries,
+    entriesByColumn,
+    entriesByRow,
+    firstId: orderedEntries.at(0)?.id ?? null,
+    positionById: new Map(entries.map((entry) => [entry.id, entry])),
+  };
+}
+
+/*** Resolve validated matrix coordinates once without materializing every cell rectangle. */
+function createSparseEntry(
+  cell: GridMatrixCell,
+  rowIndexes: ReadonlyMap<string, number>,
+  columnIndexes: ReadonlyMap<string, number>,
+): MatrixGridSparseIndexEntry {
+  const rowIndex = rowIndexes.get(cell.rowId);
+  const columnIndex = columnIndexes.get(cell.columnId);
+  if (rowIndex === undefined || columnIndex === undefined) {
+    throw new Error(`Matrix cell ${cell.id} references an unknown row or column.`);
+  }
+  return { cell, columnIndex, id: cell.id, rowIndex };
+}
+
+/*** Group and sort directional neighbours so arrow navigation is logarithmic within one axis. */
+function groupEntries(
+  entries: readonly MatrixGridSparseIndexEntry[],
+  axis: 'columnIndex' | 'rowIndex',
+): ReadonlyMap<number, readonly MatrixGridSparseIndexEntry[]> {
+  const groups = new Map<number, MatrixGridSparseIndexEntry[]>();
+  for (const entry of entries) {
+    const groupKey = axis === 'columnIndex' ? entry.rowIndex : entry.columnIndex;
+    const group = groups.get(groupKey) ?? [];
+    group.push(entry);
+    groups.set(groupKey, group);
+  }
+  return new Map(
+    [...groups].map(([key, group]) => [
+      key,
+      group.sort((left, right) => compareAxisThenId(left, right, axis)),
+    ]),
+  );
+}
+
+/*** Keep the initial roving target deterministic even when sparse input arrives in arbitrary order. */
+function compareRowThenColumn(
+  left: MatrixGridSparseIndexEntry,
+  right: MatrixGridSparseIndexEntry,
+): number {
+  return (
+    left.rowIndex - right.rowIndex ||
+    left.columnIndex - right.columnIndex ||
+    left.id.localeCompare(right.id)
+  );
+}
+
+/*** Sort a row or column by its navigated coordinate and stable identity. */
+function compareAxisThenId(
+  left: MatrixGridSparseIndexEntry,
+  right: MatrixGridSparseIndexEntry,
+  axis: 'columnIndex' | 'rowIndex',
+): number {
+  return (
+    getAxisCoordinate(left, axis) - getAxisCoordinate(right, axis) ||
+    left.id.localeCompare(right.id)
+  );
+}
+
+/*** Read a selected coordinate without dynamically indexing an object. */
+function getAxisCoordinate(
+  entry: MatrixGridSparseIndexEntry,
+  axis: 'columnIndex' | 'rowIndex',
+): number {
+  return axis === 'columnIndex' ? entry.columnIndex : entry.rowIndex;
+}
+
+export type MatrixGridSparseIndex = Readonly<{
+  cellById: ReadonlyMap<string, GridMatrixCell>;
+  entries: readonly MatrixGridSparseIndexEntry[];
+  entriesByColumn: ReadonlyMap<number, readonly MatrixGridSparseIndexEntry[]>;
+  entriesByRow: ReadonlyMap<number, readonly MatrixGridSparseIndexEntry[]>;
+  firstId: string | null;
+  positionById: ReadonlyMap<string, MatrixGridSparseIndexEntry>;
+}>;
+
+export type MatrixGridSparseIndexEntry = Readonly<{
+  cell: GridMatrixCell;
+  columnIndex: number;
+  id: string;
+  rowIndex: number;
+}>;

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

@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'bun:test';
+
+import { createMatrixGridSparseIndex } from './createMatrixGridSparseIndex';
+import { getMatrixGridNextFocusId } from './getMatrixGridNextFocusId';
+
+const cells = [
+  {
+    columnId: 'a',
+    columnIndex: 0,
+    height: 1,
+    id: 'a1',
+    rowId: '1',
+    rowIndex: 0,
+    width: 1,
+    x: 0,
+    y: 0,
+  },
+  {
+    columnId: 'c',
+    columnIndex: 2,
+    height: 1,
+    id: 'c1',
+    rowId: '1',
+    rowIndex: 0,
+    width: 1,
+    x: 2,
+    y: 0,
+  },
+  {
+    columnId: 'a',
+    columnIndex: 0,
+    height: 1,
+    id: 'a3',
+    rowId: '3',
+    rowIndex: 2,
+    width: 1,
+    x: 0,
+    y: 2,
+  },
+  {
+    columnId: 'c',
+    columnIndex: 2,
+    height: 1,
+    id: 'c3',
+    rowId: '3',
+    rowIndex: 2,
+    width: 1,
+    x: 2,
+    y: 2,
+  },
+] as const;
+
+const layout = {
+  columns: [
+    { id: 'a', size: 1 },
+    { id: 'b', size: 1 },
+    { id: 'c', size: 1 },
+  ],
+  rows: [
+    { id: '1', size: 1 },
+    { id: '2', size: 1 },
+    { id: '3', size: 1 },
+  ],
+} as const;
+
+const index = createMatrixGridSparseIndex(layout, cells);
+
+describe('getMatrixGridNextFocusId', () => {
+  test('moves over sparse rows and columns without materializing missing cells', () => {
+    expect(getMatrixGridNextFocusId(index, 'a1', 'ArrowRight')).toBe('c1');
+    expect(getMatrixGridNextFocusId(index, 'c3', 'ArrowLeft')).toBe('a3');
+    expect(getMatrixGridNextFocusId(index, 'a1', 'ArrowDown')).toBe('a3');
+    expect(getMatrixGridNextFocusId(index, 'c3', 'ArrowUp')).toBe('c1');
+  });
+
+  test('retains focus at a sparse edge and initializes from the first real cell', () => {
+    expect(getMatrixGridNextFocusId(index, 'a1', 'ArrowLeft')).toBe('a1');
+    expect(getMatrixGridNextFocusId(index, null, 'ArrowRight')).toBe('a1');
+    expect(
+      getMatrixGridNextFocusId(createMatrixGridSparseIndex(layout, []), null, 'ArrowRight'),
+    ).toBeNull();
+  });
+
+  test('chooses geometric neighbours from an intentionally unsorted sparse input', () => {
+    const unsorted = createMatrixGridSparseIndex(layout, [cells[3], cells[1], cells[2], cells[0]]);
+
+    expect(getMatrixGridNextFocusId(unsorted, 'a1', 'ArrowRight')).toBe('c1');
+    expect(getMatrixGridNextFocusId(unsorted, 'c3', 'ArrowLeft')).toBe('a3');
+    expect(getMatrixGridNextFocusId(unsorted, 'a1', 'ArrowDown')).toBe('a3');
+    expect(getMatrixGridNextFocusId(unsorted, 'c3', 'ArrowUp')).toBe('c1');
+    expect(getMatrixGridNextFocusId(unsorted, null, 'ArrowRight')).toBe('a1');
+  });
+});