@readium/shared 1.2.0

package/src/publication/opds/Properties.ts

@@ -0,0 +1,84 @@
+import { Copies, Acquisition, Holds, Price, Availability } from '../../opds';
+import { positiveNumberfromJSON } from '../../util/JSONParse';
+import { Link } from '../Link';
+import { Properties } from '../Properties';
+
+// OPDS extensions for link [Properties].
+// https://drafts.opds.io/schema/properties.schema.json
+
+declare module '../Properties' {
+  export interface Properties {
+    /**
+     * Provides a hint about the expected number of items returned.
+     */
+    getNumberOfItems(): number | undefined;
+
+    /**
+     * The price of a publication is tied to its acquisition link.
+     */
+    getPrice(): Price | undefined;
+
+    /**
+     * Indirect acquisition provides a hint for the expected media type that will be acquired after
+     * additional steps.
+     */
+    getIndirectAcquisitions(): Array<Acquisition> | undefined;
+
+    /**
+     * Library-specific features when a specific book is unavailable but provides a hold list.
+     */
+    getHolds(): Holds | undefined;
+
+    /**
+     * Library-specific feature that contains information about the copies that a library has acquired.
+     */
+    getCopies(): Copies | undefined;
+
+    /**
+     * Indicated the availability of a given resource.
+     */
+    getAvailability(): Availability | undefined;
+
+    /**
+     * Indicates that the linked resource supports authentication with the associated Authentication
+     * Document.
+     *
+     * See https://drafts.opds.io/authentication-for-opds-1.0.html
+     */
+    getAuthenticate(): Link | undefined;
+  }
+}
+
+Properties.prototype.getNumberOfItems = function(): number | undefined {
+  return positiveNumberfromJSON(this.otherProperties['numberOfItems']);
+};
+
+Properties.prototype.getPrice = function(): Price | undefined {
+  return Price.deserialize(this.otherProperties['price']);
+};
+
+Properties.prototype.getIndirectAcquisitions = function():
+  | Array<Acquisition>
+  | undefined {
+  const json = this.otherProperties['indirectAcquisition'];
+  if (!(json && json instanceof Array)) return;
+  return json
+    .map<Acquisition>(item => Acquisition.deserialize(item) as Acquisition)
+    .filter(x => x !== undefined);
+};
+
+Properties.prototype.getHolds = function(): Holds | undefined {
+  return Holds.deserialize(this.otherProperties['holds']);
+};
+
+Properties.prototype.getCopies = function(): Copies | undefined {
+  return Copies.deserialize(this.otherProperties['copies']);
+};
+
+Properties.prototype.getAvailability = function(): Availability | undefined {
+  return Availability.deserialize(this.otherProperties['availability']);
+};
+
+Properties.prototype.getAuthenticate = function(): Link | undefined {
+  return Link.deserialize(this.otherProperties['authenticate']);
+};

package/src/publication/opds/Publication.ts

@@ -0,0 +1,14 @@
+import { Links } from '../Link';
+import { Publication } from '../Publication';
+
+// OPDS extensions for [Publication]
+
+declare module '../Publication' {
+  export interface Publication {
+    getImages(): Links | undefined;
+  }
+}
+
+Publication.prototype.getImages = function(): Links | undefined {
+  return this.linksWithRole('images');
+};

package/src/publication/opds/index.ts

@@ -0,0 +1,2 @@
+export * from './Properties';
+export * from './Publication';

package/src/publication/presentation/Metadata.ts

@@ -0,0 +1,19 @@
+import { Metadata } from '../Metadata';
+import { Presentation } from './Presentation';
+
+// Presentation extensions for [Metadata]
+
+declare module '../Metadata' {
+  export interface Metadata {
+    getPresentation(): Presentation | undefined;
+  }
+}
+
+Metadata.prototype.getPresentation = function(): Presentation | undefined {
+  const presentation =
+    this.otherMetadata?.['presentation'] || this.otherMetadata?.['rendition'];
+
+  if (!presentation) return;
+
+  return Presentation.deserialize(presentation);
+};

package/src/publication/presentation/Presentation.ts

@@ -0,0 +1,155 @@
+/* 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.
+ */
+
+import { EPUBLayout } from '../epub/EPUBLayout';
+
+/**
+ * Suggested orientation for the device when displaying the linked resource.
+ */
+export enum Orientation {
+  auto = 'auto',
+  landscape = 'landscape',
+  portrait = 'portrait',
+}
+
+/**
+ * Suggested method for handling overflow while displaying the linked resource.
+ */
+export enum Overflow {
+  auto = 'auto',
+  clipped = 'clipped',
+  paginated = 'paginated',
+  scrolled = 'scrolled',
+}
+
+/**
+ * Indicates how the linked resource should be displayed in a reading environment that displays
+ * synthetic spreads.
+ */
+export enum Page {
+  left = 'left',
+  right = 'right',
+  center = 'center',
+}
+
+/**
+ * Indicates the condition to be met for the linked resource to be rendered within a synthetic
+ * spread.
+ */
+export enum Spread {
+  auto = 'auto',
+  both = 'both',
+  none = 'none',
+  landscape = 'landscape',
+}
+
+/**
+ * Suggested method for constraining a resource inside the viewport.
+ */
+export enum Fit {
+  contain = 'contain',
+  cover = 'cover',
+  width = 'width',
+  height = 'height',
+}
+
+// export interface IPresentationMetadata {
+//   clipped?: boolean;
+//   continuous?: boolean;
+//   fit?: Fit;
+//   orientation?: Orientation;
+//   overflow?: Overflow;
+//   spread?: Spread;
+//   layout?: EpubLayout;
+// }
+
+/** The Presentation Hints extension defines a number of hints for User Agents about the way content
+ *  should be presented to the user.
+ *
+ *  https://readium.org/webpub-manifest/extensions/presentation.html
+ *  https://readium.org/webpub-manifest/schema/extensions/presentation/metadata.schema.json
+ *
+ *  These properties can be undefined to avoid having default values when it doesn't make sense for a
+ *  given `Publication`. If a navigator needs a default value when not specified,
+ *  `Presentation.defaultX` and `Presentation.X.default` can be used.
+ */
+export class Presentation {
+  /** Specifies whether or not the parts of a linked resource that flow out of the viewport are clipped */
+  public clipped?: boolean;
+
+  /** Suggested method for constraining a resource inside the viewport. */
+  public fit?: Fit;
+
+  /** Suggested orientation for the device when displaying the linked resource. */
+  public orientation?: Orientation;
+
+  /** Indicates the condition to be met for the linked resource to be rendered
+   *  within a synthetic spread
+   */
+  public spread?: Spread;
+
+  /** Hint about the nature of the layout for the linked resources (EPUB extension). */
+  public layout?: EPUBLayout;
+
+  /** Indicates how the progression between resources from the [readingOrder] should be handled */
+  public continuous?: boolean;
+
+  /** Indicates if the overflow of linked resources from the `readingOrder` or `resources` should
+   *  be handled using dynamic pagination or scrolling.
+   */
+  public overflow?: Overflow;
+
+  /** Creates a [Presentation]. */
+  constructor(values: {
+    clipped?: boolean;
+    continuous?: boolean;
+    fit?: Fit;
+    orientation?: Orientation;
+    overflow?: Overflow;
+    spread?: Spread;
+    layout?: EPUBLayout;
+  }) {
+    this.clipped = values.clipped;
+    this.fit = values.fit;
+    this.orientation = values.orientation;
+    this.spread = values.spread;
+    this.layout = values.layout;
+    this.continuous = values.continuous;
+    this.overflow = values.overflow;
+  }
+
+  /**
+   * Parses a [Presentation] from its RWPM JSON representation.
+   *
+   */
+  public static deserialize(json: any): Presentation | undefined {
+    if (!json) return;
+
+    return new Presentation({
+      clipped: json.clipped,
+      continuous: json.continuous,
+      fit: json.fit,
+      orientation: json.orientation,
+      overflow: json.overflow,
+      spread: json.spread,
+      layout: json.layout,
+    });
+  }
+
+  /**
+   * Serializes a [Presentation] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = {};
+    if (this.clipped !== undefined) json.clipped = this.clipped;
+    if (this.continuous !== undefined) json.continuous = this.continuous;
+    if (this.fit !== undefined) json.fit = this.fit;
+    if (this.orientation !== undefined) json.orientation = this.orientation;
+    if (this.overflow !== undefined) json.overflow = this.overflow;
+    if (this.spread !== undefined) json.spread = this.spread;
+    if (this.layout !== undefined) json.layout = this.layout;
+    return json;
+  }
+}

package/src/publication/presentation/Properties.ts

@@ -0,0 +1,70 @@
+/* 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.
+ */
+
+// Presentation extensions for link [Properties]
+
+import { Properties } from '../Properties';
+import { Fit, Orientation, Overflow, Page, Spread } from './Presentation';
+
+declare module '../Properties' {
+  export interface Properties {
+    /**
+     * Specifies whether or not the parts of a linked resource that flow out of the viewport are
+     * clipped.
+     */
+    getClipped(): boolean | undefined;
+
+    /**
+     * Suggested method for constraining a resource inside the viewport.
+     */
+    getFit(): Fit | undefined;
+
+    /**
+     * Suggested orientation for the device when displaying the linked resource.
+     */
+    getOrientation(): Orientation | undefined;
+
+    /**
+     * Suggested method for handling overflow while displaying the linked resource.
+     */
+    getOverflow(): Overflow | undefined;
+
+    /**
+     * Indicates how the linked resource should be displayed in a reading environment that displays
+     * synthetic spreads.
+     */
+    getPage(): Page | undefined;
+
+    /**
+     * Indicates the condition to be met for the linked resource to be rendered within a synthetic
+     * spread.
+     */
+    getSpread(): Spread | undefined;
+  }
+}
+
+Properties.prototype.getClipped = function(): boolean | undefined {
+  return this.otherProperties['clipped'];
+};
+
+Properties.prototype.getFit = function(): Fit | undefined {
+  return this.otherProperties['fit'];
+};
+
+Properties.prototype.getOrientation = function(): Orientation | undefined {
+  return this.otherProperties['orientation'];
+};
+
+Properties.prototype.getOverflow = function(): Overflow | undefined {
+  return this.otherProperties['overflow'];
+};
+
+Properties.prototype.getPage = function(): Page | undefined {
+  return this.otherProperties['page'] || undefined;
+};
+
+Properties.prototype.getSpread = function(): Spread | undefined {
+  return this.otherProperties['spread'] || undefined;
+};

package/src/publication/presentation/index.ts

@@ -0,0 +1,3 @@
+export * from './Presentation';
+export * from './Metadata';
+export * from './Properties';

package/src/publication/services/content/Content.ts

@@ -0,0 +1,36 @@
+import { Iterator } from "./Iterator";
+import { ContentElement, TextualElement } from "./element";
+
+/**
+ * Provides an iterable list of content [Element]s.
+ */
+export abstract class Content {
+    /**
+     * Extracts the full raw text, or returns null if no text content can be found.
+     * @param separator Separator to use between individual elements. Defaults to newline.
+     */
+    text(separator: string = "\n"): string | null {
+        return this.elements()
+            .map(element => (element as TextualElement)?.text)
+            .filter(text => text !== undefined && text.length > 0)
+            .join(separator);
+    }
+
+    /**
+     * Creates a new iterator for this content.
+     */
+    abstract iterator(): Iterator;
+
+    /**
+     * Returns all the elements as a list.
+     */
+    elements(): ContentElement[] {
+        const list: ContentElement[] = [];
+        const iterator = this.iterator();
+        while (true) {
+            if(!iterator.hasNext()) break;
+            list.push(iterator.next());
+        }
+        return list;
+    }
+}

package/src/publication/services/content/ContentTokenizer.ts

@@ -0,0 +1,62 @@
+import { DefaultTextContentTokenizer, Range, TextTokenizer, TextUnit, Tokenizer } from "../../../util";
+import { Locator, LocatorText } from "../../Locator";
+import { ContentElement, TextElement, TextSegment } from "./element";
+
+// A tokenizer splitting a [Content.Element] into smaller pieces.
+export type ContentTokenizer  = Tokenizer<ContentElement, ContentElement>;
+
+export class TextContentTokenizer implements ContentTokenizer {
+    /**
+     * 
+     * @param defaultLanguage The default assumed language
+     * @param unit The unit of the produced [Locator]s.
+     * @param contextSnippetLength Length of `before` and `after` snippets in the produced [Locator]s.
+     * @param textTokenizerFactory Factory to create a [TextTokenizer] from, using the specified language and unit.
+     */
+    constructor(
+        private readonly defaultLanguage: string | null,
+        unit: TextUnit,
+        private readonly contextSnippetLength = 50,
+        private readonly textTokenizerFactory: (language: string | null) => TextTokenizer
+            = (language) => DefaultTextContentTokenizer(language, unit)
+    ) {}
+
+    tokenize(data: ContentElement): ContentElement[] {
+        if(data instanceof TextElement) {
+            return [
+                new TextElement(
+                    data.locator,
+                    data.role,
+                    data.segments.map(s => this.tokenizeSegment(s)).flat(), 
+                )
+            ];
+        }
+        return [data];
+    }
+
+    private tokenizeSegment(segment: TextSegment): TextSegment[] {
+        return this.textTokenizerFactory(segment.language ?? this.defaultLanguage)
+            .tokenize(segment.text)
+            .map(range => new TextSegment(
+                new Locator({
+                    href: segment.locator.href,
+                    type: segment.locator.type,
+                    title: segment.locator.title,
+                    locations: segment.locator.locations,
+                    text: this.extractTextContextIn(segment.text, range)
+                }),
+                segment.text.substring(range[0], range[1]),
+                segment._attributes
+            ));
+    }
+
+    private extractTextContextIn(str: string, range: Range): LocatorText {
+        const after = str.substring(range[1], range[1] + this.contextSnippetLength);
+        const before = str.substring(range[0] - this.contextSnippetLength, range[0]);
+        return new LocatorText({
+            after: after.length > 0 ? after : undefined,
+            before: before.length > 0 ? before : undefined,
+            highlight: str.substring(range[0], range[1]),
+        })
+    }
+}

package/src/publication/services/content/Iterator.ts

@@ -0,0 +1,46 @@
+import { ContentElement } from "./element";
+
+export class IllegalStateError extends Error {
+    constructor(message: string) {
+        super(message);
+    }
+}
+
+/**
+ * Iterates through a list of [Element] items asynchronously.
+ * [hasNext] and [hasPrevious] refer to the last element computed by a previous call to any of both methods.
+ */
+export abstract class Iterator {
+    /**
+     * Returns true if the iterator has a next element, suspending the caller while processing it.
+     */
+    abstract hasNext(): Promise<boolean>;
+    /**
+     * Retrieves the element computed by a preceding call to [hasNext], or throws an
+     * [IllegalStateError] if [hasNext] was not invoked. This method should only be used in
+     * pair with [hasNext].
+     */
+    abstract next(): ContentElement;
+    /**
+     * Advances to the next item and returns it, or null if we reached the end.
+     */
+    async nextOrNull(): Promise<ContentElement | null> {
+        return (await this.hasNext()) ? this.next() : null;
+    }
+    /**
+     * Returns true if the iterator has a previous element, suspending the caller while processing it.
+     */
+    abstract hasPrevious(): Promise<boolean>;
+    /**
+     * Retrieves the element computed by a preceding call to [hasPrevious], or throws an
+     * [IllegalStateError] if [hasPrevious] was not invoked. This method should only be used in
+     * pair with [hasPrevious].
+     */
+    abstract previous(): ContentElement;
+    /**
+     * Advances to the previous item and returns it, or null if we reached the beginning.
+     */
+    async previousOrNull(): Promise<ContentElement | null> {
+        return (await this.hasPrevious()) ? this.previous() : null;
+    }
+}

package/src/publication/services/content/element/attributes.ts

@@ -0,0 +1,44 @@
+import { Language } from "../../../../util/Language";
+
+export class Attribute<V> {
+    constructor(
+        public key: AttributeKeys | string,
+        public value: V
+    ) { }
+}
+
+export enum AttributeKeys {
+    ACCESSIBILITY_LABEL = "accessibilityLabel",
+    LANGUAGE = "language",
+}
+
+export abstract class AttributesHolder {
+    constructor(
+        /**
+         * Associated list of attributes.
+         */
+        readonly _attributes: Attribute<any>[] = []
+    ) {}
+
+    get language(): Language | undefined {
+        return this.attribute(AttributeKeys.LANGUAGE);
+    }
+
+    get accessibilityLabel(): string | undefined {
+        return this.attribute(AttributeKeys.ACCESSIBILITY_LABEL);
+    }
+
+    /**
+     * Gets the first attribute with the given [key].
+     */
+    attribute<V>(key: AttributeKeys | string): V | undefined {
+        return this._attributes.find(attribute => attribute.key === key)?.value;
+    }
+
+    /**
+     * Gets all the attributes with the given [key].
+     */
+    attributes<V>(key: AttributeKeys | string): V[] {
+        return this._attributes.filter(attribute => attribute.key === key).map(attribute => attribute.value);
+    }
+}

package/src/publication/services/content/element/element.ts

@@ -0,0 +1,118 @@
+import { Link } from "../../../Link";
+import { Locator } from "../../../Locator";
+import { AttributesHolder, Attribute } from "./attributes";
+import { TextRole } from "./text_role";
+
+/**
+ * Represents a single semantic content element part of a publication.
+ * NOTE: This is named "Element" in other toolkits. This conflicts with the JavaScript `Element` type so it's been renamed.
+ */
+export abstract class ContentElement extends AttributesHolder {
+    constructor(public readonly locator: Locator, attributes: Attribute<any>[] = []) {
+        super(attributes);
+    }
+}
+
+/**
+ * An element which can be represented as human-readable text.
+ * The default implementation returns the first accessibility label associated to the element.
+ */
+export class TextualElement extends ContentElement {
+    /**
+     * Human-readable text representation for this element.
+     */
+    get text(): string | undefined {
+        return this.accessibilityLabel;
+    }
+}
+
+/**
+ *  An element referencing an embedded external resource.
+ */
+export interface EmbeddedElement extends ContentElement {
+    /**
+     * Referenced resource in the publication.
+     */
+    readonly embeddedLink: Link;
+}
+
+/**
+ * An audio clip.
+ */
+export class AudioElement extends TextualElement implements EmbeddedElement {
+    constructor(
+        locator: Locator,
+        readonly embeddedLink: Link,
+        attributes: Attribute<any>[] = [],
+    ) { super(locator, attributes); }
+}
+
+/**
+ * A video clip.
+ */
+export class VideoElement extends TextualElement implements EmbeddedElement {
+    constructor(
+        locator: Locator,
+        readonly embeddedLink: Link,
+        attributes: Attribute<any>[] = [],
+    ) { super(locator, attributes); }
+}
+
+/**
+ * A bitmap image.
+ */
+export class ImageElement extends TextualElement implements EmbeddedElement {
+    constructor(
+        locator: Locator,
+        readonly embeddedLink: Link,
+        /**
+         * Short piece of text associated with the image.
+         */
+        readonly caption?: string,
+        attributes: Attribute<any>[] = [],
+    ) { super(locator, attributes); }
+
+    get text(): string | undefined {
+        // The caption might be a better text description than the accessibility label, when available.
+        return (this.caption?.length || 0) > 0 ? this.caption : super.text;
+    }
+}
+
+export class TextSegment extends AttributesHolder {
+    constructor(
+        /**
+         * Locator to the segment of text.
+         */
+        readonly locator: Locator,
+        /**
+         * Text in the segment.
+         */
+        readonly text: string,
+        /**
+         * Attributes associated with this segment, e.g. language.
+         */
+        attributes: Attribute<any>[] = [],
+    ) { super(attributes); }
+}
+
+/**
+ * A text element.
+ */
+export class TextElement extends TextualElement {
+    constructor(
+        locator: Locator,
+        /**
+         * Purpose of this element in the broader context of the document.
+         */
+        readonly role: TextRole,
+        /**
+         * Ranged portions of text with associated attributes.
+         */
+        readonly segments: TextSegment[],
+        attributes: Attribute<any>[] = [],
+    ) { super(locator, attributes); }
+
+    get text(): string | undefined {
+        return this.segments.map(segment => segment.text).join("");
+    }
+}

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

@@ -0,0 +1,3 @@
+export * from './element';
+export * from './attributes';
+export * from './text_role';