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

package/lib/web/utils/locationNormalizer.js

@@ -0,0 +1,49 @@
+/**
+ * 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 function normalizeHref(href) {
+    if (href.startsWith('/')) {
+        return href.substring(1);
+    }
+    return href;
+}
+/**
+ * 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 function normalizeLocation(location) {
+    return {
+        ...location,
+        href: normalizeHref(location.href),
+    };
+}
+/**
+ * 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 function convertToNavigatorLocator(location) {
+    // First, normalize the href
+    const normalized = normalizeLocation(location);
+    // Check if this is already a Locator (has locations property)
+    if ('locations' in normalized) {
+        // It's already a Locator, return it
+        return normalized;
+    }
+    // It's a Link - convert to basic Locator format
+    // The Readium navigator will handle finding the exact position
+    return {
+        href: normalized.href,
+        type: normalized.type || 'application/xhtml+xml',
+        title: normalized.title,
+    };
+}

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

@@ -0,0 +1,8 @@
+import { Fetcher, Manifest } from '@readium/shared';
+/**
+ * Fetches and deserializes the publication manifest
+ */
+export declare function fetchManifest(publicationURL: string): Promise<{
+    manifest: Manifest;
+    fetcher: Fetcher;
+}>;

package/lib/web/utils/manifestFetcher.js

@@ -0,0 +1,28 @@
+import { HttpFetcher, Link, Manifest } from '@readium/shared';
+import { normalizeManifest } from './manifestNormalizer';
+/**
+ * Fetches and deserializes the publication manifest
+ */
+export async function fetchManifest(publicationURL) {
+    const manifestLink = new Link({ href: 'manifest.json' });
+    const 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);
+    let manifest;
+    try {
+        manifest = Manifest.deserialize(responseObj);
+    }
+    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/lib/web/utils/manifestNormalizer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare function normalizeManifest(manifest: any): any;

package/lib/web/utils/manifestNormalizer.js

@@ -0,0 +1,70 @@
+/**
+ * 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) {
+    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/lib/web/utils/metadataNormalizer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 declare function normalizeLocalizedString(value: any): string;
+/**
+ * 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 declare function normalizeContributors(value: any): any[] | undefined;
+/**
+ * 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 declare function normalizeSubjects(value: any): any[] | undefined;
+/**
+ * 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 declare function normalizeMetadata(metadata: any): any;

package/lib/web/utils/metadataNormalizer.js

@@ -0,0 +1,220 @@
+/**
+ * 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) {
+    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] ||
+                '');
+        }
+        // Check if it's already a plain language map object
+        return (value['undefined'] ||
+            value['und'] ||
+            value['en'] ||
+            Object.values(value)[0] ||
+            '');
+    }
+    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) {
+    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) => {
+        // Format 1: Plain string
+        if (typeof contributor === 'string') {
+            return { name: contributor };
+        }
+        // Format 2: Object with potentially localized fields
+        const normalized = {
+            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) {
+    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) => {
+        // Format 1: Plain string
+        if (typeof subject === 'string') {
+            return { name: subject };
+        }
+        // Format 2: Object
+        const normalized = {
+            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) {
+    const normalized = {
+        // 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/lib/web/utils/navigatorListeners.d.ts

@@ -0,0 +1,6 @@
+import { EpubNavigatorListeners } from '@readium/navigator';
+import { Locator } from '@readium/shared';
+/**
+ * Creates navigator listeners for handling navigation events
+ */
+export declare function createNavigatorListeners(onLocationChangeWithTotalProgression: (locator: Locator) => void, onPositionChange?: (position: number | null) => void): EpubNavigatorListeners;

package/lib/web/utils/navigatorListeners.js

@@ -0,0 +1,50 @@
+/**
+ * Creates navigator listeners for handling navigation events
+ */
+export function createNavigatorListeners(onLocationChangeWithTotalProgression, onPositionChange) {
+    return {
+        frameLoaded: function (_wnd) {
+            // noop
+        },
+        positionChanged: function (_locator) {
+            onLocationChangeWithTotalProgression(_locator);
+            if (onPositionChange) {
+                onPositionChange(_locator.locations?.position || null);
+            }
+            window.focus();
+        },
+        tap: function (_e) {
+            return false;
+        },
+        click: function (_e) {
+            return false;
+        },
+        zoom: function (_scale) {
+            // noop
+        },
+        miscPointer: function (_amount) {
+            // noop
+        },
+        scroll: function (_amount) {
+            // noop
+        },
+        customEvent: function (_key, _data) { },
+        handleLocator: function (locator) {
+            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) {
+            // noop
+        },
+    };
+}

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

@@ -0,0 +1,15 @@
+import { Locator, Manifest, Publication } from '@readium/shared';
+/**
+ * Normalizes a publication URL to ensure it ends with /
+ * If URL ends with manifest.json, extracts the base directory
+ */
+export declare function normalizePublicationURL(url: string): string;
+/**
+ * Creates positions array from publication reading order
+ * NOTE: The published npm packages (v2.2.5) require positions to be passed explicitly
+ */
+export declare function createPositions(publication: Publication): Locator[];
+/**
+ * Extracts table of contents items from manifest
+ */
+export declare function extractTableOfContents(manifest: Manifest): any[];

package/lib/web/utils/publicationUtils.js

@@ -0,0 +1,39 @@
+import { Locator, LocatorLocations, } from '@readium/shared';
+/**
+ * Normalizes a publication URL to ensure it ends with /
+ * If URL ends with manifest.json, extracts the base directory
+ */
+export function normalizePublicationURL(url) {
+    if (url.endsWith('manifest.json')) {
+        return url.substring(0, url.lastIndexOf('/') + 1);
+    }
+    return url.endsWith('/') ? url : `${url}/`;
+}
+/**
+ * Creates positions array from publication reading order
+ * NOTE: The published npm packages (v2.2.5) require positions to be passed explicitly
+ */
+export function createPositions(publication) {
+    return publication.readingOrder.items.map((link, idx) => {
+        const position = idx + 1;
+        return new Locator({
+            href: link.href,
+            type: link.type,
+            title: link.title,
+            locations: new LocatorLocations({
+                position: position,
+                progression: 0,
+                totalProgression: idx / publication.readingOrder.items.length,
+            }),
+        });
+    });
+}
+/**
+ * Extracts table of contents items from manifest
+ */
+export function extractTableOfContents(manifest) {
+    return Array.isArray(manifest.toc)
+        ? manifest.toc
+        : // @ts-ignore
+            manifest.toc.items || [];
+}

package/nitro.json

@@ -0,0 +1,16 @@
+{
+  "cxxNamespace": ["readium"],
+  "ios": {
+    "iosModuleName": "NitroReadium"
+  },
+  "android": {
+    "androidNamespace": ["reactnativereadium"],
+    "androidCxxLibName": "NitroReadium"
+  },
+  "autolinking": {
+    "ReadiumView": {
+      "swift": "HybridReadiumView",
+      "kotlin": "HybridReadiumView"
+    }
+  }
+}

package/nitrogen/generated/.gitattributes

@@ -0,0 +1 @@
+** linguist-generated=true

package/nitrogen/generated/android/NitroReadium+autolinking.cmake

@@ -0,0 +1,83 @@
+#
+# NitroReadium+autolinking.cmake
+# This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+# https://github.com/mrousavy/nitro
+# Copyright © Marc Rousavy @ Margelo
+#
+
+# This is a CMake file that adds all files generated by Nitrogen
+# to the current CMake project.
+#
+# To use it, add this to your CMakeLists.txt:
+# ```cmake
+# include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroReadium+autolinking.cmake)
+# ```
+
+# Define a flag to check if we are building properly
+add_definitions(-DBUILDING_NITROREADIUM_WITH_GENERATED_CMAKE_PROJECT)
+
+# Enable Raw Props parsing in react-native (for Nitro Views)
+add_definitions(-DRN_SERIALIZABLE_STATE)
+
+# Add all headers that were generated by Nitrogen
+include_directories(
+  "../nitrogen/generated/shared/c++"
+  "../nitrogen/generated/android/c++"
+  "../nitrogen/generated/android/"
+)
+
+# Add all .cpp sources that were generated by Nitrogen
+target_sources(
+  # CMake project name (Android C++ library name)
+  NitroReadium PRIVATE
+  # Autolinking Setup
+  ../nitrogen/generated/android/NitroReadiumOnLoad.cpp
+  # Shared Nitrogen C++ sources
+  ../nitrogen/generated/shared/c++/HybridReadiumViewSpec.cpp
+  ../nitrogen/generated/shared/c++/views/HybridReadiumViewComponent.cpp
+  # Android-specific Nitrogen C++ sources
+  ../nitrogen/generated/android/c++/JHybridReadiumViewSpec.cpp
+  ../nitrogen/generated/android/c++/views/JHybridReadiumViewStateUpdater.cpp
+)
+
+# From node_modules/react-native/ReactAndroid/cmake-utils/folly-flags.cmake
+# Used in node_modules/react-native/ReactAndroid/cmake-utils/ReactNative-application.cmake
+target_compile_definitions(
+  NitroReadium PRIVATE
+  -DFOLLY_NO_CONFIG=1
+  -DFOLLY_HAVE_CLOCK_GETTIME=1
+  -DFOLLY_USE_LIBCPP=1
+  -DFOLLY_CFG_NO_COROUTINES=1
+  -DFOLLY_MOBILE=1
+  -DFOLLY_HAVE_RECVMMSG=1
+  -DFOLLY_HAVE_PTHREAD=1
+  # Once we target android-23 above, we can comment
+  # the following line. NDK uses GNU style stderror_r() after API 23.
+  -DFOLLY_HAVE_XSI_STRERROR_R=1
+)
+
+# Add all libraries required by the generated specs
+find_package(fbjni REQUIRED) # <-- Used for communication between Java <-> C++
+find_package(ReactAndroid REQUIRED) # <-- Used to set up React Native bindings (e.g. CallInvoker/TurboModule)
+find_package(react-native-nitro-modules REQUIRED) # <-- Used to create all HybridObjects and use the Nitro core library
+
+# Link all libraries together
+target_link_libraries(
+        NitroReadium
+        fbjni::fbjni                              # <-- Facebook C++ JNI helpers
+        ReactAndroid::jsi                         # <-- RN: JSI
+        react-native-nitro-modules::NitroModules  # <-- NitroModules Core :)
+)
+
+# Link react-native (different prefab between RN 0.75 and RN 0.76)
+if(ReactAndroid_VERSION_MINOR GREATER_EQUAL 76)
+    target_link_libraries(
+        NitroReadium
+        ReactAndroid::reactnative                 # <-- RN: Native Modules umbrella prefab
+    )
+else()
+    target_link_libraries(
+        NitroReadium
+        ReactAndroid::react_nativemodule_core     # <-- RN: TurboModules Core
+    )
+endif()