@readium/shared 1.2.0

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

@@ -0,0 +1,101 @@
+/**
+ * One or more alternative expressions of the location.
+ * https://github.com/readium/architecture/tree/master/models/locators#the-location-object
+ */
+export declare class LocatorLocations {
+    /** Contains one or more fragment in the resource referenced by the `Locator`. */
+    readonly fragments: Array<string>;
+    /** Progression in the resource expressed as a percentage (between 0 and 1). */
+    readonly progression?: number;
+    /** Progression in the publication expressed as a percentage (between 0 and 1). */
+    readonly totalProgression?: number;
+    /** An index in the publication (>= 1).*/
+    readonly position?: number;
+    /** Additional locations for extensions. */
+    readonly otherLocations?: Map<string, any>;
+    /**
+     * Creates a [Locations].
+     */
+    constructor(values: {
+        fragments?: Array<string>;
+        progression?: number;
+        totalProgression?: number;
+        position?: number;
+        otherLocations?: Map<string, any>;
+    });
+    /**
+     * Parses a [Locations] from its RWPM JSON representation.
+     */
+    static deserialize(json: any): LocatorLocations | undefined;
+    /**
+     * Serializes a [Locations] to its RWPM JSON representation.
+     */
+    serialize(): any;
+}
+export declare class LocatorText {
+    readonly after?: string;
+    readonly before?: string;
+    readonly highlight?: string;
+    /**
+     * Creates a [Text].
+     */
+    constructor(values: {
+        after?: string;
+        before?: string;
+        highlight?: string;
+    });
+    /**
+     * Parses a [Locations] from its RWPM JSON representation.
+     */
+    static deserialize(json: any): LocatorText | undefined;
+    /**
+     * Serializes a [Locations] to its RWPM JSON representation.
+     */
+    serialize(): any;
+}
+/**
+ * Provides a precise location in a publication in a format that can be stored and shared.
+ *
+ * There are many different use cases for locators:
+ *  - getting back to the last position in a publication
+ *  - bookmarks
+ *  - highlights & annotations
+ *  - search results
+ *  - human-readable (and shareable) reference in a publication
+ *
+ * https://github.com/readium/architecture/tree/master/locators
+ */
+export declare class Locator {
+    /** The URI of the resource that the Locator Object points to. */
+    readonly href: string;
+    /** The media type of the resource that the Locator Object points to. */
+    readonly type: string;
+    /** The title of the chapter or section which is more relevant in the context of this locator. */
+    readonly title?: string;
+    /** One or more alternative expressions of the location. */
+    readonly locations: LocatorLocations;
+    /** Textual context of the locator. */
+    readonly text?: LocatorText;
+    /**
+     * Creates a [Locator].
+     */
+    constructor(values: {
+        href: string;
+        type: string;
+        title?: string;
+        locations?: LocatorLocations;
+        text?: LocatorText;
+    });
+    /**
+     * Parses a [Link] from its RWPM JSON representation.
+     */
+    static deserialize(json: any): Locator | undefined;
+    /**
+     * Serializes a [Link] to its RWPM JSON representation.
+     */
+    serialize(): any;
+    /**
+     * Shortcut to get a copy of the [Locator] with different [Locations] sub-properties.
+     */
+    copyWithLocations(values: any): Locator;
+}

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

@@ -0,0 +1,54 @@
+import { Links } from './Link';
+import { LocalizedString } from './LocalizedString';
+import { Locator } from './Locator';
+/**
+ * Holds the metadata of a `LocatorCollection`.
+ */
+export declare class LocatorCollectionMetadata {
+    title?: LocalizedString;
+    /** numberOfItems Indicates the total number of locators in the collection. */
+    numberOfItems?: number;
+    otherMetadata?: Map<string, any>;
+    /**
+     * Creates a [LocatorMetadata].
+     */
+    constructor(values: {
+        title?: LocalizedString;
+        numberOfItems?: number;
+        otherMetadata?: Map<string, any>;
+    });
+    /**
+     * Parses a [LocatorMetadata] from its RWPM JSON representation.
+     */
+    static deserialize(json: any): LocatorCollectionMetadata | undefined;
+    /**
+     * Serializes a [LocatorMetadata] to its RWPM JSON representation.
+     */
+    serialize(): any;
+}
+/**
+ * Represents a sequential list of `Locator` objects.
+ *
+ * For example, a search result or a list of positions.
+ */
+export declare class LocatorCollection {
+    metadata: LocatorCollectionMetadata;
+    links: Links;
+    locators: Array<Locator>;
+    /**
+     * Creates a [LocatorCollection].
+     */
+    constructor(values: {
+        metadata?: LocatorCollectionMetadata;
+        links?: Links;
+        locators?: Array<Locator>;
+    });
+    /**
+     * Parses a [LocatorCollection] from its RWPM JSON representation.
+     */
+    static deserialize(json: any): LocatorCollection | undefined;
+    /**
+     * Serializes a [LocatorCollection] to its RWPM JSON representation.
+     */
+    serialize(): any;
+}

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

@@ -0,0 +1,59 @@
+import { Metadata } from './Metadata';
+import { Link, Links } from './Link';
+import { PublicationCollection } from './PublicationCollection';
+import { Locator } from "./Locator";
+/** Holds the metadata of a Readium publication, as described in
+ *  the Readium Web Publication Manifest.
+ *  See. https://readium.org/webpub-manifest/
+ */
+export declare class Manifest {
+    readonly context?: Array<string>;
+    readonly metadata: Metadata;
+    readonly links: Links;
+    /** Identifies a list of resources in reading order for the publication. */
+    readonly readingOrder: Links;
+    /** Identifies resources that are necessary for rendering the publication. */
+    readonly resources?: Links;
+    /** Identifies the collection that contains a table of contents. */
+    readonly tableOfContents?: Links;
+    readonly subcollections?: Map<string, Array<PublicationCollection>>;
+    constructor(values: {
+        context?: Array<string>;
+        metadata: Metadata;
+        links: Links;
+        readingOrder: Links;
+        resources?: Links;
+        tableOfContents?: Links;
+        subcollections?: Map<string, Array<PublicationCollection>>;
+    });
+    /**
+     * Parses a [Publication] from its RWPM JSON representation.
+     *
+     * https://readium.org/webpub-manifest/
+     * https://readium.org/webpub-manifest/schema/publication.schema.json
+     */
+    static deserialize(json: any): Manifest | undefined;
+    /**
+     * Serializes a [Publication] to its RWPM JSON representation.
+     */
+    serialize(): any;
+    /** Finds the first link with the given relation in the manifest's links. */
+    linkWithRel(rel: string): Link | undefined;
+    /** Finds all the links with the given relation in the manifest's links. */
+    linksWithRel(rel: string): Array<Link>;
+    /**
+     * Creates a new [Locator] object from a [Link] to a resource of this manifest.
+     * Returns null if the resource is not found in this manifest.
+     */
+    locatorFromLink(link: Link): Locator | undefined;
+    /** Finds the first Link having the given `href` in the publication's links. */
+    linkWithHref(href: string): Link | undefined;
+    /** The URL where this publication is served, computed from the `Link` with `self` relation.
+     *  e.g. https://provider.com/pub1293/manifest.json gives https://provider.com/pub1293/
+     */
+    get baseURL(): string | undefined;
+    /**
+     * Sets the URL where this [Publication]'s RWPM manifest is served.
+     */
+    setSelfLink(href: string): void;
+}

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

@@ -0,0 +1,101 @@
+import { BelongsTo } from './BelongsTo';
+import { Contributors } from './Contributor';
+import { LocalizedString } from './LocalizedString';
+import { ReadingProgression } from './ReadingProgression';
+import { Subjects } from './Subject';
+/**
+ * https://readium.org/webpub-manifest/schema/metadata.schema.json
+ *
+ * readingProgression : This contains the reading progression as declared in the
+ *     publication, so it might be [auto]. To lay out the content, use [effectiveReadingProgression]
+ *     to get the calculated reading progression from the declared direction and the language.
+ * otherMetadata Additional metadata for extensions, as a JSON dictionary.
+ */
+export declare class Metadata {
+    title: LocalizedString;
+    typeUri?: string;
+    identifier?: string;
+    subtitle?: LocalizedString;
+    sortAs?: LocalizedString;
+    artists?: Contributors;
+    authors?: Contributors;
+    colorists?: Contributors;
+    contributors?: Contributors;
+    editors?: Contributors;
+    illustrators?: Contributors;
+    inkers?: Contributors;
+    letterers?: Contributors;
+    narrators?: Contributors;
+    pencilers?: Contributors;
+    translators?: Contributors;
+    languages?: Array<string>;
+    description?: string;
+    publishers?: Contributors;
+    imprints?: Contributors;
+    published?: Date;
+    modified?: Date;
+    subjects?: Subjects;
+    belongsTo?: BelongsTo;
+    belongsToCollections?: Contributors;
+    belongsToSeries?: Contributors;
+    readingProgression?: ReadingProgression;
+    duration?: number;
+    numberOfPages?: number;
+    otherMetadata?: {
+        [key: string]: any;
+    };
+    /**All metadata not in otherMetadata */
+    private static readonly mappedProperties;
+    /** Creates [Metadata] object */
+    constructor(values: {
+        title: LocalizedString;
+        typeUri?: string;
+        identifier?: string;
+        subtitle?: LocalizedString;
+        sortAs?: LocalizedString;
+        artists?: Contributors;
+        authors?: Contributors;
+        colorists?: Contributors;
+        contributors?: Contributors;
+        editors?: Contributors;
+        illustrators?: Contributors;
+        inkers?: Contributors;
+        letterers?: Contributors;
+        narrators?: Contributors;
+        pencilers?: Contributors;
+        translators?: Contributors;
+        languages?: Array<string>;
+        description?: string;
+        publishers?: Contributors;
+        imprints?: Contributors;
+        published?: Date;
+        modified?: Date;
+        subjects?: Subjects;
+        belongsTo?: BelongsTo;
+        belongsToCollections?: Contributors;
+        belongsToSeries?: Contributors;
+        readingProgression?: ReadingProgression;
+        duration?: number;
+        numberOfPages?: number;
+        otherMetadata?: {
+            [key: string]: any;
+        };
+    });
+    /**
+     * Parses a [Metadata] from its RWPM JSON representation.
+     *
+     * If the metadata can't be parsed, a warning will be logged with [warnings].
+     */
+    static deserialize(json: any): Metadata | undefined;
+    /**
+     * Serializes a [Metadata] to its RWPM JSON representation.
+     */
+    serialize(): any;
+    /**
+     * Computes a [ReadingProgression] when the value of [readingProgression] is set to
+     * auto, using the publication language.
+     *
+     * See this issue for more details: https://github.com/readium/architecture/issues/113
+     */
+    get effectiveReadingProgression(): ReadingProgression;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Properties associated to the linked resource.
+ *
+ * This is opened for extensions.
+ * https://readium.org/webpub-manifest/schema/link.schema.json
+ */
+export declare class Properties {
+    otherProperties: {
+        [key: string]: any;
+    };
+    constructor(values: {
+        [key: string]: any;
+    });
+    /**
+     * Creates a [Properties] from its RWPM JSON representation.
+     */
+    static deserialize(json: any): Properties | undefined;
+    /**
+     * Serializes a [Properties] to its RWPM JSON representation.
+     */
+    serialize(): any;
+    /**
+     * Makes a copy of this [Properties] after merging in the given additional other [properties].
+     */
+    add(properties: {
+        [key: string]: any;
+    }): Properties;
+}

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

@@ -0,0 +1,53 @@
+import { Link, Links } from './Link';
+import { Locator } from './Locator';
+import { Manifest } from './Manifest';
+import { Metadata } from './Metadata';
+import { Fetcher } from '../fetcher/Fetcher';
+import { PublicationCollection } from './PublicationCollection';
+import { Resource } from '../fetcher/Resource';
+import { GuidedNavigationDocument } from "./GuidedNavigation";
+export type ServiceFactory = () => null;
+/** Shared model for a Readium Publication. */
+export declare class Publication {
+    /** The manifest holding the publication metadata extracted from the publication file */
+    manifest: Manifest;
+    private readonly fetcher;
+    readonly context?: Array<string>;
+    readonly metadata: Metadata;
+    readonly links: Links;
+    /** Identifies a list of resources in reading order for the publication. */
+    readonly readingOrder: Links;
+    /** Identifies resources that are necessary for rendering the publication. */
+    readonly resources?: Links;
+    /** Identifies the collection that contains a table of contents. */
+    readonly tableOfContents?: Links;
+    /** Identifies the collection that contains sub collections. */
+    readonly subcollections?: Map<string, Array<PublicationCollection>>;
+    constructor(values: {
+        manifest: Manifest;
+        fetcher?: Fetcher;
+    });
+    /** The URL where this publication is served, computed from the `Link` with `self` relation.
+     *  e.g. https://provider.com/pub1293/manifest.json gives https://provider.com/pub1293/
+     */
+    get baseURL(): string | undefined;
+    /** Finds the first Link having the given `href` in the publication's links. */
+    linkWithHref(href: string): Link | undefined;
+    /**
+     * Returns the [links] of the first child [PublicationCollection] with the given role, or an
+     * empty list.
+     */
+    linksWithRole(role: string): Links | undefined;
+    /** Finds all the links with the given relation in the publication's links. */
+    linksWithRel(rel: string): Array<Link>;
+    /**
+     * Finds the first [Link] having the given [rel] in the publications's links.
+     */
+    linkWithRel(rel: string): Link | undefined;
+    positionsFromManifest(): Promise<Locator[]>;
+    guideForLink(link: Link): Promise<GuidedNavigationDocument | undefined>;
+    /**
+     * Returns the resource targeted by the given non-templated [link].
+     */
+    get(link: Link): Resource;
+}

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

@@ -0,0 +1,34 @@
+import { Links } from './Link';
+/**
+ * Core Collection Model
+ *
+ * https://readium.org/webpub-manifest/schema/subcollection.schema.json
+ * Can be used as extension point in the Readium Web Publication Manifest.
+ */
+export declare class PublicationCollection {
+    metadata?: Map<string, any>;
+    links: Links;
+    subcollections?: Map<string, Array<PublicationCollection>>;
+    /**
+     * Creates a [PublicationCollection].
+     */
+    constructor(values: {
+        metadata?: Map<string, any>;
+        links: Links;
+        subcollections?: Map<string, Array<PublicationCollection>>;
+    });
+    /**
+     * Parses a [PublicationCollection] from its RWPM JSON representation.
+     */
+    static deserialize(json: any): PublicationCollection | undefined;
+    /**
+     * Parses a map of [PublicationCollection] indexed by their roles from its RWPM JSON representation.
+     *
+     */
+    static deserializeCollections(json: any): Map<string, Array<PublicationCollection>> | undefined;
+    /**
+     * Serializes a [PublicationCollection] to its RWPM JSON representation.
+     */
+    serialize(): any;
+    static serializeCollection(json: any, subcollections?: Map<string, Array<PublicationCollection>>): void;
+}

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

@@ -0,0 +1,9 @@
+import { Page } from './presentation/Presentation';
+export declare enum ReadingProgression {
+    auto = "auto",
+    btt = "btt",
+    ltr = "ltr",
+    rtl = "rtl",
+    ttb = "ttb"
+}
+export declare function leadingPage(readingProgression: ReadingProgression): Page;

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

@@ -0,0 +1,56 @@
+import { Links } from './Link';
+import { LocalizedString } from './LocalizedString';
+/**
+ * https://github.com/readium/webpub-manifest/tree/master/contexts/default#subjects
+ */
+export declare class Subject {
+    /** Subject name. */
+    readonly name: LocalizedString;
+    /** Provides a string that a machine can sort. */
+    readonly sortAs?: string;
+    /** EPUB 3.1 opf:term. */
+    readonly code?: string;
+    /** EPUB 3.1 opf:authority. */
+    readonly scheme?: string;
+    /** PUsed to retrieve similar publications for the given subjects. */
+    readonly links?: Links;
+    /** Creates a [Subject]. */
+    constructor(values: {
+        name: LocalizedString;
+        sortAs?: string;
+        code?: string;
+        scheme?: string;
+        links?: Links;
+    });
+    /**
+     * Parses a [Subject] from its RWPM JSON representation.
+     *
+     * A [Subject] can be parsed from a single string, or a full-fledged object.
+     */
+    static deserialize(json: any): Subject | undefined;
+    /**
+     * Serializes a [Subject] to its RWPM JSON representation.
+     */
+    serialize(): any;
+}
+/**
+ * https://github.com/readium/webpub-manifest/blob/master/schema/subject.schema.json
+ *
+ * Collection of [Subject]
+ */
+export declare class Subjects {
+    /**
+     * Array of [Subject] items.
+     */
+    readonly items: Array<Subject>;
+    /** Creates an Array of [Subject]. */
+    constructor(items: Array<Subject>);
+    /**
+     * Parses a [Subjects] from its RWPM JSON representation.
+     */
+    static deserialize(json: any): Subjects | undefined;
+    /**
+     * Serializes a [Subjects] to its RWPM JSON representation.
+     */
+    serialize(): any;
+}

package/types/src/publication/encryption/Encryption.d.ts

@@ -0,0 +1,33 @@
+/** Indicates that a resource is encrypted/obfuscated and provides relevant information
+ *  for decryption.
+ */
+export declare class Encryption {
+    /** Identifies the algorithm used to encrypt the resource. */
+    readonly algorithm: string;
+    /** Compression method used on the resource. */
+    readonly compression?: string;
+    /** Original length of the resource in bytes before compression and/or encryption. */
+    readonly originalLength?: number;
+    /** Identifies the encryption profile used to encrypt the resource. */
+    readonly profile?: string;
+    /** Identifies the encryption scheme used to encrypt the resource. */
+    readonly scheme?: string;
+    /**
+     * Creates a [Encryption].
+     */
+    constructor(values: {
+        algorithm: string;
+        compression?: string;
+        originalLength?: number;
+        profile?: string;
+        scheme?: string;
+    });
+    /**
+     * Parses a [Encryption] from its RWPM JSON representation.
+     */
+    static deserialize(json: any): Encryption | undefined;
+    /**
+     * Serializes a [Encryption] to its RWPM JSON representation.
+     */
+    serialize(): any;
+}

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

@@ -0,0 +1,10 @@
+import { Encryption } from './Encryption';
+declare module '../Properties' {
+    interface Properties {
+        /**
+         * Indicates that a resource is encrypted/obfuscated and provides relevant information for
+         * decryption.
+         */
+        encryption: Encryption | undefined;
+    }
+}

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

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

package/types/src/publication/epub/EPUBLayout.d.ts

@@ -0,0 +1,5 @@
+/** Hint about the nature of the layout for the linked resources. */
+export declare enum EPUBLayout {
+    fixed = "fixed",
+    reflowable = "reflowable"
+}

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

@@ -0,0 +1,7 @@
+import { Link } from '../Link';
+import { EPUBLayout } from './EPUBLayout';
+declare module '../presentation/Presentation' {
+    interface Presentation {
+        layoutOf(link: Link): EPUBLayout;
+    }
+}

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

@@ -0,0 +1,14 @@
+import { EPUBLayout } from './EPUBLayout';
+declare module '../Properties' {
+    interface Properties {
+        /**
+         * Identifies content contained in the linked resource, that cannot be strictly identified using a
+         * media type.
+         */
+        getContains(): Set<string> | undefined;
+        /**
+         * Hints how the layout of the resource should be presented.
+         */
+        getLayout(): EPUBLayout | undefined;
+    }
+}

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

@@ -0,0 +1,19 @@
+import { Links } from '../Link';
+declare module '../Publication' {
+    interface Publication {
+        /**
+         * Provides navigation to positions in the Publication content that correspond to the locations of
+         * page boundaries present in a print source being represented by this EPUB Publication.
+         */
+        getPageList(): Links | undefined;
+        /**
+         * Identifies fundamental structural components of the publication in order to enable Reading
+         * Systems to provide the User efficient access to them.
+         */
+        getLandmarks(): Links | undefined;
+        getListOfAudioClips(): Links | undefined;
+        getListOfIllustrations(): Links | undefined;
+        getListOfTables(): Links | undefined;
+        getListOfVideoClips(): Links | undefined;
+    }
+}

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

@@ -0,0 +1,4 @@
+export * from './EPUBLayout';
+export * from './Presentation';
+export * from './Properties';
+export * from './Publication';

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

@@ -0,0 +1,40 @@
+import { DomRangePoint } from './DomRangePoint';
+/**
+ * This construct enables a serializable representation of a DOM Range.
+ *
+ * In a DOM Range object, the startContainer + startOffset tuple represents the [start] boundary
+ * point. Similarly, the the endContainer + endOffset tuple represents the [end] boundary point.
+ * In both cases, the start/endContainer property is a pointer to either a DOM text node, or a DOM
+ * element (this typically depends on the mechanism from which the DOM Range instance originates,
+ * for example when obtaining the currently-selected document fragment using the `window.selection`
+ * API). In the case of a DOM text node, the start/endOffset corresponds to a position within the
+ * character data. In the case of a DOM element node, the start/endOffset corresponds to a position
+ * that designates a child text node.
+ *
+ * Note that [end] field is optional. When only the start field is specified, the domRange object
+ * represents a "collapsed" range that has identical [start] and [end] boundary points.
+ *
+ * https://github.com/readium/architecture/blob/master/models/locators/extensions/html.md#the-domrange-object
+ *
+ */
+export declare class DomRange {
+    /** A serializable representation of the "start" boundary point of the DOM Range. */
+    start: DomRangePoint;
+    /** A serializable representation of the "end" boundary point of the DOM Range. */
+    end?: DomRangePoint;
+    /**
+     * Creates a [DomRange].
+     */
+    constructor(values: {
+        start: DomRangePoint;
+        end?: DomRangePoint;
+    });
+    /**
+     * Parses a [DomRange] from its RWPM JSON representation.
+     */
+    static deserialize(json: any): DomRange | undefined;
+    /**
+     * Serializes a [DomRange] to its RWPM JSON representation.
+     */
+    serialize(): any;
+}