@readium/navigator 2.1.1 → 2.2.0

package/src/webpub/WebPubNavigator.ts

@@ -0,0 +1,417 @@
+import { Link, Locator, Publication, ReadingProgression, LocatorLocations } from "@readium/shared";
+import { VisualNavigator, VisualNavigatorViewport, ProgressionRange } from "../Navigator";
+import { WebPubFramePoolManager } from "./WebPubFramePoolManager";
+import { BasicTextSelection, CommsEventKey, FrameClickEvent, ModuleLibrary, ModuleName, WebPubModules } from "@readium/navigator-html-injectables";
+import * as path from "path-browserify";
+import { ManagerEventKey } from "../epub/EpubNavigator";
+
+export interface WebPubNavigatorListeners {
+    frameLoaded: (wnd: Window) => void;
+    positionChanged: (locator: Locator) => void;
+    tap: (e: FrameClickEvent) => boolean;
+    click: (e: FrameClickEvent) => boolean;
+    zoom: (scale: number) => void;
+    scroll: (delta: number) => void;
+    customEvent: (key: string, data: unknown) => void;
+    handleLocator: (locator: Locator) => boolean;
+    textSelected: (selection: BasicTextSelection) => void;
+}
+
+const defaultListeners = (listeners: WebPubNavigatorListeners): WebPubNavigatorListeners => ({
+    frameLoaded: listeners.frameLoaded || (() => {}),
+    positionChanged: listeners.positionChanged || (() => {}),
+    tap: listeners.tap || (() => false),
+    click: listeners.click || (() => false),
+    zoom: listeners.zoom || (() => {}),
+    scroll: listeners.scroll || (() => {}),
+    customEvent: listeners.customEvent || (() => {}),
+    handleLocator: listeners.handleLocator || (() => false),
+    textSelected: listeners.textSelected || (() => {})
+});
+
+class WebPubNavigator extends VisualNavigator {
+    private readonly pub: Publication;
+    private readonly container: HTMLElement;
+    private readonly listeners: WebPubNavigatorListeners;
+    private framePool: WebPubFramePoolManager;
+    private currentIndex: number = 0;
+    private currentLocation: Locator;
+    private webViewport: VisualNavigatorViewport = {
+        readingOrder: [],
+        progressions: new Map(),
+        positions: null
+    };
+
+    constructor(container: HTMLElement, pub: Publication, listeners: WebPubNavigatorListeners, initialPosition: Locator | undefined = undefined) {
+        super();
+        this.pub = pub;
+        this.container = container;
+        this.listeners = defaultListeners(listeners);
+        this.framePool = new WebPubFramePoolManager(this.container);
+        if (initialPosition && typeof initialPosition.copyWithLocations === 'function') {
+            this.currentLocation = initialPosition;
+            // Update currentIndex to match the initial position
+            const index = this.pub.readingOrder.findIndexWithHref(initialPosition.href);
+            if (index >= 0) {
+                this.currentIndex = index;
+            }
+        } else {
+            this.currentLocation = this.createCurrentLocator();
+        }
+    }
+
+    async load(): Promise<void> {
+        await this.framePool.update(this.pub, this.currentLocation, this.determineModules());
+
+        this.attachListener();
+
+        // Notify listeners of initial position
+        this.listeners.positionChanged(this.currentLocation);
+    }
+
+    public eventListener(key: CommsEventKey | ManagerEventKey, data: unknown) {
+        switch (key) {
+            case "_pong":
+                this.listeners.frameLoaded(this.framePool.currentFrames[0]!.iframe.contentWindow!);
+                this.listeners.positionChanged(this.currentLocation);
+                break;
+            case "first_visible_locator":
+                const loc = Locator.deserialize(data as string);
+                if(!loc) break;
+                this.currentLocation = new Locator({
+                    href: this.currentLocation.href,
+                    type: this.currentLocation.type,
+                    title: this.currentLocation.title,
+                    locations: loc?.locations,
+                    text: loc?.text
+                });
+                this.listeners.positionChanged(this.currentLocation);
+                break;
+            case "text_selected":
+                this.listeners.textSelected(data as BasicTextSelection);
+                break;
+            case "click":
+            case "tap":
+                const edata = data as FrameClickEvent;
+                if (edata.interactiveElement) {
+                    const element = new DOMParser().parseFromString(
+                        edata.interactiveElement,
+                        "text/html"
+                    ).body.children[0];
+                    if (
+                        element.nodeType === element.ELEMENT_NODE &&
+                        element.nodeName === "A" &&
+                        element.hasAttribute("href")
+                    ) {
+                        const origHref = element.attributes.getNamedItem("href")?.value!;
+                        if (origHref.startsWith("#")) {
+                            this.go(this.currentLocation.copyWithLocations({
+                                fragments: [origHref.substring(1)]
+                            }), false, () => { });
+                        } else if(
+                            origHref.startsWith("mailto:") ||
+                            origHref.startsWith("tel:")
+                        ) {
+                            this.listeners.handleLocator(new Link({
+                                href: origHref,
+                            }).locator);
+                        } else {
+                            // Handle internal links that should navigate within the WebPub
+                            // This includes relative links and full URLs that might be in the readingOrder
+                            try {
+                                let hrefToCheck;
+
+                                // If origHref is already a full URL, use it directly
+                                if (origHref.startsWith("http://") || origHref.startsWith("https://")) {
+                                    hrefToCheck = origHref;
+                                } else {
+                                    // For relative URLs, use different strategies based on base URL format
+                                    if (this.currentLocation.href.startsWith("http://") || this.currentLocation.href.startsWith("https://")) {
+                                        // Base URL is absolute, use URL constructor
+                                        const currentUrl = new URL(this.currentLocation.href);
+                                        const resolvedUrl = new URL(origHref, currentUrl);
+                                        hrefToCheck = resolvedUrl.href;
+                                    } else {
+                                        // Base URL is relative, use path operations
+                                        hrefToCheck = path.join(path.dirname(this.currentLocation.href), origHref);
+                                    }
+                                }
+
+                                const link = this.pub.readingOrder.findWithHref(hrefToCheck);
+                                if (link) {
+                                    this.goLink(link, false, () => { });
+                                } else {
+                                    console.warn(`Internal link not found in readingOrder: ${hrefToCheck}`);
+                                    this.listeners.handleLocator(new Link({
+                                        href: origHref,
+                                    }).locator);
+                                }
+                            } catch (error) {
+                                console.warn(`Couldn't resolve internal link for ${origHref}: ${error}`);
+                                this.listeners.handleLocator(new Link({
+                                    href: origHref,
+                                }).locator);
+                            }
+                        }
+                    } else console.log("Clicked on", element);
+                } else {
+                    const handled = key === "click" ? this.listeners.click(edata) : this.listeners.tap(edata);
+                    if(handled) break;
+                }
+                break;
+            case "scroll":
+                this.listeners.scroll(data as number);
+                break;
+            case "zoom":
+                this.listeners.zoom(data as number);
+                break;
+            case "progress":
+                this.syncLocation(data as ProgressionRange);
+                break;
+            case "log":
+                console.log(this.framePool.currentFrames[0]?.source?.split("/")[3], ...(data as any[]));
+                break;
+            default:
+                this.listeners.customEvent(key, data);
+                break;
+        }
+    }
+
+    private determineModules(): ModuleName[] {
+        let modules = Array.from(ModuleLibrary.keys()) as ModuleName[];
+
+        // For WebPub, use the predefined WebPubModules array and filter
+        return modules.filter((m) => WebPubModules.includes(m));
+    }
+
+    private attachListener() {
+        if (this.framePool.currentFrames[0]?.msg) {
+            this.framePool.currentFrames[0].msg.listener = (key: CommsEventKey | ManagerEventKey, value: unknown) => {
+                this.eventListener(key, value);
+            };
+        }
+    }
+
+    private async apply() {
+        await this.framePool.update(this.pub, this.currentLocation, this.determineModules());
+
+        this.attachListener();
+
+        const idx = this.pub.readingOrder.findIndexWithHref(this.currentLocation.href);
+        if (idx < 0)
+            throw Error("Link for " + this.currentLocation.href + " not found!");
+    }
+
+    public async destroy() {
+        await this.framePool?.destroy();
+    }
+
+    private async changeResource(relative: number): Promise<boolean> {
+        if (relative === 0) return false;
+
+        const curr = this.pub.readingOrder.findIndexWithHref(this.currentLocation.href);
+        const i = Math.max(
+            0,
+            Math.min(this.pub.readingOrder.items.length - 1, curr + relative)
+        );
+        if (i === curr) {
+            return false;
+        }
+        this.currentIndex = i;
+        this.currentLocation = this.createCurrentLocator();
+        await this.apply();
+        return true;
+    }
+
+    private updateViewport(progression: ProgressionRange) {
+        this.webViewport.readingOrder = [];
+        this.webViewport.progressions.clear();
+        this.webViewport.positions = null;
+
+        // Use the current position's href
+        if (this.currentLocation) {
+            this.webViewport.readingOrder.push(this.currentLocation.href);
+            this.webViewport.progressions.set(this.currentLocation.href, progression);
+
+            if (this.currentLocation.locations?.position !== undefined) {
+                this.webViewport.positions = [this.currentLocation.locations.position];
+                // WebPub doesn't have lastLocationInView like EPUB, so no second position
+            }
+        }
+    }
+
+    private async syncLocation(iframeProgress: ProgressionRange): Promise<void> {
+        const progression = iframeProgress;
+        if (this.currentLocation) {
+            this.currentLocation = this.currentLocation.copyWithLocations({
+                progression: progression.start
+            });
+        }
+
+        this.updateViewport(progression);
+        this.listeners.positionChanged(this.currentLocation);
+        await this.framePool.update(this.pub, this.currentLocation, this.determineModules());
+    }
+
+    goBackward(_animated: boolean, cb: (ok: boolean) => void): void {
+        this.changeResource(-1).then((success) => {
+            cb(success);
+        });
+    }
+
+    goForward(_animated: boolean, cb: (ok: boolean) => void): void {
+        this.changeResource(1).then((success) => {
+            cb(success);
+        });
+    }
+
+    get currentLocator(): Locator {
+        return this.currentLocation;
+    }
+
+    get viewport(): VisualNavigatorViewport {
+        return this.webViewport;
+    }
+
+    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);
+    }
+
+    get readingProgression(): ReadingProgression {
+        return this.pub.metadata.effectiveReadingProgression;
+    }
+
+    get publication(): Publication {
+        return this.pub;
+    }
+
+    private async loadLocator(locator: Locator, cb: (ok: boolean) => void) {
+        let done = false;
+        let cssSelector = (typeof locator.locations.getCssSelector === 'function') && locator.locations.getCssSelector();
+        if(locator.text?.highlight) {
+            done = await new Promise<boolean>((res, _) => {
+                // Attempt to go to a highlighted piece of text in the resource
+                this.framePool.currentFrames[0]!.msg!.send(
+                    "go_text",
+                    cssSelector ? [
+                        locator.text?.serialize(),
+                        cssSelector // Include CSS selector if it exists
+                    ] : locator.text?.serialize(),
+                    (ok) => res(ok)
+                );
+            });
+        } else if(cssSelector) {
+            done = await new Promise<boolean>((res, _) => {
+                this.framePool.currentFrames[0]!.msg!.send(
+                    "go_text",
+                    [
+                        "", // No text!
+                        cssSelector // Just CSS selector
+                    ],
+                    (ok) => res(ok)
+                );
+            });
+        }
+        if(done) {
+            cb(done);
+            return;
+        }
+        // This sanity check has to be performed because we're still passing non-locator class
+        // locator objects to this function. This is not good and should eventually be forbidden
+        // or the locator should be deserialized sometime before this function.
+        const hid = (typeof locator.locations.htmlId === 'function') && locator.locations.htmlId();
+        if(hid)
+            done = await new Promise<boolean>((res, _) => {
+                // Attempt to go to an HTML ID in the resource
+                this.framePool.currentFrames[0]!.msg!.send("go_id", hid, (ok) => res(ok));
+            });
+        if(done) {
+            cb(done);
+            return;
+        }
+
+        const progression = locator?.locations?.progression;
+        const hasProgression = progression && progression > 0;
+        if(hasProgression)
+            done = await new Promise<boolean>((res, _) => {
+                // Attempt to go to a progression in the resource
+                this.framePool.currentFrames[0]!.msg!.send("go_progression", progression, (ok) => res(ok));
+            });
+        else done = true;
+        cb(done);
+    }
+
+    public go(locator: Locator, _: boolean, cb: (ok: boolean) => void): void {
+        const href = locator.href.split("#")[0];
+        let link = this.pub.readingOrder.findWithHref(href);
+        if(!link) {
+            return cb(this.listeners.handleLocator(locator));
+        }
+
+         // Update currentIndex to point to the found link
+        const index = this.pub.readingOrder.findIndexWithHref(href);
+        if (index >= 0) {
+            this.currentIndex = index;
+        }
+
+        this.currentLocation = this.createCurrentLocator();
+        this.apply().then(() => this.loadLocator(locator, (ok) => cb(ok))).then(() => {
+            // Now that we've gone to the right locator, we can attach the listeners.
+            // Doing this only at this stage reduces janky UI with multiple locator updates.
+            this.attachListener();
+        });
+    }
+
+    public goLink(link: Link, animated: boolean, cb: (ok: boolean) => void): void {
+        return this.go(link.locator, animated, cb);
+    }
+
+    // Specifics to WebPub
+    // Util method
+    private createCurrentLocator(): Locator {
+        const readingOrder = this.pub.readingOrder;
+        const currentLink = readingOrder.items[this.currentIndex];
+
+        if (!currentLink) {
+            throw new Error("No current resource available");
+        }
+
+        // Check if we're on the same resource
+        const isSameResource = this.currentLocation && this.currentLocation.href === currentLink.href;
+
+        // Preserve progression if staying on same resource, otherwise start from beginning
+        const progression = isSameResource && this.currentLocation.locations.progression
+            ? this.currentLocation.locations.progression
+            : 0;
+
+        return this.pub.manifest.locatorFromLink(currentLink) || new Locator({
+            href: currentLink.href,
+            type: currentLink.type || "text/html",
+            locations: new LocatorLocations({
+                fragments: [],
+                progression: progression,
+                position: this.currentIndex + 1
+            })
+        });
+    }
+}
+
+export const ExperimentalWebPubNavigator = WebPubNavigator;

package/src/webpub/index.ts

@@ -0,0 +1,4 @@
+export * from "./WebPubNavigator";
+export * from "./WebPubBlobBuilder";
+export * from "./WebPubFrameManager";
+export * from "./WebPubFramePoolManager";

package/types/src/index.d.ts

@@ -1,4 +1,5 @@
 export * from './Navigator';
+export * from './webpub';
 export * from './epub';
 export * from './audio';
 export * from './helpers';

package/types/src/web/WebPubBlobBuilder.d.ts

@@ -0,0 +1,10 @@
+import { Link, Publication } from "@readium/shared";
+export declare class WebPubBlobBuilder {
+    private readonly item;
+    private readonly publication;
+    constructor(publication: Publication, item: Link);
+    build(): Promise<string>;
+    private buildHtmlFrame;
+    private serializeAsHTML;
+    private hasExecutable;
+}

package/types/src/web/WebPubFrameManager.d.ts

@@ -0,0 +1,20 @@
+import { Loader } from "../../../navigator-html-injectables/src/Loader";
+import { FrameComms } from "../../../navigator/src/epub/frame/FrameComms";
+export declare class WebPubFrameManager {
+    private frame;
+    private loader;
+    readonly source: string;
+    private comms;
+    private destroyed;
+    private currModules;
+    constructor(source: string);
+    load(modules?: string[]): Promise<Window>;
+    destroy(): Promise<void>;
+    get iframe(): HTMLIFrameElement;
+    get realSize(): DOMRect;
+    get window(): Window;
+    get atLeft(): boolean;
+    get atRight(): boolean;
+    get msg(): FrameComms | undefined;
+    get ldr(): Loader<import("../../../navigator-html-injectables/src/modules/ModuleLibrary").ModuleName> | undefined;
+}

package/types/src/web/WebPubNavigator.d.ts

@@ -0,0 +1,48 @@
+import { Link, Locator, Publication, ReadingProgression } from "@readium/shared";
+import { VisualNavigator, VisualNavigatorViewport } from "../Navigator";
+import { BasicTextSelection, FrameClickEvent } from '@readium/navigator-html-injectables';
+export interface WebPubNavigatorListeners {
+    frameLoaded: (wnd: Window) => void;
+    positionChanged: (locator: Locator) => void;
+    tap?: (e: FrameClickEvent) => boolean;
+    click?: (e: FrameClickEvent) => boolean;
+    zoom?: (scale: number) => void;
+    scroll?: (delta: number) => void;
+    customEvent?: (key: string, data: unknown) => void;
+    handleLocator?: (locator: Locator) => boolean;
+    textSelected?: (selection: BasicTextSelection) => void;
+}
+export declare class WebPubNavigator extends VisualNavigator {
+    private readonly pub;
+    private readonly container;
+    private readonly listeners;
+    private frameManager;
+    private currentIndex;
+    private currentLocation;
+    private currentBlobUrl;
+    private webViewport;
+    constructor(container: HTMLElement, pub: Publication, listeners?: Partial<WebPubNavigatorListeners>, initialPosition?: Locator | undefined);
+    load(): Promise<void>;
+    private eventListener;
+    private attachListener;
+    private apply;
+    destroy(): void;
+    private changeResource;
+    private updateViewport;
+    private syncLocation;
+    goBackward(_animated: boolean, cb: (ok: boolean) => void): void;
+    goForward(_animated: boolean, cb: (ok: boolean) => void): void;
+    get currentLocator(): Locator;
+    get viewport(): VisualNavigatorViewport;
+    get isScrollStart(): boolean;
+    get isScrollEnd(): boolean;
+    get canGoBackward(): boolean;
+    get canGoForward(): boolean;
+    get readingProgression(): ReadingProgression;
+    get publication(): Publication;
+    private loadLocator;
+    go(locator: Locator, _animated: boolean, cb: (ok: boolean) => void): void;
+    goLink(link: Link, _animated: boolean, cb: (ok: boolean) => void): void;
+    private frameUpdate;
+    private createCurrentLocator;
+}

package/types/src/web/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./WebPubNavigator";
+export * from "./WebPubBlobBuilder";
+export * from "./WebPubFrameManager";

package/types/src/webpub/WebPubBlobBuilder.d.ts

@@ -0,0 +1,12 @@
+import { Link, Publication } from "@readium/shared";
+export declare class WebPubBlobBuilder {
+    private readonly item;
+    private readonly burl;
+    private readonly pub;
+    constructor(pub: Publication, baseURL: string, item: Link);
+    build(): Promise<string>;
+    private buildHtmlFrame;
+    private hasExecutable;
+    private finalizeDOM;
+    private serializeAsHTML;
+}

package/types/src/webpub/WebPubFrameManager.d.ts

@@ -0,0 +1,20 @@
+import { Loader, ModuleName } from "@readium/navigator-html-injectables";
+import { FrameComms } from "../epub/frame/FrameComms";
+export declare class WebPubFrameManager {
+    private frame;
+    private loader;
+    readonly source: string;
+    private comms;
+    private destroyed;
+    private currModules;
+    constructor(source: string);
+    load(modules?: ModuleName[]): Promise<Window>;
+    destroy(): Promise<void>;
+    hide(): Promise<void>;
+    show(atProgress?: number): Promise<void>;
+    get iframe(): HTMLIFrameElement;
+    get realSize(): DOMRect;
+    get window(): Window;
+    get msg(): FrameComms | undefined;
+    get ldr(): Loader<ModuleName> | undefined;
+}

package/types/src/webpub/WebPubFramePoolManager.d.ts

@@ -0,0 +1,16 @@
+import { ModuleName } from "@readium/navigator-html-injectables";
+import { Locator, Publication } from "@readium/shared";
+import { WebPubFrameManager } from "./WebPubFrameManager";
+export declare class WebPubFramePoolManager {
+    private readonly container;
+    private _currentFrame;
+    private readonly pool;
+    private readonly blobs;
+    private readonly inprogress;
+    private currentBaseURL;
+    constructor(container: HTMLElement);
+    destroy(): Promise<void>;
+    update(pub: Publication, locator: Locator, modules: ModuleName[]): Promise<void>;
+    get currentFrames(): (WebPubFrameManager | undefined)[];
+    get currentBounds(): DOMRect;
+}

package/types/src/webpub/WebPubNavigator.d.ts

@@ -0,0 +1,50 @@
+import { Link, Locator, Publication, ReadingProgression } from "@readium/shared";
+import { VisualNavigator, VisualNavigatorViewport } from "../Navigator";
+import { BasicTextSelection, CommsEventKey, FrameClickEvent } from "@readium/navigator-html-injectables";
+import { ManagerEventKey } from "../epub/EpubNavigator";
+export interface WebPubNavigatorListeners {
+    frameLoaded: (wnd: Window) => void;
+    positionChanged: (locator: Locator) => void;
+    tap: (e: FrameClickEvent) => boolean;
+    click: (e: FrameClickEvent) => boolean;
+    zoom: (scale: number) => void;
+    scroll: (delta: number) => void;
+    customEvent: (key: string, data: unknown) => void;
+    handleLocator: (locator: Locator) => boolean;
+    textSelected: (selection: BasicTextSelection) => void;
+}
+declare class WebPubNavigator extends VisualNavigator {
+    private readonly pub;
+    private readonly container;
+    private readonly listeners;
+    private framePool;
+    private currentIndex;
+    private currentLocation;
+    private webViewport;
+    constructor(container: HTMLElement, pub: Publication, listeners: WebPubNavigatorListeners, initialPosition?: Locator | undefined);
+    load(): Promise<void>;
+    eventListener(key: CommsEventKey | ManagerEventKey, data: unknown): void;
+    private determineModules;
+    private attachListener;
+    private apply;
+    destroy(): Promise<void>;
+    private changeResource;
+    private updateViewport;
+    private syncLocation;
+    goBackward(_animated: boolean, cb: (ok: boolean) => void): void;
+    goForward(_animated: boolean, cb: (ok: boolean) => void): void;
+    get currentLocator(): Locator;
+    get viewport(): VisualNavigatorViewport;
+    get isScrollStart(): boolean;
+    get isScrollEnd(): boolean;
+    get canGoBackward(): boolean;
+    get canGoForward(): boolean;
+    get readingProgression(): ReadingProgression;
+    get publication(): Publication;
+    private loadLocator;
+    go(locator: Locator, _: boolean, cb: (ok: boolean) => void): void;
+    goLink(link: Link, animated: boolean, cb: (ok: boolean) => void): void;
+    private createCurrentLocator;
+}
+export declare const ExperimentalWebPubNavigator: typeof WebPubNavigator;
+export {};

package/types/src/webpub/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./WebPubNavigator";
+export * from "./WebPubBlobBuilder";
+export * from "./WebPubFrameManager";
+export * from "./WebPubFramePoolManager";