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

package/README.md

@@ -5,7 +5,7 @@
 ![PRs welcome!](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)
 ![This project is released under the MIT license](https://img.shields.io/badge/license-MIT-blue.svg)
 
-----
+---
 
 ## Have A Bug/Feature You Care About?
 
@@ -15,7 +15,7 @@ we're able to work on them. Have an issue you care about?
 - [Dive Into The Code!](CONTRIBUTING.md)
 - [Sponsor Your Issue](#sponsor-the-library)
 
-----
+---
 
 ## Overview
 
@@ -24,7 +24,7 @@ allows you to do things like:
 
 - Render an ebook view.
 - Register for location changes (as the user pages through the book).
-- Register for the Table of Contents (so that you can display things like chapters in your app)
+- Access publication metadata including table of contents, positions, and more via the `onPublicationReady` callback
 - Control settings of the Reader. Things like:
   - Dark Mode, Light Mode, Sepia Mode
   - Font Size
@@ -42,8 +42,8 @@ allows you to do things like:
 - [Release](#release)
 - [License](#license)
 
-| Dark Mode| Light Mode |
-|----------|------------|
+| Dark Mode                                                                                        | Light Mode                                                                                         |
+| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
 | ![Dark Mode](https://github.com/5-stones/react-native-readium/blob/main/docs/demo-dark-mode.gif) | ![Light Mode](https://github.com/5-stones/react-native-readium/blob/main/docs/demo-light-mode.gif) |
 
 ## Installation
@@ -53,7 +53,7 @@ allows you to do things like:
 1. **iOS**: Requires an iOS target >= `13.0` (see the iOS section for more details).
 2. **Android**: Requires `compileSdkVersion` >= `31` (see the Android section for more details).
 
-:warning: This library does not current support `newArch`. Please disable `newArch` if you intend to use it. PR's welcome.
+This library uses [Nitro Modules](https://nitro.margelo.com/) and supports both the old and new React Native architectures.
 
 #### Install Module
 
@@ -71,25 +71,39 @@ yarn add react-native-readium
 
 #### iOS
 
+Requirements:
+
+- Minimum iOS deployment target: iOS 13.4
+- Swift compiler: Swift 6.0
+- Xcode: Xcode 16.2 (or newer)
+
 Due to the current state of the `Readium` swift libraries you need to manually
 update your `Podfile` ([see more on that here](https://github.com/readium/swift-toolkit/issues/38)).
 
+##### Breaking change when upgrading from v4 to v5!
+
+If you are migrating from v4 to v5, please note that you must update your iOS Podfile to use the new Readium Pods (see iOS documentation below). Please make a note of both the new Pod names and the addition of the `source`'s in the Podfile.
+
 ```rb
 # ./ios/Podfile
+source 'https://github.com/readium/podspecs'
+source 'https://cdn.cocoapods.org/'
+
 ...
-platform :ios, '13.0'
+
+platform :ios, '13.4'
 
 ...
 
 target 'ExampleApp' do
   config = use_native_modules!
   ...
-  pod 'GCDWebServer', podspec: 'https://raw.githubusercontent.com/readium/GCDWebServer/3.7.5/GCDWebServer.podspec', modular_headers: true
-  pod 'ReadiumAdapterGCDWebServer', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.6.0/Support/CocoaPods/ReadiumAdapterGCDWebServer.podspec', modular_headers: true
-  pod 'R2Navigator', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.6.0/Support/CocoaPods/ReadiumNavigator.podspec'
-  pod 'R2Shared', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.6.0/Support/CocoaPods/ReadiumShared.podspec'
-  pod 'R2Streamer', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.6.0/Support/CocoaPods/ReadiumStreamer.podspec'
-  pod 'ReadiumInternal', podspec: 'https://raw.githubusercontent.com/readium/swift-toolkit/2.6.0/Support/CocoaPods/ReadiumInternal.podspec'
+  pod 'ReadiumGCDWebServer', :modular_headers => true
+  pod 'ReadiumAdapterGCDWebServer', '~> 3.5.0'
+  pod 'ReadiumInternal',  '~> 3.5.0'
+  pod 'ReadiumShared',    '~> 3.5.0'
+  pod 'ReadiumStreamer',  '~> 3.5.0'
+  pod 'ReadiumNavigator', '~> 3.5.0'
   pod 'Minizip', modular_headers: true
   ...
 end
@@ -101,6 +115,16 @@ Finally, install the pods:
 
 #### Android
 
+##### Breaking change when upgrading from v4 to v5!
+
+This release upgrades the Android native implementation to a newer Readium Kotlin Toolkit.
+Most apps won’t need code changes, but your **Android build configuration** might.
+
+Requirements:
+
+- **JDK 17** is required to build the Android app (the library targets Java/Kotlin 17).
+- **compileSdkVersion** must be >= `31`.
+
 If you're not using `compileSdkVersion` >= 31 you'll need to update that:
 
 ```groovy
@@ -114,8 +138,35 @@ buildscript {
 ...
 ```
 
+##### Core library desugaring (may be required)
+
+If you see build errors related to missing Java 8+ APIs (commonly `java.time.*`), enable
+core library desugaring in your app:
+
+```groovy
+// android/app/build.gradle
+android {
+  ...
+  compileOptions {
+    coreLibraryDesugaringEnabled true
+  }
+}
+
+dependencies {
+  coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.1.2"
+}
+```
+
+##### Expo managed workflow
+
+If your app uses Expo managed workflow (native `android/` is generated via `prebuild` / EAS),
+apply the desugaring settings through an Expo config plugin (or `expo-build-properties`) so
+they persist across builds.
+
 ## Usage
 
+### Basic Example
+
 ```tsx
 import React, { useState } from 'react';
 import { ReadiumView } from 'react-native-readium';
@@ -126,26 +177,140 @@ const MyComponent: React.FC = () => {
     url: SOME_LOCAL_FILE_URL,
   });
 
+  return <ReadiumView file={file} />;
+};
+```
+
+### Using Publication Metadata
+
+Access the table of contents, positions, and metadata when the publication is ready:
+
+```tsx
+import React, { useState } from 'react';
+import { ReadiumView } from 'react-native-readium';
+import type { File, PublicationReadyEvent } from 'react-native-readium';
+
+const MyComponent: React.FC = () => {
+  const [file] = useState<File>({
+    url: SOME_LOCAL_FILE_URL,
+  });
+
+  const [toc, setToc] = useState([]);
+
+  const handlePublicationReady = (event: PublicationReadyEvent) => {
+    console.log('Title:', event.metadata.title);
+    console.log('Author:', event.metadata.author);
+    console.log('Table of Contents:', event.tableOfContents);
+    console.log('Positions:', event.positions);
+
+    setToc(event.tableOfContents);
+  };
+
+  return (
+    <ReadiumView file={file} onPublicationReady={handlePublicationReady} />
+  );
+};
+```
+
+### Highlights & Note Taking
+
+The `selectionActions`, `decorations`, `onSelectionAction`, and `onDecorationActivated` props work together to build highlighting and note-taking features. Here's how the flow works:
+
+1. **Define selection actions** to add custom items to the text selection context menu.
+2. **Handle `onSelectionAction`** to capture what the user selected and which action they chose.
+3. **Create a `Decoration`** from the selection's locator and add it to your `decorations` state.
+4. **Handle `onDecorationActivated`** to let users tap existing highlights to edit or delete them.
+
+```tsx
+import React, { useState, useCallback } from 'react';
+import { ReadiumView } from 'react-native-readium';
+import type {
+  File,
+  Decoration,
+  DecorationGroup,
+  SelectionAction,
+  SelectionActionEvent,
+  DecorationActivatedEvent,
+} from 'react-native-readium';
+
+// Register a "Highlight" action in the text selection context menu
+const selectionActions: SelectionAction[] = [
+  { id: 'highlight', label: 'Highlight' },
+];
+
+const MyReader: React.FC<{ file: File }> = ({ file }) => {
+  const [decorations, setDecorations] = useState<DecorationGroup[]>([
+    { name: 'highlights', decorations: [] },
+  ]);
+
+  // User tapped "Highlight" in the selection menu
+  const handleSelectionAction = useCallback((event: SelectionActionEvent) => {
+    if (event.actionId === 'highlight') {
+      const newHighlight: Decoration = {
+        id: `highlight-${Date.now()}`,
+        locator: event.locator,
+        style: {
+          type: 'highlight',
+          tint: '#FFFF00',
+        },
+        extras: {
+          note: '',
+          selectedText: event.selectedText,
+        },
+      };
+
+      setDecorations((prev) =>
+        prev.map((g) =>
+          g.name === 'highlights'
+            ? { ...g, decorations: [...g.decorations, newHighlight] }
+            : g
+        )
+      );
+    }
+  }, []);
+
+  // User tapped on an existing highlight
+  const handleDecorationActivated = useCallback(
+    (event: DecorationActivatedEvent) => {
+      const { decoration } = event;
+      // Show an edit/delete dialog for this highlight
+      console.log('Tapped highlight:', decoration.id);
+      console.log('Note:', decoration.extras?.note);
+    },
+    []
+  );
+
   return (
     <ReadiumView
       file={file}
+      decorations={decorations}
+      selectionActions={selectionActions}
+      onSelectionAction={handleSelectionAction}
+      onDecorationActivated={handleDecorationActivated}
     />
   );
-}
+};
 ```
 
-[Take a look at the Example App](https://github.com/5-stones/react-native-readium/blob/main/example/src/App.tsx) for a more complex usage example.
+Key concepts:
+
+- **`DecorationGroup`**: A named group of decorations (e.g. `"highlights"`, `"underlines"`). Pass an array of groups to the `decorations` prop.
+- **`Decoration`**: A single visual annotation. It references a location in the publication via a `Locator` and defines its appearance via a `DecorationStyle` (supported types: `"highlight"`, `"underline"`).
+- **`extras`**: An optional `Record<string, string>` on each `Decoration` where you can store arbitrary metadata like notes, timestamps, or the original selected text.
+- **`onSelectionChange`**: Fires as the user adjusts their text selection, useful for showing a live preview or tracking selection state.
+
+[Take a look at the Example App](https://github.com/5-stones/react-native-readium/blob/main/apps/example-native/src/App.tsx) for a full implementation with color picking, note editing, and highlight management.
 
 ## Supported Formats & DRM
 
 #### Format Support
 
-| Format | Support | Notes |
-|--------|---------|-------|
-| Epub 2 | :white_check_mark: | |
-| Epub 3 | :white_check_mark: | |
-| PDF | :x: | On the roadmap, feel free to submit a PR or ask for direction. |
-| CBZ | :x: | On the roadmap, feel free to submit a PR or ask for direction. |
+| Format | Support            | Notes                                                          |
+| ------ | ------------------ | -------------------------------------------------------------- |
+| Epub 2 | :white_check_mark: |                                                                |
+| Epub 3 | :white_check_mark: |                                                                |
+| PDF    | :x:                | On the roadmap, feel free to submit a PR or ask for direction. |
+| CBZ    | :x:                | On the roadmap, feel free to submit a PR or ask for direction. |
 
 **Missing a format you need?** Reach out and see if it can be added to the roadmap.
 
@@ -157,14 +322,46 @@ DRM is not supported at this time. However, there is a clear path to [support it
 
 #### View Props
 
-| Name | Type | Optional | Description |
-|------|------|----------|-------------|
-| `file`     | [`File`](https://github.com/5-stones/react-native-readium/blob/main/src/interfaces/File.ts)               | :x:                | A file object containing the path to the eBook file on disk. |
-| `location` | [`Locator`](https://github.com/5-stones/react-native-readium/blob/main/src/interfaces/Locator.ts) \| [`Link`](https://github.com/5-stones/react-native-readium/blob/main/src/interfaces/Link.ts)           | :white_check_mark: | A locator prop that allows you to externally control the location of the reader (e.g. Chapters or Bookmarks). <br/><br/>:warning: If you want to set the `location` of an ebook on initial load, you should use the `File.initialLocation` property (look at the `file` prop). See more [here](https://github.com/5-stones/react-native-readium/issues/16#issuecomment-1344128937) |
-| `preferences` | [`Partial<Preferences>`](https://github.com/readium/swift-toolkit/blob/main/docs/Guides/Navigator%20Preferences.md#appendix-preference-constraints)  | :white_check_mark: | An object that allows you to control various aspects of the reader's UI (epub only) |
-| `style`    | `ViewStyle`          | :white_check_mark: | A traditional style object. |
-| `onLocationChange` | `(locator: Locator) => void` | :white_check_mark: | A callback that fires whenever the location is changed (e.g. the user transitions to a new page)|
-| `onTableOfContents` | `(toc: Link[] \| null) => void` | :white_check_mark: | A callback that fires once the file is parsed and emits the table of contents embedded in the file. Returns `null` or an empty `[]` if no TOC exists. See the [`Link`](https://github.com/5-stones/react-native-readium/blob/main/src/interfaces/Link.ts) interface for more info. |
+| Name                     | Type                                                                                                                                                                                             | Optional           | Description                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `file`                   | [`File`](https://github.com/5-stones/react-native-readium/blob/main/src/interfaces/File.ts)                                                                                                      | :x:                | A file object containing the path to the eBook file on disk.                                                                                                                                                                                                                                                                                                                       |
+| `location`               | [`Locator`](https://github.com/5-stones/react-native-readium/blob/main/src/interfaces/Locator.ts) \| [`Link`](https://github.com/5-stones/react-native-readium/blob/main/src/interfaces/Link.ts) | :white_check_mark: | A locator prop that allows you to externally control the location of the reader (e.g. Chapters or Bookmarks). <br/><br/>:warning: If you want to set the `location` of an ebook on initial load, you should use the `File.initialLocation` property (look at the `file` prop). See more [here](https://github.com/5-stones/react-native-readium/issues/16#issuecomment-1344128937) |
+| `preferences`            | [`Partial<Preferences>`](https://github.com/readium/swift-toolkit/blob/main/docs/Guides/Navigator%20Preferences.md#appendix-preference-constraints)                                              | :white_check_mark: | An object that allows you to control various aspects of the reader's UI (epub only)                                                                                                                                                                                                                                                                                                |
+| `decorations`            | [`DecorationGroup[]`](https://github.com/5-stones/react-native-readium/blob/main/src/interfaces/Decoration.ts)                                                                                   | :white_check_mark: | An array of decoration groups to render in the publication (e.g. highlights, underlines).                                                                                                                                                                                                                                                                                           |
+| `selectionActions`       | [`SelectionAction[]`](https://github.com/5-stones/react-native-readium/blob/main/src/interfaces/SelectionAction.ts)                                                                              | :white_check_mark: | Custom actions to show in the context menu when the user selects text.                                                                                                                                                                                                                                                                                                             |
+| `style`                  | `ViewStyle`                                                                                                                                                                                      | :white_check_mark: | A traditional style object.                                                                                                                                                                                                                                                                                                                                                        |
+| `onLocationChange`       | `(locator: Locator) => void`                                                                                                                                                                     | :white_check_mark: | A callback that fires whenever the location is changed (e.g. the user transitions to a new page).                                                                                                                                                                                                                                                                                  |
+| `onPublicationReady`     | `(event: PublicationReadyEvent) => void`                                                                                                                                                         | :white_check_mark: | A callback that fires once the publication is loaded and provides access to the table of contents, positions, and metadata. See the [`PublicationReadyEvent`](https://github.com/5-stones/react-native-readium/blob/main/src/interfaces/PublicationReady.ts) interface for details.                                                                                                |
+| `onDecorationActivated`  | `(event: DecorationActivatedEvent) => void`                                                                                                                                                      | :white_check_mark: | A callback that fires when a user taps on a decoration (e.g. a highlight).                                                                                                                                                                                                                                                                                                         |
+| `onSelectionChange`      | `(event: SelectionEvent) => void`                                                                                                                                                                | :white_check_mark: | A callback that fires when the user's text selection changes.                                                                                                                                                                                                                                                                                                                      |
+| `onSelectionAction`      | `(event: SelectionActionEvent) => void`                                                                                                                                                          | :white_check_mark: | A callback that fires when the user taps a custom selection action from the context menu.                                                                                                                                                                                                                                                                                          |
+
+#### Ref Methods
+
+The `ReadiumView` component accepts a ref that exposes imperative navigation methods:
+
+```tsx
+import React, { useRef } from 'react';
+import { ReadiumView } from 'react-native-readium';
+import type { ReadiumViewRef } from 'react-native-readium';
+
+const MyComponent: React.FC = () => {
+  const ref = useRef<ReadiumViewRef>(null);
+
+  return (
+    <>
+      <ReadiumView ref={ref} file={file} />
+      <Button title="Next" onPress={() => ref.current?.goForward()} />
+      <Button title="Previous" onPress={() => ref.current?.goBackward()} />
+    </>
+  );
+};
+```
+
+| Method        | Description                                              |
+| ------------- | -------------------------------------------------------- |
+| `goForward()` | Navigate forward in the publication (e.g. next page).    |
+| `goBackward()`| Navigate backward in the publication (e.g. previous page). |
 
 #### :warning: Web vs Native File URLs
 
@@ -173,7 +370,7 @@ the `manifest.json` of the unpacked epub. In native contexts it needs to be a
 local filepath to the epub file itself on disk. If you're not sure how to
 serve epub books [take a look at this example](https://github.com/d-i-t-a/R2D2BC/blob/production/examples/server.ts)
 which is based on the `dita-streamer-js` project (which is built on all the
-readium [r2-*-js](https://github.com/readium?q=js) libraries)
+readium [r2-\*-js](https://github.com/readium?q=js) libraries)
 
 ## Contributing
 
@@ -194,7 +391,6 @@ This command will:
 1. Bump the package version
 1. Tag & pushing the commit
 
-
 e.g.
 
 ```

package/android/.cxx/Debug/1o6u5d69/arm64-v8a/metadata_generation_command.txt

@@ -0,0 +1,20 @@
+                        -H/Users/jspizziri/Documents/Projects/readium/react-native-readium/android
+-DCMAKE_SYSTEM_NAME=Android
+-DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+-DCMAKE_SYSTEM_VERSION=24
+-DANDROID_PLATFORM=android-24
+-DANDROID_ABI=arm64-v8a
+-DCMAKE_ANDROID_ARCH_ABI=arm64-v8a
+-DANDROID_NDK=/Users/jspizziri/Library/Android/sdk/ndk/27.0.12077973
+-DCMAKE_ANDROID_NDK=/Users/jspizziri/Library/Android/sdk/ndk/27.0.12077973
+-DCMAKE_TOOLCHAIN_FILE=/Users/jspizziri/Library/Android/sdk/ndk/27.0.12077973/build/cmake/android.toolchain.cmake
+-DCMAKE_MAKE_PROGRAM=/Users/jspizziri/Library/Android/sdk/cmake/3.22.1/bin/ninja
+-DCMAKE_CXX_FLAGS=-O2 -frtti -fexceptions -Wall -fstack-protector-all
+-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=/Users/jspizziri/Documents/Projects/readium/react-native-readium/android/build/intermediates/cxx/Debug/1o6u5d69/obj/arm64-v8a
+-DCMAKE_RUNTIME_OUTPUT_DIRECTORY=/Users/jspizziri/Documents/Projects/readium/react-native-readium/android/build/intermediates/cxx/Debug/1o6u5d69/obj/arm64-v8a
+-DCMAKE_BUILD_TYPE=Debug
+-DCMAKE_FIND_ROOT_PATH=/Users/jspizziri/Documents/Projects/readium/react-native-readium/android/.cxx/Debug/1o6u5d69/prefab/arm64-v8a/prefab
+-B/Users/jspizziri/Documents/Projects/readium/react-native-readium/android/.cxx/Debug/1o6u5d69/arm64-v8a
+-GNinja
+                        Build command args: []
+                        Version: 2

package/android/.cxx/Debug/1o6u5d69/arm64-v8a/prefab_config.json

@@ -0,0 +1,9 @@
+{
+  "enabled": true,
+  "prefabPath": "/Users/jspizziri/.gradle/caches/modules-2/files-2.1/com.google.prefab/cli/2.1.0/aa32fec809c44fa531f01dcfb739b5b3304d3050/cli-2.1.0-all.jar",
+  "packages": [
+    "/Users/jspizziri/.gradle/caches/9.0.0/transforms/975b5584e106111fd48e7aac9046beec/transformed/jetified-react-android-0.83.1-debug/prefab",
+    "/Users/jspizziri/Documents/Projects/readium/react-native-readium/node_modules/react-native-nitro-modules/android/build/intermediates/prefab_package/debug/prefab",
+    "/Users/jspizziri/.gradle/caches/9.0.0/transforms/49cde1acd35737fffc0a351edeac3186/transformed/jetified-fbjni-0.7.0/prefab"
+  ]
+}

package/android/.cxx/Debug/1o6u5d69/hash_key.txt

@@ -0,0 +1,27 @@
+# Values used to calculate the hash in this folder name.
+# Should not depend on the absolute path of the project itself.
+#   - AGP: 8.12.0.
+#   - $NDK is the path to NDK 27.0.12077973.
+#   - $PROJECT is the path to the parent folder of the root Gradle build file.
+#   - $ABI is the ABI to be built with. The specific value doesn't contribute to the value of the hash.
+#   - $HASH is the hash value computed from this text.
+#   - $CMAKE is the path to CMake 3.22.1.
+#   - $NINJA is the path to Ninja.
+-H/Users/jspizziri/Documents/Projects/readium/react-native-readium/android
+-DCMAKE_SYSTEM_NAME=Android
+-DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+-DCMAKE_SYSTEM_VERSION=24
+-DANDROID_PLATFORM=android-24
+-DANDROID_ABI=$ABI
+-DCMAKE_ANDROID_ARCH_ABI=$ABI
+-DANDROID_NDK=$NDK
+-DCMAKE_ANDROID_NDK=$NDK
+-DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake
+-DCMAKE_MAKE_PROGRAM=$NINJA
+-DCMAKE_CXX_FLAGS=-O2 -frtti -fexceptions -Wall -fstack-protector-all
+-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=/Users/jspizziri/Documents/Projects/readium/react-native-readium/android/build/intermediates/cxx/Debug/$HASH/obj/$ABI
+-DCMAKE_RUNTIME_OUTPUT_DIRECTORY=/Users/jspizziri/Documents/Projects/readium/react-native-readium/android/build/intermediates/cxx/Debug/$HASH/obj/$ABI
+-DCMAKE_BUILD_TYPE=Debug
+-DCMAKE_FIND_ROOT_PATH=/Users/jspizziri/Documents/Projects/readium/react-native-readium/android/.cxx/Debug/$HASH/prefab/$ABI/prefab
+-B/Users/jspizziri/Documents/Projects/readium/react-native-readium/android/.cxx/Debug/$HASH/$ABI
+-GNinja