@readium/shared 1.2.1 → 2.0.0

package/src/publication/GuidedNavigation.ts

@@ -43,6 +43,66 @@ export class GuidedNavigationDocument {
     }
 }
 
+/**
+ * Represents a text value containing plain text, SSML, and language information.
+ */
+export class GuidedNavigationText {
+    /** Plain text content */
+    public readonly plain?: string;
+    
+    /** SSML (Speech Synthesis Markup Language) content */
+    public 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})+))$
+     */
+    public readonly language?: string;
+
+    constructor(values: {
+        plain?: string;
+        ssml?: string;
+        language?: string;
+    }) {
+        this.plain = values.plain;
+        this.ssml = values.ssml;
+        this.language = values.language;
+    }
+
+    /**
+     * Deserializes a GuidedNavigationText from JSON
+     */
+    public static deserialize(json: any): GuidedNavigationText | undefined {
+        if (json === undefined || json === null) return undefined;
+        
+        if (typeof json === 'string') {
+            return new GuidedNavigationText({ plain: json });
+        }
+        
+        // Only create if there are actual values
+        if (json.plain || json.ssml || json.language) {
+            return new GuidedNavigationText({
+                plain: json.plain,
+                ssml: json.ssml,
+                language: json.language
+            });
+        }
+        
+        return undefined;
+    }
+
+    /**
+     * Serializes the text to a plain object
+     */
+    public serialize(): any {
+        const result: any = {};
+        if (this.plain !== undefined) result.plain = this.plain;
+        if (this.ssml !== undefined) result.ssml = this.ssml;
+        if (this.language !== undefined) result.language = this.language;
+        return Object.keys(result).length > 0 ? result : undefined;
+    }
+}
+
 /**
  * Guided Navigation Object
  * https://github.com/readium/guided-navigation/blob/main/schema/object.schema.json
@@ -61,12 +121,27 @@ export class GuidedNavigationObject {
   /** Convey the structural semantics of a publication. */
   public readonly role?: Set<string>;
   
-  /** Textual equivalent of the resources or fragment of the resources referenced by the current Guided Navigation Object. */
-  public readonly text?: string;
+  /** 
+   * Indicates the heading level (1-6) for the navigation object.
+   * @minimum 1
+   * @maximum 6
+   */
+  public readonly level?: number;
+  
+  /** 
+   * Textual equivalent of the resources or fragment of the resources referenced by the current Guided Navigation Object.
+   */
+  public readonly text?: GuidedNavigationText;
   
   /** References a textual resource or a fragment of it. */
   public 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.
+   */
+  public readonly description?: Omit<GuidedNavigationObject, 'level' | 'children'>;
+
     /**
      * Creates a [GuidedNavigation] object.
     */
@@ -75,41 +150,68 @@ export class GuidedNavigationObject {
         children?: GuidedNavigationObject[];
         imgref?: string;
         role?: Set<string>;
-        text?: string;
+        level?: number;
+        text?: GuidedNavigationText;
         textref?: string;
+        description?: Omit<GuidedNavigationObject, 'level' | 'children'>;
     }) {
         this.audioref = values.audioref;
         this.children = values.children;
         this.imgref = values.imgref;
         this.role = values.role;
+        this.level = values.level !== undefined ? Math.min(6, Math.max(1, values.level)) : undefined;
         this.text = values.text;
         this.textref = values.textref;
+        this.description = values.description;
     }
 
     /**
-     * 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.
+     */
+    public get plainText(): string | undefined {
+        return this.text?.plain;
+    }
+
+    /**
+     * Gets the SSML content if available.
+     */
+    public get ssmlText(): string | undefined {
+        return this.text?.ssml;
+    }
+
+    /**
+     * Gets the language of the text if available.
+     */
+    public get textLanguage(): string | undefined {
+        return this.text?.language;
+    }
+
+    /**
+     * Deserializes a GuidedNavigationObject from JSON
+     */
     public static deserialize(json: any): GuidedNavigationObject | undefined {
-        if (!json) return;
+        if (!json) return undefined;
+        
         return new GuidedNavigationObject({
             audioref: json.audioref,
             children: GuidedNavigationObject.deserializeArray(json.children),
             imgref: json.imgref,
             role: json.role
-            ? new Set<string>(arrayfromJSONorString(json.role))
-            : undefined,
-            text: json.text,
+                ? new Set<string>(arrayfromJSONorString(json.role))
+                : undefined,
+            level: typeof json.level === 'number' ? json.level : undefined,
+            text: GuidedNavigationText.deserialize(json.text),
             textref: json.textref,
+            description: GuidedNavigationObject.deserialize(json.description)
         });
     }
 
     /** 
      * Parses a [GuidedNavigationObject] array from its RWPM JSON representation.
-    */
+     */
     public static deserializeArray(json: any): GuidedNavigationObject[] | undefined {
-        if (!(json instanceof Array)) return;
+        if (!(json instanceof Array)) return undefined;
         return json
             .map<GuidedNavigationObject>((item) => GuidedNavigationObject.deserialize(item) as GuidedNavigationObject)
             .filter((x) => x !== undefined);
@@ -117,15 +219,24 @@ export class GuidedNavigationObject {
 
     /**
      * Serializes a [GuidedNavigationObject] to its RWPM JSON representation.
-    */
+     */
     public serialize(): any {
         const json: any = {};
         if (this.audioref !== undefined) json.audioref = this.audioref;
         if (this.children !== undefined) json.children = this.children.map(x => x.serialize());
         if (this.imgref !== undefined) json.imgref = this.imgref;
         if (this.role !== undefined) json.role = setToArray(this.role);
-        if (this.text !== undefined) json.text = this.text;
+        if (this.level !== undefined) json.level = this.level;
+        if (this.text !== undefined) {
+            const serializedText = this.text.serialize();
+            if (serializedText !== undefined) {
+                json.text = serializedText;
+            }
+        }
         if (this.textref !== undefined) json.textref = this.textref;
+        if (this.description) {
+            json.description = this.description.serialize();
+        }
         return json;
     }
 

package/src/publication/Layout.ts

@@ -0,0 +1,13 @@
+/* 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.
+ */
+
+/** Hint about the nature of the layout for the publication. 
+ *  https://readium.org/webpub-manifest/contexts/default/#layout-and-reading-progression
+*/
+export enum Layout {
+  reflowable = 'reflowable',
+  fixed = 'fixed',
+  scrolled = 'scrolled'
+}

package/src/publication/Link.ts

@@ -42,6 +42,9 @@ export class Link {
   /** Width of the linked resource in pixels. */
   public readonly width?: number;
 
+  /** Size of the linked resource in bytes. */
+  public readonly size?: number;
+
   /** Length of the linked resource in seconds. */
   public readonly duration?: number;
 
@@ -69,6 +72,7 @@ export class Link {
     properties?: Properties;
     height?: number;
     width?: number;
+    size?: number;
     duration?: number;
     bitrate?: number;
     languages?: Array<string>;
@@ -83,6 +87,7 @@ export class Link {
     this.properties = values.properties;
     this.height = values.height;
     this.width = values.width;
+    this.size = values.size;
     this.duration = values.duration;
     this.bitrate = values.bitrate;
     this.languages = values.languages;
@@ -94,7 +99,8 @@ export class Link {
    * Parses a [Link] from its RWPM JSON representation.
    */
   public static deserialize(json: any): Link | undefined {
-    if (!(json && json.href && typeof json.href === 'string')) return;
+    if (!json || typeof json.href !== 'string') return;
+    
     return new Link({
       href: json.href,
       templated: json.templated,
@@ -108,6 +114,7 @@ export class Link {
       properties: Properties.deserialize(json.properties),
       height: positiveNumberfromJSON(json.height),
       width: positiveNumberfromJSON(json.width),
+      size: positiveNumberfromJSON(json.size),
       duration: positiveNumberfromJSON(json.duration),
       bitrate: positiveNumberfromJSON(json.bitrate),
       languages: arrayfromJSONorString(json.language),
@@ -128,6 +135,7 @@ export class Link {
     if (this.properties) json.properties = this.properties.serialize();
     if (this.height !== undefined) json.height = this.height;
     if (this.width !== undefined) json.width = this.width;
+    if (this.size !== undefined) json.size = this.size;
     if (this.duration !== undefined) json.duration = this.duration;
     if (this.bitrate !== undefined) json.bitrate = this.bitrate;
     if (this.languages) json.language = this.languages;

package/src/publication/Manifest.ts

@@ -28,7 +28,7 @@ export class Manifest {
   public readonly resources?: Links;
 
   /** Identifies the collection that contains a table of contents. */
-  public readonly tableOfContents?: Links;
+  public readonly toc?: Links;
 
   public readonly subcollections?: Map<string, Array<PublicationCollection>>;
 
@@ -38,7 +38,7 @@ export class Manifest {
     links: Links;
     readingOrder: Links;
     resources?: Links;
-    tableOfContents?: Links;
+    toc?: Links;
     subcollections?: Map<string, Array<PublicationCollection>>;
   }) {
     this.context = values.context;
@@ -46,7 +46,7 @@ export class Manifest {
     this.links = values.links;
     this.readingOrder = values.readingOrder;
     this.resources = values.resources;
-    this.tableOfContents = values.tableOfContents;
+    this.toc = values.toc;
     this.subcollections = values.subcollections;
   }
 
@@ -79,7 +79,7 @@ export class Manifest {
       links,
       readingOrder,
       resources: Links.deserialize(json.resources),
-      tableOfContents: Links.deserialize(json.toc),
+      toc: Links.deserialize(json.toc),
       subcollections: PublicationCollection.deserializeCollections({
         sub: json.sub,
       }),
@@ -96,7 +96,7 @@ export class Manifest {
     json.links = this.links.serialize();
     json.readingOrder = this.readingOrder.serialize();
     if (this.resources) json.resources = this.resources.serialize();
-    if (this.tableOfContents) json.toc = this.tableOfContents.serialize();
+    if (this.toc) json.toc = this.toc.serialize();
     PublicationCollection.serializeCollection(json, this.subcollections);
     return json;
   }

package/src/publication/Metadata.ts

@@ -8,11 +8,15 @@ import {
   datefromJSON,
   positiveNumberfromJSON,
 } from '../util/JSONParse';
+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
@@ -25,7 +29,9 @@ import { Subjects } from './Subject';
 export class Metadata {
   public title: LocalizedString;
   public typeUri?: string;
+  public conformsTo?: Array<Profile>;
   public identifier?: string;
+  public altIdentifier?: AltIdentifier;
   public subtitle?: LocalizedString;
   public sortAs?: LocalizedString;
   public artists?: Contributors;
@@ -49,16 +55,20 @@ export class Metadata {
   public belongsTo?: BelongsTo;
   public belongsToCollections?: Contributors;
   public belongsToSeries?: Contributors;
+  public layout?: Layout;
   public readingProgression?: ReadingProgression;
   public duration?: number;
   public numberOfPages?: number;
+  public tdm?: TDM;
   public otherMetadata?: { [key: string]: any };
 
   /**All metadata not in otherMetadata */
   private static readonly mappedProperties = [
     'title',
     '@type',
+    'conformsTo',
     'identifier',
+    'altIdentifier',
     'subtitle',
     'sortAs',
     'artist',
@@ -80,16 +90,20 @@ export class Metadata {
     'modified',
     'subject',
     'belongsTo',
+    'layout',
     'readingProgression',
     'duration',
     'numberOfPages',
+    'tdm'
   ];
 
   /** Creates [Metadata] object */
   constructor(values: {
     title: LocalizedString;
     typeUri?: string;
+    conformsTo?: Array<Profile>;
     identifier?: string;
+    altIdentifier?: AltIdentifier;
     subtitle?: LocalizedString;
     sortAs?: LocalizedString;
     artists?: Contributors;
@@ -113,15 +127,19 @@ export class Metadata {
     belongsTo?: BelongsTo;
     belongsToCollections?: Contributors;
     belongsToSeries?: Contributors;
+    layout?: Layout;
     readingProgression?: ReadingProgression;
     duration?: number;
     numberOfPages?: number;
+    tdm?: TDM;
     otherMetadata?: { [key: string]: any };
   }) {
     //title always required
     this.title = values.title as LocalizedString;
     this.typeUri = values.typeUri;
+    this.conformsTo = values.conformsTo;
     this.identifier = values.identifier;
+    this.altIdentifier = values.altIdentifier;
     this.subtitle = values.subtitle;
     this.sortAs = values.sortAs;
     this.artists = values.artists;
@@ -145,7 +163,6 @@ export class Metadata {
     this.belongsTo = values.belongsTo;
     this.belongsToCollections = values.belongsToCollections;
     this.belongsToSeries = values.belongsToSeries;
-
     if (
       this.belongsToCollections &&
       this.belongsToCollections.items.length > 0
@@ -163,9 +180,11 @@ export class Metadata {
       this.belongsTo.items.set('series', this.belongsToSeries);
     }
 
+    this.layout = values.layout;
     this.readingProgression = values.readingProgression;
     this.duration = values.duration;
     this.numberOfPages = values.numberOfPages;
+    this.tdm = values.tdm;
     this.otherMetadata = values.otherMetadata;
   }
 
@@ -179,7 +198,9 @@ export class Metadata {
 
     const title = LocalizedString.deserialize(json.title) as LocalizedString;
     const typeUri = json['@type'];
+    const conformsTo = arrayfromJSONorString(json.conformsTo);
     const identifier = json.identifier;
+    const altIdentifier = AltIdentifier.deserialize(json.altIdentifier);
     const subtitle = LocalizedString.deserialize(json.subtitle);
     const sortAs = LocalizedString.deserialize(json.sortAs);
     const artists = Contributors.deserialize(json.artist);
@@ -201,9 +222,11 @@ export class Metadata {
     const modified = datefromJSON(json.modified);
     const subjects = Subjects.deserialize(json.subject);
     const belongsTo = BelongsTo.deserialize(json.belongsTo);
+    const layout = json.layout;
     const readingProgression = json.readingProgression;
     const duration = positiveNumberfromJSON(json.duration);
     const numberOfPages = positiveNumberfromJSON(json.numberOfPages);
+    const tdm = TDM.deserialize(json.tdm);
 
     let otherMetadata = Object.assign({}, json);
     Metadata.mappedProperties.forEach(x => delete otherMetadata[x]);
@@ -214,7 +237,9 @@ export class Metadata {
     return new Metadata({
       title,
       typeUri,
+      conformsTo,
       identifier,
+      altIdentifier,
       subtitle,
       sortAs,
       artists,
@@ -236,10 +261,12 @@ export class Metadata {
       modified,
       subjects,
       belongsTo,
+      layout,
       readingProgression,
       duration,
       numberOfPages,
-      otherMetadata,
+      tdm,
+      otherMetadata
     });
   }
 
@@ -249,7 +276,9 @@ export class Metadata {
   public serialize(): any {
     const json: any = { title: this.title.serialize() };
     if (this.typeUri !== undefined) json['@type'] = this.typeUri;
+    if (this.conformsTo) json.conformsTo = this.conformsTo;
     if (this.identifier !== undefined) json.identifier = this.identifier;
+    if (this.altIdentifier) json.altIdentifier = this.altIdentifier.serialize();
     if (this.subtitle) json.subtitle = this.subtitle.serialize();
     if (this.sortAs) json.sortAs = this.sortAs.serialize();
     if (this.editors) json.editor = this.editors.serialize();
@@ -273,11 +302,13 @@ export class Metadata {
       json.modified = this.modified.toISOString();
     if (this.subjects) json.subject = this.subjects.serialize();
     if (this.belongsTo) json.belongsTo = this.belongsTo.serialize();
+    if (this.layout) json.layout = this.layout;
     if (this.readingProgression)
       json.readingProgression = this.readingProgression;
     if (this.duration !== undefined) json.duration = this.duration;
     if (this.numberOfPages !== undefined)
       json.numberOfPages = this.numberOfPages;
+    if (this.tdm) json.tdm = this.tdm.serialize();
 
     if (this.otherMetadata) {
       const metadata = this.otherMetadata;
@@ -288,16 +319,54 @@ export class Metadata {
   }
 
   /**
-   * 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.
+   */
+  public get effectiveLayout(): Layout | null {
+    if (!this.conformsTo) {
+      return null; // Default Web Publication behavior
+    }
+
+    // Check each profile in order, stopping at the first match
+    for (const profile of this.conformsTo) {
+      switch (profile) {
+        case Profile.EPUB:
+          // EPUB defaults to reflowable if layout is not set
+          return this.layout || Layout.reflowable;
+
+        case Profile.DIVINA:
+          // Divina defaults to fixed if layout is not set
+          // Layout is ignored if set to reflowable
+          if (this.layout === Layout.reflowable) {
+            return Layout.fixed;
+          }
+          return this.layout || Layout.fixed;
+
+        case Profile.AUDIOBOOK:
+        case Profile.PDF:
+          // Layout is ignored for audiobook and PDF profiles
+          return null;
+      }
+    }
+
+    // If we get here, we have a conformsTo but no matching profile
+    return 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
    */
   public get effectiveReadingProgression(): ReadingProgression {
-    if (
-      this.readingProgression &&
-      this.readingProgression !== ReadingProgression.auto
-    ) {
+    if (this.readingProgression) {
       return this.readingProgression;
     }
 

package/src/publication/Profiles.ts

@@ -0,0 +1,15 @@
+/* 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.
+ */
+
+/**
+ * Registered profiles.
+ * https://readium.org/webpub-manifest/profiles/
+ */
+export 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/src/publication/Properties.ts

@@ -3,6 +3,12 @@
  * available in the LICENSE file present in the Github repository of the project.
  */
 
+export enum Page {
+  left = 'left',
+  right = 'right',
+  center = 'center'
+}
+
 /**
  * Properties associated to the linked resource.
  *
@@ -16,6 +22,10 @@ export class Properties {
     this.otherProperties = values;
   }
 
+  get page(): Page | undefined {
+    return this.otherProperties['page'] as Page | undefined;
+  }
+
   /**
    * Creates a [Properties] from its RWPM JSON representation.
    */

package/src/publication/Publication.ts

@@ -30,7 +30,7 @@ export class Publication {
   /** Identifies resources that are necessary for rendering the publication. */
   public readonly resources?: Links;
   /** Identifies the collection that contains a table of contents. */
-  public readonly tableOfContents?: Links;
+  public readonly toc?: Links;
   /** Identifies the collection that contains sub collections. */
   public readonly subcollections?: Map<string, Array<PublicationCollection>>;
 
@@ -42,7 +42,7 @@ export class Publication {
     this.links = values.manifest.links;
     this.readingOrder = values.manifest.readingOrder;
     this.resources = values.manifest.resources;
-    this.tableOfContents = values.manifest.tableOfContents;
+    this.toc = values.manifest.toc;
     this.subcollections = values.manifest.subcollections;
   }
 

package/src/publication/ReadingProgression.ts

@@ -3,26 +3,13 @@
  * available in the LICENSE file present in the Github repository of the project.
  */
 
-import { Page } from './presentation/Presentation';
+import { Page } from "./Properties";
 
 export enum ReadingProgression {
-  auto = 'auto',
-  btt = 'btt',
   ltr = 'ltr',
   rtl = 'rtl',
-  ttb = 'ttb',
 }
 
 export function leadingPage(readingProgression: ReadingProgression): Page {
-  switch (readingProgression) {
-    case ReadingProgression.auto:
-    case ReadingProgression.ttb:
-    case ReadingProgression.ltr:
-      return Page.left;
-    case ReadingProgression.rtl:
-    case ReadingProgression.btt:
-      return Page.right;
-    default:
-      return Page.left;
-  }
+  return readingProgression === ReadingProgression.rtl ? Page.right : Page.left;
 }

package/src/publication/TDM.ts

@@ -0,0 +1,56 @@
+/* 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.
+ */
+
+/**
+ * https://readium.org/webpub-manifest/contexts/default/#text-and-data-mining
+ */
+
+export enum TDMReservation {
+  all = 'all',
+  none = 'none'
+}
+
+export class TDM {
+  /**
+   * Indicates whether the publication allows text and data mining.
+   */
+  public readonly reservation?: TDMReservation;
+
+  /**
+   * Additional policy information about text and data mining usage.
+   */
+  public readonly policy?: string;
+
+  /** Creates a [TDM] object */
+  constructor(values: {
+    reservation?: TDMReservation;
+    policy?: string;
+  }) {
+    this.reservation = values.reservation;
+    this.policy = values.policy;
+  }
+
+  /**
+   * Parses a [TDM] from its RWPM JSON representation.
+   */
+  public static deserialize(json: any): TDM | undefined {
+    if (!json) return;
+    
+    return new TDM({
+      reservation: json.reservation as TDMReservation,
+      policy: json.policy,
+    });
+  }
+
+  /**
+   * Serializes a [TDM] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = {};
+    if (this.reservation !== undefined) json.reservation = this.reservation;
+    if (this.policy !== undefined) json.policy = this.policy;
+    return json;
+  }
+}