@readium/shared 2.2.0-beta.1 → 2.2.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readium/shared",
-  "version": "2.2.0-beta.1",
+  "version": "2.2.0-beta.3",
   "type": "module",
   "description": "Shared models to be used across other Readium projects and implementations in Typescript",
   "author": "readium",

package/src/publication/Publication.ts

@@ -13,6 +13,7 @@ import { Resource } from '../fetcher/Resource';
 import { GuidedNavigationDocument } from "./GuidedNavigation";
 import { URITemplate } from "../util";
 import { MediaType } from "../util/mediatype/MediaType";
+import { Timeline } from './services/timeline/Timeline';
 
 export type ServiceFactory = () => null;
 
@@ -21,6 +22,7 @@ export class Publication {
   /** The manifest holding the publication metadata extracted from the publication file */
   public manifest: Manifest;
   private readonly fetcher: Fetcher = new EmptyFetcher();
+  private _timeline: Timeline | undefined;
 
   // Shortcuts to manifest properties
   public readonly context?: Array<string>;
@@ -47,6 +49,16 @@ export class Publication {
     this.subcollections = values.manifest.subcollections;
   }
 
+  /**
+   * Returns the publication's timeline, built from its reading order and table of contents.
+   * Called with no arguments, the result is cached. Pass options to build a fresh timeline
+   * with a specific configuration (e.g. a depth limit).
+   */
+  public get timeline(): Timeline {
+    if (!this._timeline) this._timeline = Timeline.build(this);
+    return this._timeline;
+  }
+
   /** 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/
    */

package/src/publication/services/index.ts

@@ -1 +1,2 @@
-export * from './content';
+export * from './content';
+export * from './timeline';

package/src/publication/services/timeline/Timeline.ts

@@ -0,0 +1,335 @@
+import { Link, Links } from "../../Link";
+import { Locator } from "../../Locator";
+import { TimelineItem } from "./TimelineItem";
+
+interface PublicationLike {
+    toc?: Links;
+    readingOrder: Links;
+}
+
+/**
+ * A publication's timeline, built once from its reading order and table of contents.
+ *
+ * **Source of truth**: the reading order.  Every reading order item becomes
+ * exactly one top-level `TimelineItem`.  The TOC is consulted to:
+ *   1. Derive a display title when the reading order item has none.
+ *   2. Populate flat children — all TOC fragment entries that reference the
+ *      resource, collected depth-first in TOC declaration order.
+ *
+ * No TOC hierarchy is reconstructed; that requires role context and is not yet
+ * implemented.  TOC entries whose href does not match any reading order item
+ * are ignored.
+ *
+ * The `depth` build option limits how many levels deep into the TOC tree both
+ * title resolution and child collection may look.  Level 1 = top-level TOC
+ * entries; level 2 = their children; etc.  `undefined` means no limit.
+ */
+export class Timeline {
+    private readonly _allItems: TimelineItem[];
+    private readonly linkMap: Map<TimelineItem, Link>;
+    private _depth: number | undefined;
+    private _items: TimelineItem[] | undefined;
+    private _flat: TimelineItem[] | undefined;
+
+    constructor(items: TimelineItem[], linkMap: Map<TimelineItem, Link>) {
+        this._allItems = items;
+        this.linkMap = linkMap;
+    }
+
+    static build(publication: PublicationLike, options: { depth?: number } = {}): Timeline {
+        const tocLinks = publication.toc?.items ?? [];
+        const roLinks = publication.readingOrder.items;
+        const { depth } = options;
+        const linkMap = new Map<TimelineItem, Link>();
+        const items: TimelineItem[] = [];
+
+        for (let i = 0; i < roLinks.length; i++) {
+            const ro = roLinks[i];
+            const bare = Timeline.bareHref(ro.href);
+
+            const title =
+                ro.title ??
+                Timeline.findTitleInToc(tocLinks, bare, depth) ??
+                `Resource ${i + 1}`;
+
+            const tocChildren = Timeline.collectChildrenFromToc(tocLinks, bare, depth, 1, linkMap);
+
+            const item: TimelineItem = {
+                title,
+                references: [ro.href],
+                children: tocChildren.length > 0 ? tocChildren : undefined,
+            };
+
+            linkMap.set(item, ro);
+            items.push(item);
+        }
+
+        return new Timeline(items, linkMap);
+    }
+
+    /**
+     * The active depth limit for TOC traversal (title resolution and child
+     * collection).  `undefined` means unlimited.  Setting the same value again
+     * is a no-op; a new value invalidates the cached items and flat list.
+     */
+    get depth(): number | undefined {
+        return this._depth;
+    }
+
+    set depth(value: number | undefined) {
+        if (this._depth === value) return;
+        this._depth = value;
+        this._items = undefined;
+        this._flat = undefined;
+    }
+
+    /** Top-level timeline items.  Cached; invalidated when `depth` changes. */
+    get items(): TimelineItem[] {
+        if (!this._items) {
+            this._items = this._depth !== undefined
+                ? Timeline.trimToDepth(this._allItems, this._depth)
+                : this._allItems;
+        }
+        return this._items;
+    }
+
+    locate(locator: Locator): TimelineItem | undefined {
+        const href = locator.href.split("#")[0];
+        const time = locator.locations?.time();
+
+        let match: TimelineItem | undefined;
+
+        if (time !== undefined) {
+            for (const item of this.flat) {
+                if (this.itemMatchesTime(item, href, time)) match = item;
+            }
+        }
+
+        if (!match) {
+            match = this.flat.find(item => this.bareHrefFromItem(item) === href);
+        }
+
+        return match;
+    }
+
+    adjacentTo(item: TimelineItem): { previous: TimelineItem | undefined; next: TimelineItem | undefined } {
+        const index = this.flat.indexOf(item);
+        return {
+            previous: index > 0 ? this.flat[index - 1] : undefined,
+            next: index >= 0 && index < this.flat.length - 1 ? this.flat[index + 1] : undefined,
+        };
+    }
+
+    segmentsForHref(href: string): TimelineItem[] {
+        const bare = href.split("#")[0];
+        const item = this.items.find(i => this.bareHrefFromItem(i) === bare);
+        if (!item) return [];
+        return item.children?.length ? item.children : [item];
+    }
+
+    itemAtProgression(href: string, progression: number, duration?: number): TimelineItem | undefined {
+        const bare = href.split("#")[0];
+        const item = this.items.find(i => this.bareHrefFromItem(i) === bare);
+        if (!item) return undefined;
+        if (!item.children?.length) return item;
+
+        if (duration !== undefined) {
+            const time = progression * duration;
+            let match: TimelineItem = item;
+            for (const child of item.children) {
+                const t = this.timeFromItem(child);
+                if (t === undefined || t > time) break;
+                match = child;
+            }
+            return match;
+        }
+
+        const index = Math.min(Math.floor(progression * item.children.length), item.children.length - 1);
+        return item.children[index];
+    }
+
+    ancestors(item: TimelineItem): TimelineItem[] {
+        return this.ancestorPath(this.items, item) ?? [];
+    }
+
+    linkFor(item: TimelineItem): Link | undefined {
+        return this.linkMap.get(item);
+    }
+
+    private get flat(): TimelineItem[] {
+        if (!this._flat) this._flat = this.flattenItems(this.items);
+        return this._flat;
+    }
+
+    // -------------------------------------------------------------------------
+    // TOC title resolution
+    // -------------------------------------------------------------------------
+
+    /**
+     * Resolve a display title for `bare` from the TOC, looking no deeper than
+     * `maxDepth` levels (1 = top-level entries only).  Priority:
+     *   1. A start-of-resource entry: bare href or `#t=0` (audio).
+     *   2. Exactly one fragment entry referencing this resource — unambiguous.
+     *   3. Multiple fragment entries — ambiguous, returns `undefined`.
+     */
+    private static findTitleInToc(
+        tocLinks: Link[],
+        bare: string,
+        maxDepth: number | undefined,
+    ): string | undefined {
+        const { atStart, fragments } = Timeline.collectTocCandidates(tocLinks, bare, maxDepth, 1);
+        if (atStart.length > 0) return atStart[0].title!;
+        if (fragments.length === 1) return fragments[0].title!;
+        return undefined;
+    }
+
+    /**
+     * Collect all TOC entries that reference `bare` as flat children, walking
+     * up to `maxDepth` levels deep.  Start-of-resource entries (#t=0 or no
+     * fragment) are excluded — they contribute to title resolution, not children.
+     * Order follows TOC declaration (depth-first).
+     */
+    private static collectChildrenFromToc(
+        tocLinks: Link[],
+        bare: string,
+        maxDepth: number | undefined,
+        currentDepth: number,
+        linkMap: Map<TimelineItem, Link>,
+    ): TimelineItem[] {
+        if (maxDepth !== undefined && currentDepth > maxDepth) return [];
+
+        const result: TimelineItem[] = [];
+
+        for (const link of tocLinks) {
+            if (Timeline.bareHref(link.href) === bare && link.title && !Timeline.isStartOfResource(link.href)) {
+                const child: TimelineItem = { title: link.title, references: [link.href] };
+                linkMap.set(child, link);
+                result.push(child);
+            }
+
+            if (link.children?.items?.length) {
+                result.push(...Timeline.collectChildrenFromToc(
+                    link.children.items, bare, maxDepth, currentDepth + 1, linkMap,
+                ));
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Walk the TOC tree up to `maxDepth` levels and collect all entries whose
+     * bare href matches `bare`, split into start-of-resource entries and
+     * fragment entries.
+     */
+    private static collectTocCandidates(
+        tocLinks: Link[],
+        bare: string,
+        maxDepth: number | undefined,
+        currentDepth: number,
+    ): { atStart: Link[]; fragments: Link[] } {
+        if (maxDepth !== undefined && currentDepth > maxDepth) {
+            return { atStart: [], fragments: [] };
+        }
+
+        const atStart: Link[] = [];
+        const fragments: Link[] = [];
+
+        for (const link of tocLinks) {
+            if (Timeline.bareHref(link.href) === bare && link.title) {
+                if (Timeline.isStartOfResource(link.href)) {
+                    atStart.push(link);
+                } else {
+                    fragments.push(link);
+                }
+            }
+
+            if (link.children?.items?.length) {
+                const child = Timeline.collectTocCandidates(
+                    link.children.items, bare, maxDepth, currentDepth + 1,
+                );
+                atStart.push(...child.atStart);
+                fragments.push(...child.fragments);
+            }
+        }
+
+        return { atStart, fragments };
+    }
+
+    /**
+     * A TOC href points to the start of its resource when it has no fragment,
+     * or when the fragment is `t=0` (audio: explicit beginning of the file).
+     */
+    private static isStartOfResource(href: string): boolean {
+        const fragment = href.split("#")[1];
+        if (!fragment) return true;
+        return fragment === "t=0";
+    }
+
+    // -------------------------------------------------------------------------
+    // Shared utilities
+    // -------------------------------------------------------------------------
+
+    private static trimToDepth(items: TimelineItem[], remaining: number): TimelineItem[] {
+        return items.map(item => ({
+            ...item,
+            children: remaining > 1 && item.children?.length
+                ? Timeline.trimToDepth(item.children, remaining - 1)
+                : undefined,
+        }));
+    }
+
+    private flattenItems(items: TimelineItem[]): TimelineItem[] {
+        const result: TimelineItem[] = [];
+        for (const item of items) {
+            result.push(item);
+            if (item.children) result.push(...this.flattenItems(item.children));
+        }
+        return result;
+    }
+
+    private itemMatchesTime(item: TimelineItem, href: string, time: number): boolean {
+        for (const ref of item.references) {
+            const hashIndex = ref.indexOf("#");
+            const refHref = hashIndex >= 0 ? ref.slice(0, hashIndex) : ref;
+            const refFragment = hashIndex >= 0 ? ref.slice(hashIndex + 1) : undefined;
+            if ((refHref || href) !== href) continue;
+            if (time >= Timeline.parseTimeFragment(refFragment)) return true;
+        }
+        return false;
+    }
+
+    private static parseTimeFragment(fragment: string | undefined): number {
+        if (!fragment) return 0;
+        const match = fragment.match(/(?:^|&)t=(\d+(?:\.\d+)?)/);
+        return match ? parseFloat(match[1]) : 0;
+    }
+
+    private bareHrefFromItem(item: TimelineItem): string {
+        return (item.references[0] ?? "").split("#")[0];
+    }
+
+    private timeFromItem(item: TimelineItem): number | undefined {
+        const ref = item.references[0];
+        if (!ref) return undefined;
+        const fragment = ref.split("#")[1];
+        if (!fragment) return undefined;
+        const match = fragment.match(/(?:^|&)t=(\d+(?:\.\d+)?)/);
+        return match ? parseFloat(match[1]) : undefined;
+    }
+
+    private ancestorPath(items: TimelineItem[], target: TimelineItem): TimelineItem[] | null {
+        for (const item of items) {
+            if (item === target) return [];
+            if (item.children) {
+                const path = this.ancestorPath(item.children, target);
+                if (path !== null) return [item, ...path];
+            }
+        }
+        return null;
+    }
+
+    private static bareHref(href: string): string {
+        return href.split("#")[0];
+    }
+}

package/src/publication/services/timeline/TimelineItem.ts

@@ -0,0 +1,24 @@
+/**
+ * Represents a single entry in a publication's timeline.
+ *
+ * The timeline contextualizes the reading order and table of contents so that
+ * consuming apps can display the current chapter title, build a progress bar,
+ * show previous/next as chapter titles, group search results by chapter, etc.
+ */
+export interface TimelineItem {
+    /** Display title of this entry. */
+    title: string;
+    /**
+     * References as hrefs with optional fragments.
+     * e.g. ["track1.mp3#t=60"] for audio, ["chapter1.html"] for EPUB, ["#page=6"] for PDF.
+     */
+    references: string[];
+    /** Structural roles of this entry, e.g. ["chapter"], ["part"]. */
+    role?: string[];
+    /** Position number in the reading order context. */
+    position?: number;
+    /** Scroll progression within the resource (0 to 1), for entries that start mid-way in a resource. */
+    scroll?: number;
+    /** Nested entries. */
+    children?: TimelineItem[];
+}

package/src/publication/services/timeline/index.ts

@@ -0,0 +1,2 @@
+export * from './Timeline';
+export * from './TimelineItem';

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

@@ -6,12 +6,14 @@ import { Fetcher } from '../fetcher/Fetcher';
 import { PublicationCollection } from './PublicationCollection';
 import { Resource } from '../fetcher/Resource';
 import { GuidedNavigationDocument } from "./GuidedNavigation";
+import { Timeline } from './services/timeline/Timeline';
 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;
+    private _timeline;
     readonly context?: Array<string>;
     readonly metadata: Metadata;
     readonly links: Links;
@@ -27,6 +29,12 @@ export declare class Publication {
         manifest: Manifest;
         fetcher?: Fetcher;
     });
+    /**
+     * Returns the publication's timeline, built from its reading order and table of contents.
+     * Called with no arguments, the result is cached. Pass options to build a fresh timeline
+     * with a specific configuration (e.g. a depth limit).
+     */
+    get timeline(): Timeline;
     /** 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/
      */

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

@@ -1 +1,2 @@
 export * from './content';
+export * from './timeline';

package/types/src/publication/services/timeline/Timeline.d.ts

@@ -0,0 +1,89 @@
+import { Link, Links } from "../../Link";
+import { Locator } from "../../Locator";
+import { TimelineItem } from "./TimelineItem";
+interface PublicationLike {
+    toc?: Links;
+    readingOrder: Links;
+}
+/**
+ * A publication's timeline, built once from its reading order and table of contents.
+ *
+ * **Source of truth**: the reading order.  Every reading order item becomes
+ * exactly one top-level `TimelineItem`.  The TOC is consulted to:
+ *   1. Derive a display title when the reading order item has none.
+ *   2. Populate flat children — all TOC fragment entries that reference the
+ *      resource, collected depth-first in TOC declaration order.
+ *
+ * No TOC hierarchy is reconstructed; that requires role context and is not yet
+ * implemented.  TOC entries whose href does not match any reading order item
+ * are ignored.
+ *
+ * The `depth` build option limits how many levels deep into the TOC tree both
+ * title resolution and child collection may look.  Level 1 = top-level TOC
+ * entries; level 2 = their children; etc.  `undefined` means no limit.
+ */
+export declare class Timeline {
+    private readonly _allItems;
+    private readonly linkMap;
+    private _depth;
+    private _items;
+    private _flat;
+    constructor(items: TimelineItem[], linkMap: Map<TimelineItem, Link>);
+    static build(publication: PublicationLike, options?: {
+        depth?: number;
+    }): Timeline;
+    /**
+     * The active depth limit for TOC traversal (title resolution and child
+     * collection).  `undefined` means unlimited.  Setting the same value again
+     * is a no-op; a new value invalidates the cached items and flat list.
+     */
+    get depth(): number | undefined;
+    set depth(value: number | undefined);
+    /** Top-level timeline items.  Cached; invalidated when `depth` changes. */
+    get items(): TimelineItem[];
+    locate(locator: Locator): TimelineItem | undefined;
+    adjacentTo(item: TimelineItem): {
+        previous: TimelineItem | undefined;
+        next: TimelineItem | undefined;
+    };
+    segmentsForHref(href: string): TimelineItem[];
+    itemAtProgression(href: string, progression: number, duration?: number): TimelineItem | undefined;
+    ancestors(item: TimelineItem): TimelineItem[];
+    linkFor(item: TimelineItem): Link | undefined;
+    private get flat();
+    /**
+     * Resolve a display title for `bare` from the TOC, looking no deeper than
+     * `maxDepth` levels (1 = top-level entries only).  Priority:
+     *   1. A start-of-resource entry: bare href or `#t=0` (audio).
+     *   2. Exactly one fragment entry referencing this resource — unambiguous.
+     *   3. Multiple fragment entries — ambiguous, returns `undefined`.
+     */
+    private static findTitleInToc;
+    /**
+     * Collect all TOC entries that reference `bare` as flat children, walking
+     * up to `maxDepth` levels deep.  Start-of-resource entries (#t=0 or no
+     * fragment) are excluded — they contribute to title resolution, not children.
+     * Order follows TOC declaration (depth-first).
+     */
+    private static collectChildrenFromToc;
+    /**
+     * Walk the TOC tree up to `maxDepth` levels and collect all entries whose
+     * bare href matches `bare`, split into start-of-resource entries and
+     * fragment entries.
+     */
+    private static collectTocCandidates;
+    /**
+     * A TOC href points to the start of its resource when it has no fragment,
+     * or when the fragment is `t=0` (audio: explicit beginning of the file).
+     */
+    private static isStartOfResource;
+    private static trimToDepth;
+    private flattenItems;
+    private itemMatchesTime;
+    private static parseTimeFragment;
+    private bareHrefFromItem;
+    private timeFromItem;
+    private ancestorPath;
+    private static bareHref;
+}
+export {};

package/types/src/publication/services/timeline/TimelineItem.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Represents a single entry in a publication's timeline.
+ *
+ * The timeline contextualizes the reading order and table of contents so that
+ * consuming apps can display the current chapter title, build a progress bar,
+ * show previous/next as chapter titles, group search results by chapter, etc.
+ */
+export interface TimelineItem {
+    /** Display title of this entry. */
+    title: string;
+    /**
+     * References as hrefs with optional fragments.
+     * e.g. ["track1.mp3#t=60"] for audio, ["chapter1.html"] for EPUB, ["#page=6"] for PDF.
+     */
+    references: string[];
+    /** Structural roles of this entry, e.g. ["chapter"], ["part"]. */
+    role?: string[];
+    /** Position number in the reading order context. */
+    position?: number;
+    /** Scroll progression within the resource (0 to 1), for entries that start mid-way in a resource. */
+    scroll?: number;
+    /** Nested entries. */
+    children?: TimelineItem[];
+}

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

@@ -0,0 +1,2 @@
+export * from './Timeline';
+export * from './TimelineItem';

package/types/test/AltIdentifier.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/Contributor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/GuidedNavigation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/Link.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/LocalizedString.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/Locator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/LocatorCollection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/Manifest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/Metadata.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/Properties.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/Publication.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/PublicationCollection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/Subject.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/TDM.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/Timeline.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/accessibility/Accessibility.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/accessibility/AccessibilityMetadataDisplayGuide.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/accessibility/Localization.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/encryption/Encryption.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/encryption/Properties.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/epub/MediaOverlay.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/epub/Metadata.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/epub/PropertiesTest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/epub/PublicationTest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/html/DomRange.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/html/Locator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/opds/PropertiesTest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/opds/PublicationTest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/util/URITemplate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/test/util/mediatype/MediaType.test.d.ts

@@ -0,0 +1 @@
+export {};