@ankhorage/zora 25.1.0 → 25.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "25.1.0",
+  "version": "25.2.1",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {
@@ -40,7 +40,7 @@
     "react-native-worklets": "0.10.1"
   },
   "dependencies": {
-    "@ankhorage/ankh": "^0.12.2",
+    "@ankhorage/ankh": "^0.13.0",
     "@ankhorage/color-theory": "^0.3.1",
     "@ankhorage/contracts": "^24.2.1",
     "@ankhorage/game": "^0.1.2",
@@ -132,20 +132,20 @@
     "version-packages": "ankhorage-changeset version"
   },
   "devDependencies": {
-    "@ankhorage/devtools": "^2.3.6",
+    "@ankhorage/devtools": "^2.3.9",
     "@ankhorage/paradox": "^0.3.1",
     "@react-native-vector-icons/fontawesome": "^13.1.4",
     "@react-native-vector-icons/fontawesome5": "^13.1.4",
     "@react-native-vector-icons/fontawesome6": "^13.1.4",
     "@react-native-vector-icons/ionicons": "^13.1.4",
     "@types/bun": "^1.4.2",
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@types/react-native-web": "^0.19.3",
     "cytoscape": "^3.34.3",
     "cytoscape-elk": "^2.3.0",
-    "happy-dom": "^20.14.5",
+    "happy-dom": "^20.14.6",
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "react-native": "0.86.3",

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

@@ -9,6 +9,11 @@ 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';
 
@@ -28,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,
@@ -41,6 +54,7 @@ function ExplorerInner({
   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 = React.useMemo(
@@ -50,6 +64,43 @@ function ExplorerInner({
   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(
@@ -138,24 +189,42 @@ function ExplorerInner({
     );
   };
 
+  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
-      focusedItemId={keyboard.focusedId ?? undefined}
-      height={height}
-      interactionPolicy={interactionPolicy}
-      onColumnsChange={setColumns}
-      onVisibleItemIdsChange={setVisibleIds}
-      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>
   );
 }
 

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,

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;