@readium/shared 1.2.1 → 2.0.0

package/src/publication/epub/MediaOverlay.ts

@@ -0,0 +1,43 @@
+/* Copyright 2025 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.
+ */
+
+export class MediaOverlay {
+  /** Author-defined CSS class name to apply to the currently-playing EPUB Content Document element. */
+  public activeClass?: string;
+
+  /** Author-defined CSS class name to apply to the EPUB Content Document's document element when playback is active. */
+  public playbackActiveClass?: string;
+
+  /** Creates a MediaOverlay object */
+  constructor(values: {
+    activeClass?: string;
+    playbackActiveClass?: string;
+  }) {
+    this.activeClass = values.activeClass;
+    this.playbackActiveClass = values.playbackActiveClass;
+  }
+
+  /**
+   * Parses a MediaOverlay from its RWPM JSON representation.
+   */
+  public static deserialize(json: any): MediaOverlay | undefined {
+    if (!json) return;
+    
+    return new MediaOverlay({
+      activeClass: json.activeClass,
+      playbackActiveClass: json.playbackActiveClass,
+    });
+  }
+
+  /**
+   * Serializes a MediaOverlay to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = {};
+    if (this.activeClass) json.activeClass = this.activeClass;
+    if (this.playbackActiveClass) json.playbackActiveClass = this.playbackActiveClass;
+    return json;
+  }
+}

package/src/publication/epub/Metadata.ts

@@ -0,0 +1,16 @@
+import { Metadata } from "../Metadata";
+import { MediaOverlay } from "./MediaOverlay";
+
+declare module '../Metadata' {
+  export interface Metadata {
+    getMediaOverlay(): MediaOverlay | undefined;
+  }
+}
+
+Metadata.prototype.getMediaOverlay = function(): MediaOverlay | undefined {
+  const mediaOverlay = this.otherMetadata?.['mediaOverlay'];
+
+  if (!mediaOverlay) return;
+
+  return MediaOverlay.deserialize(mediaOverlay);
+};

package/src/publication/epub/Properties.ts

@@ -1,5 +1,4 @@
 import { Properties } from '../Properties';
-import { EPUBLayout } from './EPUBLayout';
 
 // EPUB extensions for link [Properties].
 // https://readium.org/webpub-manifest/schema/extensions/epub/properties.schema.json
@@ -11,18 +10,9 @@ declare module '../Properties' {
      * 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/index.ts

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

package/src/publication/index.ts

@@ -2,8 +2,8 @@ export * from './encryption';
 export * from './epub';
 export * from './html';
 export * from './opds';
-export * from './presentation';
 export * from './services';
+export * from './AltIdentifier';
 export * from './BelongsTo';
 export * from './Contributor';
 export * from './Link';
@@ -12,9 +12,12 @@ export * from './Locator';
 export * from './LocatorCollection';
 export * from './Manifest';
 export * from './Metadata';
+export * from './Profiles';
 export * from './Properties';
 export * from './Publication';
 export * from './PublicationCollection';
+export * from './Layout';
 export * from './ReadingProgression';
 export * from './Subject';
+export * from './TDM';
 export * from './GuidedNavigation';

package/src/util/JSONParse.ts

@@ -23,9 +23,9 @@ export function positiveNumberfromJSON(json: any): number | undefined {
   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>();
+/** Converts a Set to an Array object */
+export function setToArray(obj: Set<any>): Array<any> {
+  const list = new Array<any>();
   obj.forEach(x => list.push(x));
   return list;
 }

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

@@ -0,0 +1,23 @@
+/**
+ * Represents an alternate identifier for a publication.
+ * https://readium.org/webpub-manifest/schema/altIdentifier.schema.json
+ */
+export declare class AltIdentifier {
+    /** The value of the alternate identifier. */
+    readonly value: string;
+    /** The scheme of the alternate identifier (URI format). */
+    readonly scheme?: string;
+    /** Creates an AltIdentifier object */
+    constructor(values: {
+        value: string;
+        scheme?: string;
+    });
+    /**
+     * Parses an AltIdentifier from its RWPM JSON representation.
+     */
+    static deserialize(json: string | any): AltIdentifier | undefined;
+    /**
+     * Serializes an AltIdentifier to its RWPM JSON representation.
+     */
+    serialize(): string | any;
+}

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

@@ -1,5 +1,6 @@
 import { Links } from './Link';
 import { LocalizedString } from './LocalizedString';
+import { AltIdentifier } from './AltIdentifier';
 /**
  * Contributor Object for the Readium Web Publication Manifest.
  * https://readium.org/webpub-manifest/schema/contributor-object.schema.json
@@ -11,6 +12,8 @@ export declare class Contributor {
     readonly sortAs?: string;
     /** An unambiguous reference to this contributor. */
     readonly identifier?: string;
+    /** Alternate identifiers for this contributor. */
+    readonly altIdentifiers?: Set<AltIdentifier>;
     /** The role of the contributor in the publication making. */
     readonly roles?: Set<string>;
     /** Used to retrieve similar publications for the given contributor. */
@@ -24,6 +27,7 @@ export declare class Contributor {
         name: LocalizedString;
         sortAs?: string;
         identifier?: string;
+        altIdentifiers?: Set<AltIdentifier>;
         roles?: Set<string>;
         links?: Links;
         position?: number;

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

@@ -19,6 +19,33 @@ export declare class GuidedNavigationDocument {
     static deserialize(json: any): GuidedNavigationDocument | undefined;
     serialize(): any;
 }
+/**
+ * Represents a text value containing plain text, SSML, and language information.
+ */
+export declare class GuidedNavigationText {
+    /** Plain text content */
+    readonly plain?: string;
+    /** SSML (Speech Synthesis Markup Language) content */
+    readonly ssml?: string;
+    /**
+     * BCP 47 language tag
+     * @pattern ^((?<grandfathered>(en-GB-oed|i-ami|i-bnn|i-default|i-enochian|i-hak|i-klingon|i-lux|i-mingo|i-navajo|i-pwn|i-tao|i-tay|i-tsu|sgn-BE-FR|sgn-BE-NL|sgn-CH-DE)|(art-lojban|cel-gaulish|no-bok|no-nyn|zh-guoyu|zh-hakka|zh-min|zh-min-nan|zh-xiang))|((?<language>([A-Za-z]{2,3}(-(?<extlang>[A-Za-z]{3}(-[A-Za-z]{3}){0,2}))?)|[A-Za-z]{4}|[A-Za-z]{5,8})(-(?<script>[A-Za-z]{4}))?(-(?<region>[A-Za-z]{2}|[0-9]{3}))?(-(?<variant>[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-(?<extension>[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+))*(-(?<privateUse>x(-[A-Za-z0-9]{1,8})+))?)|(?<privateUse2>x(-[A-Za-z0-9]{1,8})+))$
+     */
+    readonly language?: string;
+    constructor(values: {
+        plain?: string;
+        ssml?: string;
+        language?: string;
+    });
+    /**
+     * Deserializes a GuidedNavigationText from JSON
+     */
+    static deserialize(json: any): GuidedNavigationText | undefined;
+    /**
+     * Serializes the text to a plain object
+     */
+    serialize(): any;
+}
 /**
  * Guided Navigation Object
  * https://github.com/readium/guided-navigation/blob/main/schema/object.schema.json
@@ -32,10 +59,23 @@ export declare class GuidedNavigationObject {
     readonly imgref?: string;
     /** Convey the structural semantics of a publication. */
     readonly role?: Set<string>;
-    /** Textual equivalent of the resources or fragment of the resources referenced by the current Guided Navigation Object. */
-    readonly text?: string;
+    /**
+     * Indicates the heading level (1-6) for the navigation object.
+     * @minimum 1
+     * @maximum 6
+     */
+    readonly level?: number;
+    /**
+     * Textual equivalent of the resources or fragment of the resources referenced by the current Guided Navigation Object.
+     */
+    readonly text?: GuidedNavigationText;
     /** References a textual resource or a fragment of it. */
     readonly textref?: string;
+    /**
+     * Describes the image referenced by the current Guided Navigation Object.
+     * This is a GuidedNavigationObject that should not contain 'level' or 'children' properties.
+     */
+    readonly description?: Omit<GuidedNavigationObject, 'level' | 'children'>;
     /**
      * Creates a [GuidedNavigation] object.
     */
@@ -44,22 +84,35 @@ export declare class GuidedNavigationObject {
         children?: GuidedNavigationObject[];
         imgref?: string;
         role?: Set<string>;
-        text?: string;
+        level?: number;
+        text?: GuidedNavigationText;
         textref?: string;
+        description?: Omit<GuidedNavigationObject, 'level' | 'children'>;
     });
     /**
-     * Parses a [GuidedNavigationObject] from its RWPM JSON representation.
-     *
-     * A GuidedNavigationObject can be parsed from a single string, or a full-fledged object.
-    */
+     * Gets the plain text content.
+     * Returns undefined if no text is available.
+     */
+    get plainText(): string | undefined;
+    /**
+     * Gets the SSML content if available.
+     */
+    get ssmlText(): string | undefined;
+    /**
+     * Gets the language of the text if available.
+     */
+    get textLanguage(): string | undefined;
+    /**
+     * Deserializes a GuidedNavigationObject from JSON
+     */
     static deserialize(json: any): GuidedNavigationObject | undefined;
     /**
      * Parses a [GuidedNavigationObject] array from its RWPM JSON representation.
-    */
+     */
     static deserializeArray(json: any): GuidedNavigationObject[] | undefined;
     /**
      * Serializes a [GuidedNavigationObject] to its RWPM JSON representation.
-    */
+     */
     serialize(): any;
     get audioFile(): string | undefined;
     get audioTime(): string | undefined;

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

@@ -0,0 +1,8 @@
+/** Hint about the nature of the layout for the publication.
+ *  https://readium.org/webpub-manifest/contexts/default/#layout-and-reading-progression
+*/
+export declare enum Layout {
+    reflowable = "reflowable",
+    fixed = "fixed",
+    scrolled = "scrolled"
+}

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

@@ -22,6 +22,8 @@ export declare class Link {
     readonly height?: number;
     /** Width of the linked resource in pixels. */
     readonly width?: number;
+    /** Size of the linked resource in bytes. */
+    readonly size?: number;
     /** Length of the linked resource in seconds. */
     readonly duration?: number;
     /** Bitrate of the linked resource in kbps. */
@@ -44,6 +46,7 @@ export declare class Link {
         properties?: Properties;
         height?: number;
         width?: number;
+        size?: number;
         duration?: number;
         bitrate?: number;
         languages?: Array<string>;

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

@@ -15,7 +15,7 @@ export declare class Manifest {
     /** 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 toc?: Links;
     readonly subcollections?: Map<string, Array<PublicationCollection>>;
     constructor(values: {
         context?: Array<string>;
@@ -23,7 +23,7 @@ export declare class Manifest {
         links: Links;
         readingOrder: Links;
         resources?: Links;
-        tableOfContents?: Links;
+        toc?: Links;
         subcollections?: Map<string, Array<PublicationCollection>>;
     });
     /**

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

@@ -1,8 +1,12 @@
+import { AltIdentifier } from './AltIdentifier';
 import { BelongsTo } from './BelongsTo';
 import { Contributors } from './Contributor';
+import { Layout } from './Layout';
 import { LocalizedString } from './LocalizedString';
+import { Profile } from './Profiles';
 import { ReadingProgression } from './ReadingProgression';
 import { Subjects } from './Subject';
+import { TDM } from './TDM';
 /**
  * https://readium.org/webpub-manifest/schema/metadata.schema.json
  *
@@ -14,7 +18,9 @@ import { Subjects } from './Subject';
 export declare class Metadata {
     title: LocalizedString;
     typeUri?: string;
+    conformsTo?: Array<Profile>;
     identifier?: string;
+    altIdentifier?: AltIdentifier;
     subtitle?: LocalizedString;
     sortAs?: LocalizedString;
     artists?: Contributors;
@@ -38,9 +44,11 @@ export declare class Metadata {
     belongsTo?: BelongsTo;
     belongsToCollections?: Contributors;
     belongsToSeries?: Contributors;
+    layout?: Layout;
     readingProgression?: ReadingProgression;
     duration?: number;
     numberOfPages?: number;
+    tdm?: TDM;
     otherMetadata?: {
         [key: string]: any;
     };
@@ -50,7 +58,9 @@ export declare class Metadata {
     constructor(values: {
         title: LocalizedString;
         typeUri?: string;
+        conformsTo?: Array<Profile>;
         identifier?: string;
+        altIdentifier?: AltIdentifier;
         subtitle?: LocalizedString;
         sortAs?: LocalizedString;
         artists?: Contributors;
@@ -74,9 +84,11 @@ export declare class Metadata {
         belongsTo?: BelongsTo;
         belongsToCollections?: Contributors;
         belongsToSeries?: Contributors;
+        layout?: Layout;
         readingProgression?: ReadingProgression;
         duration?: number;
         numberOfPages?: number;
+        tdm?: TDM;
         otherMetadata?: {
             [key: string]: any;
         };
@@ -92,8 +104,19 @@ export declare class Metadata {
      */
     serialize(): any;
     /**
-     * Computes a [ReadingProgression] when the value of [readingProgression] is set to
-     * auto, using the publication language.
+     * Computes a [Layout] using the [conformsTo] profile and layout property.
+     *
+     * Special cases:
+     * - EPUB profile defaults to reflowable if layout is not present
+     * - Divina profile defaults to fixed if layout is not present
+     * - Layout is ignored for audiobook and PDF profiles
+     * - Layout is ignored if set to reflowable on a Divina profile
+     *
+     * Note: Stops at the first matching profile.
+     */
+    get effectiveLayout(): Layout | null;
+    /**
+     * Computes a [ReadingProgression] when the value of [readingProgression] is undefined, using the publication language.
      *
      * See this issue for more details: https://github.com/readium/architecture/issues/113
      */

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

@@ -0,0 +1,10 @@
+/**
+ * Registered profiles.
+ * https://readium.org/webpub-manifest/profiles/
+ */
+export declare enum Profile {
+    EPUB = "https://readium.org/webpub-manifest/profiles/epub",
+    AUDIOBOOK = "https://readium.org/webpub-manifest/profiles/audiobook",
+    DIVINA = "https://readium.org/webpub-manifest/profiles/divina",
+    PDF = "https://readium.org/webpub-manifest/profiles/pdf"
+}

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

@@ -1,3 +1,8 @@
+export declare enum Page {
+    left = "left",
+    right = "right",
+    center = "center"
+}
 /**
  * Properties associated to the linked resource.
  *
@@ -11,6 +16,7 @@ export declare class Properties {
     constructor(values: {
         [key: string]: any;
     });
+    get page(): Page | undefined;
     /**
      * Creates a [Properties] from its RWPM JSON representation.
      */

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

@@ -20,7 +20,7 @@ export declare class Publication {
     /** 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 toc?: Links;
     /** Identifies the collection that contains sub collections. */
     readonly subcollections?: Map<string, Array<PublicationCollection>>;
     constructor(values: {

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

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

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

@@ -0,0 +1,30 @@
+/**
+ * https://readium.org/webpub-manifest/contexts/default/#text-and-data-mining
+ */
+export declare enum TDMReservation {
+    all = "all",
+    none = "none"
+}
+export declare class TDM {
+    /**
+     * Indicates whether the publication allows text and data mining.
+     */
+    readonly reservation?: TDMReservation;
+    /**
+     * Additional policy information about text and data mining usage.
+     */
+    readonly policy?: string;
+    /** Creates a [TDM] object */
+    constructor(values: {
+        reservation?: TDMReservation;
+        policy?: string;
+    });
+    /**
+     * Parses a [TDM] from its RWPM JSON representation.
+     */
+    static deserialize(json: any): TDM | undefined;
+    /**
+     * Serializes a [TDM] to its RWPM JSON representation.
+     */
+    serialize(): any;
+}