@ankhorage/expo-runtime 3.1.1 → 3.2.2

package/src/generatedSources.test.ts

@@ -1,11 +1,20 @@
 import { describe, expect, it } from 'bun:test';
 
-import { getExpoBarcodeScannerViewSource } from './generatedSources';
+import {
+  getExpoBarcodeScannerViewSource,
+  getExpoReaderSurfaceViewSource,
+} from './generatedSources';
 
 describe('generated Expo runtime sources', () => {
   it('emits the barcode scanner view adapter in canonical source format', () => {
     expect(getExpoBarcodeScannerViewSource()).toBe(
-      "export { ExpoBarcodeScannerAdapter as ExpoBarcodeScannerView } from '@ankhorage/expo-runtime';\n",
+      "export { ExpoBarcodeScannerAdapter as ExpoBarcodeScannerView } from '@ankhorage/expo-runtime/barcode-scanner';\n",
+    );
+  });
+
+  it('emits the reader surface adapter through its capability-scoped entrypoint', () => {
+    expect(getExpoReaderSurfaceViewSource()).toBe(
+      "export { ExpoReaderSurfaceAdapter as ExpoReaderSurfaceView } from '@ankhorage/expo-runtime/reader';\n",
     );
   });
 });

package/src/generatedSources.ts

@@ -1,9 +1,19 @@
 const EXPO_BARCODE_SCANNER_VIEW_SOURCE = [
   'export { ExpoBarcodeScannerAdapter as ExpoBarcodeScannerView }',
-  " from '@ankhorage/expo-runtime';",
+  " from '@ankhorage/expo-runtime/barcode-scanner';",
+  '\n',
+] as const;
+
+const EXPO_READER_SURFACE_VIEW_SOURCE = [
+  'export { ExpoReaderSurfaceAdapter as ExpoReaderSurfaceView }',
+  " from '@ankhorage/expo-runtime/reader';",
   '\n',
 ] as const;
 
 export function getExpoBarcodeScannerViewSource(): string {
   return EXPO_BARCODE_SCANNER_VIEW_SOURCE.join('');
 }
+
+export function getExpoReaderSurfaceViewSource(): string {
+  return EXPO_READER_SURFACE_VIEW_SOURCE.join('');
+}

package/src/index.ts

@@ -48,11 +48,15 @@ export {
   resolveExpoRuntimeGeneratedAppOutput,
   resolveExpoRuntimeNativeOutput,
 } from './generatedAppOutput';
-export { getExpoBarcodeScannerViewSource } from './generatedSources';
+export {
+  getExpoBarcodeScannerViewSource,
+  getExpoReaderSurfaceViewSource,
+} from './generatedSources';
 export {
   type ExpoRuntimeLayoutIntegrationPlan,
   resolveExpoRuntimeLayoutIntegration,
 } from './layoutIntegrationPlanning';
+export { ExpoReaderSurfaceAdapter } from './reader/ExpoReaderSurfaceAdapter';
 export type {
   ExpoRuntimeAdapterId,
   ExpoRuntimePlan,

package/src/planning.ts

@@ -8,7 +8,10 @@ export {
   resolveExpoRuntimeGeneratedAppOutput,
   resolveExpoRuntimeNativeOutput,
 } from './generatedAppOutput';
-export { getExpoBarcodeScannerViewSource } from './generatedSources';
+export {
+  getExpoBarcodeScannerViewSource,
+  getExpoReaderSurfaceViewSource,
+} from './generatedSources';
 export {
   type ExpoRuntimeLayoutIntegrationPlan,
   resolveExpoRuntimeLayoutIntegration,

package/src/reader/ExpoReaderSurfaceAdapter.tsx

@@ -0,0 +1,170 @@
+import { type ReaderErrorEvent, ReaderSurface, type ReaderSurfaceProps } from '@ankhorage/zora';
+import React from 'react';
+import { Image, StyleSheet, View } from 'react-native';
+
+import ReaderViewport from './ReaderViewport';
+import type { ReaderAppearance, ReaderCommand, ReaderViewportState } from './types';
+
+const INITIAL_STATE: ReaderViewportState = {
+  canGoNext: false,
+  canGoPrevious: false,
+  page: 1,
+  progress: 0,
+  status: 'loading',
+};
+
+export function ExpoReaderSurfaceAdapter(props: ReaderSurfaceProps) {
+  const sourceUri = resolveReaderSourceUri(props.source);
+  const controller = useReaderController(props, sourceUri);
+  const appearance = useReaderAppearance(props);
+  const viewport = sourceUri ? (
+    <ReaderAdapterViewport
+      appearance={appearance}
+      command={controller.command}
+      format={props.format}
+      initialLocation={props.location}
+      onError={controller.handleError}
+      onOpenExternalLink={controller.handleOpenExternalLink}
+      onStateChange={controller.handleStateChange}
+      sourceUri={sourceUri}
+    />
+  ) : undefined;
+
+  return (
+    <ReaderSurface
+      {...props}
+      canGoNext={controller.state.canGoNext}
+      canGoPrevious={controller.state.canGoPrevious}
+      chapterLabel={controller.state.location?.chapterTitle ?? props.chapterLabel}
+      onNextPage={controller.handleNextPage}
+      onPreviousPage={controller.handlePreviousPage}
+      page={controller.state.page}
+      pageCount={controller.state.pageCount}
+      progress={controller.state.progress}
+      status={controller.error ? 'error' : sourceUri ? controller.state.status : 'idle'}
+      viewport={viewport}
+    />
+  );
+}
+
+function ReaderAdapterViewport({
+  appearance,
+  command,
+  format,
+  initialLocation,
+  onError,
+  onOpenExternalLink,
+  onStateChange,
+  sourceUri,
+}: React.ComponentProps<typeof ReaderViewport>) {
+  return (
+    <View style={styles.viewport}>
+      <ReaderViewport
+        appearance={appearance}
+        command={command}
+        dom={DOM_CONFIGURATION}
+        format={format}
+        initialLocation={initialLocation}
+        key={`${format}:${sourceUri}`}
+        onError={onError}
+        onOpenExternalLink={onOpenExternalLink}
+        onStateChange={onStateChange}
+        sourceUri={sourceUri}
+      />
+    </View>
+  );
+}
+
+function useReaderController(props: ReaderSurfaceProps, sourceUri: string | undefined) {
+  const { onLocationChange, onNextPage, onOpenExternalLink, onPreviousPage, onReaderError } = props;
+  const [state, setState] = React.useState<ReaderViewportState>(INITIAL_STATE);
+  const [error, setError] = React.useState<ReaderErrorEvent>();
+  const { command, issueCommand } = useReaderCommandState(sourceUri);
+  const handlePreviousPage = React.useCallback(() => {
+    issueCommand('previous');
+    void onPreviousPage?.();
+  }, [issueCommand, onPreviousPage]);
+  const handleNextPage = React.useCallback(() => {
+    issueCommand('next');
+    void onNextPage?.();
+  }, [issueCommand, onNextPage]);
+  const handleStateChange = React.useCallback(
+    async (nextState: ReaderViewportState) => {
+      setState(nextState);
+      setError(undefined);
+      if (nextState.location) await onLocationChange?.(nextState.location);
+    },
+    [onLocationChange],
+  );
+  const handleError = React.useCallback(
+    async (event: ReaderErrorEvent) => {
+      setError(event);
+      await onReaderError?.(event);
+    },
+    [onReaderError],
+  );
+  const handleOpenExternalLink = React.useCallback(
+    async (event: { readonly url: string }) => onOpenExternalLink?.(event),
+    [onOpenExternalLink],
+  );
+  return {
+    command,
+    error,
+    handleError,
+    handleNextPage,
+    handleOpenExternalLink,
+    handlePreviousPage,
+    handleStateChange,
+    state,
+  };
+}
+
+function useReaderCommandState(sourceUri: string | undefined) {
+  const [command, setCommand] = React.useState<ReaderCommand>();
+  const commandIdRef = React.useRef(0);
+  const issueCommand = React.useCallback(
+    (type: ReaderCommand['type']) => {
+      if (!sourceUri) return;
+      commandIdRef.current += 1;
+      setCommand({ id: commandIdRef.current, sourceUri, type });
+    },
+    [sourceUri],
+  );
+  return { command, issueCommand };
+}
+
+function useReaderAppearance(props: ReaderSurfaceProps): ReaderAppearance {
+  const colorScheme = props.readerColorScheme ?? 'system';
+  const fontScale = props.fontScale ?? 1;
+  const lineHeight = resolveLineHeight(props.lineHeight ?? 'normal');
+  return React.useMemo(
+    () => ({ colorScheme, fontScale, lineHeight }),
+    [colorScheme, fontScale, lineHeight],
+  );
+}
+
+function resolveReaderSourceUri(source: ReaderSurfaceProps['source']): string | undefined {
+  if (typeof source === 'string') return source;
+  if (typeof source === 'number') return Image.resolveAssetSource(source).uri;
+  return source ? source.uri : undefined;
+}
+
+function resolveLineHeight(lineHeight: NonNullable<ReaderSurfaceProps['lineHeight']>): number {
+  if (lineHeight === 'compact') return 1.25;
+  if (lineHeight === 'relaxed') return 1.75;
+  return 1.5;
+}
+
+const styles = StyleSheet.create({
+  viewport: { flex: 1, minHeight: 360 },
+});
+
+const DOM_CONFIGURATION = {
+  allowsInlineMediaPlayback: false,
+  javaScriptCanOpenWindowsAutomatically: false,
+  mediaPlaybackRequiresUserAction: true,
+  originWhitelist: ['about:blank', 'blob:*'],
+  scrollEnabled: false,
+  style: styles.viewport,
+  unstable_useExpoModulesBridge: false,
+};

package/src/reader/ReaderDocumentError.ts

@@ -0,0 +1,11 @@
+import type { ReaderErrorCode } from '@ankhorage/zora';
+
+export class ReaderDocumentError extends Error {
+  constructor(
+    readonly code: ReaderErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'ReaderDocumentError';
+  }
+}

package/src/reader/ReaderViewport.tsx

@@ -0,0 +1,319 @@
+'use dom';
+
+import React from 'react';
+
+import { EpubReaderDriver } from './drivers/EpubReaderDriver';
+import { PdfReaderDriver } from './drivers/PdfReaderDriver';
+import { loadReaderSourceAsync } from './loadReaderSourceAsync';
+import { resolveReaderKeyboardIntent } from './navigation/resolveReaderKeyboardIntent';
+import { resolveReaderNavigationIntent } from './navigation/resolveReaderNavigationIntent';
+import { ReaderDocumentError } from './ReaderDocumentError';
+import { LOADING_STATE, READER_STYLES } from './readerViewportPresentation';
+import type {
+  ReaderDriver,
+  ReaderDriverState,
+  ReaderTouchStart,
+  ReaderViewportProps,
+  ReaderViewportState,
+} from './types';
+
+type ReaderTrigger = NonNullable<ReaderViewportState['location']>['trigger'];
+type EmitReaderState = (state: ReaderDriverState, trigger: ReaderTrigger) => void;
+
+export default function ReaderViewport(props: ReaderViewportProps) {
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const runtime = useReaderLifecycle(props, containerRef);
+  useReaderCommand(props.command, props.sourceUri, runtime.driverRef, runtime.emitState);
+  const input = useReaderInput(runtime.driverRef, runtime.driverStateRef, runtime.emitState);
+
+  return (
+    <div
+      aria-label="Reader viewport"
+      className={`reader-root reader-${props.appearance.colorScheme}`}
+      onKeyDown={input.handleKeyDown}
+      onTouchEnd={input.handleTouchEnd}
+      onTouchStart={input.handleTouchStart}
+      role="document"
+      tabIndex={0}
+    >
+      <style>{READER_STYLES}</style>
+      <div className="reader-content" ref={containerRef} />
+    </div>
+  );
+}
+
+function useReaderLifecycle(
+  props: ReaderViewportProps,
+  containerRef: React.RefObject<HTMLDivElement | null>,
+) {
+  const driverRef = React.useRef<ReaderDriver | undefined>(undefined);
+  const driverStateRef = React.useRef<ReaderDriverState | undefined>(undefined);
+  const emitState = useEmitReaderState(props, driverStateRef);
+  useReaderDriverEffect(props, containerRef, driverRef, driverStateRef, emitState);
+  return { driverRef, driverStateRef, emitState };
+}
+
+function useEmitReaderState(
+  props: ReaderViewportProps,
+  stateRef: React.RefObject<ReaderDriverState | undefined>,
+): EmitReaderState {
+  const { format, onStateChange } = props;
+  return React.useCallback<EmitReaderState>(
+    (state, trigger) => {
+      stateRef.current = state;
+      void onStateChange(toViewportState(state, format, trigger));
+    },
+    [format, onStateChange, stateRef],
+  );
+}
+
+function useReaderDriverEffect(
+  props: ReaderViewportProps,
+  containerRef: React.RefObject<HTMLDivElement | null>,
+  driverRef: React.RefObject<ReaderDriver | undefined>,
+  driverStateRef: React.RefObject<ReaderDriverState | undefined>,
+  emitState: EmitReaderState,
+): void {
+  const { appearance, format, onError, onOpenExternalLink, onStateChange, sourceUri } = props;
+  const { colorScheme, fontScale, lineHeight } = appearance;
+  const [initialLocation] = React.useState(props.initialLocation);
+
+  React.useEffect(
+    () =>
+      mountReaderDriver({
+        container: containerRef.current,
+        driverRef,
+        driverStateRef,
+        emitState,
+        onError,
+        onStateChange,
+        reader: {
+          appearance: { colorScheme, fontScale, lineHeight },
+          format,
+          initialLocation,
+          onError,
+          onOpenExternalLink,
+          sourceUri,
+        },
+      }),
+    [
+      colorScheme,
+      containerRef,
+      driverRef,
+      driverStateRef,
+      emitState,
+      format,
+      fontScale,
+      initialLocation,
+      lineHeight,
+      onError,
+      onOpenExternalLink,
+      onStateChange,
+      sourceUri,
+    ],
+  );
+}
+
+function mountReaderDriver(args: MountReaderDriverArgs): () => void {
+  const controller = new AbortController();
+  const holder: { driver?: ReaderDriver } = {};
+  args.container?.replaceChildren();
+  void args.onStateChange(LOADING_STATE);
+  if (args.container) {
+    void initializeReaderDriver(args.reader, args.container, controller.signal, args.emitState)
+      .then(async (driver) => {
+        if (controller.signal.aborted) return driver.destroy();
+        holder.driver = driver;
+        args.driverRef.current = driver;
+        args.emitState(driver.getState(), 'location');
+      })
+      .catch((error: unknown) => {
+        if (!controller.signal.aborted)
+          void args.onError(normalizeReaderError(error, args.reader.format));
+      });
+  }
+  return () => {
+    controller.abort();
+    args.driverRef.current = undefined;
+    args.driverStateRef.current = undefined;
+    if (holder.driver) void holder.driver.destroy();
+  };
+}
+
+async function initializeReaderDriver(
+  props: Pick<
+    ReaderViewportProps,
+    'appearance' | 'format' | 'initialLocation' | 'onError' | 'onOpenExternalLink' | 'sourceUri'
+  >,
+  container: HTMLElement,
+  signal: AbortSignal,
+  emitState: EmitReaderState,
+): Promise<ReaderDriver> {
+  const bytes = await loadReaderSourceAsync(props.sourceUri, signal);
+  if (props.format === 'pdf') {
+    return PdfReaderDriver.create({
+      bytes,
+      container,
+      initialLocation: props.initialLocation,
+      onExternalLink: (url) => void props.onOpenExternalLink({ url }),
+      onRenderError: (error) => void props.onError(normalizeReaderError(error, props.format)),
+    });
+  }
+  return EpubReaderDriver.create({
+    appearance: props.appearance,
+    bytes,
+    container,
+    initialLocation: props.initialLocation,
+    onExternalLink: (url) => void props.onOpenExternalLink({ url }),
+    onStateChange: (state) => emitState(state, 'location'),
+    signal,
+  });
+}
+
+interface MountReaderDriverArgs {
+  readonly container: HTMLElement | null;
+  readonly driverRef: React.RefObject<ReaderDriver | undefined>;
+  readonly driverStateRef: React.RefObject<ReaderDriverState | undefined>;
+  readonly emitState: EmitReaderState;
+  readonly onError: ReaderViewportProps['onError'];
+  readonly onStateChange: ReaderViewportProps['onStateChange'];
+  readonly reader: Pick<
+    ReaderViewportProps,
+    'appearance' | 'format' | 'initialLocation' | 'onError' | 'onOpenExternalLink' | 'sourceUri'
+  >;
+}
+
+function useReaderCommand(
+  command: ReaderViewportProps['command'],
+  sourceUri: string,
+  driverRef: React.RefObject<ReaderDriver | undefined>,
+  emitState: EmitReaderState,
+): void {
+  const lastCommandIdRef = React.useRef(0);
+  React.useEffect(() => {
+    if (command?.sourceUri !== sourceUri || command.id <= lastCommandIdRef.current) return;
+    lastCommandIdRef.current = command.id;
+    const trigger = command.type === 'next' ? 'nextControl' : 'previousControl';
+    void navigate(driverRef.current, command.type, trigger, emitState);
+  }, [command, driverRef, emitState, sourceUri]);
+}
+
+function useReaderInput(
+  driverRef: React.RefObject<ReaderDriver | undefined>,
+  stateRef: React.RefObject<ReaderDriverState | undefined>,
+  emitState: EmitReaderState,
+) {
+  const touchStartRef = React.useRef<ReaderTouchStart | undefined>(undefined);
+  const handleTouchStart = React.useCallback((event: React.TouchEvent<HTMLDivElement>) => {
+    const touch = event.changedTouches[0];
+    if (touch) {
+      touchStartRef.current = {
+        interactive: isInteractiveTarget(event.target),
+        x: touch.clientX,
+        y: touch.clientY,
+      };
+    }
+  }, []);
+  const handleTouchEnd = React.useCallback(
+    (event: React.TouchEvent<HTMLDivElement>) => {
+      handleSwipe(event, touchStartRef.current, driverRef.current, stateRef.current, emitState);
+      touchStartRef.current = undefined;
+    },
+    [driverRef, emitState, stateRef],
+  );
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) =>
+      handleKeyboard(event, driverRef.current, stateRef.current, emitState),
+    [driverRef, emitState, stateRef],
+  );
+  return { handleKeyDown, handleTouchEnd, handleTouchStart };
+}
+
+function handleSwipe(
+  event: React.TouchEvent<HTMLDivElement>,
+  start: ReaderTouchStart | undefined,
+  driver: ReaderDriver | undefined,
+  state: ReaderDriverState | undefined,
+  emitState: EmitReaderState,
+): void {
+  const touch = event.changedTouches[0];
+  if (!start || !touch || !driver || !state) return;
+  const intent = resolveReaderNavigationIntent({
+    canGoNext: state.canGoNext,
+    canGoPrevious: state.canGoPrevious,
+    deltaX: touch.clientX - start.x,
+    deltaY: touch.clientY - start.y,
+    direction: driver.direction,
+    hasSelection: !window.getSelection()?.isCollapsed,
+    isInteractiveTarget: start.interactive,
+    viewportWidth: event.currentTarget.clientWidth,
+  });
+  if (intent) void navigate(driver, intent, 'swipe', emitState);
+}
+
+function handleKeyboard(
+  event: React.KeyboardEvent<HTMLDivElement>,
+  driver: ReaderDriver | undefined,
+  state: ReaderDriverState | undefined,
+  emitState: EmitReaderState,
+): void {
+  if (!driver || !state) return;
+  const intent = resolveReaderKeyboardIntent({
+    canGoNext: state.canGoNext,
+    canGoPrevious: state.canGoPrevious,
+    direction: driver.direction,
+    hasModifier: event.altKey || event.ctrlKey || event.metaKey || event.shiftKey,
+    isInteractiveTarget: isInteractiveTarget(event.target),
+    key: event.key,
+  });
+  if (!intent) return;
+  event.preventDefault();
+  void navigate(driver, intent, 'keyboard', emitState);
+}
+
+async function navigate(
+  driver: ReaderDriver | undefined,
+  intent: 'next' | 'previous',
+  trigger: ReaderTrigger,
+  emitState: EmitReaderState,
+): Promise<void> {
+  if (!driver) return;
+  if (intent === 'next') await driver.goNext(trigger);
+  else await driver.goPrevious(trigger);
+  emitState(driver.getState(), trigger);
+}
+
+function toViewportState(
+  state: ReaderDriverState,
+  format: ReaderViewportProps['format'],
+  trigger: ReaderTrigger,
+): ReaderViewportState {
+  return {
+    canGoNext: state.canGoNext,
+    canGoPrevious: state.canGoPrevious,
+    location: { format, trigger, ...state },
+    page: state.page,
+    pageCount: state.pageCount,
+    progress: state.progression,
+    status: 'ready',
+  };
+}
+
+function isInteractiveTarget(target: EventTarget): boolean {
+  return (
+    target instanceof Element &&
+    target.closest(
+      'a, button, input, select, textarea, [contenteditable="true"], [role="button"]',
+    ) !== null
+  );
+}
+
+function normalizeReaderError(error: unknown, format: ReaderViewportProps['format']) {
+  if (error instanceof ReaderDocumentError)
+    return { code: error.code, format, message: error.message };
+  return {
+    code: 'load-failed' as const,
+    format,
+    message: error instanceof Error ? error.message : 'The document could not be loaded.',
+  };
+}