@ankhorage/zora 25.0.0 → 25.1.0

package/src/features/explorer/application/getExplorerNextFocusId.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'bun:test';
+
+import { getExplorerNextFocusId } from './getExplorerNextFocusId';
+
+describe('Explorer virtualized keyboard focus', () => {
+  const ids = ['a', 'b', 'c', 'd', 'e', 'f', 'g'];
+
+  test('moves by tile and by responsive row while staying within the catalogue', () => {
+    expect(getExplorerNextFocusId(ids, 'b', 'ArrowRight', 3)).toBe('c');
+    expect(getExplorerNextFocusId(ids, 'b', 'ArrowDown', 3)).toBe('e');
+    expect(getExplorerNextFocusId(ids, 'b', 'ArrowUp', 3)).toBe('a');
+    expect(getExplorerNextFocusId(ids, 'g', 'ArrowDown', 3)).toBe('g');
+  });
+
+  test('uses full visual positions and skips disabled items without collapsing rows', () => {
+    const disabled = new Set(['d', 'a']);
+    expect(getExplorerNextFocusId(ids, 'b', 'ArrowDown', 3, disabled)).toBe('e');
+    expect(getExplorerNextFocusId(ids, 'b', 'Home', 3, disabled)).toBe('b');
+    expect(getExplorerNextFocusId(ids, 'f', 'ArrowLeft', 3, new Set(['e']))).toBe('d');
+    expect(getExplorerNextFocusId(ids, 'g', 'End', 3, new Set(['g']))).toBe('f');
+    expect(getExplorerNextFocusId(ids, 'b', 'Home', 3, new Set(ids))).toBeNull();
+  });
+
+  test('navigates across ten thousand virtual positions without materializing DOM cells', () => {
+    const large = Array.from({ length: 10000 }, (_, index) => `tile-${index}`);
+    expect(getExplorerNextFocusId(large, 'tile-0', 'End', 4)).toBe('tile-9999');
+    expect(getExplorerNextFocusId(large, 'tile-9999', 'Home', 4)).toBe('tile-0');
+    expect(getExplorerNextFocusId(large, 'tile-2', 'ArrowDown', 4)).toBe('tile-6');
+    expect(getExplorerNextFocusId(large, 'tile-2', 'ArrowDown', 2)).toBe('tile-4');
+  });
+
+  test('supports first and last collection navigation without creating placeholder cells', () => {
+    expect(getExplorerNextFocusId(ids, 'd', 'Home', 3)).toBe('a');
+    expect(getExplorerNextFocusId(ids, 'd', 'End', 3)).toBe('g');
+    expect(getExplorerNextFocusId(ids, 'd', 'Enter', 3)).toBeNull();
+  });
+});

package/src/features/explorer/application/getExplorerNextFocusId.ts

@@ -0,0 +1,61 @@
+/***
+ * Resolve focus along actual tile positions while skipping unavailable items
+ * without collapsing the visual row geometry.
+ */
+export function getExplorerNextFocusId(
+  ids: readonly string[],
+  currentId: string | null,
+  key: string,
+  columns: number,
+  disabledIds: ReadonlySet<string> = new Set(),
+): string | null {
+  const delta = resolveFocusDelta(key, columns);
+  if (delta === null || ids.length === 0) return null;
+
+  const firstIndex = ids.findIndex((id) => !disabledIds.has(id));
+  if (firstIndex < 0) return null;
+
+  const currentIndex = Math.max(firstIndex, ids.indexOf(currentId ?? ''));
+  const candidateIndex =
+    delta === Number.NEGATIVE_INFINITY
+      ? 0
+      : delta === Number.POSITIVE_INFINITY
+        ? ids.length - 1
+        : Math.max(0, Math.min(ids.length - 1, currentIndex + delta));
+  const direction =
+    delta === Number.NEGATIVE_INFINITY
+      ? 1
+      : delta === Number.POSITIVE_INFINITY
+        ? -1
+        : Math.sign(delta);
+
+  for (let index = candidateIndex; index >= 0 && index < ids.length; index += direction) {
+    const candidate = ids.at(index);
+    if (candidate !== undefined && !disabledIds.has(candidate)) return candidate;
+  }
+  const current = ids.at(currentIndex);
+  return current !== undefined && !disabledIds.has(current)
+    ? current
+    : (ids.at(firstIndex) ?? null);
+}
+
+/*** Translate navigation keys into collection-relative movements. */
+function resolveFocusDelta(key: string, columns: number): number | null {
+  const rowSize = Math.max(1, Math.floor(columns));
+  switch (key) {
+    case 'ArrowLeft':
+      return -1;
+    case 'ArrowRight':
+      return 1;
+    case 'ArrowUp':
+      return -rowSize;
+    case 'ArrowDown':
+      return rowSize;
+    case 'Home':
+      return Number.NEGATIVE_INFINITY;
+    case 'End':
+      return Number.POSITIVE_INFINITY;
+    default:
+      return null;
+  }
+}

package/src/features/explorer/public.ts

@@ -9,4 +9,5 @@ export type {
 export { Explorer } from './adapters/inbound/Explorer';
 export { FileExplorer } from './adapters/inbound/FileExplorer';
 export { MediaExplorer } from './adapters/inbound/MediaExplorer';
+export { getExplorerNextFocusId } from './application/getExplorerNextFocusId';
 export { resolveExplorerSelection } from './application/resolveExplorerSelection';

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

@@ -1,4 +1,9 @@
-import { getVisibleGridItems, type GridViewport, worldToViewport } from '@ankhorage/grid-view';
+import {
+  getVisibleGridItems,
+  type GridViewport,
+  revealWorldRect,
+  worldToViewport,
+} from '@ankhorage/grid-view';
 import React from 'react';
 import { ScrollView as NativeScrollView, View as NativeView } from 'react-native';
 
@@ -18,13 +23,18 @@ export function GridView({
   height,
   zoom = 1,
   overscanPixels = 160,
+  focusedItemId,
+  revealPaddingPixels = 8,
   interactionPolicy,
   onViewportChange,
+  onVisibleItemIdsChange,
   renderItem,
   testID,
 }: GridViewProps) {
   const [scrollX, setScrollX] = React.useState(0);
   const [scrollY, setScrollY] = React.useState(0);
+  const horizontalScrollRef = React.useRef<NativeScrollView>(null);
+  const verticalScrollRef = React.useRef<NativeScrollView>(null);
   const scale = Math.max(0.01, zoom);
   const viewport = React.useMemo<GridViewport>(
     () => ({
@@ -41,13 +51,50 @@ export function GridView({
     () => getVisibleGridItems(items, viewport, overscanPixels),
     [items, overscanPixels, viewport],
   );
+  const viewportVisibleIds = React.useMemo(
+    () => getVisibleGridItems(visibleItems, viewport).map((item) => item.id),
+    [viewport, visibleItems],
+  );
+  const previousVisibleIdsRef = React.useRef<readonly string[]>([]);
+
+  React.useEffect(() => {
+    if (!onVisibleItemIdsChange) return;
+    const previous = previousVisibleIdsRef.current;
+    if (
+      previous.length === viewportVisibleIds.length &&
+      previous.every((id, index) => id === viewportVisibleIds.at(index))
+    ) {
+      return;
+    }
+    previousVisibleIdsRef.current = viewportVisibleIds;
+    onVisibleItemIdsChange(viewportVisibleIds);
+  }, [onVisibleItemIdsChange, viewportVisibleIds]);
 
   React.useEffect(() => {
     onViewportChange?.(viewport);
   }, [onViewportChange, viewport]);
 
+  const viewportRef = React.useRef(viewport);
+  React.useEffect(() => {
+    viewportRef.current = viewport;
+  }, [viewport]);
+
+  React.useEffect(() => {
+    const currentViewport = viewportRef.current;
+    const focusedItem = items.find((item) => item.id === focusedItemId);
+    if (!focusedItem) return;
+    const revealed = revealWorldRect(currentViewport, focusedItem, revealPaddingPixels);
+    if (revealed.offsetX !== currentViewport.offsetX) {
+      horizontalScrollRef.current?.scrollTo({ x: revealed.offsetX * scale, animated: true });
+    }
+    if (revealed.offsetY !== currentViewport.offsetY) {
+      verticalScrollRef.current?.scrollTo({ y: revealed.offsetY * scale, animated: true });
+    }
+  }, [focusedItemId, height, items, revealPaddingPixels, scale, width]);
+
   return (
     <NativeScrollView
+      ref={horizontalScrollRef}
       horizontal
       scrollEnabled={interactionPolicy !== 'passive'}
       scrollEventThrottle={32}
@@ -57,6 +104,7 @@ export function GridView({
       onScroll={(event) => setScrollX(event.nativeEvent.contentOffset.x)}
     >
       <NativeScrollView
+        ref={verticalScrollRef}
         scrollEnabled={interactionPolicy !== 'passive'}
         scrollEventThrottle={32}
         showsVerticalScrollIndicator

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

@@ -14,6 +14,10 @@ export function TileGrid({
   gap = 12,
   zoom = 1,
   overscanPixels,
+  focusedItemId,
+  revealPaddingPixels,
+  onColumnsChange,
+  onVisibleItemIdsChange,
   renderItem,
   interactionPolicy,
   testID,
@@ -26,6 +30,10 @@ export function TileGrid({
   );
   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)}
@@ -37,13 +45,16 @@ export function TileGrid({
           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;
           }}
+          revealPaddingPixels={revealPaddingPixels}
           width={resolvedWidth}
           zoom={zoom}
         />

package/src/types/grid-view.ts

@@ -12,7 +12,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;
 }
 
@@ -30,5 +35,10 @@ 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;
 }

package/web-dist/chunks/{Accordion-8m8p9wpw.js → Accordion-54k0ncs3.js}

@@ -36,6 +36,42 @@ function getVisibleGridItems(items, viewport, overscanPixels = 0) {
   const bounds = getVisibleWorldBounds(viewport, overscanPixels);
   return items.filter((item) => item.x <= bounds.x + bounds.width && item.x + item.width >= bounds.x && item.y <= bounds.y + bounds.height && item.y + item.height >= bounds.y);
 }
+// node_modules/@ankhorage/grid-view/dist/features/viewport/revealWorldRect.js
+function revealWorldRect(viewport, rect, paddingPixels = 0) {
+  validateRevealInput(viewport, rect, paddingPixels);
+  return {
+    ...viewport,
+    offsetX: revealAxis(viewport.offsetX, viewport.width, viewport.pixelsPerUnitX, rect.x, rect.width, paddingPixels),
+    offsetY: revealAxis(viewport.offsetY, viewport.height, viewport.pixelsPerUnitY, rect.y, rect.height, paddingPixels)
+  };
+}
+function revealAxis(offset, viewportPixels, pixelsPerUnit, rectStart, rectSize, paddingPixels) {
+  const visibleStart = offset + paddingPixels / pixelsPerUnit;
+  const visibleEnd = offset + (viewportPixels - paddingPixels) / pixelsPerUnit;
+  const rectEnd = rectStart + rectSize;
+  if (rectSize > visibleEnd - visibleStart || rectStart < visibleStart) {
+    return rectStart - paddingPixels / pixelsPerUnit;
+  }
+  if (rectEnd > visibleEnd) {
+    return rectEnd - (viewportPixels - paddingPixels) / pixelsPerUnit;
+  }
+  return offset;
+}
+function validateRevealInput(viewport, rect, paddingPixels) {
+  if (![
+    viewport.width,
+    viewport.height,
+    viewport.offsetX,
+    viewport.offsetY,
+    viewport.pixelsPerUnitX,
+    viewport.pixelsPerUnitY
+  ].every(Number.isFinite) || viewport.width <= 0 || viewport.height <= 0 || viewport.pixelsPerUnitX <= 0 || viewport.pixelsPerUnitY <= 0 || !Number.isFinite(paddingPixels) || paddingPixels < 0 || paddingPixels * 2 >= viewport.width || paddingPixels * 2 >= viewport.height) {
+    throw new RangeError("Viewport geometry must be finite and padding must leave visible space.");
+  }
+  if (![rect.x, rect.y, rect.width, rect.height].every(Number.isFinite) || rect.width < 0 || rect.height < 0) {
+    throw new RangeError("World rectangles must have finite nonnegative dimensions.");
+  }
+}
 // node_modules/@ankhorage/grid-view/dist/features/viewport/worldToViewport.js
 function worldToViewport(point, viewport) {
   return {
@@ -55,13 +91,18 @@ function GridView2({
   height,
   zoom = 1,
   overscanPixels = 160,
+  focusedItemId,
+  revealPaddingPixels = 8,
   interactionPolicy,
   onViewportChange,
+  onVisibleItemIdsChange,
   renderItem,
   testID
 }) {
   const [scrollX, setScrollX] = React.useState(0);
   const [scrollY, setScrollY] = React.useState(0);
+  const horizontalScrollRef = React.useRef(null);
+  const verticalScrollRef = React.useRef(null);
   const scale = Math.max(0.01, zoom);
   const viewport = React.useMemo(() => ({
     width,
@@ -72,10 +113,40 @@ function GridView2({
     pixelsPerUnitY: scale
   }), [height, scale, scrollX, scrollY, width]);
   const visibleItems = React.useMemo(() => getVisibleGridItems(items, viewport, overscanPixels), [items, overscanPixels, viewport]);
+  const viewportVisibleIds = React.useMemo(() => getVisibleGridItems(visibleItems, viewport).map((item) => item.id), [viewport, visibleItems]);
+  const previousVisibleIdsRef = React.useRef([]);
+  React.useEffect(() => {
+    if (!onVisibleItemIdsChange)
+      return;
+    const previous = previousVisibleIdsRef.current;
+    if (previous.length === viewportVisibleIds.length && previous.every((id, index) => id === viewportVisibleIds.at(index))) {
+      return;
+    }
+    previousVisibleIdsRef.current = viewportVisibleIds;
+    onVisibleItemIdsChange(viewportVisibleIds);
+  }, [onVisibleItemIdsChange, viewportVisibleIds]);
   React.useEffect(() => {
     onViewportChange?.(viewport);
   }, [onViewportChange, viewport]);
+  const viewportRef = React.useRef(viewport);
+  React.useEffect(() => {
+    viewportRef.current = viewport;
+  }, [viewport]);
+  React.useEffect(() => {
+    const currentViewport = viewportRef.current;
+    const focusedItem = items.find((item) => item.id === focusedItemId);
+    if (!focusedItem)
+      return;
+    const revealed = revealWorldRect(currentViewport, focusedItem, revealPaddingPixels);
+    if (revealed.offsetX !== currentViewport.offsetX) {
+      horizontalScrollRef.current?.scrollTo({ x: revealed.offsetX * scale, animated: true });
+    }
+    if (revealed.offsetY !== currentViewport.offsetY) {
+      verticalScrollRef.current?.scrollTo({ y: revealed.offsetY * scale, animated: true });
+    }
+  }, [focusedItemId, height, items, revealPaddingPixels, scale, width]);
   return /* @__PURE__ */ jsx(import_react_native.ScrollView, {
+    ref: horizontalScrollRef,
     horizontal: true,
     scrollEnabled: interactionPolicy !== "passive",
     scrollEventThrottle: 32,
@@ -84,6 +155,7 @@ function GridView2({
     testID,
     onScroll: (event) => setScrollX(event.nativeEvent.contentOffset.x),
     children: /* @__PURE__ */ jsx(import_react_native.ScrollView, {
+      ref: verticalScrollRef,
       scrollEnabled: interactionPolicy !== "passive",
       scrollEventThrottle: 32,
       showsVerticalScrollIndicator: true,
@@ -148,6 +220,10 @@ function TileGrid2({
   gap = 12,
   zoom = 1,
   overscanPixels,
+  focusedItemId,
+  revealPaddingPixels,
+  onColumnsChange,
+  onVisibleItemIdsChange,
   renderItem,
   interactionPolicy,
   testID
@@ -156,6 +232,10 @@ function TileGrid2({
   const resolvedWidth = width ?? measuredWidth;
   const layout = React2.useMemo(() => layoutTileGrid(items, resolvedWidth, tileSize, gap, zoom), [items, resolvedWidth, tileSize, gap, zoom]);
   const itemLookup = React2.useMemo(() => new Map(items.map((item) => [item.id, item])), [items]);
+  React2.useEffect(() => {
+    if (resolvedWidth > 0)
+      onColumnsChange?.(layout.columns);
+  }, [layout.columns, onColumnsChange, resolvedWidth]);
   return /* @__PURE__ */ jsx2(import_react_native2.View, {
     onLayout: (event) => setMeasuredWidth(event.nativeEvent.layout.width),
     style: { width, height, overflow: "hidden" },
@@ -164,13 +244,16 @@ function TileGrid2({
       contentHeight: layout.height,
       contentWidth: Math.max(resolvedWidth / zoom, layout.width),
       height,
+      focusedItemId,
       interactionPolicy,
       items: layout.items,
+      onVisibleItemIdsChange,
       overscanPixels,
       renderItem: (item) => {
         const source = itemLookup.get(item.id);
         return source ? renderItem(source) : null;
       },
+      revealPaddingPixels,
       width: resolvedWidth,
       zoom
     }) : null