@readium/navigator 2.11.0 → 2.12.0

package/src/helpers/serialize.ts

@@ -0,0 +1,9 @@
+// Returns a function that runs operations one after another, even when one rejects
+export function createSerializer() {
+    let queue: Promise<unknown> = Promise.resolve();
+    return <T>(operation: () => Promise<T>): Promise<T> => {
+        const result = queue.then(operation);
+        queue = result.catch(() => {});
+        return result;
+    };
+}

package/src/index.ts

@@ -8,3 +8,4 @@ export * from './helpers/index.ts';
 export * from './preferences/index.ts';
 export * from './css/index.ts';
 export * from './injection/index.ts';
+export * from './readaloud/index.ts';

package/src/preferences/guards.ts

@@ -82,6 +82,17 @@ export function ensureValueInRange(value: number | null | undefined, range: [num
   return value >= min && value <= max ? value : undefined;
 }
 
+export function ensureDecorationStyle<T extends object>(value: T | false | null | undefined): T | false | null | undefined {
+  if (value === undefined || value === null || value === false) {
+    return value;
+  }
+  if (typeof value !== "object") {
+    return undefined;
+  }
+  const type = (value as { type?: unknown }).type;
+  return type === undefined || typeof type === "string" ? value : undefined;
+}
+
 export function withFallback<T>(value: T | null | undefined, defaultValue: T | null): T | null {
   return value === undefined ? defaultValue : value;
 }

package/src/readaloud/GuidedNavigationProvider.ts

@@ -0,0 +1,87 @@
+import { GuidedNavigationObject, Link, Publication } from "@readium/shared";
+import { decodeTextref, makeGnd } from "@readium/guided-navigation";
+
+export interface GuidedNavigationProvider {
+    /**
+     * Guided Navigation objects of a resource, with every textref qualified by the resource's href.
+     * Resolves to undefined when the resource has nothing to read.
+     */
+    guideFor(link: Link): Promise<GuidedNavigationObject[] | undefined>;
+}
+
+export interface PublicationGuidedNavigationProviderOptions {
+    /** Generates from the resource's markup without using the publication's Guided Navigation document. */
+    generateFromMarkup?: boolean;
+}
+
+/**
+ * Uses the publication's Guided Navigation document when its text can be located in the resource,
+ * and generates one from the resource's markup otherwise, or always with `generateFromMarkup`.
+ * Only the objects of the resource are kept from a document covering the whole publication.
+ */
+export class PublicationGuidedNavigationProvider implements GuidedNavigationProvider {
+    constructor(private readonly publication: Publication, private readonly options: PublicationGuidedNavigationProviderOptions = {}) {}
+
+    async guideFor(link: Link): Promise<GuidedNavigationObject[] | undefined> {
+        const href = link.href.split("#")[0];
+        if (!this.options.generateFromMarkup) {
+            const document = await this.publication.guideForLink(link, { skipAudio: true }).catch(() => undefined);
+            if (document) {
+                const guided = this.objectsIn(document.guided, href);
+                if (guided.length > 0 && this.isLocatable(guided)) return guided;
+            }
+        }
+        return this.generate(link, href);
+    }
+
+    private async generate(link: Link, href: string): Promise<GuidedNavigationObject[] | undefined> {
+        const resource = this.publication.get(link);
+        try {
+            const resourceLink = await resource.link();
+            if (!resourceLink.mediaType.isHTML) return undefined;
+            const doc = await resource.readAsXML();
+            if (!doc || doc.getElementsByTagNameNS("*", "parsererror").length > 0) return undefined;
+            const body = doc.querySelector("body");
+            if (!body) return undefined;
+            const mediaType = resourceLink.mediaType.essence === "text/html" ? "text/html" : "application/xhtml+xml";
+            return makeGnd(body, mediaType, { textrefs: { roles: true }, href })?.guided;
+        } finally {
+            resource.close();
+        }
+    }
+
+    // Objects without a resource of their own belong to their parent's, and are kept when that is `href` or unknown.
+    private objectsIn(objects: GuidedNavigationObject[], href: string, parentHref?: string): GuidedNavigationObject[] {
+        return objects.flatMap(object => {
+            const objectHref = this.resourceOf(object) ?? parentHref;
+            const children = object.children ? this.objectsIn(object.children, href, objectHref) : [];
+            if (objectHref !== undefined && objectHref !== href) return children;
+            if (children.length === 0 && !object.text && !object.textref && !object.imgref) return [];
+            // A fragment-only textref, as a resource's own document may use, is in that resource.
+            const textref = object.textref?.startsWith("#") ? href + object.textref : object.textref;
+            return [new GuidedNavigationObject({ ...object, textref, children: children.length > 0 ? children : undefined })];
+        });
+    }
+
+    private resourceOf(object: GuidedNavigationObject): string | undefined {
+        const textHref = object.textref?.split("#")[0];
+        if (textHref) return textHref;
+        return this.imageOf(object);
+    }
+
+    // An imgref only names a resource when it's an image of the reading order, as in Divina.
+    private imageOf(object: GuidedNavigationObject): string | undefined {
+        const href = object.imgref?.split("#")[0];
+        return href && this.publication.readingOrder.findWithHref(href) ? href : undefined;
+    }
+
+    // Every object with text must be locatable by its own ref or an ancestor's, or following would miss it.
+    private isLocatable(objects: GuidedNavigationObject[], ancestorLocatable = false): boolean {
+        return objects.every(object => {
+            const own = object.textref ? decodeTextref(object) !== undefined : this.imageOf(object) !== undefined;
+            const locatable = ancestorLocatable || own;
+            if (object.text && !locatable) return false;
+            return !object.children || this.isLocatable(object.children, locatable);
+        });
+    }
+}