@ankhorage/zora 25.0.1 → 25.2.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/application/shouldDispatchExplorerPageRequest.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  type ExplorerPageRequestSignature,
+  shouldDispatchExplorerPageRequest,
+} from './shouldDispatchExplorerPageRequest';
+
+describe('Explorer page request lifecycle', () => {
+  const initialRequest: ExplorerPageRequestSignature = {
+    collectionId: 'recent-media',
+    loadedItemCount: 60,
+    retryToken: undefined,
+  };
+
+  test('deduplicates a settled or failed request until the provider explicitly retries it', () => {
+    expect(shouldDispatchExplorerPageRequest(null, initialRequest)).toBe(true);
+    expect(shouldDispatchExplorerPageRequest(initialRequest, initialRequest)).toBe(false);
+    expect(
+      shouldDispatchExplorerPageRequest(initialRequest, {
+        ...initialRequest,
+        retryToken: 'retry-1',
+      }),
+    ).toBe(true);
+  });
+
+  test('resets paging for a replacement collection with the same loaded row count', () => {
+    expect(
+      shouldDispatchExplorerPageRequest(initialRequest, {
+        ...initialRequest,
+        collectionId: 'search-results',
+      }),
+    ).toBe(true);
+  });
+
+  test('allows the next normal page when the provider extends the collection', () => {
+    expect(
+      shouldDispatchExplorerPageRequest(initialRequest, {
+        ...initialRequest,
+        loadedItemCount: 120,
+      }),
+    ).toBe(true);
+  });
+});

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

@@ -0,0 +1,18 @@
+export interface ExplorerPageRequestSignature {
+  readonly collectionId: string | undefined;
+  readonly loadedItemCount: number;
+  readonly retryToken: string | undefined;
+}
+
+/*** Preserves one request per provider page boundary until its collection, row count, or retry token changes. */
+export function shouldDispatchExplorerPageRequest(
+  previous: ExplorerPageRequestSignature | null,
+  next: ExplorerPageRequestSignature,
+): boolean {
+  if (previous === null) return true;
+  return (
+    previous.collectionId !== next.collectionId ||
+    previous.loadedItemCount !== next.loadedItemCount ||
+    previous.retryToken !== next.retryToken
+  );
+}

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

@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'bun:test';
+
+import { shouldRequestExplorerPage } from './shouldRequestExplorerPage';
+
+describe('Explorer paging boundary', () => {
+  const ids = Array.from({ length: 100 }, (_, index) => `asset-${index}`);
+  const available = ['granted', 'limited'] as const;
+
+  test('requests a page only when the visible virtual window reaches the loaded end', () => {
+    expect(
+      shouldRequestExplorerPage(
+        ids,
+        ['asset-50', 'asset-51'],
+        true,
+        false,
+        false,
+        undefined,
+        'granted',
+      ),
+    ).toBe(false);
+    expect(
+      shouldRequestExplorerPage(
+        ids,
+        ['asset-88', 'asset-89'],
+        true,
+        false,
+        false,
+        undefined,
+        'granted',
+      ),
+    ).toBe(true);
+  });
+
+  test('does not request while the provider has no page or is already loading one', () => {
+    expect(
+      shouldRequestExplorerPage(ids, ['asset-99'], false, false, false, undefined, 'granted'),
+    ).toBe(false);
+    expect(
+      shouldRequestExplorerPage(ids, ['asset-99'], true, true, false, undefined, 'granted'),
+    ).toBe(false);
+  });
+
+  test('gates paging until the collection is accessible, loaded, and error-free', () => {
+    for (const permissionStatus of ['denied', 'unavailable'] as const) {
+      expect(
+        shouldRequestExplorerPage(
+          ids,
+          ['asset-99'],
+          true,
+          false,
+          false,
+          undefined,
+          permissionStatus,
+        ),
+      ).toBe(false);
+    }
+    for (const permissionStatus of available) {
+      expect(
+        shouldRequestExplorerPage(
+          ids,
+          ['asset-99'],
+          true,
+          false,
+          true,
+          undefined,
+          permissionStatus,
+        ),
+      ).toBe(false);
+      expect(
+        shouldRequestExplorerPage(
+          ids,
+          ['asset-99'],
+          true,
+          false,
+          false,
+          'Failed to load',
+          permissionStatus,
+        ),
+      ).toBe(false);
+      expect(
+        shouldRequestExplorerPage(
+          ids,
+          ['asset-99'],
+          true,
+          false,
+          false,
+          undefined,
+          permissionStatus,
+        ),
+      ).toBe(true);
+    }
+  });
+});

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

@@ -0,0 +1,26 @@
+import type { ExplorerPermissionStatus } from '../../../types/explorer';
+
+/*** Determines whether the mounted, accessible viewport has reached the provider-owned page boundary. */
+export function shouldRequestExplorerPage(
+  itemIds: readonly string[],
+  visibleIds: readonly string[],
+  hasMore: boolean,
+  loadingMore: boolean,
+  loading: boolean,
+  errorText: string | undefined,
+  permissionStatus: ExplorerPermissionStatus,
+  threshold = 12,
+): boolean {
+  if (
+    !hasMore ||
+    loadingMore ||
+    loading ||
+    errorText !== undefined ||
+    (permissionStatus !== 'granted' && permissionStatus !== 'limited') ||
+    visibleIds.length === 0
+  ) {
+    return false;
+  }
+  const firstPagingIndex = Math.max(0, itemIds.length - threshold);
+  return visibleIds.some((id) => itemIds.indexOf(id) >= firstPagingIndex);
+}

package/src/features/explorer/meta.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from 'bun:test';
+
+import { fileExplorerMeta, mediaExplorerMeta } from './meta';
+
+describe('Explorer authoring metadata', () => {
+  const authorableProps = [
+    'items',
+    'selectionMode',
+    'selectedIds',
+    'defaultSelectedIds',
+    'width',
+    'height',
+    'tileSize',
+    'zoom',
+    'loading',
+    'hasMore',
+    'loadingMore',
+    'pagingCollectionId',
+    'pagingRetryToken',
+    'permissionStatus',
+    'permissionText',
+    'errorText',
+    'emptyText',
+    'disabled',
+    'readOnly',
+  ] as const;
+
+  test('keeps MediaExplorer and FileExplorer serializable props in parity', () => {
+    for (const meta of [mediaExplorerMeta, fileExplorerMeta]) {
+      expect(meta.directManifestNode).toBe(true);
+      for (const prop of authorableProps) expect(meta.props).toHaveProperty(prop);
+      expect(meta.props.pagingCollectionId).toMatchObject({ type: 'string', category: 'Paging' });
+      expect(meta.props.pagingRetryToken).toMatchObject({ type: 'string', category: 'Paging' });
+      expect(meta.props.permissionStatus).toMatchObject({
+        type: 'enum',
+        enum: ['granted', 'limited', 'denied', 'unavailable'],
+      });
+    }
+  });
+
+  test('normalizes paging and permission actions without exposing provider objects', () => {
+    for (const meta of [mediaExplorerMeta, fileExplorerMeta]) {
+      expect(meta.events.loadMore).toEqual({
+        label: 'Load more',
+        eventType: 'explorer.loadMore',
+        payloadFields: [{ path: 'loadedItemCount', type: 'number' }],
+      });
+      expect(meta.events.requestPermission).toEqual({
+        label: 'Request permission',
+        eventType: 'explorer.requestPermission',
+        payloadFields: [],
+      });
+    }
+  });
+});

package/src/features/explorer/meta.ts

@@ -30,16 +30,31 @@ const explorerProps = {
     default: 'single',
   },
   selectedIds: { type: 'array', category: 'Selection' },
+  defaultSelectedIds: { type: 'array', category: 'Selection' },
+  width: { type: 'number', category: 'Layout' },
   tileSize: { type: 'number', category: 'Layout', default: 120 },
   height: { type: 'number', category: 'Layout', default: 440 },
   zoom: { type: 'number', category: 'Layout', default: 1 },
   loading: { type: 'boolean', category: 'State' },
+  hasMore: { type: 'boolean', category: 'Paging' },
+  loadingMore: { type: 'boolean', category: 'Paging' },
+  pagingCollectionId: { type: 'string', category: 'Paging' },
+  pagingRetryToken: { type: 'string', category: 'Paging' },
+  permissionStatus: {
+    type: 'enum',
+    category: 'Permission',
+    enum: ['granted', 'limited', 'denied', 'unavailable'],
+    default: 'granted',
+  },
+  permissionText: { type: 'string', category: 'Permission' },
   errorText: { type: 'string', category: 'State' },
   emptyText: { type: 'string', category: 'Content' },
   disabled: { type: 'boolean', category: 'State' },
   readOnly: { type: 'boolean', category: 'State' },
   onSelectionChange: { type: 'action', category: 'Events' },
   onActivate: { type: 'action', category: 'Events' },
+  onLoadMore: { type: 'action', category: 'Events' },
+  onRequestPermission: { type: 'action', category: 'Events' },
 } as const;
 
 const explorerEvents = {
@@ -53,6 +68,16 @@ const explorerEvents = {
     eventType: 'explorer.activate',
     payloadFields: [{ path: 'id', type: 'string' }],
   },
+  loadMore: {
+    label: 'Load more',
+    eventType: 'explorer.loadMore',
+    payloadFields: [{ path: 'loadedItemCount', type: 'number' }],
+  },
+  requestPermission: {
+    label: 'Request permission',
+    eventType: 'explorer.requestPermission',
+    payloadFields: [],
+  },
 } as const;
 
 /** Framework-bound Explorer is a composition primitive, not a separate manifest shape. */

package/src/features/explorer/public.ts

@@ -2,6 +2,8 @@ export type {
   ExplorerActivateEvent,
   ExplorerItem,
   ExplorerItemKind,
+  ExplorerPageRequestEvent,
+  ExplorerPermissionStatus,
   ExplorerProps,
   ExplorerSelectionChangeEvent,
   ExplorerSelectionMode,
@@ -9,4 +11,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/explorer.ts

@@ -18,6 +18,9 @@ export interface ExplorerItem {
 
 export type ExplorerSelectionMode = 'single' | 'multi';
 
+/** Provider-owned access state projected into the portable explorer presentation. */
+export type ExplorerPermissionStatus = 'granted' | 'limited' | 'denied' | 'unavailable';
+
 export interface ExplorerActivateEvent {
   readonly id: string;
 }
@@ -26,6 +29,11 @@ export interface ExplorerSelectionChangeEvent {
   readonly selectedIds: readonly string[];
 }
 
+/** Requests the next provider page without exposing a provider cursor or native object. */
+export interface ExplorerPageRequestEvent {
+  readonly loadedItemCount: number;
+}
+
 export interface ExplorerProps extends ZoraBaseProps {
   items: readonly ExplorerItem[];
   selectionMode?: ExplorerSelectionMode;
@@ -38,6 +46,28 @@ export interface ExplorerProps extends ZoraBaseProps {
   tileSize?: number;
   zoom?: number;
   loading?: boolean;
+  /** Provider paging remains application-owned; Explorer only requests the next page near its end. */
+  hasMore?: boolean;
+  loadingMore?: boolean;
+  /**
+   * Stable serializable identity for a provider collection.
+   *
+   * Supply this whenever paging is enabled so a replacement collection with the same number of
+   * loaded rows receives its own initial page request.
+   */
+  pagingCollectionId?: string;
+  /**
+   * Provider-controlled retry token for the current page boundary.
+   *
+   * Change this after a failed request to permit one deliberate retry without causing automatic
+   * retry loops.
+   */
+  pagingRetryToken?: string;
+  onLoadMore?: (event: ExplorerPageRequestEvent) => void;
+  /** Never pass a native permission object through this presentation boundary. */
+  permissionStatus?: ExplorerPermissionStatus;
+  permissionText?: string;
+  onRequestPermission?: () => void;
   errorText?: string;
   emptyText?: string;
   disabled?: boolean;

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