@readium/navigator-html-injectables 1.2.0

package/src/vendor/hypothesis/anchoring/xpath.ts

@@ -0,0 +1,164 @@
+/**
+ * Get the node name for use in generating an xpath expression.
+ */
+function getNodeName(node: Node): string {
+  const nodeName = node.nodeName.toLowerCase();
+  return nodeName === '#text' ? 'text()' : nodeName;
+}
+
+/**
+ * Get the index of the node as it appears in its parent's child list
+ */
+function getNodePosition(node: Node): number {
+  let pos = 0;
+  let tmp: Node | null = node;
+  while (tmp) {
+    if (tmp.nodeName === node.nodeName) {
+      pos += 1;
+    }
+    tmp = tmp.previousSibling;
+  }
+  return pos;
+}
+
+function getPathSegment(node: Node): string {
+  const name = getNodeName(node);
+  const pos = getNodePosition(node);
+  return `${name}[${pos}]`;
+}
+
+/**
+ * A simple XPath generator which can generate XPaths of the form
+ * /tag[index]/tag[index].
+ *
+ * @param node - The node to generate a path to
+ * @param root - Root node to which the returned path is relative
+ */
+export function xpathFromNode(node: Node, root: Node) {
+  let xpath = '';
+
+  let elem: Node | null = node;
+  while (elem !== root) {
+    if (!elem) {
+      throw new Error('Node is not a descendant of root');
+    }
+    xpath = getPathSegment(elem) + '/' + xpath;
+    elem = elem.parentNode;
+  }
+  xpath = '/' + xpath;
+  xpath = xpath.replace(/\/$/, ''); // Remove trailing slash
+
+  return xpath;
+}
+
+/**
+ * Return the `index`'th immediate child of `element` whose tag name is
+ * `nodeName` (case insensitive).
+ */
+function nthChildOfType(
+  element: Element,
+  nodeName: string,
+  index: number
+): Element | null {
+  nodeName = nodeName.toUpperCase();
+
+  let matchIndex = -1;
+  for (let i = 0; i < element.children.length; i++) {
+    const child = element.children[i];
+    if (child.nodeName.toUpperCase() === nodeName) {
+      ++matchIndex;
+      if (matchIndex === index) {
+        return child;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Evaluate a _simple XPath_ relative to a `root` element and return the
+ * matching element.
+ *
+ * A _simple XPath_ is a sequence of one or more `/tagName[index]` strings.
+ *
+ * Unlike `document.evaluate` this function:
+ *
+ *  - Only supports simple XPaths
+ *  - Is not affected by the document's _type_ (HTML or XML/XHTML)
+ *  - Ignores element namespaces when matching element names in the XPath against
+ *    elements in the DOM tree
+ *  - Is case-insensitive for all elements, not just HTML elements
+ *
+ * The matching element is returned or `null` if no such element is found.
+ * An error is thrown if `xpath` is not a simple XPath.
+ */
+function evaluateSimpleXPath(xpath: string, root: Element): Element | null {
+  const isSimpleXPath =
+    xpath.match(/^(\/[A-Za-z0-9-]+(\[[0-9]+\])?)+$/) !== null;
+  if (!isSimpleXPath) {
+    throw new Error('Expression is not a simple XPath');
+  }
+
+  const segments = xpath.split('/');
+  let element = root;
+
+  // Remove leading empty segment. The regex above validates that the XPath
+  // has at least two segments, with the first being empty and the others non-empty.
+  segments.shift();
+
+  for (const segment of segments) {
+    let elementName;
+    let elementIndex;
+
+    const separatorPos = segment.indexOf('[');
+    if (separatorPos !== -1) {
+      elementName = segment.slice(0, separatorPos);
+
+      const indexStr = segment.slice(separatorPos + 1, segment.indexOf(']'));
+      elementIndex = parseInt(indexStr) - 1;
+      if (elementIndex < 0) {
+        return null;
+      }
+    } else {
+      elementName = segment;
+      elementIndex = 0;
+    }
+
+    const child = nthChildOfType(element, elementName, elementIndex);
+    if (!child) {
+      return null;
+    }
+
+    element = child;
+  }
+
+  return element;
+}
+
+/**
+ * Finds an element node using an XPath relative to `root`
+ *
+ * Example:
+ *   node = nodeFromXPath('/main/article[1]/p[3]', document.body)
+ */
+export function nodeFromXPath(
+  xpath: string,
+  /* istanbul ignore next */
+  root: Element = document.body
+): Node | null {
+  try {
+    return evaluateSimpleXPath(xpath, root);
+  } catch (err) {
+    return document.evaluate(
+      '.' + xpath,
+      root,
+
+      // nb. The `namespaceResolver` and `result` arguments are optional in the spec
+      // but required in Edge Legacy.
+      null /* namespaceResolver */,
+      XPathResult.FIRST_ORDERED_NODE_TYPE,
+      null /* result */
+    ).singleNodeValue;
+  }
+}

package/src/vendor/hypothesis/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+
+    // Needed for some npm packages
+    "allowSyntheticDefaultImports": true,
+
+    "checkJs": true,
+    "lib": ["es2020", "dom", "dom.iterable"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+    "module": "es2020",
+    "moduleResolution": "node",
+    "noEmit": true,
+    "strict": true,
+    "target": "ES2020",
+
+    // Let argument to catch statement be `any` rather than `unknown`.
+    "useUnknownInCatchVariables": false,
+
+    // Prevent automatic inclusion of global variables defined in `@types/<name>` packages.
+    // This prevents eg. Node globals from `@types/node` being included when writing
+    // code for the browser.
+    // "types": ["redux-thunk/extend-redux"]
+  },
+  "include": ["**/*.js", "**/*.ts", "**/*.tsx", "types/*.d.ts"],
+  "exclude": [
+    // Tests are not checked.
+    "**/test/**/*.js",
+    "test-util/**/*.js",
+    "karma.config.js"
+  ]
+}

package/src/vendor/hypothesis/types/shared.ts

@@ -0,0 +1,40 @@
+/**
+ * Clusters provide the client application a mechanism for categorizing
+ * annotations so that their drawn anchor highlights may be styled distinctively
+ * in the annotated document. An annotation can only belong to one cluster.
+ */
+export type HighlightCluster =
+  | 'other-content' // default cluster: content not belonging to the current user
+  | 'user-annotations' // An annotation belonging to the current user
+  | 'user-highlights'; // A highlight (highlights are private; they always belong to the current user)
+
+/**
+ * Annotation properties not present on API objects, but added by the client
+ */
+export type ClientAnnotationData = {
+  $cluster?: HighlightCluster;
+
+  /**
+   * Client-side identifier: set even if annotation does not have a
+   * server-provided `id` (i.e. is unsaved)
+   */
+  $tag: string;
+
+  /**
+   * Flag indicating whether waiting for the annotation to anchor timed out
+   */
+  $anchorTimeout?: boolean;
+
+  /**
+   * Flag indicating that this annotation was created using the "Highlight" button,
+   * as opposed to "Annotate".
+   */
+  $highlight?: boolean;
+
+  /**
+   * Flag indicating that this annotation was not found in the document.
+   * It is initially `undefined` while anchoring is in progress and then set to
+   * `true` if anchoring failed or `false` if it succeeded.
+   */
+  $orphan?: boolean;
+};

package/types/src/Loader.d.ts

@@ -0,0 +1,33 @@
+import { ReadiumWindow } from "./helpers/dom";
+import { ModuleName } from "./modules";
+/**
+ * The Module loader. Handles initialization of the HTML injectables
+ * in the target Window, which could be an IFrame, or the current window).
+ */
+export declare class Loader<T extends string = ModuleName> {
+    private loadedModules;
+    private readonly wnd;
+    private readonly comms;
+    /**
+     * @param wnd Window instance to operate on
+     * @param initialModules List of initial modules to load
+     */
+    constructor(wnd?: ReadiumWindow, initialModules?: string[]);
+    private loadModule;
+    /**
+     * Add a module by name
+     * @param moduleName Module name
+     * @returns Success
+     */
+    addModule(moduleName: T): boolean;
+    /**
+     * Remove a module by name
+     * @param moduleName Module name
+     * @returns Success
+     */
+    removeModule(moduleName: T): boolean;
+    /**
+     * Unmount and remove all modules
+     */
+    destroy(): void;
+}

package/types/src/comms/comms.d.ts

@@ -0,0 +1,40 @@
+import { ReadiumWindow } from "../helpers/dom";
+import { CommsEventKey, CommsCommandKey } from "./keys";
+export declare const COMMS_VERSION = 1;
+export interface CommsMessage {
+    _readium: number;
+    _channel: string;
+    id?: string;
+    strict?: boolean;
+    key: CommsEventKey | CommsCommandKey;
+    data: unknown;
+}
+export interface Registrant {
+    module: string;
+    cb: CommsCallback;
+}
+export type CommsAck = (ok: boolean) => void;
+export type CommsCallback = (data: unknown, ack: CommsAck) => void;
+/**
+ * Comms is basically a wrapper around window.postMessage that
+ * adds structure to the messages and lets modules register callbacks.
+ */
+export declare class Comms {
+    private readonly wnd;
+    private destination;
+    private registrar;
+    private origin;
+    private channelId;
+    constructor(wnd: ReadiumWindow);
+    private receive;
+    private receiver;
+    private handle;
+    register(key: CommsCommandKey | CommsCommandKey[], module: string, callback: CommsCallback): void;
+    unregister(key: CommsCommandKey | CommsCommandKey[], module: string): void;
+    unregisterAll(module: string): void;
+    private preLog;
+    log(...data: any[]): void;
+    get ready(): boolean;
+    destroy(): void;
+    send(key: CommsEventKey, data: unknown, id?: unknown, transfer?: Transferable[]): void;
+}

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

@@ -0,0 +1,3 @@
+export * from './comms';
+export * from './keys';
+export * from './mid';

package/types/src/comms/keys.d.ts

@@ -0,0 +1,2 @@
+export type CommsEventKey = "_pong" | "_unhandled" | "_ack" | "log" | "error" | "click" | "tap" | "tap_more" | "no_more" | "no_less" | "swipe" | "progress" | "first_visible_locator" | "text_selected" | "media_play" | "media_pause";
+export type CommsCommandKey = "_ping" | "go_prev" | "go_next" | "go_id" | "go_text" | "go_end" | "go_start" | "go_progression" | "set_property" | "remove_property" | "first_visible_locator" | "decorate" | "protect" | "unprotect" | "unfocus" | "focus" | "activate" | "shake";

package/types/src/comms/mid.d.ts

@@ -0,0 +1 @@
+export declare const mid: () => string;

package/types/src/helpers/animation.d.ts

@@ -0,0 +1 @@
+export declare function easeInOutQuad(t: number): number;

package/types/src/helpers/css.d.ts

@@ -0,0 +1,4 @@
+import { ReadiumWindow } from "./dom";
+export declare function getProperty(wnd: ReadiumWindow, key: string): string;
+export declare function setProperty(wnd: ReadiumWindow, key: string, value: string): void;
+export declare function removeProperty(wnd: ReadiumWindow, key: string): void;

package/types/src/helpers/document.d.ts

@@ -0,0 +1,8 @@
+import { ReadiumWindow } from "./dom";
+export declare function isRTL(wnd: ReadiumWindow): boolean;
+export declare function getColumnCountPerScreen(wnd: ReadiumWindow): number;
+/**
+ * Having an odd number of columns when displaying two columns per screen causes snapping and page
+ * turning issues. To fix this, we insert a blank virtual column at the end of the resource.
+ */
+export declare function appendVirtualColumnIfNeeded(wnd: ReadiumWindow): void;

package/types/src/helpers/dom.d.ts

@@ -0,0 +1,15 @@
+import { Locator } from "@readium/shared";
+import type { getCssSelector } from "css-selector-generator";
+type BlockedEventData = [0, Function, any[], any[]] | [1, Event, EventTarget];
+export interface ReadiumWindow extends Window {
+    _readium_blockEvents: boolean;
+    _readium_blockedEvents: BlockedEventData[];
+    _readium_eventBlocker: EventListenerOrEventListenerObject;
+    _readium_cssSelectorGenerator: {
+        getCssSelector: typeof getCssSelector;
+    };
+}
+export declare function deselect(wnd: ReadiumWindow): void;
+export declare function nearestInteractiveElement(element: Element): Element | null;
+export declare function findFirstVisibleLocator(wnd: ReadiumWindow, scrolling: boolean): Locator;
+export {};

package/types/src/helpers/locator.d.ts

@@ -0,0 +1,2 @@
+import { Locator } from "@readium/shared";
+export declare function rangeFromLocator(doc: Document, locator: Locator): Range | null;

package/types/src/helpers/rect.d.ts

@@ -0,0 +1,10 @@
+export interface Rect {
+    bottom: number;
+    height: number;
+    left: number;
+    right: number;
+    top: number;
+    width: number;
+}
+export declare function getClientRectsNoOverlap(range: Range, doNotMergeHorizontallyAlignedRects: boolean): Rect[];
+export declare function rectContainsPoint(rect: Rect, x: number, y: number, tolerance: number): boolean;

package/types/src/helpers/scrollSnapperHelper.d.ts

@@ -0,0 +1,5 @@
+export declare class AnchorObserver extends HTMLElement {
+    connectedCallback(): void;
+}
+export declare function helperCreateAnchorElements(iframeElement: HTMLElement): void;
+export declare function helperRemoveAnchorElements(iframeElement: HTMLElement): void;

package/types/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from './comms';
+export * from './modules';
+export * from './Loader';

package/types/src/modules/Decorator.d.ts

@@ -0,0 +1,43 @@
+import { Locator } from "@readium/shared";
+import { Comms } from "../comms/comms";
+import { Module } from "./Module";
+import { ModuleName } from "./ModuleLibrary";
+import { ReadiumWindow } from "../helpers/dom";
+export declare 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"
+}
+export declare enum Layout {
+    Boxes = "boxes",// One HTML element for each CSS border box (e.g. line of text).
+    Bounds = "bounds"
+}
+export interface Style {
+    tint: string;
+    layout: Layout;
+    width: Width;
+}
+export interface Decoration {
+    id: string;
+    locator: Locator;
+    style: Style;
+}
+export interface DecoratorRequest {
+    group: string;
+    action: "add" | "remove" | "clear" | "update";
+    decoration: Decoration | undefined;
+}
+export declare class Decorator extends Module {
+    static readonly moduleName: ModuleName;
+    private resizeObserver;
+    private wnd;
+    private resizeFrame;
+    private lastGroupId;
+    private groups;
+    private cleanup;
+    private handleResize;
+    private readonly handleResizer;
+    mount(wnd: ReadiumWindow, comms: Comms): boolean;
+    unmount(wnd: ReadiumWindow, comms: Comms): boolean;
+}

package/types/src/modules/Module.d.ts

@@ -0,0 +1,11 @@
+import { Comms } from "../comms";
+import { ReadiumWindow } from "../helpers/dom";
+import { ModuleName } from "./ModuleLibrary";
+export declare abstract class Module {
+    static readonly moduleName: ModuleName;
+    abstract mount(wnd: ReadiumWindow, comms: Comms): boolean;
+    abstract unmount(wnd: ReadiumWindow, comms: Comms): boolean;
+}
+export type ModuleDerived = {
+    new (): Module;
+} & typeof Module;

package/types/src/modules/ModuleLibrary.d.ts

@@ -0,0 +1,5 @@
+import { ModuleDerived } from "./Module";
+export type ModuleName = "setup" | "snapper" | "column_snapper" | "scroll_snapper" | "fixed_setup" | "decorator" | "reflowable_setup" | "peripherals";
+export declare const FXLModules: ModuleName[];
+export declare const ReflowableModules: ModuleName[];
+export declare const ModuleLibrary: Map<string, ModuleDerived>;

package/types/src/modules/Peripherals.d.ts

@@ -0,0 +1,39 @@
+import { Comms } from "../comms/comms";
+import { Module } from "./Module";
+import { ReadiumWindow } 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 declare class Peripherals extends Module {
+    static readonly moduleName = "peripherals";
+    private wnd;
+    private comms;
+    private pointerMoved;
+    onPointUp(event: PointerEvent): void;
+    private readonly onPointerUp;
+    onPointMove(event: PointerEvent): void;
+    private readonly onPointerMove;
+    onPointDown(): void;
+    private readonly onPointerDown;
+    onContext(event: MouseEvent): void;
+    private readonly onContextMenu;
+    onClick(event: MouseEvent): void;
+    private readonly onClicker;
+    mount(wnd: ReadiumWindow, comms: Comms): boolean;
+    unmount(wnd: ReadiumWindow, comms: Comms): boolean;
+}

package/types/src/modules/ReflowablePeripherals.d.ts

@@ -0,0 +1,37 @@
+import { Comms } from "../comms/comms";
+import { Module } from "./Module";
+export interface FrameClickEvent {
+    defaultPrevented: boolean;
+    doNotDisturb: boolean;
+    interactiveElement: 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 declare class ReflowablePeripherals extends Module {
+    static readonly moduleName = "reflowable_peripherals";
+    private wnd;
+    private comms;
+    private pointerMoved;
+    onPointUp(event: PointerEvent): void;
+    private readonly onPointerUp;
+    onPointMove(event: PointerEvent): void;
+    private readonly onPointerMove;
+    onPointDown(): void;
+    private readonly onPointerDown;
+    onContext(event: MouseEvent): void;
+    private readonly onContextMenu;
+    onClick(event: MouseEvent): void;
+    private readonly onClicker;
+    mount(wnd: Window, comms: Comms): boolean;
+    unmount(wnd: Window, comms: Comms): boolean;
+}

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

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

package/types/src/modules/setup/FixedSetup.d.ts

@@ -0,0 +1,9 @@
+import { Comms } from "../../comms/comms";
+import { Setup } from "./Setup";
+import { ModuleName } from "../ModuleLibrary";
+import { ReadiumWindow } from "../../helpers/dom";
+export declare class FixedSetup extends Setup {
+    static readonly moduleName: ModuleName;
+    mount(wnd: ReadiumWindow, comms: Comms): boolean;
+    unmount(wnd: ReadiumWindow, comms: Comms): boolean;
+}

package/types/src/modules/setup/ReflowableSetup.d.ts

@@ -0,0 +1,9 @@
+import { Comms } from "../../comms/comms";
+import { Setup } from "./Setup";
+import { ReadiumWindow } from "../../helpers/dom";
+export declare class ReflowableSetup extends Setup {
+    static readonly moduleName = "reflowable_setup";
+    onViewportWidthChanged(event: Event): void;
+    mount(wnd: ReadiumWindow, comms: Comms): boolean;
+    unmount(wnd: ReadiumWindow, comms: Comms): boolean;
+}

package/types/src/modules/setup/Setup.d.ts

@@ -0,0 +1,17 @@
+import { Comms } from "../../comms/comms";
+import { ReadiumWindow } from "../../helpers/dom";
+import { Module } from "../Module";
+import { ModuleName } from "../ModuleLibrary";
+export declare abstract class Setup extends Module {
+    static readonly moduleName: ModuleName;
+    private comms;
+    wndOnErr(event: ErrorEvent): void;
+    protected unblock(wnd: ReadiumWindow): void;
+    private mediaPlayingCount;
+    private onMediaPlayEvent;
+    private onMediaPauseEvent;
+    private pauseAllMedia;
+    private allAnimations;
+    mount(wnd: ReadiumWindow, comms: Comms): boolean;
+    unmount(wnd: ReadiumWindow, comms: Comms): boolean;
+}

package/types/src/modules/snapper/ColumnSnapper.d.ts

@@ -0,0 +1,41 @@
+import { Comms } from "../../comms";
+import { Snapper } from "./Snapper";
+import { ModuleName } from "../ModuleLibrary";
+import { ReadiumWindow } from "../../helpers/dom";
+/**
+ * A {Snapper} for reflowable resources using a column-based layout
+ */
+export declare class ColumnSnapper extends Snapper {
+    static readonly moduleName: ModuleName;
+    private resizeObserver;
+    private mutationObserver;
+    private wnd;
+    private comms;
+    private doc;
+    private scrollOffset;
+    snapOffset(offset: number): number;
+    reportProgress(): void;
+    private shakeTimeout;
+    shake(): void;
+    private snappingCancelled;
+    private alreadyScrollLeft;
+    private overscroll;
+    private cachedScrollWidth;
+    private takeOverSnap;
+    snapCurrentOffset(smooth?: boolean, noprogress?: boolean): void;
+    private touchState;
+    private startingX;
+    private endingX;
+    private dragOffset;
+    private clearTouches;
+    onTouchStart(e: TouchEvent): void;
+    private readonly onTouchStarter;
+    onTouchEnd(_: TouchEvent): void;
+    private readonly onTouchEnder;
+    private onWidthChange;
+    private readonly onWidthChanger;
+    onTouchMove(e: TouchEvent): void;
+    private readonly onTouchMover;
+    mount(wnd: ReadiumWindow, comms: Comms): boolean;
+    unmount(wnd: ReadiumWindow, comms: Comms): boolean;
+}

package/types/src/modules/snapper/ScrollSnapper.d.ts

@@ -0,0 +1,16 @@
+import { Comms } from "../../comms";
+import { ReadiumWindow } from "../../helpers/dom";
+import { ModuleName } from "../ModuleLibrary";
+import { Snapper } from "./Snapper";
+export declare class ScrollSnapper extends Snapper {
+    static readonly moduleName: ModuleName;
+    private wnd;
+    private comms;
+    private doc;
+    private createAnchorElements;
+    private removeAnchorElements;
+    private createCustomElement;
+    private reportProgress;
+    mount(wnd: ReadiumWindow, comms: Comms): boolean;
+    unmount(wnd: ReadiumWindow, comms: Comms): boolean;
+}

package/types/src/modules/snapper/Snapper.d.ts

@@ -0,0 +1,11 @@
+import { Comms } from "../../comms";
+import { ReadiumWindow } from "../../helpers/dom";
+import { Module } from "../Module";
+import { ModuleName } from "../ModuleLibrary";
+export declare abstract class Snapper extends Module {
+    static readonly moduleName: ModuleName;
+    private protected;
+    buildStyles(): string;
+    mount(wnd: ReadiumWindow, comms: Comms): boolean;
+    unmount(wnd: ReadiumWindow, comms: Comms): boolean;
+}