@readium/shared 1.2.0

package/types/src/publication/html/DomRangePoint.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A serializable representation of a boundary point in a DOM Range.
+ *
+ * The [cssSelector] field always references a DOM element. If the original DOM Range
+ * start/endContainer property references a DOM text node, the [textNodeIndex] field is used to
+ * complement the CSS Selector; thereby providing a pointer to a child DOM text node; and
+ * [charOffset] is used to tell a position within the character data of that DOM text node
+ * (just as the DOM Range start/endOffset does). If the original DOM Range start/endContainer
+ * property references a DOM Element, then the [textNodeIndex] field is used to designate the
+ * child Text node (just as the DOM Range start/endOffset does), and the optional [charOffset]
+ * field is not used (as there is no explicit position within the character data of the text
+ * node).
+ *
+ * https://github.com/readium/architecture/blob/master/models/locators/extensions/html.md#the-start-and-end-object
+ */
+export declare class DomRangePoint {
+    cssSelector: string;
+    textNodeIndex: number;
+    charOffset?: number;
+    /**
+     * Creates a [DomRange].
+     */
+    constructor(values: {
+        cssSelector: string;
+        textNodeIndex: number;
+        charOffset?: number;
+    });
+    /**
+     * Parses a [DomRangePoint] from its RWPM JSON representation.
+     */
+    static deserialize(json: any): DomRangePoint | undefined;
+    /**
+     * Serializes a [DomRangePoint] to its RWPM JSON representation.
+     */
+    serialize(): any;
+}

package/types/src/publication/html/Locations.d.ts

@@ -0,0 +1,45 @@
+import { DomRange } from './DomRange';
+declare module '../Locator' {
+    interface LocatorLocations {
+        /**
+         * A CSS Selector.
+         */
+        getCssSelector(): string | undefined;
+        /**
+         * [partialCfi] is an expression conforming to the "right-hand" side of the EPUB CFI syntax, that is
+         * to say: without the EPUB-specific OPF spine item reference that precedes the first ! exclamation
+         * mark (which denotes the "step indirection" into a publication document). Note that the wrapping
+         * epubcfi(***) syntax is not used for the [partialCfi] string, i.e. the "fragment" part of the CFI
+         * grammar is ignored.
+         */
+        getPartialCfi(): string | undefined;
+        /**
+         * An HTML DOM range.
+         */
+        getDomRange(): DomRange | undefined;
+        /**
+         * All named parameters found in the fragments, such as `p=5`.
+         */
+        fragmentParameters(): Map<string, string>;
+        /**
+         * HTML ID fragment identifier.
+         */
+        htmlId(): string | undefined;
+        /**
+         * Page fragment identifier, used for example in PDF.
+         */
+        page(): number | undefined;
+        /**
+         * Temporal Dimension media fragment, used for example in audiobooks.
+         *
+         * https://www.w3.org/TR/media-frags/
+         */
+        time(): number | undefined;
+        /**
+         * Spatial Dimension media fragment, used for example in audiobooks.
+         *
+         * https://www.w3.org/TR/media-frags/
+         */
+        space(): [number, number, number, number] | undefined;
+    }
+}

package/types/src/publication/html/index.d.ts

@@ -0,0 +1,3 @@
+export * from './DomRange';
+export * from './DomRangePoint';
+export * from './Locations';

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

@@ -0,0 +1,19 @@
+export * from './encryption';
+export * from './epub';
+export * from './html';
+export * from './opds';
+export * from './presentation';
+export * from './BelongsTo';
+export * from './Contributor';
+export * from './Link';
+export * from './LocalizedString';
+export * from './Locator';
+export * from './LocatorCollection';
+export * from './Manifest';
+export * from './Metadata';
+export * from './Properties';
+export * from './Publication';
+export * from './PublicationCollection';
+export * from './ReadingProgression';
+export * from './Subject';
+export * from './GuidedNavigation';

package/types/src/publication/opds/Properties.d.ts

@@ -0,0 +1,38 @@
+import { Copies, Acquisition, Holds, Price, Availability } from '../../opds';
+import { Link } from '../Link';
+declare module '../Properties' {
+    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;
+    }
+}

package/types/src/publication/opds/Publication.d.ts

@@ -0,0 +1,6 @@
+import { Links } from '../Link';
+declare module '../Publication' {
+    interface Publication {
+        getImages(): Links | undefined;
+    }
+}

package/types/src/publication/opds/index.d.ts

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

package/types/src/publication/presentation/Metadata.d.ts

@@ -0,0 +1,6 @@
+import { Presentation } from './Presentation';
+declare module '../Metadata' {
+    interface Metadata {
+        getPresentation(): Presentation | undefined;
+    }
+}

package/types/src/publication/presentation/Presentation.d.ts

@@ -0,0 +1,95 @@
+import { EPUBLayout } from '../epub/EPUBLayout';
+/**
+ * Suggested orientation for the device when displaying the linked resource.
+ */
+export declare enum Orientation {
+    auto = "auto",
+    landscape = "landscape",
+    portrait = "portrait"
+}
+/**
+ * Suggested method for handling overflow while displaying the linked resource.
+ */
+export declare 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 declare 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 declare enum Spread {
+    auto = "auto",
+    both = "both",
+    none = "none",
+    landscape = "landscape"
+}
+/**
+ * Suggested method for constraining a resource inside the viewport.
+ */
+export declare enum Fit {
+    contain = "contain",
+    cover = "cover",
+    width = "width",
+    height = "height"
+}
+/** 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 declare class Presentation {
+    /** Specifies whether or not the parts of a linked resource that flow out of the viewport are clipped */
+    clipped?: boolean;
+    /** Suggested method for constraining a resource inside the viewport. */
+    fit?: Fit;
+    /** Suggested orientation for the device when displaying the linked resource. */
+    orientation?: Orientation;
+    /** Indicates the condition to be met for the linked resource to be rendered
+     *  within a synthetic spread
+     */
+    spread?: Spread;
+    /** Hint about the nature of the layout for the linked resources (EPUB extension). */
+    layout?: EPUBLayout;
+    /** Indicates how the progression between resources from the [readingOrder] should be handled */
+    continuous?: boolean;
+    /** Indicates if the overflow of linked resources from the `readingOrder` or `resources` should
+     *  be handled using dynamic pagination or scrolling.
+     */
+    overflow?: Overflow;
+    /** Creates a [Presentation]. */
+    constructor(values: {
+        clipped?: boolean;
+        continuous?: boolean;
+        fit?: Fit;
+        orientation?: Orientation;
+        overflow?: Overflow;
+        spread?: Spread;
+        layout?: EPUBLayout;
+    });
+    /**
+     * Parses a [Presentation] from its RWPM JSON representation.
+     *
+     */
+    static deserialize(json: any): Presentation | undefined;
+    /**
+     * Serializes a [Presentation] to its RWPM JSON representation.
+     */
+    serialize(): any;
+}

package/types/src/publication/presentation/Properties.d.ts

@@ -0,0 +1,32 @@
+import { Fit, Orientation, Overflow, Page, Spread } from './Presentation';
+declare module '../Properties' {
+    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;
+    }
+}

package/types/src/publication/presentation/index.d.ts

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

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

@@ -0,0 +1,20 @@
+import { Iterator } from "./Iterator";
+import { ContentElement } from "./element";
+/**
+ * Provides an iterable list of content [Element]s.
+ */
+export declare 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): string | null;
+    /**
+     * Creates a new iterator for this content.
+     */
+    abstract iterator(): Iterator;
+    /**
+     * Returns all the elements as a list.
+     */
+    elements(): ContentElement[];
+}

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

@@ -0,0 +1,19 @@
+import { TextTokenizer, TextUnit, Tokenizer } from "../../../util";
+import { ContentElement } from "./element";
+export type ContentTokenizer = Tokenizer<ContentElement, ContentElement>;
+export declare class TextContentTokenizer implements ContentTokenizer {
+    private readonly defaultLanguage;
+    private readonly contextSnippetLength;
+    private readonly textTokenizerFactory;
+    /**
+     *
+     * @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(defaultLanguage: string | null, unit: TextUnit, contextSnippetLength?: number, textTokenizerFactory?: (language: string | null) => TextTokenizer);
+    tokenize(data: ContentElement): ContentElement[];
+    private tokenizeSegment;
+    private extractTextContextIn;
+}

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

@@ -0,0 +1,38 @@
+import { ContentElement } from "./element";
+export declare class IllegalStateError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare 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.
+     */
+    nextOrNull(): Promise<ContentElement | 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.
+     */
+    previousOrNull(): Promise<ContentElement | null>;
+}

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

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

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

@@ -0,0 +1,107 @@
+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 declare abstract class ContentElement extends AttributesHolder {
+    readonly locator: Locator;
+    constructor(locator: Locator, attributes?: Attribute<any>[]);
+}
+/**
+ * An element which can be represented as human-readable text.
+ * The default implementation returns the first accessibility label associated to the element.
+ */
+export declare class TextualElement extends ContentElement {
+    /**
+     * Human-readable text representation for this element.
+     */
+    get text(): string | undefined;
+}
+/**
+ *  An element referencing an embedded external resource.
+ */
+export interface EmbeddedElement extends ContentElement {
+    /**
+     * Referenced resource in the publication.
+     */
+    readonly embeddedLink: Link;
+}
+/**
+ * An audio clip.
+ */
+export declare class AudioElement extends TextualElement implements EmbeddedElement {
+    readonly embeddedLink: Link;
+    constructor(locator: Locator, embeddedLink: Link, attributes?: Attribute<any>[]);
+}
+/**
+ * A video clip.
+ */
+export declare class VideoElement extends TextualElement implements EmbeddedElement {
+    readonly embeddedLink: Link;
+    constructor(locator: Locator, embeddedLink: Link, attributes?: Attribute<any>[]);
+}
+/**
+ * A bitmap image.
+ */
+export declare class ImageElement extends TextualElement implements EmbeddedElement {
+    readonly embeddedLink: Link;
+    /**
+     * Short piece of text associated with the image.
+     */
+    readonly caption?: string | undefined;
+    constructor(locator: Locator, embeddedLink: Link, 
+    /**
+     * Short piece of text associated with the image.
+     */
+    caption?: string | undefined, attributes?: Attribute<any>[]);
+    get text(): string | undefined;
+}
+export declare class TextSegment extends AttributesHolder {
+    /**
+     * Locator to the segment of text.
+     */
+    readonly locator: Locator;
+    /**
+     * Text in the segment.
+     */
+    readonly text: string;
+    constructor(
+    /**
+     * Locator to the segment of text.
+     */
+    locator: Locator, 
+    /**
+     * Text in the segment.
+     */
+    text: string, 
+    /**
+     * Attributes associated with this segment, e.g. language.
+     */
+    attributes?: Attribute<any>[]);
+}
+/**
+ * A text element.
+ */
+export declare class TextElement extends TextualElement {
+    /**
+     * Purpose of this element in the broader context of the document.
+     */
+    readonly role: TextRole;
+    /**
+     * Ranged portions of text with associated attributes.
+     */
+    readonly segments: TextSegment[];
+    constructor(locator: Locator, 
+    /**
+     * Purpose of this element in the broader context of the document.
+     */
+    role: TextRole, 
+    /**
+     * Ranged portions of text with associated attributes.
+     */
+    segments: TextSegment[], attributes?: Attribute<any>[]);
+    get text(): string | undefined;
+}

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

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

package/types/src/publication/services/content/element/text_role.d.ts

@@ -0,0 +1,53 @@
+export type Role = "heading-1" | "heading-2" | "heading-3" | "heading-4" | "heading-5" | "heading-6" | "body" | "footnote" | "quote";
+/**
+ * Represents a purpose of an element in the broader context of the document.
+ */
+export interface TextRole {
+    get role(): Role;
+}
+/**
+ * Title of a section.
+ */
+export declare class Heading implements TextRole {
+    /**
+     * Heading importance, 1 being the highest.
+     */
+    readonly level: number;
+    constructor(
+    /**
+     * Heading importance, 1 being the highest.
+     */
+    level: number);
+    get role(): Role;
+}
+/**
+ * Normal body of content.
+ */
+export declare const Body: TextRole;
+/**
+ * A footnote at the bottom of a document.
+ */
+export declare const Footnote: TextRole;
+/**
+ * A quotation.
+ */
+export declare class TextQuote implements TextRole {
+    /**
+     * URL to the source for this quote.
+     */
+    readonly referenceUrl: URL | undefined;
+    /**
+     * Name of the source for this quote.
+     */
+    readonly referenceTitle: string | undefined;
+    readonly role: Role;
+    constructor(
+    /**
+     * URL to the source for this quote.
+     */
+    referenceUrl: URL | undefined, 
+    /**
+     * Name of the source for this quote.
+     */
+    referenceTitle: string | undefined);
+}

package/types/src/publication/services/content/index.d.ts

@@ -0,0 +1,5 @@
+export * from './Content';
+export * from './ContentTokenizer';
+export * from './Iterator';
+export * from './element';
+export * from './iterators';

package/types/src/publication/services/content/iterators/HTMLResourceContentIterator.d.ts

@@ -0,0 +1,30 @@
+import { Resource } from "../../../../fetcher/Resource";
+import { Locator } from "../../../Locator";
+import { Iterator } from "../Iterator";
+import { ContentElement } from "../element";
+/**
+ * Iterates an HTML [resource], starting from the given [locator].
+ *
+ * If you want to start mid-resource, the [locator] must contain a `cssSelector` key in its
+ * [Locator.Locations] object.
+ *
+ * If you want to start from the end of the resource, the [locator] must have a `progression` of 1.0.
+ *
+ * Locators will contain a `before` context of up to `beforeMaxLength` characters.
+ */
+export declare class HTMLResourceContentIterator extends Iterator {
+    private resource;
+    private locator;
+    private beforeMaxLength;
+    private currentElement;
+    constructor(resource: Resource, locator: Locator, beforeMaxLength?: number);
+    hasPrevious(): Promise<boolean>;
+    previous(): ContentElement;
+    hasNext(): Promise<boolean>;
+    next(): ContentElement;
+    private currentIndex;
+    private parsedElementRecipes;
+    private elements;
+    private parser;
+    private parseElements;
+}

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

@@ -0,0 +1,60 @@
+import { Locator } from "../../../Locator";
+import { Attribute, ContentElement } from "../element";
+import { Iterator } from "../Iterator";
+type TextItem = {
+    str: string;
+    dir: string;
+    locator: Locator;
+};
+/**
+ * A pdf element.
+ */
+export declare class PDFContentElement extends ContentElement {
+    /**
+     * Readable text.
+     */
+    readonly element: PDFReadableElement;
+    constructor(locator: Locator, 
+    /**
+     * Readable text.
+     */
+    element: PDFReadableElement, attributes?: Attribute<any>[]);
+    get text(): string | undefined;
+}
+export type PDFReadableElement = {
+    index: number;
+    text: string;
+    readingDirection?: string;
+};
+export declare class PageContentIteratorPDF extends Iterator {
+    /**
+     * 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;
+    private startLocator?;
+    private pageContentFiltered;
+    private currentElement;
+    private currentProgression;
+    private currentElementIndex;
+    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.
+     */
+    pageContent: Array<TextItem>, startLocator?: Locator | null | undefined);
+    current(): ContentElement | null;
+    hasPrevious(): Promise<boolean>;
+    previous(): ContentElement;
+    hasNext(): Promise<boolean>;
+    next(): ContentElement;
+    private nextIn;
+    /**
+     * Updates the current [PDFReadableElement] position in the pageContentFiltered array
+     * based on the current progression value.
+     */
+    private updateElementIndex;
+}
+export {};