@readium/navigator 1.3.4 → 2.0.0-beta.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readium/navigator",
-  "version": "1.3.4",
+  "version": "2.0.0-beta.10",
   "type": "module",
   "description": "Next generation SDK for publications in Web Apps",
   "author": "readium",
@@ -44,20 +44,21 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "build": "tsc && vite build"
+  },
   "devDependencies": {
     "@laynezh/vite-plugin-lib-assets": "^0.5.25",
+    "@readium/css": ">=2.0.0-beta.18",
+    "@readium/navigator-html-injectables": "workspace:*",
+    "@readium/shared": "workspace:*",
     "@types/path-browserify": "^1.0.3",
     "css-selector-generator": "^3.6.9",
     "path-browserify": "^1.0.1",
-    "@readium/css": "^1.1.0",
     "tslib": "^2.8.1",
     "typescript": "^5.6.3",
     "typescript-plugin-css-modules": "^5.1.0",
-    "vite": "^4.5.5",
-    "@readium/navigator-html-injectables": "1.3.2",
-    "@readium/shared": "1.2.1"
-  },
-  "scripts": {
-    "build": "tsc && vite build"
+    "user-agent-data-types": "^0.4.2",
+    "vite": "^4.5.5"
   }
-}
+}

package/src/Navigator.ts

@@ -2,6 +2,17 @@ import { Link, Locator, Publication, ReadingProgression } from "@readium/shared"
 
 type cbb = (ok: boolean) => void;
 
+export interface ProgressionRange {
+    start: number;
+    end: number;
+}
+
+export interface VisualNavigatorViewport {
+    readingOrder: string[];  // Array of href strings for visible resources
+    progressions: Map<string, ProgressionRange>;  // Map from href to visible scroll progression range
+    positions: number[] | null;  // Range of visible positions
+}
+
 export abstract class Navigator {
     abstract get publication(): Publication; // Publication rendered by this navigator.
     abstract get currentLocator(): Locator; // Current position (detailed) in the publication. Can be used to save a bookmark to the current position.

package/src/epub/EpubNavigator.ts

@@ -1,5 +1,5 @@
 import { EPUBLayout, Link, Locator, Publication, ReadingProgression } from "@readium/shared";
-import { VisualNavigator } from "../";
+import { Configurable, ConfigurablePreferences, ConfigurableSettings, LineLengths, VisualNavigator, VisualNavigatorViewport, ProgressionRange } from "../";
 import { FramePoolManager } from "./frame/FramePoolManager";
 import { FXLFramePoolManager } from "./fxl/FXLFramePoolManager";
 import { CommsEventKey, FXLModules, ModuleLibrary, ModuleName, ReflowableModules } from "@readium/navigator-html-injectables";
@@ -7,9 +7,21 @@ import { BasicTextSelection, FrameClickEvent } from "@readium/navigator-html-inj
 import * as path from "path-browserify";
 import { FXLFrameManager } from "./fxl/FXLFrameManager";
 import { FrameManager } from "./frame/FrameManager";
+import { IEpubPreferences, EpubPreferences } from "./preferences/EpubPreferences";
+import { IEpubDefaults, EpubDefaults } from "./preferences/EpubDefaults";
+import { EpubSettings } from "./preferences";
+import { EpubPreferencesEditor } from "./preferences/EpubPreferencesEditor";
+import { ReadiumCSS } from "./css/ReadiumCSS";
+import { RSProperties, UserProperties } from "./css/Properties";
+import { getContentWidth } from "../helpers/dimensions";
 
 export type ManagerEventKey = "zoom";
 
+export interface EpubNavigatorConfiguration {
+    preferences: IEpubPreferences;
+    defaults: IEpubDefaults;
+}
+
 export interface EpubNavigatorListeners {
     frameLoaded: (wnd: Window) => void;
     positionChanged: (locator: Locator) => void;
@@ -35,7 +47,7 @@ const defaultListeners = (listeners: EpubNavigatorListeners): EpubNavigatorListe
     textSelected: listeners.textSelected || (() => {})
 })
 
-export class EpubNavigator extends VisualNavigator {
+export class EpubNavigator extends VisualNavigator implements Configurable<ConfigurableSettings, ConfigurablePreferences> {
     private readonly pub: Publication;
     private readonly container: HTMLElement;
     private readonly listeners: EpubNavigatorListeners;
@@ -46,16 +58,61 @@ export class EpubNavigator extends VisualNavigator {
     private currentProgression: ReadingProgression;
     public readonly layout: EPUBLayout;
 
-    constructor(container: HTMLElement, pub: Publication, listeners: EpubNavigatorListeners, positions: Locator[] = [], initialPosition: Locator | undefined = undefined) {
+    private _preferences: EpubPreferences;
+    private _defaults: EpubDefaults;
+    private _settings: EpubSettings;
+    private _css: ReadiumCSS;
+    private _preferencesEditor: EpubPreferencesEditor | null = null;
+
+    private resizeObserver: ResizeObserver;
+
+    private reflowViewport: VisualNavigatorViewport = {
+        readingOrder: [],
+        progressions: new Map(),
+        positions: null
+    };
+
+    constructor(container: HTMLElement, pub: Publication, listeners: EpubNavigatorListeners, positions: Locator[] = [], initialPosition: Locator | undefined = undefined, configuration: EpubNavigatorConfiguration = { preferences: {}, defaults: {} }) {
         super();
         this.pub = pub;
         this.layout = EpubNavigator.determineLayout(pub);
-        this.currentProgression = pub.metadata.effectiveReadingProgression;
         this.container = container;
         this.listeners = defaultListeners(listeners);
         this.currentLocation = initialPosition!;
         if (positions.length)
             this.positions = positions;
+
+        this._preferences = new EpubPreferences(configuration.preferences);
+        this._defaults = new EpubDefaults(configuration.defaults);
+        this._settings = new EpubSettings(this._preferences, this._defaults);
+        this._css = new ReadiumCSS({ 
+            rsProperties: new RSProperties({}),
+            userProperties: new UserProperties({}),
+            lineLengths: new LineLengths({
+                optimalChars: this._settings.optimalLineLength,
+                minChars: this._settings.minimalLineLength,
+                maxChars: this._settings.maximalLineLength,
+                pageGutter: this._settings.pageGutter,
+                fontFace: this._settings.fontFamily,
+                letterSpacing: this._settings.letterSpacing,
+                wordSpacing: this._settings.wordSpacing,
+            //    sample: this.pub.metadata.description
+            }),
+            container: container,
+            constraint: this._settings.constraint
+        });
+
+        this.currentProgression = this.layout === EPUBLayout.reflowable 
+            ? (this._settings.scroll 
+                ? ReadingProgression.ttb 
+                : pub.metadata.effectiveReadingProgression) 
+            : pub.metadata.effectiveReadingProgression;
+
+        // We use a resizeObserver cos’ the container parent may not be the width of 
+        // the document/window e.g. app using a docking system with left and right panels.
+        // If we observe this.container, that won’t obviously work since we set its width.
+        this.resizeObserver = new ResizeObserver(() => this.ownerWindow.requestAnimationFrame(async () => await this.resizeHandler()));
+        this.resizeObserver.observe(this.container.parentElement || document.documentElement);
     }
 
     public static determineLayout(pub: Publication): EPUBLayout {
@@ -79,13 +136,139 @@ export class EpubNavigator extends VisualNavigator {
             this.framePool.listener = (key: CommsEventKey | ManagerEventKey, data: unknown) => {
                 this.eventListener(key, data);
             }
-        } else
-            this.framePool = new FramePoolManager(this.container, this.positions);
+        } else {
+            await this.updateCSS(false);
+            const cssProperties = this.compileCSSProperties(this._css);
+            this.framePool = new FramePoolManager(this.container, this.positions, cssProperties);
+        }
+
         if(this.currentLocation === undefined)
             this.currentLocation = this.positions[0];
+
+        await this.resizeHandler();
         await this.apply();
     }
 
+    public get settings(): Readonly<EpubSettings> {
+        if (this.layout === EPUBLayout.fixed) {
+            return Object.freeze({ ...this._settings });
+        } else {
+            // Given all the nasty issues moving auto-pagination to EpubSettings creates
+            // Especially as it’s tied to ReadiumCSS in the first place and could be 
+            // problematic if you intend to use something else,
+            // we return the properties with columnCount overridden
+            const columnCount = this._css.userProperties.colCount || this._css.rsProperties.colCount || this._settings.columnCount;
+            return Object.freeze({ ...this._settings, columnCount: columnCount });
+        }
+    }
+
+    public get preferencesEditor() {
+        if (this._preferencesEditor === null) {
+            // Note: we pass this.settings instead of this._settings to ensure the columnCount is correct
+            this._preferencesEditor = new EpubPreferencesEditor(this._preferences, this.settings, this.pub.metadata);
+        }
+        return this._preferencesEditor;
+    }
+
+    public async submitPreferences(preferences: EpubPreferences) {
+        this._preferences = this._preferences.merging(preferences) as EpubPreferences;
+        await this.applyPreferences();
+    }
+
+    private async applyPreferences() {
+        const oldSettings = this._settings;
+        this._settings = new EpubSettings(this._preferences, this._defaults);
+        
+        if (this._preferencesEditor !== null) {
+            // Note: we pass this.settings instead of this._settings to ensure the columnCount is correct
+            this._preferencesEditor = new EpubPreferencesEditor(this._preferences, this.settings, this.pub.metadata);
+        }
+
+        if (this.layout === EPUBLayout.fixed) {
+            this.handleFXLPrefs(oldSettings, this._settings);
+        } else {
+            await this.updateCSS(true);
+        }
+    }
+
+    // TODO: fit, etc.
+    private handleFXLPrefs(from: EpubSettings, to: EpubSettings) {
+        if (from.columnCount !== to.columnCount) {
+            (this.framePool as FXLFramePoolManager).setPerPage(to.columnCount);
+        }
+    }
+
+    private async updateCSS(commit: boolean) {
+        this._css.update(this._settings);
+
+        if (commit) await this.commitCSS(this._css);
+    };
+
+    private compileCSSProperties(css: ReadiumCSS) {
+        const properties: { [key: string]: string } = {};
+
+        for (const [key, value] of Object.entries(css.rsProperties.toCSSProperties())) {
+            properties[key] = value;
+        }
+
+        for (const [key, value] of Object.entries(css.userProperties.toCSSProperties())) {
+            properties[key] = value;
+        }
+
+        return properties;
+    }
+
+    private async commitCSS(css: ReadiumCSS) {
+        // Since we’re updating the CSS properties in injectables by removing
+        // the existing properties that are not inside this object first, 
+        // then adding all from it, we don’t compare the previous properties here
+        const properties = this.compileCSSProperties(css);
+
+        (this.framePool as FramePoolManager).setCSSProperties(properties);
+
+        if (
+            this._css.userProperties.view === "paged" && 
+            this.readingProgression === ReadingProgression.ttb
+        ) {
+            await this.setReadingProgression(this.pub.metadata.effectiveReadingProgression); 
+        } else if (
+            this._css.userProperties.view === "scroll" && 
+            (this.readingProgression === ReadingProgression.ltr || this.readingProgression === ReadingProgression.rtl)
+        ) {
+            await this.setReadingProgression(ReadingProgression.ttb);
+        }
+
+        this._css.setContainerWidth();
+    }
+
+    async resizeHandler() {
+        // We check the parentElement cos we want to remove constraint from the container
+        // and the container may not be the entire width of the document/window
+        const parentEl = this.container.parentElement || document.documentElement;
+
+        if (this.layout === EPUBLayout.fixed) {
+            this.container.style.width = `${ getContentWidth(parentEl) - this._settings.constraint }px`;
+            (this.framePool as FXLFramePoolManager).resizeHandler();
+        } else {
+            // for reflow ReadiumCSS gets the width from columns + line-lengths 
+            // but we need to check whether colCount has changed to commit new CSS
+            const oldColCount = this._css.userProperties.colCount;
+            const oldLineLength = this._css.userProperties.lineLength;
+            this._css.resizeHandler();
+            if (
+                this._css.userProperties.view !== "scroll" &&
+                oldColCount !== this._css.userProperties.colCount ||
+                oldLineLength !== this._css.userProperties.lineLength
+            ) {
+                await this.commitCSS(this._css);
+            }
+        }
+    }
+
+    get ownerWindow() {
+        return this.container.ownerDocument.defaultView || window;
+    }
+
     /**
      * Exposed to the public to compensate for lack of implemented readium conveniences
      * TODO remove when settings management is incorporated
@@ -217,7 +400,7 @@ export class EpubNavigator extends VisualNavigator {
                 this.listeners.zoom(data as number);
                 break;
             case "progress":
-                this.syncLocation(data as { progress: number, reference: number });
+                this.syncLocation(data as ProgressionRange);
                 break;
             case "log":
                 console.log(this._cframes[0]?.source?.split("/")[3], ...(data as any[]));
@@ -275,7 +458,7 @@ export class EpubNavigator extends VisualNavigator {
 
         if(this.layout === EPUBLayout.fixed) {
             const p = this.framePool as FXLFramePoolManager;
-            const old = p.currentNumbers[0];
+            const old = p.viewport.positions![0];
             if(relative === 1) {
                 if(!p.next(p.perPage)) return false;
             } else if(relative === -1) {
@@ -284,7 +467,7 @@ export class EpubNavigator extends VisualNavigator {
                 throw Error("Invalid relative value for FXL");
 
             // Apply change
-            const neW = p.currentNumbers[0]
+            const neW = p.viewport.positions![0]
             if(old > neW)
                 for (let j = this.positions.length - 1; j >= 0; j--) {
                     if(this.positions[j].href === this.pub.readingOrder.items[neW-1].href) {
@@ -337,10 +520,10 @@ export class EpubNavigator extends VisualNavigator {
         return true;
     }
 
-    private findLastPositionInProgressionRange(positions: Locator[], range: number[]): Locator | undefined {
+    private findLastPositionInProgressionRange(positions: Locator[], range: ProgressionRange): Locator | undefined {
         const match = positions.findLastIndex((p) => {
             const pr = p.locations.progression;
-            if (pr && pr > Math.min(...range) && pr <= Math.max(...range)) {
+            if (pr && pr > range.start && pr <= range.end) {
                 return true;
             } else {
                 return false;
@@ -349,7 +532,7 @@ export class EpubNavigator extends VisualNavigator {
         return match !== -1 ? positions[match] : undefined;
     }
 
-    private findNearestPositions(fromProgression: { progress: number, reference: number }):  { first: Locator, last: Locator | undefined } {
+    private findNearestPositions(fromProgression: ProgressionRange):  { first: Locator, last: Locator | undefined } {
         // TODO replace with locator service
         const potentialPositions = this.positions.filter(
             (p) => p.href === this.currentLocation.href
@@ -361,13 +544,12 @@ export class EpubNavigator extends VisualNavigator {
         // smaller than or equal to the requested progression.
         potentialPositions.some((p, idx) => {
             const pr = p.locations.progression ?? 0;
-            if (fromProgression.progress <= pr) {
+            if (fromProgression.start <= pr) {
                 first = p;
 
                 // If there’s a match, check the last in view, from the next progression
                 const nextPositions = potentialPositions.splice(idx + 1, potentialPositions.length);
-                const range = [fromProgression.progress, fromProgression.progress + fromProgression.reference];
-                last = this.findLastPositionInProgressionRange(nextPositions, range);
+                last = this.findLastPositionInProgressionRange(nextPositions, fromProgression);
 
                 return true;
             }
@@ -376,12 +558,36 @@ export class EpubNavigator extends VisualNavigator {
         return { first: first, last: last }
     }
 
-    private async syncLocation(iframeProgress: { progress: number, reference: number }) {
-        const nearestPositions = this.findNearestPositions(iframeProgress)
+    private updateViewport(progression: ProgressionRange) {
+        this.reflowViewport.readingOrder = [];
+        this.reflowViewport.progressions.clear();
+        this.reflowViewport.positions = null;
+    
+        // Use the current position's href
+        if (this.currentLocation) {
+            this.reflowViewport.readingOrder.push(this.currentLocation.href);
+            this.reflowViewport.progressions.set(this.currentLocation.href, progression);
+
+            if (this.currentLocation.locations?.position !== undefined) {
+                this.reflowViewport.positions = [this.currentLocation.locations.position];
+                if (this.lastLocationInView?.locations?.position !== undefined) {
+                    this.reflowViewport.positions.push(this.lastLocationInView.locations.position);
+                }
+            }
+        }
+    }
+
+    private async syncLocation(iframeProgress: ProgressionRange) {
+        const progression = iframeProgress;
+        
+        const nearestPositions = this.findNearestPositions(progression);
+        
         this.currentLocation = nearestPositions.first.copyWithLocations({
-            progression: iframeProgress.progress // Most accurate progression in resource
+            progression: progression.start
         });
+        
         this.lastLocationInView = nearestPositions.last;
+        this.updateViewport(progression);
         this.listeners.positionChanged(this.currentLocation);
         await this.framePool.update(this.pub, this.currentLocation, this.determineModules());
     }
@@ -427,12 +633,32 @@ export class EpubNavigator extends VisualNavigator {
         return this.currentLocation;
     }
 
-    // Starting and ending position currently showing in the reader
-    get currentPositionNumbers(): number[] {
-        if(this.layout === EPUBLayout.fixed)
-         return (this.framePool as FXLFramePoolManager).currentNumbers;
+    get viewport(): VisualNavigatorViewport {
+        return this.layout === EPUBLayout.fixed 
+            ? (this.framePool as FXLFramePoolManager).viewport 
+            : this.reflowViewport;
+    }
 
-        return [this.currentLocator?.locations.position ?? 0, ...(this.lastLocationInView?.locations.position ? [this.lastLocationInView.locations.position] : [])];
+    get isScrollStart(): boolean {
+        const firstHref = this.viewport.readingOrder[0];
+        const progression = this.viewport.progressions.get(firstHref);
+        return progression?.start === 0;
+    }
+    
+    get isScrollEnd(): boolean {
+        const lastHref = this.viewport.readingOrder[this.viewport.readingOrder.length - 1];
+        const progression = this.viewport.progressions.get(lastHref);
+        return progression?.end === 1;
+    }
+    
+    get canGoBackward(): boolean {
+        const firstResource = this.pub.readingOrder.items[0]?.href;
+        return this.viewport.progressions.has(firstResource) && this.viewport.progressions.get(firstResource)?.start === 0;
+    }
+    
+    get canGoForward(): boolean {
+        const lastResource = this.pub.readingOrder.items[this.pub.readingOrder.items.length - 1]?.href;
+        return this.viewport.progressions.has(lastResource) && this.viewport.progressions.get(lastResource)?.end === 1;
     }
 
     // TODO: This is temporary until user settings are implemented.
@@ -442,7 +668,7 @@ export class EpubNavigator extends VisualNavigator {
 
     // TODO: This is temporary until user settings are implemented.
     public async setReadingProgression(newProgression: ReadingProgression) {
-        if(this.currentProgression === newProgression) return;
+        if(this.currentProgression === newProgression || !this.framePool) return;
         this.currentProgression = newProgression;
         await this.framePool.update(this.pub, this.currentLocator, this.determineModules(), true);
         this.attachListener();