@ankhorage/zora 25.0.1 → 25.1.0

package/dist/features/grid-view/adapters/inbound/TileGrid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TileGrid.d.ts","sourceRoot":"","sources":["../../../../../src/features/grid-view/adapters/inbound/TileGrid.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAIjE,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,KAAK,EACL,MAAY,EACZ,QAAc,EACd,GAAQ,EACR,IAAQ,EACR,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,MAAM,GACP,EAAE,aAAa,qBAiCf"}
+{"version":3,"file":"TileGrid.d.ts","sourceRoot":"","sources":["../../../../../src/features/grid-view/adapters/inbound/TileGrid.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAIjE,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,KAAK,EACL,MAAY,EACZ,QAAc,EACd,GAAQ,EACR,IAAQ,EACR,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,sBAAsB,EACtB,UAAU,EACV,iBAAiB,EACjB,MAAM,GACP,EAAE,aAAa,qBAwCf"}

package/dist/features/grid-view/adapters/inbound/TileGrid.js

@@ -3,16 +3,20 @@ import { View as NativeView } from 'react-native';
 import { layoutTileGrid } from '../../application/layoutTileGrid';
 import { GridView } from './GridView';
 /*** Composes a responsive, virtualized tile presentation over the generic GridView renderer. */
-export function TileGrid({ items, width, height = 440, tileSize = 120, gap = 12, zoom = 1, overscanPixels, renderItem, interactionPolicy, testID, }) {
+export function TileGrid({ items, width, height = 440, tileSize = 120, gap = 12, zoom = 1, overscanPixels, focusedItemId, revealPaddingPixels, onColumnsChange, onVisibleItemIdsChange, renderItem, interactionPolicy, testID, }) {
     const [measuredWidth, setMeasuredWidth] = React.useState(0);
     const resolvedWidth = width ?? measuredWidth;
     const layout = React.useMemo(() => layoutTileGrid(items, resolvedWidth, tileSize, gap, zoom), [items, resolvedWidth, tileSize, gap, zoom]);
     const itemLookup = React.useMemo(() => new Map(items.map((item) => [item.id, item])), [items]);
+    React.useEffect(() => {
+        if (resolvedWidth > 0)
+            onColumnsChange?.(layout.columns);
+    }, [layout.columns, onColumnsChange, resolvedWidth]);
     return (<NativeView onLayout={(event) => setMeasuredWidth(event.nativeEvent.layout.width)} style={{ width, height, overflow: 'hidden' }} testID={testID}>
-      {resolvedWidth > 0 ? (<GridView contentHeight={layout.height} contentWidth={Math.max(resolvedWidth / zoom, layout.width)} height={height} interactionPolicy={interactionPolicy} items={layout.items} overscanPixels={overscanPixels} renderItem={(item) => {
+      {resolvedWidth > 0 ? (<GridView contentHeight={layout.height} contentWidth={Math.max(resolvedWidth / zoom, layout.width)} height={height} focusedItemId={focusedItemId} interactionPolicy={interactionPolicy} items={layout.items} onVisibleItemIdsChange={onVisibleItemIdsChange} overscanPixels={overscanPixels} renderItem={(item) => {
                 const source = itemLookup.get(item.id);
                 return source ? renderItem(source) : null;
-            }} width={resolvedWidth} zoom={zoom}/>) : null}
+            }} revealPaddingPixels={revealPaddingPixels} width={resolvedWidth} zoom={zoom}/>) : null}
     </NativeView>);
 }
 //# sourceMappingURL=TileGrid.js.map

package/dist/features/grid-view/adapters/inbound/TileGrid.js.map

@@ -1 +1 @@
-{"version":3,"file":"TileGrid.js","sourceRoot":"","sources":["../../../../../src/features/grid-view/adapters/inbound/TileGrid.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,gGAAgG;AAChG,MAAM,UAAU,QAAQ,CAAC,EACvB,KAAK,EACL,KAAK,EACL,MAAM,GAAG,GAAG,EACZ,QAAQ,GAAG,GAAG,EACd,GAAG,GAAG,EAAE,EACR,IAAI,GAAG,CAAC,EACR,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,MAAM,GACQ;IACd,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5D,MAAM,aAAa,GAAG,KAAK,IAAI,aAAa,CAAC;IAC7C,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAC1B,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,EAC/D,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,CAC5C,CAAC;IACF,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAE/F,OAAO,CACL,CAAC,UAAU,CACT,QAAQ,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CACtE,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAC7C,MAAM,CAAC,CAAC,MAAM,CAAC,CAEf;MAAA,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,CACnB,CAAC,QAAQ,CACP,aAAa,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAC7B,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAC3D,MAAM,CAAC,CAAC,MAAM,CAAC,CACf,iBAAiB,CAAC,CAAC,iBAAiB,CAAC,CACrC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACpB,cAAc,CAAC,CAAC,cAAc,CAAC,CAC/B,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE;gBACnB,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACvC,OAAO,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC5C,CAAC,CAAC,CACF,KAAK,CAAC,CAAC,aAAa,CAAC,CACrB,IAAI,CAAC,CAAC,IAAI,CAAC,EACX,CACH,CAAC,CAAC,CAAC,IAAI,CACV;IAAA,EAAE,UAAU,CAAC,CACd,CAAC;AACJ,CAAC","sourcesContent":["import React from 'react';\nimport { View as NativeView } from 'react-native';\n\nimport type { TileGridProps } from '../../../../types/grid-view';\nimport { layoutTileGrid } from '../../application/layoutTileGrid';\nimport { GridView } from './GridView';\n\n/*** Composes a responsive, virtualized tile presentation over the generic GridView renderer. */\nexport function TileGrid({\n  items,\n  width,\n  height = 440,\n  tileSize = 120,\n  gap = 12,\n  zoom = 1,\n  overscanPixels,\n  renderItem,\n  interactionPolicy,\n  testID,\n}: TileGridProps) {\n  const [measuredWidth, setMeasuredWidth] = React.useState(0);\n  const resolvedWidth = width ?? measuredWidth;\n  const layout = React.useMemo(\n    () => layoutTileGrid(items, resolvedWidth, tileSize, gap, zoom),\n    [items, resolvedWidth, tileSize, gap, zoom],\n  );\n  const itemLookup = React.useMemo(() => new Map(items.map((item) => [item.id, item])), [items]);\n\n  return (\n    <NativeView\n      onLayout={(event) => setMeasuredWidth(event.nativeEvent.layout.width)}\n      style={{ width, height, overflow: 'hidden' }}\n      testID={testID}\n    >\n      {resolvedWidth > 0 ? (\n        <GridView\n          contentHeight={layout.height}\n          contentWidth={Math.max(resolvedWidth / zoom, layout.width)}\n          height={height}\n          interactionPolicy={interactionPolicy}\n          items={layout.items}\n          overscanPixels={overscanPixels}\n          renderItem={(item) => {\n            const source = itemLookup.get(item.id);\n            return source ? renderItem(source) : null;\n          }}\n          width={resolvedWidth}\n          zoom={zoom}\n        />\n      ) : null}\n    </NativeView>\n  );\n}\n"]}
+{"version":3,"file":"TileGrid.js","sourceRoot":"","sources":["../../../../../src/features/grid-view/adapters/inbound/TileGrid.tsx"],"names":[],"mappings":"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","sourcesContent":["import React from 'react';\nimport { View as NativeView } from 'react-native';\n\nimport type { TileGridProps } from '../../../../types/grid-view';\nimport { layoutTileGrid } from '../../application/layoutTileGrid';\nimport { GridView } from './GridView';\n\n/*** Composes a responsive, virtualized tile presentation over the generic GridView renderer. */\nexport function TileGrid({\n  items,\n  width,\n  height = 440,\n  tileSize = 120,\n  gap = 12,\n  zoom = 1,\n  overscanPixels,\n  focusedItemId,\n  revealPaddingPixels,\n  onColumnsChange,\n  onVisibleItemIdsChange,\n  renderItem,\n  interactionPolicy,\n  testID,\n}: TileGridProps) {\n  const [measuredWidth, setMeasuredWidth] = React.useState(0);\n  const resolvedWidth = width ?? measuredWidth;\n  const layout = React.useMemo(\n    () => layoutTileGrid(items, resolvedWidth, tileSize, gap, zoom),\n    [items, resolvedWidth, tileSize, gap, zoom],\n  );\n  const itemLookup = React.useMemo(() => new Map(items.map((item) => [item.id, item])), [items]);\n\n  React.useEffect(() => {\n    if (resolvedWidth > 0) onColumnsChange?.(layout.columns);\n  }, [layout.columns, onColumnsChange, resolvedWidth]);\n\n  return (\n    <NativeView\n      onLayout={(event) => setMeasuredWidth(event.nativeEvent.layout.width)}\n      style={{ width, height, overflow: 'hidden' }}\n      testID={testID}\n    >\n      {resolvedWidth > 0 ? (\n        <GridView\n          contentHeight={layout.height}\n          contentWidth={Math.max(resolvedWidth / zoom, layout.width)}\n          height={height}\n          focusedItemId={focusedItemId}\n          interactionPolicy={interactionPolicy}\n          items={layout.items}\n          onVisibleItemIdsChange={onVisibleItemIdsChange}\n          overscanPixels={overscanPixels}\n          renderItem={(item) => {\n            const source = itemLookup.get(item.id);\n            return source ? renderItem(source) : null;\n          }}\n          revealPaddingPixels={revealPaddingPixels}\n          width={resolvedWidth}\n          zoom={zoom}\n        />\n      ) : null}\n    </NativeView>\n  );\n}\n"]}

package/dist/types/grid-view.d.ts

@@ -10,7 +10,12 @@ export interface GridViewProps extends ZoraBaseProps {
     height: number;
     zoom?: number;
     overscanPixels?: number;
+    /** Stable item identity that must be scrolled into view without duplicating viewport geometry. */
+    focusedItemId?: string;
+    /** Pixel inset retained around a revealed focused item. */
+    revealPaddingPixels?: number;
     onViewportChange?: (viewport: GridViewport) => void;
+    onVisibleItemIdsChange?: (ids: readonly string[]) => void;
     renderItem: (item: GridRectItem) => React.ReactNode;
 }
 /** An item needs a stable ID; visual positioning belongs to the TileGrid composition. */
@@ -26,6 +31,11 @@ export interface TileGridProps extends ZoraBaseProps {
     gap?: number;
     zoom?: number;
     overscanPixels?: number;
+    focusedItemId?: string;
+    revealPaddingPixels?: number;
+    /** Reports the same measured column count used to position tiles. */
+    onColumnsChange?: (columns: number) => void;
+    onVisibleItemIdsChange?: (ids: readonly string[]) => void;
     renderItem: (item: TileGridItem) => React.ReactNode;
 }
 //# sourceMappingURL=grid-view.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"grid-view.d.ts","sourceRoot":"","sources":["../../src/types/grid-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,gFAAgF;AAChF,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;IACpD,UAAU,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,KAAK,CAAC,SAAS,CAAC;CACrD;AAED,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,KAAK,CAAC,SAAS,CAAC;CACrD"}
+{"version":3,"file":"grid-view.d.ts","sourceRoot":"","sources":["../../src/types/grid-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,gFAAgF;AAChF,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kGAAkG;IAClG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;IACpD,sBAAsB,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IAC1D,UAAU,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,KAAK,CAAC,SAAS,CAAC;CACrD;AAED,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,sBAAsB,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IAC1D,UAAU,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,KAAK,CAAC,SAAS,CAAC;CACrD"}

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

@@ -1 +1 @@
-{"version":3,"file":"grid-view.js","sourceRoot":"","sources":["../../src/types/grid-view.ts"],"names":[],"mappings":"","sourcesContent":["import type { GridRectItem, GridViewport } from '@ankhorage/grid-view';\nimport type React from 'react';\n\nimport type { ZoraBaseProps } from './base';\n\n/** The renderer owns presentation only; world geometry comes from grid-view. */\nexport interface GridViewProps extends ZoraBaseProps {\n  items: readonly GridRectItem[];\n  contentWidth: number;\n  contentHeight: number;\n  width: number;\n  height: number;\n  zoom?: number;\n  overscanPixels?: number;\n  onViewportChange?: (viewport: GridViewport) => void;\n  renderItem: (item: GridRectItem) => React.ReactNode;\n}\n\n/** An item needs a stable ID; visual positioning belongs to the TileGrid composition. */\nexport interface TileGridItem {\n  readonly id: string;\n}\n\n/** Reusable tile presentation based on the generic world/viewport engine. */\nexport interface TileGridProps extends ZoraBaseProps {\n  items: readonly TileGridItem[];\n  width?: number;\n  height?: number;\n  tileSize?: number;\n  gap?: number;\n  zoom?: number;\n  overscanPixels?: number;\n  renderItem: (item: TileGridItem) => React.ReactNode;\n}\n"]}
+{"version":3,"file":"grid-view.js","sourceRoot":"","sources":["../../src/types/grid-view.ts"],"names":[],"mappings":"","sourcesContent":["import type { GridRectItem, GridViewport } from '@ankhorage/grid-view';\nimport type React from 'react';\n\nimport type { ZoraBaseProps } from './base';\n\n/** The renderer owns presentation only; world geometry comes from grid-view. */\nexport interface GridViewProps extends ZoraBaseProps {\n  items: readonly GridRectItem[];\n  contentWidth: number;\n  contentHeight: number;\n  width: number;\n  height: number;\n  zoom?: number;\n  overscanPixels?: number;\n  /** Stable item identity that must be scrolled into view without duplicating viewport geometry. */\n  focusedItemId?: string;\n  /** Pixel inset retained around a revealed focused item. */\n  revealPaddingPixels?: number;\n  onViewportChange?: (viewport: GridViewport) => void;\n  onVisibleItemIdsChange?: (ids: readonly string[]) => void;\n  renderItem: (item: GridRectItem) => React.ReactNode;\n}\n\n/** An item needs a stable ID; visual positioning belongs to the TileGrid composition. */\nexport interface TileGridItem {\n  readonly id: string;\n}\n\n/** Reusable tile presentation based on the generic world/viewport engine. */\nexport interface TileGridProps extends ZoraBaseProps {\n  items: readonly TileGridItem[];\n  width?: number;\n  height?: number;\n  tileSize?: number;\n  gap?: number;\n  zoom?: number;\n  overscanPixels?: number;\n  focusedItemId?: string;\n  revealPaddingPixels?: number;\n  /** Reports the same measured column count used to position tiles. */\n  onColumnsChange?: (columns: number) => void;\n  onVisibleItemIdsChange?: (ids: readonly string[]) => void;\n  renderItem: (item: TileGridItem) => React.ReactNode;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "25.0.1",
+  "version": "25.1.0",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {

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,8 @@ import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThem
 import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
 import { Text } from '../../../typography/public';
 import { resolveExplorerSelection } from '../../application/resolveExplorerSelection';
+import { ExplorerKeyboardProxy } from './ExplorerKeyboardProxy';
+import { useExplorerKeyboardFocus } from './useExplorerKeyboardFocus';
 
 /*** Single canonical Explorer implementation for media and file catalogue presentation. */
 export const Explorer = withZoraThemeScope(ExplorerInner);
@@ -37,9 +39,14 @@ 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 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;
 
@@ -58,53 +65,76 @@ 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>
     );
   };
 
@@ -114,8 +144,11 @@ function ExplorerInner({
 
   return (
     <TileGrid
+      focusedItemId={keyboard.focusedId ?? undefined}
       height={height}
       interactionPolicy={interactionPolicy}
+      onColumnsChange={setColumns}
+      onVisibleItemIdsChange={setVisibleIds}
       items={items}
       renderItem={renderTile}
       testID={testID}
@@ -126,7 +159,10 @@ function ExplorerInner({
   );
 }
 
-/*** 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;
+}