@ankhorage/zora 25.7.0 → 25.8.1

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

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

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;
+}