@readium/shared 1.2.0

package/src/publication/services/content/iterators/PDFTextContentIterator.ts

@@ -0,0 +1,184 @@
+import { Locator } from "../../../Locator";
+import { Attribute, ContentElement } from "../element";
+import { IllegalStateError, Iterator } from "../Iterator";
+
+// Type TextItem represents a text item in a PDF page (extracted from pdf.js TextItem type).
+type TextItem = {
+    str: string;
+    dir: string;
+    locator: Locator;
+};
+
+/**
+ * A pdf element.
+ */
+export class PDFContentElement extends ContentElement {
+    constructor(
+        locator: Locator,
+        /**
+         * Readable text.
+         */
+        readonly element: PDFReadableElement,
+        attributes: Attribute<any>[] = [],
+    ) { super(locator, attributes); }
+
+    get text(): string | undefined {
+        return this.element.text;
+    }
+}
+
+// Element in a PDF resource page.
+export type PDFReadableElement = {
+    index: number,
+    text: string;
+    readingDirection?: string;
+};
+
+enum Direction {
+    Forward = 1,
+    Backward = -1
+}
+
+// [Element] loaded with [hasPrevious] or [hasNext], associated with the move direction.
+class ElementInDirection {
+    constructor(
+        readonly element: ContentElement,
+        readonly direction: Direction
+    ) {}
+}
+
+/* An iterator which iterates through a whole PDF page provided, 
+    and returns the elements based on a [PDFReadableElement] array. */
+
+// TODO extend Iterator class!
+export class PageContentIteratorPDF extends Iterator{
+    private pageContentFiltered: Array<PDFContentElement> = [];
+    private currentElement: ElementInDirection | null = null;
+    private currentProgression: number = 0;
+    private currentElementIndex: number = 0;
+
+    constructor(
+        /**
+         * The pdf page, represented as array of [TextItem] which will be iterated through.
+         * @param {Array<TextItem>} pageContent - an array that represents the page content of a PDF page.
+         * @param {Locator} startLocator - (optional) the locator of the first element to be read.
+         */
+        private pageContent: Array<TextItem>,
+        private startLocator?: Locator | null | undefined
+    ) { 
+        super();
+        const contentFiltered = this.pageContent.filter(
+            (item: TextItem) => item?.str !== " " && item?.str !== ""
+        ) as Array<TextItem>;
+
+        this.pageContentFiltered = contentFiltered.map((item) => {
+            return new PDFContentElement(item.locator, {
+                index: contentFiltered.indexOf(item),
+                text: item.str,
+                readingDirection: item.dir
+            });
+        });
+
+        if (this.startLocator) {
+            this.currentProgression = this.startLocator?.locations?.progression || 0;
+            this.updateElementIndex();
+        }
+
+        if (this.pageContentFiltered.length > 0) {
+            const index = this.currentElementIndex;
+
+            if (index || index === 0) {
+                this.currentElement = new ElementInDirection(this.pageContentFiltered[index], Direction.Forward);
+            }
+        }
+     }
+
+
+    // Returns the current element to be read.
+    current(): ContentElement | null { 
+        return this.currentElement ? this.currentElement.element : null;
+    }
+
+    async hasPrevious(): Promise<boolean> {
+        this.currentElement?.direction === Direction.Backward;
+        return this.nextIn(Direction.Backward) !== null;
+    }
+
+    previous(): ContentElement {
+        
+        if (!this.currentElement) throw new IllegalStateError("Called next() without a successful call to hasNext() first");
+        
+        this.currentElement = this.nextIn(Direction.Backward);
+
+        if (this.currentElementIndex && this.currentElementIndex > 0) {
+            const newIndex = this.currentElementIndex - 1;
+            this.currentProgression = newIndex / this.pageContentFiltered.length * 100;
+            this.currentElementIndex = newIndex;
+        }
+        
+        return this.currentElement ? 
+            this.currentElement.element : 
+            new PDFContentElement(new Locator( { href : "", type: "" }), { index: -1, text: "" });
+        
+    }
+
+    async hasNext(): Promise<boolean> {
+        this.currentElement?.direction === Direction.Forward;
+        return this.nextIn(Direction.Forward) !== null;
+    }
+
+    next(): ContentElement {
+        
+        this.currentElement = this.nextIn(Direction.Forward);
+        const currentIndex = this.currentElementIndex;
+        if (currentIndex !== null &&
+            currentIndex >= 0 && 
+            currentIndex < this.pageContentFiltered.length - 1) {
+            const newIndex = currentIndex + 1;
+            this.currentProgression = newIndex / (this.pageContentFiltered.length) * 100;
+            this.currentElementIndex = newIndex;
+        }
+    
+        return this.currentElement ? 
+            this.currentElement.element : 
+            new PDFContentElement(new Locator( { href : "", type: "" }), { index: -1, text: "" });
+             
+    }
+
+    private nextIn(direction: Direction): ElementInDirection | null {
+        const index = this.currentElementIndex;
+
+        // If the current progression is out of bounds, return null
+        if(index === null) return null;
+
+        // If the current progression is at the end of the pageContentFiltered array, return null
+        if(index === this.pageContentFiltered.length - 1 && direction === Direction.Forward) return null;
+
+        // If the current progression is at the beginning of the pageContentFiltered array, return null
+        if(index === 0 && direction === Direction.Backward) return null;
+
+        // Get the next element in the pageContentFiltered array
+        const content = this.pageContentFiltered[index + direction];
+
+        if (content) {
+            return new ElementInDirection(content, direction);
+        } else {
+            return null;
+        }
+    }
+
+    /**
+     * Updates the current [PDFReadableElement] position in the pageContentFiltered array
+     * based on the current progression value.
+     */
+    private updateElementIndex(): number | null {
+        if (this.currentProgression === 0) return 0;
+        
+        // return null if the current progression is out of bounds
+        if (this.currentProgression < 0 || this.currentProgression >= 100) return null;
+        
+        // Convert the progression percentage to an index in the pageContentFiltered array
+        return Math.floor(this.currentProgression * this.pageContentFiltered.length / 100);
+    }
+
+}

package/src/publication/services/content/iterators/PublicationContentIterator.ts

@@ -0,0 +1,144 @@
+import { Resource } from "../../../../fetcher/Resource";
+import { Locator } from "../../../Locator";
+import { Publication } from "../../../Publication";
+import { IllegalStateError, Iterator } from "../Iterator";
+import { ContentElement } from "../element";
+
+// Creates a [Content.Iterator] instance for the [Resource], starting from the given [Locator].
+// Returns null if the resource media type is not supported.
+export type ResourceContentIteratorFactory = (resource: Resource, locator: Locator) => Iterator | null;
+
+enum Direction {
+    Forward = 1,
+    Backward = -1
+}
+
+// [Iterator] for a resource, associated with its [index] in the reading order.
+class IndexedIterator {
+    constructor(
+        readonly index: number,
+        readonly iterator: Iterator
+    ) {}
+
+    async nextContentIn(direction: Direction): Promise<ContentElement | null> {
+        return direction === Direction.Forward ? this.iterator.nextOrNull() : this.iterator.previousOrNull();
+    }
+}
+
+// [Element] loaded with [hasPrevious] or [hasNext], associated with the move direction.
+class ElementInDirection {
+    constructor(
+        readonly element: ContentElement,
+        readonly direction: Direction
+    ) {}
+}
+
+type LocatorOrProgression = Locator | number;
+
+// A composite [Content.Iterator] which iterates through a whole [publication] and delegates the
+// iteration inside a given resource to media type-specific iterators.
+export class PublicationContentIterator extends Iterator {
+    private _currentIterator: IndexedIterator | null = null;
+    private currentElement: ElementInDirection | null = null;
+
+    constructor(
+        /**
+         * The [Publication] which will be iterated through.
+         */
+        private publication: Publication,
+        /**
+         * Starting [Locator] in the publication.
+         */
+        private startLocator: Locator | undefined,
+        /**
+         * List of [ResourceContentIteratorFactory] which will be used to create the
+         * iterator for each resource. The factories are tried in order until there's a match.
+         */
+        private resourceContentIteratorFactories: ResourceContentIteratorFactory[]
+    ) { super(); }
+
+
+    async hasPrevious(): Promise<boolean> {
+        this.currentElement = await this.nextIn(Direction.Backward);
+        return this.currentElement !== null;
+    }
+
+    previous(): ContentElement {
+        if(this.currentElement?.direction !== Direction.Backward) throw new IllegalStateError("Called previous() without a successful call to hasPrevious() first");
+        return this.currentElement.element;
+    }
+
+    async hasNext(): Promise<boolean> {
+        this.currentElement = await this.nextIn(Direction.Forward);
+        return this.currentElement !== null;
+    }
+
+    next(): ContentElement {
+        if(this.currentElement?.direction !== Direction.Forward) throw new IllegalStateError("Called next() without a successful call to hasNext() first");
+        return this.currentElement.element;
+    }
+
+    private async nextIn(direction: Direction): Promise<ElementInDirection | null> {
+        const iterator = this.currentIterator;
+        if(!iterator) return null;
+
+        const content = await iterator.nextContentIn(direction);
+        if(!content) {
+            const ni = this.nextIteratorIn(direction, iterator.index);
+            if(!ni) return null;
+            this._currentIterator = ni;
+            return this.nextIn(direction);
+        }
+        return new ElementInDirection(content!, direction);
+    }
+
+    /**
+     * Returns the [Iterator] for the current [Resource] in the reading order.
+     */
+    private get currentIterator(): IndexedIterator | null {
+        if(!this._currentIterator) {
+            this._currentIterator = this.initialIterator();
+        }
+        return this._currentIterator;
+    }
+
+    /**
+     * Returns the first iterator starting at [startLocator] or the beginning of the publication.
+     */
+    private initialIterator(): IndexedIterator | null {
+        const index = this.startLocator ? this.publication.readingOrder.findIndexWithHref(this.startLocator.href) : 0;
+        const locations: LocatorOrProgression = this.startLocator || 0;
+        return this.loadIteratorAt(index, locations) ?? this.nextIteratorIn(Direction.Forward, index);
+    }
+
+    /**
+     * Returns the next resource iterator in the given [direction], starting from [fromIndex].
+     */
+    private nextIteratorIn(direction: Direction, fromIndex: number): IndexedIterator | null {
+        const index = fromIndex + direction;
+        if(index < 0 || index >= this.publication.manifest.readingOrder.items.length) return null;
+        const progression = direction === Direction.Forward ? 0 : 1;
+
+        return this.loadIteratorAt(index, progression) ?? this.nextIteratorIn(direction, index);
+    }
+
+    /**
+     * Loads the iterator at the given [index] in the reading order.
+     * The [location] will be used to compute the starting [Locator] for the iterator.
+     */
+    private loadIteratorAt(index: number, location: LocatorOrProgression): IndexedIterator | null {
+        const link = this.publication.readingOrder.items[index];
+        const locator = typeof location === "number" ? this.publication.manifest.locatorFromLink(link)?.copyWithLocations({
+            progression: location
+        }) : location;
+        if(!locator) return null;
+        const resource = this.publication.get(link);
+
+        for (const factory of this.resourceContentIteratorFactories) {
+            const res = factory(resource, locator);
+            if(res) new IndexedIterator(index, res);
+        }
+
+        return null;
+    }
+}

package/src/publication/services/content/iterators/helpers.ts

@@ -0,0 +1,146 @@
+import { LocatorText } from "../../../Locator";
+
+
+// https://github.com/jhy/jsoup/blob/0b10d516ed8f907f8fb4acb9a0806137a8988d45/src/main/java/org/jsoup/parser/Tag.java#L243
+const inlineTags = [
+    "OBJECT",
+    "BASE",
+    "FONT",
+    "TT",
+    "I",
+    "B",
+    "U",
+    "BIG",
+    "SMALL",
+    "EM",
+    "STRONG",
+    "DFN",
+    "CODE",
+    "SAMP",
+    "KBD",
+    "VAR",
+    "CITE",
+    "ABBR",
+    "TIME",
+    "ACRONYM",
+    "MARK",
+    "RUBY",
+    "RT",
+    "RP",
+    "RTC",
+    "A",
+    "IMG",
+    "BR",
+    "WBR",
+    "MAP",
+    "Q",
+    "SUB",
+    "SUP",
+    "BDO",
+    "IFRAME",
+    "EMBED",
+    "SPAN",
+    "INPUT",
+    "SELECT",
+    "TEXTAREA",
+    "LABEL",
+    "BUTTON",
+    "OPTGROUP",
+    "OPTION",
+    "LEGEND",
+    "DATALIST",
+    "KEYGEN",
+    "OUTPUT",
+    "PROGRESS",
+    "METER",
+    "AREA",
+    "PARAM",
+    "SOURCE",
+    "TRACK",
+    "SUMMARY",
+    "COMMAND",
+    "DEVICE",
+    "BASEFONT",
+    "BGSOUND",
+    "MENUITEM",
+    "DATA",
+    "BDI",
+    "S",
+    "STRIKE",
+    "NOBR",
+    "RB"
+];
+
+export function isInlineTag(n: Node) {
+    return inlineTags.includes(n.nodeName.toUpperCase());
+}
+
+export function srcRelativeToHref(e: Element, base?: string | URL): string | null {
+    const src = e.getAttribute("src");
+    if (!src?.length) return null;
+    try {
+        // TODO use readium util Href class
+        return new URL(src, base).toString();
+    } catch (error) {
+        return src; // This is a temporary solution until we implement the Href utility
+    }
+}
+
+// Inspired by golang's unicode.IsSpace
+const unicodeSpaceRange = `[\\s\\u0085\\u00A0\\u2000-\\u200A\\u2028\\u2029\\u202F\\u205F\\u3000]`;
+const allUnicodeSpace = new RegExp(`^${unicodeSpaceRange}+$`, "g");
+const unicodeSpaceTrim = new RegExp(`^${unicodeSpaceRange}+|${unicodeSpaceRange}+$/g`, "g");
+const unicodeSpaceStart = new RegExp(`^${unicodeSpaceRange}+`, "g");
+const unicodeSpaceEnd = new RegExp(`${unicodeSpaceRange}+$`, "g");
+
+export const isBlank = (s: string | null) =>
+    // Normal spaces, \t, \n, \v, \f, \r, U+0085, U+00A0, U+2000 to U+200A, U+2028, U+2029, U+202F, U+205F, U+3000
+    !s?.length ? true : allUnicodeSpace.test(s);
+
+// Like Go's strings.TrimSpace
+export const trimUnicodeSpace = (s: string) => s.replace(unicodeSpaceTrim, "");
+export const trimUnicodeSpaceStart = (s: string) => s.replace(unicodeSpaceStart, "");
+export const trimUnicodeSpaceEnd = (s: string) => s.replace(unicodeSpaceEnd, "");
+
+export const trimmingTextLocator = (text: string, before: string = ""): LocatorText =>
+    new LocatorText({
+        before: before + (unicodeSpaceStart.exec(text)?.[0] ?? ""),
+        highlight: trimUnicodeSpace(text),
+        after: unicodeSpaceEnd.exec(text)?.[0] ?? "",
+    });
+
+export function elementLanguage(e: HTMLElement | null) {
+    while (e) {
+        let lang = e.getAttribute("lang") 
+        || e.getAttributeNS("http://www.w3.org/1999/xhtml", "lang")
+        || e.getAttributeNS("http://www.w3.org/XML/1998/namespace", "lang");
+        if (lang) return lang;
+        e = e.parentElement;
+    }
+    return null;
+}
+
+// Inspired by JSoup: https://github.com/jhy/jsoup/blob/1762412a28fa7b08ccf71d93fc4c98dc73086e03/src/main/java/org/jsoup/internal/StringUtil.java#L233
+// Slight differing definition of what a whitespace characacter is
+export function appendNormalizedWhitespace(accum: string, text: string): string {
+    const stripLeading = accum.length > 0 && accum[accum.length - 1] === " ";
+    let lastWasWhite = false, reachedNonWhite = false;
+    for (let i = 0; i < text.length; i++) {
+        if (isBlank(text[i])) {
+            if ((stripLeading && !reachedNonWhite) || lastWasWhite) {
+                continue;
+            }
+            accum += " ";
+            lastWasWhite = true;
+        } else {
+            const cp = text.charCodeAt(i);
+            // zero width sp, soft hyphen
+            if (cp !== 8203 && cp !== 173) {
+                accum += text[i];
+                lastWasWhite = false;
+                reachedNonWhite = true;
+            }
+        }
+    }
+    return accum;
+}

package/src/publication/services/content/iterators/index.ts

@@ -0,0 +1,3 @@
+export * from './PublicationContentIterator';
+export * from './PDFTextContentIterator';
+export * from './HTMLResourceContentIterator';

package/src/publication/services/index.ts

@@ -0,0 +1 @@
+export * from './content';

package/src/util/JSONParse.ts

@@ -0,0 +1,31 @@
+/** Parses the given array (or undefined it it's not an array) */
+export function arrayfromJSON(json: any): Array<any> | undefined {
+  return json && json instanceof Array ? json : undefined;
+}
+
+export function arrayfromJSONorString(json: any): Array<any> | undefined {
+  return json && typeof json === 'string' ? [json] : arrayfromJSON(json);
+}
+
+/** Parses the given key and returns a Date (or undefined if it’s not a string) */
+export function datefromJSON(json: any): Date | undefined {
+  return typeof json === 'string' ? new Date(json) : undefined;
+}
+
+/** Parses a numeric value, but returns undefined if it is not a positive number. */
+export function numberfromJSON(json: any): number | undefined {
+  return isNaN(json) ? undefined : json;
+}
+
+/** Parses a numeric value, but returns undefined if it is not a positive number. */
+export function positiveNumberfromJSON(json: any): number | undefined {
+  let num = numberfromJSON(json);
+  return num !== undefined && Math.sign(json) >= 0 ? json : undefined;
+}
+
+/** Converts a Set of a string to a string Array object */
+export function setToArray(obj: Set<string>): Array<string> {
+  const list = new Array<string>();
+  obj.forEach(x => list.push(x));
+  return list;
+}

package/src/util/Language.ts

@@ -0,0 +1,5 @@
+
+export type Language = string;
+
+// TODO full language class
+// https://github.com/readium/kotlin-toolkit/blob/develop/readium/shared/src/main/java/org/readium/r2/shared/util/Language.kt

package/src/util/URITemplate.ts

@@ -0,0 +1,83 @@
+/* Copyright 2021 Readium Foundation. All rights reserved.
+ * Use of this source code is governed by a BSD-style license,
+ * available in the LICENSE file present in the Github repository of the project.
+ */
+
+/** A lightweight implementation of URI Template (RFC 6570).
+ *
+ *  Only handles simple cases, fitting Readium's use cases.
+ *  See https://tools.ietf.org/html/rfc6570
+ */
+export class URITemplate {
+  public uri: string;
+
+  /**
+   * List of URI template parameter keys, if the [Link] is templated.
+   */
+  public parameters: Set<string>;
+
+  constructor(uri: string) {
+    this.uri = uri;
+
+    /** List of URI template parameter keys. */
+    this.parameters = this.getParameters(uri);
+  }
+
+  /**
+   * List of URI template parameter keys, if the [Link] is templated.
+   */
+  private getParameters(uri: string): Set<string> {
+    const regex = /\{\??([^}]+)\}/g;
+    const match = uri.match(regex);
+    if (match) {
+      return new Set(
+        match
+          .join(',')
+          .replace(regex, '$1')
+          .split(',')
+          .map(m => m.trim())
+      );
+    }
+    return new Set();
+  }
+
+  /** Expands the URI by replacing the template variables by the given parameters.
+   *  Any extra parameter is appended as query parameters.
+   *  See RFC 6570 on URI template: https://tools.ietf.org/html/rfc6570
+   */
+  public expand(parameters: { [param: string]: string }): string {
+    const expandSimpleString = (string: string): string => {
+      return string
+        .split(',')
+        .map(parameter => {
+          const parameterValue = parameters[parameter];
+          return parameterValue ? encodeURIComponent(parameterValue) : '';
+        })
+        .join(',');
+    };
+
+    const expandFormStyle = (string: string): string => {
+      return (
+        '?' +
+        string
+          .split(',')
+          .map(expression => {
+            const parameter = expression.split('=')[0];
+            const parameterValue = parameters[parameter];
+            if (parameterValue) {
+              return `${parameter}=${encodeURIComponent(parameterValue)}`;
+            } else {
+              return '';
+            }
+          })
+          .join('&')
+      );
+    };
+
+    return this.uri.replace(/\{(\??)([^}]+)\}/g, (...groups: Array<string>) => {
+      return !groups[1]
+        ? expandSimpleString(groups[2])
+        : expandFormStyle(groups[2]);
+    });
+  }
+}

package/src/util/index.ts

@@ -0,0 +1,5 @@
+export * from './mediatype';
+export * from './JSONParse';
+export * from './URITemplate';
+export * from './Language';
+export * from './tokenizer';