@readium/navigator-html-injectables 1.2.0

package/src/modules/Decorator.ts

@@ -0,0 +1,462 @@
+import { Locator } from "@readium/shared";
+import { Comms } from "../comms/comms";
+import { Module } from "./Module";
+import { rangeFromLocator } from "../helpers/locator";
+import { ModuleName } from "./ModuleLibrary";
+import { Rect, getClientRectsNoOverlap } from "../helpers/rect";
+import { ResizeObserver as Polyfill } from '@juggle/resize-observer';
+import { getProperty } from "../helpers/css";
+import { ReadiumWindow } from "../helpers/dom";
+
+// Necessary for iOS 13 and below
+const ResizeObserver = window.ResizeObserver || Polyfill;
+
+export enum Width {
+    Wrap = "wrap", // Smallest width fitting the CSS border box.
+    Viewport = "viewport", // Fills the whole viewport.
+    Bounds = "bounds", // Fills the anchor page, useful for dual page.
+    Page = "page", // Fills the whole viewport.
+}
+
+export enum Layout {
+    Boxes = "boxes", // One HTML element for each CSS border box (e.g. line of text).
+    Bounds = "bounds", // A single HTML element covering the smallest region containing all CSS border boxes.
+}
+
+// TODO improve
+export interface Style {
+    tint: string; // CSS color string
+    layout: Layout; // Determines the number of created HTML elements and their position relative to the matching DOM range.
+    width: Width; // Indicates how the width of each created HTML element expands in the viewport.
+}
+
+export interface Decoration {
+    id: string; // Unique ID of the decoration. It must be unique in the group the decoration is applied to.
+    locator: Locator; // Location in the publication where the decoration will be rendered.
+    style: Style; // Declares the look and feel of the decoration.
+    // TODO extras (userInfo)
+}
+
+export interface DecoratorRequest {
+    group: string; // Unique ID of the decoration group
+    action: "add" | "remove" | "clear" | "update"; // Command
+    decoration: Decoration | undefined;
+}
+
+interface DecorationItem {
+    id: string;
+    decoration: Decoration;
+    range: Range;
+
+    clickableElements: HTMLElement[] | undefined;
+    container: HTMLElement | undefined;
+}
+
+const canNativeHighlight = "Highlight" in window;
+const cannotNativeHighlight = ["IMG", "IMAGE", "AUDIO", "VIDEO", "SVG"];
+
+class DecorationGroup {
+    public readonly items: DecorationItem[] = [];
+    private lastItemId = 0;
+    private container: HTMLDivElement | undefined = undefined;
+    private activateable = false;
+    public readonly experimentalHighlights: boolean = false;
+    private readonly notTextFlag: Map<string, boolean> | undefined;
+
+    /**
+     * Creates a DecorationGroup object
+     * @param id Unique HTML ID-adhering name of the group
+     * @param name Human-readable name of the group
+     */
+    constructor(
+        private readonly wnd: ReadiumWindow,
+        private readonly comms: Comms,
+        private readonly id: string,
+        private readonly name: string
+    ) {
+        if (canNativeHighlight) {
+            this.experimentalHighlights = true;
+            this.notTextFlag = new Map<string, boolean>();
+        }
+    }
+
+    get activeable() {
+        return this.activateable;
+    }
+
+    set activeable(value: boolean) {
+        this.activateable = value;
+    }
+
+    /**
+     * Adds a new decoration to the group.
+     * @param decoration Decoration to add
+     */
+    add(decoration: Decoration) {
+        const id = `${this.id}-${this.lastItemId++}`;
+
+        const range = rangeFromLocator(this.wnd.document, decoration.locator);
+        if (!range) {
+            this.comms.log("Can't locate DOM range for decoration", decoration);
+            return;
+        }
+        const ancestor = range.commonAncestorContainer as HTMLElement;
+        if(ancestor.nodeType !== Node.TEXT_NODE && this.experimentalHighlights) {
+            if(cannotNativeHighlight.includes(ancestor.nodeName.toUpperCase())) {
+                // The common ancestor is an element that definitely cannot be highlighted
+                this.notTextFlag?.set(id, true);
+            }
+            if(ancestor.querySelector(cannotNativeHighlight.join(", ").toLowerCase())) {
+                // Contains elements that definitely cannot be highlighted as children
+                this.notTextFlag?.set(id, true);
+            }
+            if((ancestor.textContent?.trim() || "").length === 0) {
+                // No text to be highlighted
+                this.notTextFlag?.set(id, true);
+            }
+        }
+
+        const item = {
+            decoration,
+            id,
+            range,
+        } as DecorationItem;
+
+        this.items.push(item);
+        this.layout(item);
+        this.renderLayout([item]);
+    }
+
+    /**
+     * Removes the decoration with given ID from the group.
+     * @param identifier ID of item to remove
+     */
+    remove(identifier: string) {
+        const index = this.items.findIndex(i => i.decoration.id === identifier);
+        if (index < 0) return;
+
+        const item = this.items[index];
+        this.items.splice(index, 1);
+        item.clickableElements = undefined;
+        if (item.container) {
+            item.container.remove();
+            item.container = undefined;
+        }
+        if (this.experimentalHighlights && !this.notTextFlag?.has(item.id)) {
+            // Remove highlight from ranges
+            const mm = ((this.wnd as any).CSS.highlights as Map<string, unknown>).get(this.id) as Set<Range>;
+            mm?.delete(item.range);
+        }
+        this.notTextFlag?.delete(item.id);
+    }
+
+    /**
+     * Notifies that the given decoration was modified and needs to be updated.
+     * @param decoration Decoration to update
+     */
+    update(decoration: Decoration) {
+        this.remove(decoration.id);
+        this.add(decoration);
+    }
+
+    /**
+     * Removes all decorations from this group.
+     */
+    clear() {
+        this.clearContainer();
+        this.items.length = 0;
+        this.notTextFlag?.clear();
+    }
+
+    /**
+     * Recreates the decoration elements.
+     * To be called after reflowing the resource, for example.
+     */
+    requestLayout() {
+        this.wnd.cancelAnimationFrame(this.currentRender);
+        this.clearContainer();
+        this.items.forEach(i => this.layout(i));
+        this.renderLayout(this.items);
+    }
+
+    private experimentalLayout(item: DecorationItem) {
+        const [stylesheet, highlighter]: [HTMLStyleElement, any] = this.requireContainer(true) as [HTMLStyleElement, unknown];
+        highlighter.add(item.range);
+
+        // TODO add caching layer ("vdom") to this so we aren't completely replacing the CSS every time
+        stylesheet.innerHTML = `
+        ::highlight(${this.id}) {
+            color: black;
+            background-color: ${item.decoration?.style?.tint ?? "yellow"};
+        }`;
+    }
+
+    /**
+     * Layouts a single DecorationItem.
+     * @param item 
+     */
+    private layout(item: DecorationItem) {
+        if (this.experimentalHighlights && !this.notTextFlag?.has(item.id)) {
+            // Highlight using the new Highlight Web API!
+            return this.experimentalLayout(item);
+        }
+        // this.comms.log("Environment does not support experimental Web Highlight API, can't layout decorations");
+
+        const itemContainer = this.wnd.document.createElement("div");
+        itemContainer.setAttribute("id", item.id);
+        // itemContainer.dataset.style = item.decoration.style; // TODO style
+        itemContainer.style.setProperty("pointer-events", "none");
+
+        const viewportWidth = this.wnd.innerWidth;
+        const columnCount = parseInt(
+            getComputedStyle(this.wnd.document.documentElement).getPropertyValue(
+                "column-count"
+            )
+        );
+        const pageWidth = viewportWidth / (columnCount || 1);
+        const scrollingElement = this.wnd.document.scrollingElement!;
+        const xOffset = scrollingElement.scrollLeft;
+        const yOffset = scrollingElement.scrollTop;
+
+        const positionElement = (element: HTMLElement, rect: Rect, boundingRect: DOMRect) => {
+            element.style.position = "absolute";
+
+            // TODO change to switch
+            if (item.decoration?.style?.width === Width.Viewport) {
+                element.style.width = `${viewportWidth}px`;
+                element.style.height = `${rect.height}px`;
+                let left = Math.floor(rect.left / viewportWidth) * viewportWidth;
+                element.style.left = `${left + xOffset}px`;
+                element.style.top = `${rect.top + yOffset}px`;
+            } else if (item.decoration?.style?.width === Width.Bounds) {
+                element.style.width = `${boundingRect.width}px`;
+                element.style.height = `${rect.height}px`;
+                element.style.left = `${boundingRect.left + xOffset}px`;
+                element.style.top = `${rect.top + yOffset}px`;
+            } else if (item.decoration?.style?.width === Width.Page) {
+                element.style.width = `${pageWidth}px`;
+                element.style.height = `${rect.height}px`;
+                let left = Math.floor(rect.left / pageWidth) * pageWidth;
+                element.style.left = `${left + xOffset}px`;
+                element.style.top = `${rect.top + yOffset}px`;
+            } else {
+                // Fall back to "wrap"
+                element.style.width = `${rect.width}px`;
+                element.style.height = `${rect.height}px`;
+                element.style.left = `${rect.left + xOffset}px`;
+                element.style.top = `${rect.top + yOffset}px`;
+            }
+        }
+
+        const boundingRect = item.range.getBoundingClientRect();
+
+        let template = this.wnd.document.createElement("template");
+        // template.innerHTML = item.decoration.element.trim();
+        // TODO more styles logic
+
+        const isDarkMode = getProperty(this.wnd, "--USER__appearance") === "readium-night-on";
+
+        template.innerHTML = `
+        <div
+            class="r2-highlight-0"
+            style="${[
+                `background-color: ${item.decoration?.style?.tint ?? "yellow"} !important`,
+                //"opacity: 0.3 !important",
+                `mix-blend-mode: ${isDarkMode ? "exclusion" : "multiply"} !important`,
+                "opacity: 1 !important",
+                "box-sizing: border-box !important"
+            ].join("; ")}"
+        >
+        </div>
+        `.trim();
+        const elementTemplate = template.content.firstElementChild!;
+
+        if(item.decoration?.style?.layout === Layout.Bounds) {
+            const bounds = elementTemplate.cloneNode(true) as HTMLDivElement;
+            bounds.style.setProperty("pointer-events", "none");
+            positionElement(bounds, boundingRect, boundingRect);
+            itemContainer.append(bounds);
+        } else {
+            // Fall back to "boxes" value for layout
+            let clientRects = getClientRectsNoOverlap(
+              item.range,
+              true // doNotMergeHorizontallyAlignedRects
+            );
+
+            clientRects = clientRects.sort((r1, r2) => {
+              if (r1.top < r2.top) {
+                return -1;
+              } else if (r1.top > r2.top) {
+                return 1;
+              } else {
+                return 0;
+              }
+            });
+
+            for (let clientRect of clientRects) {
+              const line = elementTemplate.cloneNode(true) as HTMLDivElement;
+              line.style.setProperty("pointer-events", "none");
+              positionElement(line, clientRect, boundingRect);
+              itemContainer.append(line);
+            }
+        }
+
+        item.container = itemContainer;
+        item.clickableElements = Array.from(
+            itemContainer.querySelectorAll("[data-activable='1']")
+        );
+        if(!item.clickableElements.length) {
+            item.clickableElements = Array.from(itemContainer.children) as HTMLElement[];
+        }
+    }
+
+    private currentRender = 0;
+    private renderLayout(items: DecorationItem[]) {
+        this.wnd.cancelAnimationFrame(this.currentRender);
+        this.currentRender = this.wnd.requestAnimationFrame(() => {
+            items = items.filter(i => !this.experimentalHighlights || !!this.notTextFlag?.has(i.id));
+            if(!items || items.length === 0) return;
+            const groupContainer = this.requireContainer() as HTMLDivElement;
+            groupContainer.append(...items.map(i => i.container).filter(c => !!c) as Node[])
+        });
+    }
+
+    /**
+     * Returns the group container element, after making sure it exists.
+     * @returns Group's container
+     */
+    private requireContainer(experimental=false): [HTMLStyleElement, any] | HTMLDivElement {
+        if (experimental) {
+            // Setup <style> for highlights
+            let d: HTMLStyleElement;
+            if (this.wnd.document.getElementById(`${this.id}-style`)) {
+                d = this.wnd.document.getElementById(`${this.id}-style`) as HTMLStyleElement;
+            } else {
+                d = this.wnd.document.createElement("style");
+                d.dataset.readium = "true";
+                d.id = `${this.id}-style`;
+                this.wnd.document.head.appendChild(d);
+            }
+
+            // Setup CSS.highlights
+            let h: unknown;
+            if (((this.wnd as any).CSS.highlights as Map<string, unknown>).has(this.id)) {
+                h = ((this.wnd as any).CSS.highlights as Map<string, unknown>).get(this.id)
+            } else {
+                h = new (this.wnd as any).Highlight();
+                ((this.wnd as any).CSS.highlights as Map<string, unknown>).set(this.id, h);
+            }
+            return [d, h];
+        }
+
+        if (!this.container) {
+            this.container = this.wnd.document.createElement("div");
+            this.container.setAttribute("id", this.id);
+            this.container.dataset.group = this.name;
+            this.container.dataset.readium = "true";
+            this.container.style.setProperty("pointer-events", "none");
+            this.container.style.display = "contents";
+            this.wnd.document.body.append(this.container);
+        }
+        return this.container;
+    }
+
+    /**
+     * Removes the group container.
+     */
+    private clearContainer() {
+        if (this.experimentalHighlights) {
+            ((this.wnd as any).CSS.highlights as Map<string, unknown>).delete(this.id);
+        }
+        if (this.container) {
+            this.container.remove();
+            this.container = undefined;
+        }
+    }
+}
+
+export class Decorator extends Module {
+    static readonly moduleName: ModuleName = "decorator";
+    private resizeObserver!: ResizeObserver;
+    private wnd!: ReadiumWindow;
+    /*private readonly lastSize = {
+        width: 0,
+        height: 0
+    };*/
+    private resizeFrame = 0;
+
+    private lastGroupId = 0;
+    private groups = new Map<string, DecorationGroup>();
+
+    private cleanup() {
+        // TODO cleanup all decorators
+        this.groups.forEach(g => g.clear());
+        this.groups.clear();
+    }
+
+    private handleResize() {
+        this.wnd.clearTimeout(this.resizeFrame);
+        this.resizeFrame = this.wnd.setTimeout(() => {
+            this.groups.forEach(g => {
+                if(!g.experimentalHighlights) g.requestLayout();
+            });
+        }, 50);
+    }
+    private readonly handleResizer = this.handleResize.bind(this);
+
+    mount(wnd: ReadiumWindow, comms: Comms): boolean {
+        this.wnd = wnd;
+
+        comms.register("decorate", Decorator.moduleName, (data, ack) => {
+            const req = data as DecoratorRequest;
+            if (req.decoration && req.decoration.locator) {
+                req.decoration.locator = Locator.deserialize(req.decoration.locator)!;
+            }
+            if (!this.groups.has(req.group)) {
+                this.groups.set(req.group, new DecorationGroup(
+                    wnd,
+                    comms,
+                    `readium-decoration-${this.lastGroupId++}`,
+                    req.group
+                ));
+            }
+            const group = this.groups.get(req.group);
+            switch (req.action) {
+                case "add":
+                    group?.add(req.decoration!);
+                    break;
+                case "remove":
+                    group?.remove(req.decoration!.id);
+                    break;
+                case "clear":
+                    group?.clear();
+                    break;
+                case "update":
+                    group?.update(req.decoration!);
+                    break;
+            }
+
+            ack(true);
+        });
+
+        this.resizeObserver = new ResizeObserver(() => wnd.requestAnimationFrame(() => this.handleResize()));
+        this.resizeObserver.observe(wnd.document.body);
+        wnd.addEventListener("orientationchange", this.handleResizer);
+        wnd.addEventListener("resize", this.handleResizer);
+
+        comms.log("Decorator Mounted");
+        return true;
+    }
+
+    unmount(wnd: ReadiumWindow, comms: Comms): boolean {
+        wnd.removeEventListener("orientationchange", this.handleResizer);
+        wnd.removeEventListener("resize", this.handleResizer);
+
+        comms.unregisterAll(Decorator.moduleName);
+        this.resizeObserver.disconnect();
+        this.cleanup();
+
+        comms.log("Decorator Unmounted");
+        return true;
+    }
+}

package/src/modules/Module.ts

@@ -0,0 +1,23 @@
+import { Comms } from "../comms";
+import { ReadiumWindow } from "../helpers/dom";
+import { ModuleName } from "./ModuleLibrary";
+
+export abstract class Module {
+    static readonly moduleName: ModuleName; // snake_case name of the module, must be unique.
+
+    // Called by the loader, where modules are mounted one after another.
+    // In this function, the Module can register any commands it should listen
+    // to using comms.register, and send any commands using comms.send. Modules
+    // must be designed to not use comms.send before the communication handshake
+    // has finished (so not during the mount function).
+    abstract mount(wnd: ReadiumWindow, comms: Comms): boolean;
+
+    // Unmounting should completely clean up any event listeners or
+    // active modification of the HTML content, and cease all activity. This is
+    // because an implementer should be able to mount and unmount Modules at any
+    // time, to, for example, switch reading modes. There should be no difference
+    // in behavior after mounting and unmounting a Module repeatedly.
+    abstract unmount(wnd: ReadiumWindow, comms: Comms): boolean;
+}
+
+export type ModuleDerived = {new (): Module} & typeof Module;

package/src/modules/ModuleLibrary.ts

@@ -0,0 +1,44 @@
+import { ModuleDerived } from "./Module";
+import { ColumnSnapper } from "./snapper/ColumnSnapper";
+import { ScrollSnapper } from "./snapper/ScrollSnapper";
+import { Peripherals } from "./Peripherals";
+import { ReflowableSetup } from "./setup/ReflowableSetup";
+import { FixedSetup } from "./setup/FixedSetup";
+import { Decorator } from "./Decorator";
+
+// All the module names. TODO: Come up with a better way of collecting these in a way TS will recognize
+export type ModuleName =
+    "setup" |
+    "snapper" |
+    "column_snapper" |
+    "scroll_snapper" |
+    "fixed_setup" |
+    "decorator" |
+    "reflowable_setup" |
+    "peripherals";
+
+// Modules that are valid for FXL publications
+export const FXLModules: ModuleName[] = [
+    "fixed_setup",
+    "decorator",
+    "peripherals"
+];
+
+// Modules that are valid for reflowable publications
+export const ReflowableModules: ModuleName[] = [
+    "reflowable_setup",
+    "decorator",
+    "peripherals",
+    "column_snapper",
+    "scroll_snapper"
+];
+
+export const ModuleLibrary = new Map<string, ModuleDerived>([
+    // All modules go here
+    FixedSetup,
+    ReflowableSetup,
+    Peripherals,
+    Decorator,
+    ColumnSnapper,
+    ScrollSnapper,
+].map(m => [m.moduleName, m])); // Turn module list into K/V list for quick access by name

package/src/modules/Peripherals.ts

@@ -0,0 +1,148 @@
+import { Comms } from "../comms/comms";
+import { Module } from "./Module";
+import { ReadiumWindow, nearestInteractiveElement } from "../helpers/dom";
+
+export interface FrameClickEvent {
+    defaultPrevented: boolean;
+    doNotDisturb: boolean;
+    interactiveElement: string | undefined;
+    cssSelector: string | undefined;
+    targetElement: string;
+    targetFrameSrc: string;
+    x: number;
+    y: number;
+}
+
+export interface BasicTextSelection {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    targetFrameSrc: string;
+}
+
+export class Peripherals extends Module {
+    static readonly moduleName = "peripherals";
+    private wnd!: ReadiumWindow;
+    private comms!: Comms;
+
+    private pointerMoved = false;
+
+    onPointUp(event: PointerEvent) {
+        const selection = this.wnd.getSelection();
+        if (!!selection && selection.toString()?.length > 0) {
+            const domRectList = selection.getRangeAt(0)?.getClientRects();
+            // Sanity check to avoid sending empty selections
+            if (!domRectList || domRectList.length === 0) {
+                return;
+            }
+            const rect = domRectList[0];
+            const textSelection = {
+                text: selection.toString(),
+                x: rect.x,
+                y: rect.y,
+                width: rect.width,
+                height: rect.height,
+                targetFrameSrc: this.wnd?.location?.href,
+            }
+            this.comms.send("text_selected", textSelection as BasicTextSelection);
+        }
+        if (this.pointerMoved) {
+            // If the pointer moved while tapping it's not a tap to consider
+            this.pointerMoved = false;
+            return;
+        }
+
+        if(!selection?.isCollapsed)
+            // There's an ongoing selection, the tap will dismiss it so we don't forward it.
+            return;
+
+        // if(handleDecorationClickEvent) // TODO handle clicking on decorators
+        //     return;
+        if(!event.isPrimary) return;
+
+        const pixelRatio = this.wnd.devicePixelRatio;
+        event.preventDefault(); // May have side-effects
+        this.comms.send(event.pointerType === "touch" ? "tap" : "click", {
+            defaultPrevented: event.defaultPrevented,
+            x: event.clientX * pixelRatio,
+            y: event.clientY * pixelRatio,
+            targetFrameSrc: this.wnd.location.href,
+            targetElement: (event.target as Element).outerHTML,
+            interactiveElement: nearestInteractiveElement(event.target as Element)?.outerHTML,
+            cssSelector: this.wnd._readium_cssSelectorGenerator.getCssSelector(event.target),
+        } as FrameClickEvent);
+
+        this.pointerMoved = false;
+    }
+    private readonly onPointerUp = this.onPointUp.bind(this);
+
+    onPointMove(event: PointerEvent) {
+        if(event.movementY !== undefined && event.movementX !== undefined) {
+            if(Math.abs(event.movementX) > 1 || Math.abs(event.movementY) > 1) {
+                this.pointerMoved = true;
+            }
+            return;
+        }
+
+        this.pointerMoved = true;
+    }
+    private readonly onPointerMove = this.onPointMove.bind(this);
+
+    onPointDown() {
+        this.pointerMoved = false;
+    }
+    private readonly onPointerDown = this.onPointDown.bind(this);
+
+    onContext(event: MouseEvent) {
+        // If the context menu is triggered by a long press, we manage the event using the pointup event
+        this.onPointUp(event as PointerEvent);
+        this.pointerMoved = false;
+    }
+    private readonly onContextMenu = this.onContext.bind(this);
+
+    onClick(event: MouseEvent) {
+        event.preventDefault(); // To prevent certain browser actions. May have side-effects
+        if(!event.isTrusted) {
+            // Synthetic events (probably triggered by some JavaScript) are probably not going to
+            // also send a `pointerup` event, so we have to compensate by doing so for them
+            const synthEvent = new PointerEvent("pointerup", {
+                isPrimary: true,
+                pointerType: "mouse", // Not really a better choice than this
+                clientX: event.clientX,
+                clientY: event.clientY,
+            });
+            // Override properties we cannot set in the constructor
+            Object.defineProperty(synthEvent, 'target', {writable: false, value: event.target});
+            Object.defineProperty(synthEvent, 'defaultPrevented', {writable: false, value: event.defaultPrevented });
+            // Trigger `pointerup` event
+            this.onPointUp(synthEvent);
+        }
+    }
+    private readonly onClicker = this.onClick.bind(this);
+
+    mount(wnd: ReadiumWindow, comms: Comms): boolean {
+        this.wnd = wnd;
+        this.comms = comms;
+        wnd.document.addEventListener("pointerdown", this.onPointerDown);
+        wnd.document.addEventListener("pointerup", this.onPointerUp);
+        wnd.document.addEventListener("contextmenu", this.onContextMenu);
+        wnd.document.addEventListener("pointermove", this.onPointerMove);
+        wnd.document.addEventListener("click", this.onClicker);
+
+        comms.log("Peripherals Mounted");
+        return true;
+    }
+
+    unmount(wnd: ReadiumWindow, comms: Comms): boolean {
+        wnd.document.removeEventListener("pointerdown", this.onPointerDown);
+        wnd.document.removeEventListener("pointerup", this.onPointerUp);
+        wnd.document.removeEventListener("contextmenu", this.onContextMenu);
+        wnd.document.removeEventListener("pointermove", this.onPointerMove);
+        wnd.document.removeEventListener("click", this.onClicker);
+
+        comms.log("Peripherals Unmounted");
+        return true;
+    }
+}

package/src/modules/index.ts

@@ -0,0 +1,3 @@
+export * from './Module';
+export * from './ModuleLibrary';
+export * from './Peripherals';