react-native-readium 4.0.2 → 5.0.0-rc.1

package/src/specs/ReadiumView.nitro.ts

@@ -0,0 +1,249 @@
+import {
+  type HybridView,
+  type HybridViewProps,
+  type HybridViewMethods,
+} from 'react-native-nitro-modules';
+
+// ── Locator ──────────────────────────────────────────────────────────────────
+
+export interface LocatorLocations {
+  progression: number;
+  position?: number;
+  totalProgression?: number;
+}
+
+export interface LocatorText {
+  before?: string;
+  highlight?: string;
+  after?: string;
+}
+
+export interface Locator {
+  href: string;
+  type: string;
+  target?: number;
+  title?: string;
+  locations?: LocatorLocations;
+  text?: LocatorText;
+}
+
+// ── Link ─────────────────────────────────────────────────────────────────────
+
+export interface Link {
+  href: string;
+  templated: boolean;
+  type?: string;
+  title?: string;
+  rels?: string[];
+  height?: number;
+  width?: number;
+  bitrate?: number;
+  duration?: number;
+  languages?: string[];
+}
+
+// ── Preferences ──────────────────────────────────────────────────────────────
+
+export interface Preferences {
+  backgroundColor?: string;
+  columnCount?: string;
+  fontFamily?: string;
+  fontSize?: number;
+  fontWeight?: number;
+  hyphens?: boolean;
+  imageFilter?: string;
+  language?: string;
+  letterSpacing?: number;
+  ligatures?: boolean;
+  lineHeight?: number;
+  pageMargins?: number;
+  paragraphIndent?: number;
+  paragraphSpacing?: number;
+  publisherStyles?: boolean;
+  readingProgression?: string;
+  scroll?: boolean;
+  spread?: string;
+  textAlign?: string;
+  textColor?: string;
+  textNormalization?: boolean;
+  theme?: string;
+  typeScale?: number;
+  verticalText?: boolean;
+  wordSpacing?: number;
+  merging?: boolean;
+}
+
+// ── Decoration ───────────────────────────────────────────────────────────────
+
+export interface DecorationStyle {
+  type: string;
+  tint?: string;
+  isActive?: boolean;
+  id?: string;
+  html?: string;
+  css?: string;
+  layout?: string;
+  width?: string;
+}
+
+export interface Decoration {
+  id: string;
+  locator: Locator;
+  style: DecorationStyle;
+  extras?: Record<string, string>;
+}
+
+export interface DecorationGroup {
+  name: string;
+  decorations: Decoration[];
+}
+
+// ── Rect / Point ─────────────────────────────────────────────────────────────
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+// ── Selection ────────────────────────────────────────────────────────────────
+
+export interface SelectionAction {
+  id: string;
+  label: string;
+}
+
+// ── Publication Metadata ─────────────────────────────────────────────────────
+
+export interface Contributor {
+  name: string;
+  sortAs?: string;
+  identifier?: string;
+  role?: string;
+  position?: number;
+}
+
+export interface Subject {
+  name: string;
+  sortAs?: string;
+  code?: string;
+  scheme?: string;
+}
+
+export interface SeriesInfo {
+  name: string;
+  position?: number;
+}
+
+export interface BelongsTo {
+  series?: SeriesInfo[];
+  collection?: SeriesInfo[];
+}
+
+export interface AccessibilityCertification {
+  certifiedBy?: string;
+  credential?: string;
+  report?: string;
+}
+
+export interface Accessibility {
+  conformsTo?: string[];
+  certification?: AccessibilityCertification;
+  accessMode?: string[];
+  accessModeSufficient?: string[];
+  feature?: string[];
+  hazard?: string[];
+  summary?: string;
+}
+
+export interface PublicationMetadata {
+  title: string;
+  sortAs?: string;
+  subtitle?: string;
+  identifier?: string;
+  accessibility?: Accessibility;
+  modified?: string;
+  published?: string;
+  language?: string[];
+  author?: Contributor[];
+  translator?: Contributor[];
+  editor?: Contributor[];
+  artist?: Contributor[];
+  illustrator?: Contributor[];
+  letterer?: Contributor[];
+  penciler?: Contributor[];
+  colorist?: Contributor[];
+  inker?: Contributor[];
+  narrator?: Contributor[];
+  contributor?: Contributor[];
+  publisher?: Contributor[];
+  imprint?: Contributor[];
+  subject?: Subject[];
+  layout?: string;
+  readingProgression?: string;
+  description?: string;
+  duration?: number;
+  numberOfPages?: number;
+  belongsTo?: BelongsTo;
+}
+
+// ── Events ───────────────────────────────────────────────────────────────────
+
+export interface PublicationReadyEvent {
+  tableOfContents: Link[];
+  positions: Locator[];
+  metadata: PublicationMetadata;
+}
+
+export interface DecorationActivatedEvent {
+  decoration: Decoration;
+  group: string;
+  rect?: Rect;
+  point?: Point;
+}
+
+export interface SelectionEvent {
+  locator?: Locator;
+  selectedText?: string;
+}
+
+export interface SelectionActionEvent {
+  locator: Locator;
+  selectedText: string;
+  actionId: string;
+}
+
+// ── File ─────────────────────────────────────────────────────────────────────
+
+export interface ReadiumFile {
+  url: string;
+  initialLocation?: Locator;
+}
+
+// ── HybridView ───────────────────────────────────────────────────────────────
+
+export interface ReadiumViewProps extends HybridViewProps {
+  file: ReadiumFile;
+  location?: Locator;
+  preferences?: Preferences;
+  decorations?: DecorationGroup[];
+  selectionActions?: SelectionAction[];
+  onLocationChange: (locator: Locator) => void;
+  onPublicationReady: (event: PublicationReadyEvent) => void;
+  onDecorationActivated: (event: DecorationActivatedEvent) => void;
+  onSelectionChange: (event: SelectionEvent) => void;
+  onSelectionAction: (event: SelectionActionEvent) => void;
+}
+
+export interface ReadiumViewMethods extends HybridViewMethods {
+  goForward(): void;
+  goBackward(): void;
+}
+
+export type ReadiumView = HybridView<ReadiumViewProps, ReadiumViewMethods>;

package/src/utils/index.ts

@@ -1,7 +1 @@
-export * from './clamp';
-export * from './COMPONENT_NAME';
-export * from './createFragment';
-export * from './getWidthOrHeightValue';
-export * from './indexOfObjectValue';
-export * from './LINKING_ERROR';
 export * from './RANGES';

package/web/hooks/index.ts

@@ -1,3 +1,5 @@
-export * from './useReaderRef';
-export * from './useSettingsObserver';
+export * from './useNavigator';
+export * from './usePreferencesObserver';
 export * from './useLocationObserver';
+export * from './usePositionLabel';
+export * from './useDecorationsObserver';

package/web/hooks/useDecorationsObserver.ts

@@ -0,0 +1,116 @@
+import { useEffect, useRef } from 'react';
+import type { EpubNavigator } from '@readium/navigator';
+import type {
+  DecorationGroups,
+  DecorationActivatedEvent,
+} from '../../src/interfaces';
+import { useDeepCompareEffect } from 'use-deep-compare';
+
+/**
+ * Hook to observe and apply decorations to the navigator
+ */
+export const useDecorationsObserver = (
+  navigator: EpubNavigator | null,
+  decorations: DecorationGroups | undefined,
+  onDecorationActivated?: (event: DecorationActivatedEvent) => void
+) => {
+  // Track which groups have had listeners attached
+  const activeGroupsRef = useRef<Set<string>>(new Set());
+
+  useDeepCompareEffect(() => {
+    if (!navigator || !decorations) {
+      return;
+    }
+
+    // Check if navigator supports decorations
+    // The web navigator (ts-toolkit) doesn't have decoration support yet
+    if (typeof (navigator as any).applyDecorations !== 'function') {
+      console.warn(
+        'Web navigator does not support decorations API yet. Decorations will not be rendered.'
+      );
+      return;
+    }
+
+    // Apply decorations for each group
+    Object.entries(decorations).forEach(([group, decorationList]) => {
+      // Convert decoration data to navigator format
+      const navigatorDecorations = decorationList.map((decoration) => ({
+        id: decoration.id,
+        locator: decoration.locator,
+        style: convertStyle(decoration.style),
+        extras: decoration.extras,
+      }));
+
+      // Apply decorations to the group
+      (navigator as any).applyDecorations(navigatorDecorations, group);
+
+      // Set up listener for this group if not already active
+      if (!activeGroupsRef.current.has(group)) {
+        activeGroupsRef.current.add(group);
+
+        if (typeof (navigator as any).addDecorationListener === 'function') {
+          (navigator as any).addDecorationListener(group, (event: any) => {
+            if (onDecorationActivated) {
+              onDecorationActivated({
+                decoration: {
+                  id: event.decoration.id,
+                  locator: event.decoration.locator,
+                  style: event.decoration.style,
+                  extras: event.decoration.extras,
+                },
+                group: group,
+                rect: event.rect,
+                point: event.point,
+              });
+            }
+          });
+        }
+      }
+    });
+  }, [navigator, decorations, onDecorationActivated]);
+
+  // Clean up listeners when component unmounts
+  useEffect(() => {
+    return () => {
+      if (navigator) {
+        activeGroupsRef.current.forEach((group) => {
+          // Remove decoration listener for each group
+          // Note: This depends on navigator API having a removeDecorationListener method
+          // If not available, listeners will be cleaned up when navigator is destroyed
+        });
+        activeGroupsRef.current.clear();
+      }
+    };
+  }, [navigator]);
+};
+
+/**
+ * Convert decoration style from TypeScript interface to navigator format
+ */
+function convertStyle(style: any): any {
+  switch (style.type) {
+    case 'highlight':
+      return {
+        type: 'highlight',
+        tint: style.tint,
+        isActive: style.isActive ?? false,
+      };
+    case 'underline':
+      return {
+        type: 'underline',
+        tint: style.tint,
+        isActive: style.isActive ?? false,
+      };
+    case 'custom':
+      return {
+        type: 'custom',
+        id: style.id,
+        html: style.html,
+        css: style.css,
+        layout: style.layout ?? 'bounds',
+        width: style.width ?? 'wrap',
+      };
+    default:
+      return style;
+  }
+}

package/web/hooks/useLocationObserver.ts

@@ -1,21 +1,34 @@
+import { useRef } from 'react';
 import { useDeepCompareEffect } from 'use-deep-compare';
+import { EpubNavigator } from '@readium/navigator';
 
 import type { Link, Locator } from '../../src/interfaces';
 
 export const useLocationObserver = (
-  reader?: D2Reader | null,
+  navigator?: EpubNavigator | null,
   location?: Link | Locator | null
 ) => {
+  const lastHrefRef = useRef<string | null>(null);
+
   useDeepCompareEffect(() => {
-    if (reader && location) {
-      // NOTE: technically this is a Link | Locator. However, under the hood the
-      // R2D2BC is converting Links to locators, so just force the type here.
-      reader.goTo(location as R2Locator);
+    // Only navigate if we have a navigator, a location, and the href has changed.
+    // Skip navigation if location.locations exists with progression and totalProgression
+    // (it's from the navigator's positionChanged callback)
+    const hasFullLocationData =
+      'locations' in (location ?? {}) &&
+      (location as Locator).locations?.progression !== undefined &&
+      (location as Locator).locations?.totalProgression !== undefined;
+
+    if (
+      navigator &&
+      location &&
+      location.href !== lastHrefRef.current &&
+      !hasFullLocationData
+    ) {
+      lastHrefRef.current = location.href;
+      // For Link objects (from TOC), we can pass them directly
+      // @ts-ignore
+      navigator.go(location, true, () => {});
     }
-  }, [
-    location?.href,
-    //@ts-ignore
-    location?.locations,
-    !!reader,
-  ]);
+  }, [location?.href, !!navigator]);
 };

package/web/hooks/useNavigator.ts

@@ -0,0 +1,152 @@
+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';
+import { convertToNavigatorLocator } from '../utils/locationNormalizer';
+
+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. Process initial location
+      const initialPosition = file.initialLocation
+        ? convertToNavigatorLocator(file.initialLocation)
+        : undefined;
+
+      // 7. Initialize and load the navigator
+      const configuration = {
+        preferences: { scroll: false },
+        defaults: {},
+      };
+
+      const nav = new EpubNavigator(
+        container,
+        publication,
+        listeners,
+        positionsArray,
+        initialPosition, // Pass the initial position
+        configuration as any
+      );
+      await nav.load();
+
+      // 8. 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]);
+};