@ankhorage/zora 25.0.1 → 25.2.0

package/src/capabilities/index.test.ts

@@ -1,15 +1,16 @@
 import { readFileSync } from 'node:fs';
 
 import { isCapability } from '@ankhorage/contracts/capabilities';
+import { isRecord } from '@ankhorage/utility/object';
 import { expect, test } from 'bun:test';
 
 import { CAPABILITIES } from './index';
 
-const packageCapabilities = (
-  JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')) as {
-    readonly ankh?: { readonly capabilities?: unknown };
-  }
-).ankh?.capabilities;
+const packageJson: unknown = JSON.parse(
+  readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
+);
+const packageCapabilities =
+  isRecord(packageJson) && isRecord(packageJson.ankh) ? packageJson.ankh.capabilities : undefined;
 
 test('publishes valid, uniquely identified canonical ZORA capabilities', () => {
   expect(CAPABILITIES).toHaveLength(2);
@@ -27,7 +28,10 @@ test('keeps Ankh package metadata identical to the canonical catalog', () => {
 });
 
 test('exports the catalog from the public capabilities subpath', async () => {
-  const capabilities = await import('@ankhorage/zora/capabilities');
+  const capabilities: unknown = await import('@ankhorage/zora/capabilities');
+  if (!isRecord(capabilities)) {
+    throw new Error('Expected a capability module record.');
+  }
 
   expect(capabilities.CAPABILITIES).toEqual(CAPABILITIES);
 });

package/src/features/explorer/adapters/inbound/Explorer.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Pressable as NativePressable, View as NativeView } from 'react-native';
+import { Platform, Pressable as NativePressable, View as NativeView } from 'react-native';
 
 import type { ExplorerItem, ExplorerProps } from '../../../../types/explorer';
 import { TileGrid } from '../../../grid-view/public';
@@ -9,6 +9,13 @@ import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThem
 import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
 import { Text } from '../../../typography/public';
 import { resolveExplorerSelection } from '../../application/resolveExplorerSelection';
+import {
+  type ExplorerPageRequestSignature,
+  shouldDispatchExplorerPageRequest,
+} from '../../application/shouldDispatchExplorerPageRequest';
+import { shouldRequestExplorerPage } from '../../application/shouldRequestExplorerPage';
+import { ExplorerKeyboardProxy } from './ExplorerKeyboardProxy';
+import { useExplorerKeyboardFocus } from './useExplorerKeyboardFocus';
 
 /*** Single canonical Explorer implementation for media and file catalogue presentation. */
 export const Explorer = withZoraThemeScope(ExplorerInner);
@@ -26,6 +33,14 @@ function ExplorerInner({
   tileSize = 120,
   zoom = 1,
   loading = false,
+  hasMore = false,
+  loadingMore = false,
+  pagingCollectionId,
+  pagingRetryToken,
+  onLoadMore,
+  permissionStatus = 'granted',
+  permissionText,
+  onRequestPermission,
   errorText,
   emptyText = 'No items',
   disabled = false,
@@ -37,12 +52,55 @@ function ExplorerInner({
   const [internalSelectedIds, setInternalSelectedIds] =
     React.useState<readonly string[]>(defaultSelectedIds);
   const anchorId = React.useRef<string | null>(null);
+  const [columns, setColumns] = React.useState(1);
+  const [visibleIds, setVisibleIds] = React.useState<readonly string[]>([]);
+  const lastPageRequestRef = React.useRef<ExplorerPageRequestSignature | null>(null);
   const effectiveSelectedIds = selectedIds ?? internalSelectedIds;
   const itemLookup = React.useMemo(() => new Map(items.map((item) => [item.id, item])), [items]);
-  const ids = items.filter((item) => !item.disabled).map((item) => item.id);
+  const ids = React.useMemo(
+    () => items.filter((item) => !item.disabled).map((item) => item.id),
+    [items],
+  );
   const selected = new Set(effectiveSelectedIds);
   const passive = interactionPolicy === 'passive' || disabled || readOnly;
 
+  React.useEffect(() => {
+    const request = {
+      collectionId: pagingCollectionId,
+      loadedItemCount: items.length,
+      retryToken: pagingRetryToken,
+    };
+    if (
+      !onLoadMore ||
+      !shouldDispatchExplorerPageRequest(lastPageRequestRef.current, request) ||
+      !shouldRequestExplorerPage(
+        ids,
+        visibleIds,
+        hasMore,
+        loadingMore,
+        loading,
+        errorText,
+        permissionStatus,
+      )
+    ) {
+      return;
+    }
+    lastPageRequestRef.current = request;
+    onLoadMore({ loadedItemCount: items.length });
+  }, [
+    errorText,
+    hasMore,
+    ids,
+    items.length,
+    loading,
+    loadingMore,
+    onLoadMore,
+    pagingCollectionId,
+    pagingRetryToken,
+    permissionStatus,
+    visibleIds,
+  ]);
+
   const select = (item: ExplorerItem, intent: 'replace' | 'toggle' | 'range') => {
     if (passive || item.disabled) return;
     const next = resolveExplorerSelection(
@@ -58,75 +116,122 @@ function ExplorerInner({
     onSelectionChange?.({ selectedIds: next });
   };
 
+  const keyboard = useExplorerKeyboardFocus(
+    items,
+    columns,
+    passive,
+    visibleIds,
+    (targetId, originId, shiftKey) => {
+      if (!shiftKey) return;
+      anchorId.current ??= originId;
+      const nextItem = itemLookup.get(targetId);
+      if (nextItem) select(nextItem, 'range');
+    },
+  );
+
   const renderTile = (tile: { readonly id: string }) => {
     const item = itemLookup.get(tile.id);
     if (!item) return null;
     const isSelected = selected.has(item.id);
     const canInteract = !passive && !item.disabled;
     return (
-      <NativePressable
-        accessibilityLabel={item.name}
-        accessibilityRole="button"
-        accessibilityState={{ selected: isSelected, disabled: !canInteract }}
-        disabled={!canInteract}
-        onLongPress={() => select(item, 'toggle')}
-        onPress={(event) => {
-          const intent = resolveExplorerPressIntent(event.nativeEvent);
-          select(item, intent);
-          if (selectionMode === 'single' && intent === 'replace') {
-            onActivate?.({ id: item.id });
-          }
-        }}
-        style={{
-          flex: 1,
-          overflow: 'hidden',
-          borderRadius: 8,
-          borderWidth: isSelected ? 2 : 1,
-          borderColor: isSelected ? theme.colors.primary : theme.semantics.neutral.divider,
-          backgroundColor: theme.semantics.neutral.surface,
-          padding: 8,
-          gap: 4,
-        }}
-        testID={`explorer-item-${item.id}`}
+      <ExplorerKeyboardProxy
+        onKeyDown={(key, shiftKey) => keyboard.onKeyDown(item.id, key, shiftKey)}
       >
-        <NativeView style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
-          {item.thumbnailUri ? (
-            <Image
-              accessibilityLabel={item.name}
-              aspectRatio={1}
-              source={item.thumbnailUri}
-              width="100%"
-            />
-          ) : (
-            <Icon name={item.kind === 'folder' ? 'folder-outline' : 'document-outline'} size={32} />
-          )}
-        </NativeView>
-        <Text numberOfLines={1} variant="caption">
-          {item.name}
-        </Text>
-      </NativePressable>
+        <NativePressable
+          accessibilityLabel={item.name}
+          accessibilityRole="button"
+          accessibilityState={{ selected: isSelected, disabled: !canInteract }}
+          disabled={!canInteract}
+          focusable={canInteract && (Platform.OS !== 'web' || item.id === keyboard.tabStopId)}
+          onFocus={() => keyboard.onFocus(item.id)}
+          onLongPress={() => select(item, 'toggle')}
+          onPress={(event) => {
+            const intent = resolveExplorerPressIntent(event.nativeEvent);
+            select(item, intent);
+            if (selectionMode === 'single' && intent === 'replace') {
+              onActivate?.({ id: item.id });
+            }
+          }}
+          style={{
+            flex: 1,
+            overflow: 'hidden',
+            borderRadius: 8,
+            borderWidth: isSelected ? 2 : 1,
+            borderColor: isSelected ? theme.colors.primary : theme.semantics.neutral.divider,
+            backgroundColor: theme.semantics.neutral.surface,
+            padding: 8,
+            gap: 4,
+          }}
+          ref={(node) => keyboard.registerTile(item.id, node)}
+          testID={`explorer-item-${item.id}`}
+        >
+          <NativeView style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
+            {item.thumbnailUri ? (
+              <Image
+                accessibilityLabel={item.name}
+                aspectRatio={1}
+                source={item.thumbnailUri}
+                width="100%"
+              />
+            ) : (
+              <Icon
+                name={item.kind === 'folder' ? 'folder-outline' : 'document-outline'}
+                size={32}
+              />
+            )}
+          </NativeView>
+          <Text numberOfLines={1} variant="caption">
+            {item.name}
+          </Text>
+        </NativePressable>
+      </ExplorerKeyboardProxy>
     );
   };
 
+  if (permissionStatus === 'denied' || permissionStatus === 'unavailable') {
+    return (
+      <NativeView testID={testID}>
+        <Text>{permissionText ?? 'This collection is unavailable without permission.'}</Text>
+        {permissionStatus === 'denied' && onRequestPermission ? (
+          <NativePressable accessibilityRole="button" onPress={onRequestPermission}>
+            <Text>Grant access</Text>
+          </NativePressable>
+        ) : null}
+      </NativeView>
+    );
+  }
   if (errorText) return <Text testID={testID}>{errorText}</Text>;
   if (loading) return <Text testID={testID}>Loading…</Text>;
   if (items.length === 0) return <Text testID={testID}>{emptyText}</Text>;
 
   return (
-    <TileGrid
-      height={height}
-      interactionPolicy={interactionPolicy}
-      items={items}
-      renderItem={renderTile}
-      testID={testID}
-      tileSize={tileSize}
-      width={width}
-      zoom={zoom}
-    />
+    <NativeView>
+      {permissionStatus === 'limited' ? (
+        <Text>{permissionText ?? 'Showing the media you have allowed.'}</Text>
+      ) : null}
+      <TileGrid
+        focusedItemId={keyboard.focusedId ?? undefined}
+        height={height}
+        interactionPolicy={interactionPolicy}
+        onColumnsChange={setColumns}
+        onVisibleItemIdsChange={setVisibleIds}
+        items={items}
+        renderItem={renderTile}
+        testID={testID}
+        tileSize={tileSize}
+        width={width}
+        zoom={zoom}
+      />
+      {loadingMore ? <Text>Loading more…</Text> : null}
+    </NativeView>
   );
 }
 
-/*** Normalize platform press modifiers for multi-selection without passing event objects into contracts. */
+/***
+ * Normalize platform press modifiers into selection intents
+ * without passing event objects into the public contracts.
+ */
 function resolveExplorerPressIntent(event: unknown): 'replace' | 'toggle' | 'range' {
   if (typeof event !== 'object' || event === null) return 'replace';
   if ('shiftKey' in event && event.shiftKey === true) return 'range';

package/src/features/explorer/adapters/inbound/ExplorerKeyboardProxy.native.tsx

@@ -0,0 +1,11 @@
+import type React from 'react';
+
+/*** Keeps Explorer navigation portable when a native host has no DOM keyboard event surface. */
+export function ExplorerKeyboardProxy({ children }: ExplorerKeyboardProxyProps) {
+  return <>{children}</>;
+}
+
+interface ExplorerKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly onKeyDown: (key: string, shiftKey: boolean) => boolean;
+}

package/src/features/explorer/adapters/inbound/ExplorerKeyboardProxy.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 ExplorerKeyboardProxy({ children }: ExplorerKeyboardProxyProps) {
+  return <>{children}</>;
+}
+
+interface ExplorerKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly onKeyDown: (key: string, shiftKey: boolean) => boolean;
+}

package/src/features/explorer/adapters/inbound/ExplorerKeyboardProxy.web.tsx

@@ -0,0 +1,20 @@
+import type React from 'react';
+
+/*** Bridges RNW's rendered DOM focus events into Explorer's platform-neutral navigation policy. */
+export function ExplorerKeyboardProxy({ children, onKeyDown }: ExplorerKeyboardProxyProps) {
+  return (
+    <div
+      onKeyDown={(event) => {
+        if (onKeyDown(event.key, event.shiftKey)) event.preventDefault();
+      }}
+      style={{ display: 'flex', flex: 1 }}
+    >
+      {children}
+    </div>
+  );
+}
+
+interface ExplorerKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly onKeyDown: (key: string, shiftKey: boolean) => boolean;
+}

package/src/features/explorer/adapters/inbound/useExplorerKeyboardFocus.test.tsx

@@ -0,0 +1,232 @@
+import { expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import type { ExplorerItem } from '../../../../types/explorer';
+import { layoutTileGrid } from '../../../grid-view/application/layoutTileGrid';
+import { ExplorerKeyboardProxy } from './ExplorerKeyboardProxy.web';
+import { useExplorerKeyboardFocus } from './useExplorerKeyboardFocus';
+
+interface HarnessProps {
+  readonly items: readonly ExplorerItem[];
+  readonly mountedIds: readonly string[];
+  readonly columns: number;
+  readonly navigation: { origin: string; target: string; extend: boolean }[];
+}
+
+function FocusHarness({ items, mountedIds, columns, navigation }: HarnessProps) {
+  const keyboard = useExplorerKeyboardFocus(
+    items,
+    columns,
+    false,
+    mountedIds,
+    (target, origin, extend) => {
+      navigation.push({ origin, target, extend });
+    },
+  );
+  return (
+    <div>
+      {mountedIds.map((id) => (
+        <ExplorerKeyboardProxy
+          key={id}
+          onKeyDown={(key, shiftKey) => keyboard.onKeyDown(id, key, shiftKey)}
+        >
+          <button
+            data-tile={id}
+            onFocus={() => keyboard.onFocus(id)}
+            ref={(node) => keyboard.registerTile(id, node)}
+            tabIndex={id === keyboard.tabStopId ? 0 : -1}
+            type="button"
+          >
+            {id}
+          </button>
+        </ExplorerKeyboardProxy>
+      ))}
+    </div>
+  );
+}
+
+test('restores native DOM focus only after a far virtual tile mounts', () => {
+  const browser = new Window();
+  const restore = installBrowserGlobals(browser);
+  const host = document.createElement('div');
+  document.body.append(host);
+  const root = createRoot(host);
+  const navigation: { origin: string; target: string; extend: boolean }[] = [];
+  const items = Array.from({ length: 10000 }, (_, i): ExplorerItem => ({
+    id: `tile-${i}`,
+    name: `Tile ${i}`,
+    kind: 'image',
+  }));
+  const render = (mountedIds: string[]) => (
+    <FocusHarness columns={4} items={items} mountedIds={mountedIds} navigation={navigation} />
+  );
+
+  try {
+    act(() => root.render(render(['tile-0', 'tile-1', 'tile-2', 'tile-3'])));
+    const first = host.querySelector<HTMLButtonElement>('[data-tile="tile-0"]');
+    if (!first) throw new Error('Missing first tile');
+    act(() => first.focus());
+
+    const event = new browser.KeyboardEvent('keydown', {
+      key: 'End',
+      bubbles: true,
+      cancelable: true,
+    });
+    act(() => {
+      first.dispatchEvent(event);
+    });
+
+    expect(event.defaultPrevented).toBe(true);
+    expect(navigation).toEqual([{ origin: 'tile-0', target: 'tile-9999', extend: false }]);
+    expect(host.querySelector('[data-tile="tile-9999"]')).toBeNull();
+
+    act(() => root.render(render(['tile-9996', 'tile-9997', 'tile-9998', 'tile-9999'])));
+    expect(document.activeElement?.getAttribute('data-tile')).toBe('tile-9999');
+    expect(host.querySelectorAll('[tabindex="0"]')).toHaveLength(1);
+  } finally {
+    act(() => root.unmount());
+    host.remove();
+    browser.close();
+    restore();
+  }
+});
+
+test('restores focus after rapid navigation, resize and unavailable tiles', () => {
+  const browser = new Window();
+  const restore = installBrowserGlobals(browser);
+  const host = document.createElement('div');
+  document.body.append(host);
+  const root = createRoot(host);
+  const navigation: { origin: string; target: string; extend: boolean }[] = [];
+  const items: readonly ExplorerItem[] = [
+    { id: 'a', name: 'A', kind: 'file' },
+    { id: 'b', name: 'B', kind: 'file' },
+    { id: 'c', name: 'C', kind: 'file', disabled: true },
+    { id: 'd', name: 'D', kind: 'file' },
+    { id: 'e', name: 'E', kind: 'file' },
+    { id: 'f', name: 'F', kind: 'file' },
+  ];
+  const render = (width: number, mountedIds: string[]) => (
+    <FocusHarness
+      columns={layoutTileGrid(items, width, 100, 10).columns}
+      items={items}
+      mountedIds={mountedIds}
+      navigation={navigation}
+    />
+  );
+  try {
+    act(() => root.render(render(450, ['a', 'b', 'c', 'd'])));
+    const first = host.querySelector<HTMLButtonElement>('[data-tile="a"]');
+    if (!first) throw new Error('Missing first tile');
+    act(() => first.focus());
+
+    act(() => {
+      first.dispatchEvent(
+        new browser.KeyboardEvent('keydown', {
+          key: 'ArrowDown',
+          shiftKey: true,
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+    });
+    expect(navigation.at(-1)).toEqual({ origin: 'a', target: 'e', extend: true });
+
+    act(() => root.render(render(230, ['a', 'b', 'c', 'd'])));
+    act(() => {
+      first.dispatchEvent(new browser.KeyboardEvent('keydown', { key: 'Home', bubbles: true }));
+    });
+    act(() => {
+      first.dispatchEvent(
+        new browser.KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }),
+      );
+    });
+    expect(navigation.at(-1)).toEqual({ origin: 'a', target: 'd', extend: false });
+
+    act(() => {
+      first.dispatchEvent(new browser.KeyboardEvent('keydown', { key: 'End', bubbles: true }));
+    });
+    act(() => {
+      first.dispatchEvent(new browser.KeyboardEvent('keydown', { key: 'Home', bubbles: true }));
+    });
+    act(() => root.render(render(230, ['a', 'b', 'c', 'd', 'e', 'f'])));
+    expect(document.activeElement?.getAttribute('data-tile')).toBe('a');
+    expect(host.querySelectorAll('[tabindex="0"]')).toHaveLength(1);
+    expect(host.querySelector<HTMLButtonElement>('[data-tile="c"]')?.tabIndex).toBe(-1);
+
+    act(() => root.render(render(230, ['d', 'e', 'f'])));
+    expect(host.querySelector<HTMLButtonElement>('[data-tile="d"]')?.tabIndex).toBe(0);
+    expect(host.querySelectorAll('[tabindex="0"]')).toHaveLength(1);
+  } finally {
+    act(() => root.unmount());
+    host.remove();
+    browser.close();
+    restore();
+  }
+});
+
+test('web proxy leaves non-navigation keys to ordinary activation', () => {
+  const browser = new Window();
+  const restore = installBrowserGlobals(browser);
+  const host = document.createElement('div');
+  document.body.append(host);
+  const root = createRoot(host);
+  try {
+    act(() =>
+      root.render(
+        <ExplorerKeyboardProxy onKeyDown={(key) => key === 'ArrowRight'}>
+          <button type="button">Action</button>
+        </ExplorerKeyboardProxy>,
+      ),
+    );
+    const button = host.querySelector('button');
+    if (!button) throw new Error('Missing action');
+    const arrow = new browser.KeyboardEvent('keydown', {
+      key: 'ArrowRight',
+      bubbles: true,
+      cancelable: true,
+    });
+    act(() => {
+      button.dispatchEvent(arrow);
+    });
+    expect(arrow.defaultPrevented).toBe(true);
+
+    const enter = new browser.KeyboardEvent('keydown', {
+      key: 'Enter',
+      bubbles: true,
+      cancelable: true,
+    });
+    act(() => {
+      button.dispatchEvent(enter);
+    });
+    expect(enter.defaultPrevented).toBe(false);
+  } finally {
+    act(() => root.unmount());
+    host.remove();
+    browser.close();
+    restore();
+  }
+});
+
+/*** Install a deterministic RNW-like browser environment for real focus and event propagation. */
+function installBrowserGlobals(browser: Window): () => void {
+  const keys = ['window', 'document', 'Node', 'navigator', 'IS_REACT_ACT_ENVIRONMENT'] as const;
+  const previous = keys.map(
+    (key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)] as const,
+  );
+  Object.assign(globalThis, {
+    window: browser,
+    document: browser.document,
+    Node: browser.Node,
+    navigator: browser.navigator,
+    IS_REACT_ACT_ENVIRONMENT: true,
+  });
+  return () => {
+    for (const [key, descriptor] of previous) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  };
+}

package/src/features/explorer/adapters/inbound/useExplorerKeyboardFocus.ts

@@ -0,0 +1,77 @@
+import React from 'react';
+
+import type { ExplorerItem } from '../../../../types/explorer';
+import { getExplorerNextFocusId } from '../../application/getExplorerNextFocusId';
+
+/*** Tracks the one keyboard tab stop and restores focus only after a virtualized tile mounts. */
+export function useExplorerKeyboardFocus(
+  items: readonly ExplorerItem[],
+  columns: number,
+  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 tileRefs = React.useRef(new Map<string, FocusableTile>());
+  const ids = React.useMemo(() => items.map(({ id }) => id), [items]);
+  const idSet = React.useMemo(() => new Set(ids), [ids]);
+  const disabledIds = React.useMemo(
+    () => new Set(items.filter((item) => item.disabled).map(({ id }) => id)),
+    [items],
+  );
+  const visibleEligibleIds = visibleIds.filter((id) => idSet.has(id) && !disabledIds.has(id));
+  const tabStopId =
+    focusedId !== null && visibleEligibleIds.includes(focusedId)
+      ? focusedId
+      : (visibleEligibleIds[0] ?? ids.find((id) => !disabledIds.has(id)));
+
+  const onFocus = React.useCallback((id: string) => {
+    pendingFocusRef.current = null;
+    focusedRef.current = id;
+    setFocusedId(id);
+  }, []);
+
+  const registerTile = React.useCallback((id: string, node: FocusableTile | null) => {
+    if (node === null) {
+      tileRefs.current.delete(id);
+      return;
+    }
+    tileRefs.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) return false;
+      if (!['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End'].includes(key))
+        return false;
+      const originId = focusedRef.current ?? id;
+      const nextId = getExplorerNextFocusId(ids, originId, key, columns, disabledIds);
+      if (nextId === null || nextId === originId) return true;
+
+      focusedRef.current = nextId;
+      pendingFocusRef.current = nextId;
+      setFocusedId(nextId);
+      onNavigate(nextId, originId, shiftKey);
+
+      const mounted = tileRefs.current.get(nextId);
+      if (mounted) {
+        pendingFocusRef.current = null;
+        mounted.focus();
+      }
+      return true;
+    },
+    [columns, disabled, disabledIds, ids, onNavigate],
+  );
+
+  return { focusedId, tabStopId, onFocus, onKeyDown, registerTile };
+}
+
+interface FocusableTile {
+  focus: () => void;
+}