@readium/shared 1.2.0

package/src/publication/Subject.ts

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

package/src/publication/encryption/Encryption.ts

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

package/src/publication/encryption/Properties.ts

@@ -0,0 +1,20 @@
+import { Properties } from '../Properties';
+import { Encryption } from './Encryption';
+
+// Encryption extensions for link [Properties].
+
+declare module '../Properties' {
+  export interface Properties {
+    /**
+     * Indicates that a resource is encrypted/obfuscated and provides relevant information for
+     * decryption.
+     */
+    encryption: Encryption | undefined;
+  }
+}
+
+Object.defineProperty(Properties.prototype, 'encryption', {
+  get: function(): Encryption | undefined {
+    return Encryption.deserialize(this.otherProperties.encrypted);
+  },
+});

package/src/publication/encryption/index.ts

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

package/src/publication/epub/EPUBLayout.ts

@@ -0,0 +1,10 @@
+/* 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.
+ */
+
+/** Hint about the nature of the layout for the linked resources. */
+export enum EPUBLayout {
+  fixed = 'fixed',
+  reflowable = 'reflowable',
+}

package/src/publication/epub/Presentation.ts

@@ -0,0 +1,16 @@
+import { Link } from '../Link';
+import { Presentation } from '../presentation/Presentation';
+import { EPUBLayout } from './EPUBLayout';
+
+declare module '../presentation/Presentation' {
+  export interface Presentation {
+    layoutOf(link: Link): EPUBLayout;
+  }
+}
+
+/** Determines the layout of the given resource in this publication.
+ *  Default layout is reflowable.
+ */
+Presentation.prototype.layoutOf = function(link: Link): EPUBLayout {
+  return link.properties?.getLayout() || this.layout || EPUBLayout.reflowable;
+};

package/src/publication/epub/Properties.ts

@@ -0,0 +1,28 @@
+import { Properties } from '../Properties';
+import { EPUBLayout } from './EPUBLayout';
+
+// EPUB extensions for link [Properties].
+// https://readium.org/webpub-manifest/schema/extensions/epub/properties.schema.json
+
+declare module '../Properties' {
+  export 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;
+  }
+}
+
+Properties.prototype.getContains = function(): Set<string> | undefined {
+  return new Set<string>(this.otherProperties['contains'] || []);
+};
+
+Properties.prototype.getLayout = function(): EPUBLayout | undefined {
+  return this.otherProperties['layout'];
+};

package/src/publication/epub/Publication.ts

@@ -0,0 +1,51 @@
+import { Links } from '../Link';
+import { Publication } from '../Publication';
+
+// EPUB extensions for [Publication].
+// https://readium.org/webpub-manifest/schema/extensions/epub/subcollections.schema.json
+// https://idpf.github.io/epub-vocabs/structure/#navigation
+
+declare module '../Publication' {
+  export 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;
+  }
+}
+
+Publication.prototype.getPageList = function(): Links | undefined {
+  return this.linksWithRole('pageList');
+};
+
+Publication.prototype.getLandmarks = function(): Links | undefined {
+  return this.linksWithRole('landmarks');
+};
+
+Publication.prototype.getListOfAudioClips = function(): Links | undefined {
+  return this.linksWithRole('loa');
+};
+
+Publication.prototype.getListOfIllustrations = function(): Links | undefined {
+  return this.linksWithRole('loi');
+};
+
+Publication.prototype.getListOfTables = function(): Links | undefined {
+  return this.linksWithRole('lot');
+};
+
+Publication.prototype.getListOfVideoClips = function(): Links | undefined {
+  return this.linksWithRole('lov');
+};

package/src/publication/epub/index.ts

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

package/src/publication/html/DomRange.ts

@@ -0,0 +1,63 @@
+/* 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 { 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 class DomRange {
+  /** A serializable representation of the "start" boundary point of the DOM Range. */
+  public start: DomRangePoint;
+
+  /** A serializable representation of the "end" boundary point of the DOM Range. */
+  public end?: DomRangePoint;
+
+  /**
+   * Creates a [DomRange].
+   */
+  constructor(values: { start: DomRangePoint; end?: DomRangePoint }) {
+    this.start = values.start;
+    this.end = values.end;
+  }
+
+  /**
+   * Parses a [DomRange] from its RWPM JSON representation.
+   */
+  public static deserialize(json: any): DomRange | undefined {
+    if (!json) return;
+    let start = DomRangePoint.deserialize(json.start);
+    if (!start) return;
+
+    return new DomRange({
+      start,
+      end: DomRangePoint.deserialize(json.end),
+    });
+  }
+
+  /**
+   * Serializes a [DomRange] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = { start: this.start.serialize() };
+    if (this.end) json.end = this.end.serialize();
+    return json;
+  }
+}

package/src/publication/html/DomRangePoint.ts

@@ -0,0 +1,64 @@
+import { positiveNumberfromJSON } from '../../util/JSONParse';
+
+/**
+ * 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 class DomRangePoint {
+  public cssSelector: string;
+  public textNodeIndex: number;
+  public charOffset?: number;
+
+  /**
+   * Creates a [DomRange].
+   */
+  constructor(values: {
+    cssSelector: string;
+    textNodeIndex: number;
+    charOffset?: number;
+  }) {
+    this.cssSelector = values.cssSelector;
+    this.textNodeIndex = values.textNodeIndex;
+    this.charOffset = values.charOffset;
+  }
+
+  /**
+   * Parses a [DomRangePoint] from its RWPM JSON representation.
+   */
+  public static deserialize(json: any): DomRangePoint | undefined {
+    if (!(json && json.cssSelector)) return;
+    let textNodeIndex = positiveNumberfromJSON(json.textNodeIndex);
+    if (textNodeIndex === undefined) return;
+    let charOffset = positiveNumberfromJSON(json.charOffset);
+    if (charOffset === undefined)
+      charOffset = positiveNumberfromJSON(json.offset);
+    return new DomRangePoint({
+      cssSelector: json.cssSelector,
+      textNodeIndex,
+      charOffset,
+    });
+  }
+
+  /**
+   * Serializes a [DomRangePoint] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = {
+      cssSelector: this.cssSelector,
+      textNodeIndex: this.textNodeIndex,
+    };
+    if (this.charOffset !== undefined) json.charOffset = this.charOffset;
+    return json;
+  }
+}

package/src/publication/html/Locations.ts

@@ -0,0 +1,129 @@
+import { LocatorLocations } from '../Locator';
+import { DomRange } from './DomRange';
+
+// HTML extensions for [Locations].
+// https://github.com/readium/architecture/blob/master/models/locators/extensions/html.md
+
+declare module '../Locator' {
+  export 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;
+  }
+}
+
+LocatorLocations.prototype.getCssSelector = function(): string | undefined {
+  return this.otherLocations?.get('cssSelector');
+};
+
+LocatorLocations.prototype.getPartialCfi = function(): string | undefined {
+  return this.otherLocations?.get('partialCfi');
+};
+
+LocatorLocations.prototype.getDomRange = function(): DomRange | undefined {
+  return DomRange.deserialize(this.otherLocations?.get('domRange'));
+};
+
+// Below is technically part of the Navigator's Locator extensions, we're putting it here for now
+
+// Reference: https://www.w3.org/TR/fragid-best-practices
+LocatorLocations.prototype.fragmentParameters = function(): Map<string, string> {
+  return new Map(
+    this.fragments
+      // Concatenates fragments together, after dropping any #
+      .map(f => f.startsWith("#") ? f.slice(1) : f)
+      .join("&")
+      // Splits parameters
+      .split("&")
+      .filter(f => !f.startsWith("#"))
+      .map(f => f.split("="))
+      // Only keep named parameters
+      .filter(f => f.length === 2)
+      .map(f => [
+        f[0].trim().toLowerCase(),
+        f[1].trim()
+      ])
+  );
+};
+
+LocatorLocations.prototype.htmlId = function(): string | undefined {
+  /*
+  The HTML 5 specification (used for WebPub) allows any character in an HTML ID, except spaces.
+  This is an issue to differentiate with named parameters, so we ignore any ID containing `=`.
+  */
+  if(!this.fragments.length) return;
+  let f = this.fragments.find(f => f.length && !f.includes("="));
+  if(!f) {
+    const fp = this.fragmentParameters();
+    if(fp.has("id")) f = fp.get("id");
+    else if(fp.has("name")) f = fp.get("name");
+  }
+  return f?.startsWith("#") ? f.slice(1) : f;
+};
+
+LocatorLocations.prototype.page = function(): number | undefined {
+  const i = parseInt(this.fragmentParameters().get("page")!);
+  if(!isNaN(i) && i >= 0) return i;
+  return undefined;
+}
+
+LocatorLocations.prototype.time = function(): number | undefined {
+  // TODO more sophiticated parsing
+  const i = parseInt(this.fragmentParameters().get("t")!);
+  if(!isNaN(i)) return i;
+  return undefined;
+}
+
+LocatorLocations.prototype.space = function(): [number, number, number, number] | undefined {
+  const fp = this.fragmentParameters();
+  if(!fp.has("xywh")) return;
+  // TODO more sophiticated parsing to handle the format
+  const xywh = fp.get("xywh")!.split(",").map(s => parseInt(s));
+  if(xywh.length !== 4) return; // Must have four parts
+  if(xywh.some(isNaN)) return; // All parts must be numbers
+  return xywh as [number, number, number, number];
+}

package/src/publication/html/index.ts

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

package/src/publication/index.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';