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

package/lib/src/interfaces/index.d.ts

@@ -1,6 +1,11 @@
-export * from './BaseReadiumViewProps';
+export * from './Decoration';
 export * from './Dimensions';
 export * from './File';
 export * from './Link';
 export * from './Locator';
 export * from './Preferences';
+export * from './PublicationMetadata';
+export * from './PublicationReady';
+export * from './Selection';
+export * from './SelectionAction';
+export type { Rect, Point } from '../specs/ReadiumView.nitro';

package/lib/src/interfaces/index.js

@@ -1,6 +1,10 @@
-export * from './BaseReadiumViewProps';
+export * from './Decoration';
 export * from './Dimensions';
 export * from './File';
 export * from './Link';
 export * from './Locator';
 export * from './Preferences';
+export * from './PublicationMetadata';
+export * from './PublicationReady';
+export * from './Selection';
+export * from './SelectionAction';

package/lib/src/specs/ReadiumView.nitro.d.ts

@@ -0,0 +1,199 @@
+import { type HybridView, type HybridViewProps, type HybridViewMethods } from 'react-native-nitro-modules';
+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;
+}
+export interface Link {
+    href: string;
+    templated: boolean;
+    type?: string;
+    title?: string;
+    rels?: string[];
+    height?: number;
+    width?: number;
+    bitrate?: number;
+    duration?: number;
+    languages?: string[];
+}
+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;
+}
+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[];
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface SelectionAction {
+    id: string;
+    label: string;
+}
+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;
+}
+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;
+}
+export interface ReadiumFile {
+    url: string;
+    initialLocation?: Locator;
+}
+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/lib/src/specs/ReadiumView.nitro.js

@@ -0,0 +1 @@
+export {};

package/lib/src/utils/index.d.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/lib/src/utils/index.js

@@ -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/lib/web/hooks/index.d.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/lib/web/hooks/index.js

@@ -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/lib/web/hooks/useDecorationsObserver.d.ts

@@ -0,0 +1,6 @@
+import type { EpubNavigator } from '@readium/navigator';
+import type { DecorationGroups, DecorationActivatedEvent } from '../../src/interfaces';
+/**
+ * Hook to observe and apply decorations to the navigator
+ */
+export declare const useDecorationsObserver: (navigator: EpubNavigator | null, decorations: DecorationGroups | undefined, onDecorationActivated?: (event: DecorationActivatedEvent) => void) => void;

package/lib/web/hooks/useDecorationsObserver.js

@@ -0,0 +1,96 @@
+import { useEffect, useRef } from 'react';
+import { useDeepCompareEffect } from 'use-deep-compare';
+/**
+ * Hook to observe and apply decorations to the navigator
+ */
+export const useDecorationsObserver = (navigator, decorations, onDecorationActivated) => {
+    // Track which groups have had listeners attached
+    const activeGroupsRef = useRef(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.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.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.addDecorationListener === 'function') {
+                    navigator.addDecorationListener(group, (event) => {
+                        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) {
+    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/lib/web/hooks/useLocationObserver.d.ts

@@ -1,2 +1,3 @@
+import { EpubNavigator } from '@readium/navigator';
 import type { Link, Locator } from '../../src/interfaces';
-export declare const useLocationObserver: (reader?: D2Reader | null, location?: Link | Locator | null) => void;
+export declare const useLocationObserver: (navigator?: EpubNavigator | null, location?: Link | Locator | null) => void;

package/lib/web/hooks/useLocationObserver.js

@@ -1,15 +1,22 @@
+import { useRef } from 'react';
 import { useDeepCompareEffect } from 'use-deep-compare';
-export const useLocationObserver = (reader, location) => {
+export const useLocationObserver = (navigator, location) => {
+    const lastHrefRef = useRef(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);
+        // 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.locations?.progression !== undefined &&
+            location.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/lib/web/hooks/useNavigator.d.ts

@@ -0,0 +1,12 @@
+import { EpubNavigator } from '@readium/navigator';
+import { Locator } from '@readium/shared';
+import type { ReadiumProps } from '../../src/components/ReadiumView';
+interface RefProps extends Pick<ReadiumProps, 'file' | 'onLocationChange' | 'onPublicationReady'> {
+    container: HTMLElement | null;
+    onPositionChange?: (position: number | null) => void;
+}
+export declare const useNavigator: ({ file, onLocationChange, onPublicationReady, container, onPositionChange, }: RefProps) => {
+    navigator: EpubNavigator | null;
+    positions: Locator[];
+};
+export {};

package/lib/web/hooks/useNavigator.js

@@ -0,0 +1,92 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { EpubNavigator } from '@readium/navigator';
+import { Publication } from '@readium/shared';
+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';
+export const useNavigator = ({ file, onLocationChange, onPublicationReady, container, onPositionChange, }) => {
+    const [navigator, setNavigator] = useState(null);
+    const [positions, setPositions] = useState([]);
+    const readingOrder = useRef([]);
+    const onLocationChangeWithTotalProgression = useCallback((newLocation) => {
+        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);
+            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/lib/web/hooks/usePositionLabel.d.ts

@@ -0,0 +1,9 @@
+import { EpubNavigator } from '@readium/navigator';
+import type { Locator } from '../../src/interfaces';
+interface PositionLabelData {
+    currentPosition: number | null;
+    totalPositions: number;
+    label: string | null;
+}
+export declare const usePositionLabel: (navigator: EpubNavigator | null, positionsArray: Locator[]) => PositionLabelData;
+export {};

package/lib/web/hooks/usePositionLabel.js

@@ -0,0 +1,33 @@
+import { useEffect, useState } from 'react';
+export const usePositionLabel = (navigator, positionsArray) => {
+    const [currentPosition, setCurrentPosition] = useState(null);
+    const [totalPositions, setTotalPositions] = useState(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.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/lib/web/hooks/usePreferencesObserver.d.ts

@@ -0,0 +1,2 @@
+import { EpubNavigator } from '@readium/navigator';
+export declare const usePreferencesObserver: (navigator?: EpubNavigator | null, preferences?: any) => void;

package/lib/web/hooks/usePreferencesObserver.js

@@ -0,0 +1,54 @@
+import { useDeepCompareEffect } from 'use-deep-compare';
+/**
+ * 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) {
+    const mapped = { ...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];
+        if (themeColors) {
+            mapped.backgroundColor = themeColors.backgroundColor;
+            mapped.textColor = themeColors.textColor;
+        }
+    }
+    return mapped;
+}
+export const usePreferencesObserver = (navigator, preferences) => {
+    useDeepCompareEffect(() => {
+        if (navigator && preferences) {
+            const mappedPreferences = mapPreferencesToNavigator(preferences);
+            navigator?.submitPreferences(mappedPreferences);
+        }
+    }, [preferences, !!navigator]);
+};

package/lib/web/utils/locationNormalizer.d.ts

@@ -0,0 +1,28 @@
+import type { Locator } from '@readium/shared';
+import type { Link, Locator as LocalLocator } from '../../src/interfaces';
+/**
+ * Normalizes an href by removing leading slashes for consistency across platforms.
+ *
+ * The Readium toolkit expects hrefs in relative format (e.g., "OPS/main3.xml")
+ * rather than absolute format (e.g., "/OPS/main3.xml").
+ *
+ * @param href - The href to normalize
+ * @returns The normalized href without leading slash
+ */
+export declare function normalizeHref(href: string): string;
+/**
+ * Normalizes a location object (Link or Locator) by normalizing its href.
+ *
+ * @param location - The Link or Locator to normalize
+ * @returns A new location object with normalized href
+ */
+export declare function normalizeLocation<T extends {
+    href: string;
+}>(location: T): T;
+/**
+ * Converts a Link or Locator to a Readium Locator format suitable for navigation.
+ *
+ * @param location - The Link or Locator from the file.initialLocation
+ * @returns A Locator object ready for the Readium navigator, or undefined if invalid
+ */
+export declare function convertToNavigatorLocator(location: Link | LocalLocator): Locator | undefined;