react-native-readium 4.0.1 → 5.0.0-rc.0

package/web/hooks/useNavigator.ts

@@ -0,0 +1,146 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { EpubNavigator } from '@readium/navigator';
+import { Locator, Publication } from '@readium/shared';
+
+import type { ReadiumProps } from '../../src/components/ReadiumView';
+import { normalizeMetadata } from '../utils/metadataNormalizer';
+import { fetchManifest } from '../utils/manifestFetcher';
+import { createNavigatorListeners } from '../utils/navigatorListeners';
+import {
+  normalizePublicationURL,
+  createPositions,
+  extractTableOfContents,
+} from '../utils/publicationUtils';
+
+interface RefProps
+  extends Pick<
+    ReadiumProps,
+    'file' | 'onLocationChange' | 'onPublicationReady'
+  > {
+  container: HTMLElement | null;
+  onPositionChange?: (position: number | null) => void;
+}
+
+export const useNavigator = ({
+  file,
+  onLocationChange,
+  onPublicationReady,
+  container,
+  onPositionChange,
+}: RefProps) => {
+  const [navigator, setNavigator] = useState<EpubNavigator | null>(null);
+  const [positions, setPositions] = useState<Locator[]>([]);
+  const readingOrder = useRef<Locator[]>([]);
+
+  const onLocationChangeWithTotalProgression = useCallback(
+    (newLocation: Locator) => {
+      if (
+        !onLocationChange ||
+        !readingOrder.current ||
+        !newLocation.locations
+      ) {
+        return;
+      }
+
+      let totalProgression = newLocation.locations.totalProgression;
+
+      if (!totalProgression) {
+        const newLocationIndex = readingOrder.current.findIndex(
+          (entry) => entry.href === newLocation.href
+        );
+        if (newLocationIndex < 0 || !readingOrder.current[newLocationIndex]) {
+          return;
+        }
+        const readingOrderCount = readingOrder.current.length;
+        const chapterTotalProgression =
+          readingOrder.current[newLocationIndex].locations?.totalProgression ||
+          0;
+
+        const newLocationProgression = newLocation.locations.progression || 0;
+        const intraChapterTotalProgression =
+          newLocationProgression / readingOrderCount;
+        totalProgression =
+          chapterTotalProgression + intraChapterTotalProgression;
+      }
+
+      // Create a new location object with the calculated totalProgression
+      const updatedLocation = {
+        ...newLocation,
+        locations: {
+          ...newLocation.locations,
+          progression: newLocation.locations.progression || 0,
+          totalProgression,
+        },
+      };
+
+      // @ts-ignore - Type compatibility between Readium Locator and our Locator interface
+      onLocationChange(updatedLocation);
+    },
+    [onLocationChange]
+  );
+
+  useEffect(() => {
+    async function initializeNavigator() {
+      if (!container) return;
+
+      // 1. Normalize the publication URL
+      const publicationURL = normalizePublicationURL(file.url);
+
+      // 2. Fetch and deserialize the manifest
+      const { manifest, fetcher } = await fetchManifest(publicationURL);
+
+      // 3. Create the publication
+      const publication = new Publication({ manifest, fetcher });
+
+      // 4. Create positions array for navigation
+      const positionsArray = createPositions(publication);
+      readingOrder.current = positionsArray;
+      setPositions(positionsArray);
+
+      // 5. Create navigator listeners
+      const listeners = createNavigatorListeners(
+        onLocationChangeWithTotalProgression,
+        onPositionChange
+      );
+
+      // 6. Initialize and load the navigator
+      const configuration = {
+        preferences: { scroll: false },
+        defaults: {},
+      };
+
+      const nav = new EpubNavigator(
+        container,
+        publication,
+        listeners,
+        positionsArray,
+        undefined, // initialPosition
+        configuration as any
+      );
+      await nav.load();
+
+      // 7. Emit onPublicationReady event
+      if (onPublicationReady) {
+        const tocItems = extractTableOfContents(manifest);
+        const metadata = normalizeMetadata(manifest.metadata);
+
+        // @ts-ignore - Type compatibility between Readium types and our interfaces
+        onPublicationReady({
+          // @ts-ignore
+          tableOfContents: tocItems,
+          // @ts-ignore
+          positions: positionsArray,
+          metadata: metadata,
+        });
+      }
+
+      setNavigator(nav);
+    }
+
+    initializeNavigator();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [file.url, container]);
+
+  return { navigator, positions };
+};

package/web/hooks/usePositionLabel.ts

@@ -0,0 +1,51 @@
+import { useEffect, useState } from 'react';
+import { EpubNavigator } from '@readium/navigator';
+import type { Locator } from '../../src/interfaces';
+
+interface PositionLabelData {
+  currentPosition: number | null;
+  totalPositions: number;
+  label: string | null;
+}
+
+export const usePositionLabel = (
+  navigator: EpubNavigator | null,
+  positionsArray: Locator[]
+): PositionLabelData => {
+  const [currentPosition, setCurrentPosition] = useState<number | null>(null);
+  const [totalPositions, setTotalPositions] = useState<number>(0);
+
+  // Update total positions when positions array changes
+  useEffect(() => {
+    if (positionsArray && positionsArray.length > 0) {
+      setTotalPositions(positionsArray.length);
+    }
+  }, [positionsArray]);
+
+  // Listen to navigator position changes
+  useEffect(() => {
+    if (!navigator) return;
+
+    // Get initial position if available
+    const initialPosition = (navigator as any).currentLocation?.locations
+      ?.position;
+    if (initialPosition) {
+      setCurrentPosition(initialPosition);
+    }
+
+    // Note: The positionChanged listener is already set up in useNavigator
+    // We'll need to expose position updates through a callback
+  }, [navigator]);
+
+  // Generate label text
+  const label =
+    currentPosition && totalPositions > 0
+      ? `${currentPosition} / ${totalPositions}`
+      : null;
+
+  return {
+    currentPosition,
+    totalPositions,
+    label,
+  };
+};

package/web/hooks/usePreferencesObserver.ts

@@ -0,0 +1,69 @@
+import { useDeepCompareEffect } from 'use-deep-compare';
+
+import { EpubNavigator, EpubPreferences } from '@readium/navigator';
+
+/**
+ * Theme color mappings
+ */
+const THEME_COLORS = {
+  light: {
+    backgroundColor: '#ffffff',
+    textColor: '#000000',
+  },
+  dark: {
+    backgroundColor: '#000000',
+    textColor: '#ffffff',
+  },
+  sepia: {
+    backgroundColor: '#f4ecd8',
+    textColor: '#5f4b32',
+  },
+};
+
+// Base value for scaling pageMargins multiplier to pixels
+// Matches Readium's default pageGutter of 20px
+const PAGE_GUTTER_BASE = 20;
+
+/**
+ * Maps our app's preferences to the navigator's expected format
+ */
+function mapPreferencesToNavigator(preferences: any): EpubPreferences {
+  const mapped: any = { ...preferences };
+
+  // Map pageMargins to pageGutter (the navigator uses pageGutter, not pageMargins)
+  // Our app uses a multiplier (0.5-4.0), but Readium expects pixel values
+  // Scale the multiplier to pixels: multiplier * base (e.g., 1.0 * 20 = 20px)
+  if (preferences.pageMargins !== undefined) {
+    mapped.pageGutter = preferences.pageMargins * PAGE_GUTTER_BASE;
+    delete mapped.pageMargins;
+  }
+
+  // Convert theme to backgroundColor and textColor
+  // Only apply if backgroundColor/textColor aren't explicitly set
+  if (
+    preferences.theme &&
+    !preferences.backgroundColor &&
+    !preferences.textColor
+  ) {
+    const themeColors =
+      THEME_COLORS[preferences.theme as keyof typeof THEME_COLORS];
+    if (themeColors) {
+      mapped.backgroundColor = themeColors.backgroundColor;
+      mapped.textColor = themeColors.textColor;
+    }
+  }
+
+  return mapped as EpubPreferences;
+}
+
+export const usePreferencesObserver = (
+  navigator?: EpubNavigator | null,
+  preferences?: any
+) => {
+  useDeepCompareEffect(() => {
+    if (navigator && preferences) {
+      const mappedPreferences = mapPreferencesToNavigator(preferences);
+      navigator?.submitPreferences(mappedPreferences);
+    }
+  }, [preferences, !!navigator]);
+};

package/web/utils/manifestFetcher.ts

@@ -0,0 +1,38 @@
+import { Fetcher, HttpFetcher, Link, Manifest } from '@readium/shared';
+import { normalizeManifest } from './manifestNormalizer';
+
+/**
+ * Fetches and deserializes the publication manifest
+ */
+export async function fetchManifest(publicationURL: string): Promise<{
+  manifest: Manifest;
+  fetcher: Fetcher;
+}> {
+  const manifestLink = new Link({ href: 'manifest.json' });
+  const fetcher: Fetcher = new HttpFetcher(undefined, publicationURL);
+  const fetched = fetcher.get(manifestLink);
+  const selfLink = (await fetched.link()).toURL(publicationURL)!;
+
+  const response = await fetched.readAsJSON();
+  const responseObj = normalizeManifest(response as any);
+
+  let manifest;
+  try {
+    manifest = Manifest.deserialize(responseObj as string);
+  } catch (error) {
+    console.error('Error during manifest deserialization:', error);
+    console.error('Manifest that failed:', responseObj);
+    throw error;
+  }
+
+  if (!manifest) {
+    console.error(
+      'Failed to deserialize manifest (returned null/undefined):',
+      responseObj
+    );
+    throw new Error('Manifest deserialization returned null/undefined');
+  }
+
+  manifest.setSelfLink(selfLink);
+  return { manifest, fetcher };
+}

package/web/utils/manifestNormalizer.ts

@@ -0,0 +1,74 @@
+/**
+ * Normalizes a Readium manifest object to ensure compatibility with the navigator.
+ * Handles various inconsistencies in manifest formats:
+ * - Converts string properties to arrays where required
+ * - Normalizes date formats to ISO 8601
+ * - Ensures required properties exist
+ */
+export function normalizeManifest(manifest: any): any {
+  const responseObj = manifest;
+  const metadata = responseObj.metadata;
+
+  // Normalize root-level properties
+  if (typeof responseObj.conformsTo === 'string') {
+    responseObj.conformsTo = [responseObj.conformsTo];
+  }
+  if (typeof metadata?.conformsTo === 'string') {
+    metadata.conformsTo = [metadata.conformsTo];
+  }
+  if (typeof metadata?.accessMode === 'string') {
+    metadata.accessMode = [metadata.accessMode];
+  }
+  if (typeof metadata?.accessibilityFeature === 'string') {
+    metadata.accessibilityFeature = [metadata.accessibilityFeature];
+  }
+  if (typeof metadata?.accessibilityHazard === 'string') {
+    metadata.accessibilityHazard = [metadata.accessibilityHazard];
+  }
+
+  // Normalize nested accessibility properties
+  const accessibility = metadata?.accessibility;
+  if (accessibility) {
+    if (typeof accessibility.conformsTo === 'string') {
+      accessibility.conformsTo = [accessibility.conformsTo];
+    }
+    if (typeof accessibility.accessMode === 'string') {
+      accessibility.accessMode = [accessibility.accessMode];
+    }
+    if (typeof accessibility.feature === 'string') {
+      accessibility.feature = [accessibility.feature];
+    }
+    if (typeof accessibility.hazard === 'string') {
+      accessibility.hazard = [accessibility.hazard];
+    }
+  }
+
+  // Normalize date formats
+  // Some manifests use JavaScript Date.toString() format instead of ISO 8601
+  if (metadata?.modified && typeof metadata.modified === 'string') {
+    const date = new Date(metadata.modified);
+    if (!isNaN(date.getTime())) {
+      metadata.modified = date.toISOString();
+    }
+  }
+  if (metadata?.published && typeof metadata.published === 'string') {
+    const date = new Date(metadata.published);
+    if (!isNaN(date.getTime())) {
+      metadata.published = date.toISOString();
+    }
+  }
+
+  // Ensure links property exists (required by RWPM spec)
+  // Some manifests may have landmarks instead of links
+  if (!responseObj.links) {
+    // If landmarks exist, convert them to links
+    if (responseObj.landmarks && Array.isArray(responseObj.landmarks)) {
+      responseObj.links = responseObj.landmarks;
+    } else {
+      // Otherwise create an empty links array
+      responseObj.links = [];
+    }
+  }
+
+  return responseObj;
+}

package/web/utils/metadataNormalizer.ts

@@ -0,0 +1,238 @@
+/**
+ * Normalizes metadata to ensure consistent structure per RWPM spec.
+ *
+ * This normalizer is library-agnostic and based on the stable RWPM specification,
+ * ensuring it works regardless of how the underlying Readium library serializes data.
+ *
+ * https://readium.org/webpub-manifest/
+ */
+
+/**
+ * Normalizes a localized string per RWPM spec.
+ *
+ * Per RWPM spec, a localized string can be:
+ * 1. Plain string: "Moby-Dick"
+ * 2. Language map: {"en": "Moby-Dick", "fr": "Moby Dick"}
+ *
+ * Priority for language selection:
+ * 1. "undefined" or "und" (default/undetermined language)
+ * 2. "en" (English fallback)
+ * 3. First available language
+ *
+ * https://readium.org/webpub-manifest/contexts/default/
+ */
+export function normalizeLocalizedString(value: any): string {
+  if (!value) return '';
+
+  // Format 1: Plain string (spec-compliant shorthand)
+  if (typeof value === 'string') return value;
+
+  // Format 2: Language map (spec-compliant full form)
+  if (typeof value === 'object') {
+    // Check if it's a LocalizedString instance with translations property
+    if (value.translations) {
+      const translations = value.translations;
+      return (
+        translations['undefined'] ||
+        translations['und'] ||
+        translations['en'] ||
+        (Object.values(translations)[0] as string) ||
+        ''
+      );
+    }
+
+    // Check if it's already a plain language map object
+    return (
+      value['undefined'] ||
+      value['und'] ||
+      value['en'] ||
+      (Object.values(value)[0] as string) ||
+      ''
+    );
+  }
+
+  return '';
+}
+
+/**
+ * Normalizes contributors per RWPM spec.
+ *
+ * Per RWPM spec, a contributor can be:
+ * 1. Plain string: "Herman Melville"
+ * 2. Object: {"name": "Herman Melville", "sortAs": "Melville, Herman"}
+ *
+ * The Web library uses a Contributors class with an "items" property.
+ *
+ * https://readium.org/webpub-manifest/schema/contributor-object.schema.json
+ */
+export function normalizeContributors(value: any): any[] | undefined {
+  if (!value) return undefined;
+
+  // Handle TypeScript library's Contributors class format (has .items property)
+  const items = value.items || value;
+
+  if (!Array.isArray(items)) return undefined;
+
+  return items
+    .map((contributor: any) => {
+      // Format 1: Plain string
+      if (typeof contributor === 'string') {
+        return { name: contributor };
+      }
+
+      // Format 2: Object with potentially localized fields
+      const normalized: any = {
+        name: normalizeLocalizedString(contributor.name),
+      };
+
+      if (contributor.sortAs) {
+        normalized.sortAs = normalizeLocalizedString(contributor.sortAs);
+      }
+      if (contributor.identifier) {
+        normalized.identifier = contributor.identifier;
+      }
+      if (contributor.role) {
+        normalized.role = contributor.role;
+      }
+      if (contributor.position !== undefined) {
+        normalized.position = contributor.position;
+      }
+
+      return normalized;
+    })
+    .filter((c) => c.name); // Remove contributors without names
+}
+
+/**
+ * Normalizes subjects per RWPM spec.
+ *
+ * Subject names can be LocalizedStrings.
+ * The Web library uses a Subjects class with an "items" property.
+ *
+ * https://readium.org/webpub-manifest/schema/subject.schema.json
+ */
+export function normalizeSubjects(value: any): any[] | undefined {
+  if (!value) return undefined;
+
+  // Handle Subjects class format (has .items property)
+  const items = value.items || value;
+
+  if (!Array.isArray(items)) return undefined;
+
+  return items
+    .map((subject: any) => {
+      // Format 1: Plain string
+      if (typeof subject === 'string') {
+        return { name: subject };
+      }
+
+      // Format 2: Object
+      const normalized: any = {
+        name: normalizeLocalizedString(subject.name),
+      };
+
+      if (subject.sortAs) {
+        normalized.sortAs = normalizeLocalizedString(subject.sortAs);
+      }
+      if (subject.code) {
+        normalized.code = subject.code;
+      }
+      if (subject.scheme) {
+        normalized.scheme = subject.scheme;
+      }
+
+      return normalized;
+    })
+    .filter((s) => s.name);
+}
+
+/**
+ * Normalizes the entire metadata object per RWPM spec.
+ *
+ * This function is library-agnostic and based on the stable RWPM specification,
+ * ensuring it works regardless of how the underlying Readium library serializes data.
+ *
+ * https://readium.org/webpub-manifest/
+ */
+export function normalizeMetadata(metadata: any): any {
+  const normalized: any = {
+    // Title is required
+    title: normalizeLocalizedString(metadata.title),
+  };
+
+  // Optional localized string fields
+  if (metadata.subtitle) {
+    normalized.subtitle = normalizeLocalizedString(metadata.subtitle);
+  }
+  if (metadata.sortAs) {
+    normalized.sortAs = normalizeLocalizedString(metadata.sortAs);
+  }
+
+  // Direct copy fields
+  if (metadata.identifier) normalized.identifier = metadata.identifier;
+  if (metadata.conformsTo) normalized.conformsTo = metadata.conformsTo;
+  if (metadata.description) normalized.description = metadata.description;
+  if (metadata.readingProgression)
+    normalized.readingProgression = metadata.readingProgression;
+  if (metadata.layout) normalized.layout = metadata.layout;
+  if (metadata.duration) normalized.duration = metadata.duration;
+  if (metadata.numberOfPages) normalized.numberOfPages = metadata.numberOfPages;
+
+  // Date fields - convert to ISO strings
+  if (metadata.modified) {
+    normalized.modified =
+      metadata.modified instanceof Date
+        ? metadata.modified.toISOString()
+        : metadata.modified;
+  }
+  if (metadata.published) {
+    normalized.published =
+      metadata.published instanceof Date
+        ? metadata.published.toISOString()
+        : metadata.published;
+  }
+
+  // Languages (Web uses plural 'languages', our interface uses singular 'language')
+  if (metadata.languages) {
+    normalized.language = metadata.languages;
+  }
+
+  // Normalize all contributor types (Web uses plural names, our interface uses singular)
+  if (metadata.authors)
+    normalized.author = normalizeContributors(metadata.authors);
+  if (metadata.translators)
+    normalized.translator = normalizeContributors(metadata.translators);
+  if (metadata.editors)
+    normalized.editor = normalizeContributors(metadata.editors);
+  if (metadata.artists)
+    normalized.artist = normalizeContributors(metadata.artists);
+  if (metadata.illustrators)
+    normalized.illustrator = normalizeContributors(metadata.illustrators);
+  if (metadata.letterers)
+    normalized.letterer = normalizeContributors(metadata.letterers);
+  if (metadata.pencilers)
+    normalized.penciler = normalizeContributors(metadata.pencilers);
+  if (metadata.colorists)
+    normalized.colorist = normalizeContributors(metadata.colorists);
+  if (metadata.inkers)
+    normalized.inker = normalizeContributors(metadata.inkers);
+  if (metadata.narrators)
+    normalized.narrator = normalizeContributors(metadata.narrators);
+  if (metadata.contributors)
+    normalized.contributor = normalizeContributors(metadata.contributors);
+  if (metadata.publishers)
+    normalized.publisher = normalizeContributors(metadata.publishers);
+  if (metadata.imprints)
+    normalized.imprint = normalizeContributors(metadata.imprints);
+
+  // Normalize subjects
+  if (metadata.subjects) {
+    normalized.subject = normalizeSubjects(metadata.subjects);
+  }
+
+  // Copy complex objects as-is
+  if (metadata.belongsTo) normalized.belongsTo = metadata.belongsTo;
+  if (metadata.accessibility) normalized.accessibility = metadata.accessibility;
+
+  return normalized;
+}

package/web/utils/navigatorListeners.ts

@@ -0,0 +1,60 @@
+import {
+  BasicTextSelection,
+  FrameClickEvent,
+} from '@readium/navigator-html-injectables';
+import { EpubNavigatorListeners } from '@readium/navigator';
+import { Locator } from '@readium/shared';
+
+/**
+ * Creates navigator listeners for handling navigation events
+ */
+export function createNavigatorListeners(
+  onLocationChangeWithTotalProgression: (locator: Locator) => void,
+  onPositionChange?: (position: number | null) => void
+): EpubNavigatorListeners {
+  return {
+    frameLoaded: function (_wnd: Window): void {
+      // noop
+    },
+    positionChanged: function (_locator: Locator): void {
+      onLocationChangeWithTotalProgression(_locator);
+      if (onPositionChange) {
+        onPositionChange(_locator.locations?.position || null);
+      }
+      window.focus();
+    },
+    tap: function (_e: FrameClickEvent): boolean {
+      return false;
+    },
+    click: function (_e: FrameClickEvent): boolean {
+      return false;
+    },
+    zoom: function (_scale: number): void {
+      // noop
+    },
+    miscPointer: function (_amount: number): void {
+      // noop
+    },
+    scroll: function (_amount: number): void {
+      // noop
+    },
+    customEvent: function (_key: string, _data: unknown): void {},
+    handleLocator: function (locator: Locator): boolean {
+      const href = locator.href;
+      if (
+        href.startsWith('http://') ||
+        href.startsWith('https://') ||
+        href.startsWith('mailto:') ||
+        href.startsWith('tel:')
+      ) {
+        if (confirm(`Open "${href}" ?`)) window.open(href, '_blank');
+      } else {
+        console.warn('Unhandled locator', locator);
+      }
+      return false;
+    },
+    textSelected: function (_selection: BasicTextSelection): void {
+      // noop
+    },
+  };
+}