@readium/shared 2.2.0-alpha.2 → 2.2.0-beta.2

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/
      */
@@ -44,6 +52,12 @@ export declare class Publication {
      * Finds the first [Link] having the given [rel] in the publications's links.
      */
     linkWithRel(rel: string): Link | undefined;
+    /**
+     * Gets the cover image for the publication.
+     * First looks for rel='cover' in links/resources/readingOrder,
+     * then falls back to any image (JPEG, PNG, GIF, AVIF, SVG) as bitmap fallback.
+     */
+    getCover(): Link | undefined;
     positionsFromManifest(): Promise<Locator[]>;
     guideForLink(link: Link): Promise<GuidedNavigationDocument | undefined>;
     /**

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

@@ -41,11 +41,5 @@ declare module '../Locator' {
          * https://www.w3.org/TR/media-frags/
          */
         space(): [number, number, number, number] | undefined;
-        /**
-         * Text fragments, used by browsers to jump to/highlight text.
-         *
-         * https://developer.mozilla.org/en-US/docs/Web/URI/Fragment/Text_fragments
-         */
-        text(): string | undefined;
     }
 }

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,94 @@
+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;
+    /**
+     * Return the most relevant TOC Link for `bare` (used for `linkFor`).
+     * Prefers a start-of-resource entry; falls back to the first fragment entry.
+     */
+    private static findTocLink;
+    /**
+     * 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/src/util/mediatype/MediaType.d.ts

@@ -89,6 +89,7 @@ export declare class MediaType {
     static get ACSM(): MediaType;
     static get AIFF(): MediaType;
     static get AVI(): MediaType;
+    static get AVIF(): MediaType;
     static get BINARY(): MediaType;
     static get BMP(): MediaType;
     static get CBZ(): MediaType;

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 {};

package/LICENSE

@@ -1,28 +0,0 @@
-BSD 3-Clause License
-
-Copyright (c) 2022, Readium Foundation
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.