@readium/shared 2.3.0 → 2.4.0-alpha.1

package/src/publication/html/Locations.ts

@@ -2,81 +2,128 @@ import { LocatorLocations } from '../Locator.ts';
 import { DomRange } from './DomRange.ts';
 import { parseNptTime } from '../../util/npt.ts';
 
-// HTML extensions for LocatorLocations.
+// HTML extensions for [Locations].
 // https://github.com/readium/architecture/blob/master/models/locators/extensions/html.md
 
-export function getCssSelector(loc: LocatorLocations): string | undefined {
-  return loc.otherLocations?.get('cssSelector');
-}
+declare module '../Locator' {
+  export interface LocatorLocations {
+    /**
+     * A CSS Selector.
+     */
+    getCssSelector(): string | undefined;
 
-export function getPartialCfi(loc: LocatorLocations): string | undefined {
-  return loc.otherLocations?.get('partialCfi');
-}
+    /**
+     * [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;
 
-export function getDomRange(loc: LocatorLocations): DomRange | undefined {
-  return DomRange.deserialize(loc.otherLocations?.get('domRange'));
+    /**
+     * 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;
+  }
 }
 
-export function getFragmentParameters(loc: LocatorLocations): Map<string, string> {
+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(
-    loc.fragments
-      .map(f => f.startsWith('#') ? f.slice(1) : f)
-      .join('&')
-      .split('&')
-      .filter(f => !f.startsWith('#'))
-      .map(f => f.split('='))
+    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()])
+      .map(f => [
+        f[0].trim().toLowerCase(),
+        f[1].trim()
+      ])
   );
-}
+};
 
-export function getHtmlId(loc: LocatorLocations): string | undefined {
+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 (!loc.fragments.length) return;
-  let f = loc.fragments.find(f => f.length && !f.includes('='));
-  if (!f) {
-    const fp = getFragmentParameters(loc);
-    if (fp.has('id')) f = fp.get('id');
-    else if (fp.has('name')) f = fp.get('name');
+  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;
-}
+  return f?.startsWith("#") ? f.slice(1) : f;
+};
 
-export function getPage(loc: LocatorLocations): number | undefined {
-  const i = parseInt(getFragmentParameters(loc).get('page')!);
-  if (!isNaN(i) && i >= 0) return i;
+LocatorLocations.prototype.page = function(): number | undefined {
+  const i = parseInt(this.fragmentParameters().get("page")!);
+  if(!isNaN(i) && i >= 0) return i;
   return undefined;
 }
 
-export function getTime(loc: LocatorLocations): number | undefined {
-  const raw = getFragmentParameters(loc).get('t');
+LocatorLocations.prototype.time = function(): number | undefined {
+  const raw = this.fragmentParameters().get("t");
   if (!raw) return undefined;
   return parseNptTime(raw);
 }
 
-export function getSpace(loc: LocatorLocations): { unit: "pixel" | "percent"; x: number; y: number; width: number; height: number } | undefined {
-  const fp = getFragmentParameters(loc);
-  if (!fp.has('xywh')) return;
-
-  const raw = fp.get('xywh')!;
-  let unit: "pixel" | "percent" = "pixel";
-  let coords = raw;
-
-  const normalizedRaw = raw.toLowerCase();
-  if (normalizedRaw.startsWith("pixel:")) {
-    coords = raw.slice(6);
-  } else if (normalizedRaw.startsWith("percent:")) {
-    unit = "percent";
-    coords = raw.slice(8);
-  }
-
-  const parse = unit === "percent" ? parseFloat : (s: string) => parseInt(s, 10);
-  const parts = coords.split(",").map(parse);
-  if (parts.length !== 4 || parts.some(isNaN)) return;
-
-  const [x, y, width, height] = parts;
-  return { unit, x, y, width, height };
+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/opds/Properties.ts

@@ -3,37 +3,82 @@ import { positiveNumberfromJSON } from '../../util/JSONParse.ts';
 import { Link } from '../Link.ts';
 import { Properties } from '../Properties.ts';
 
-// OPDS extensions for link Properties.
+// OPDS extensions for link [Properties].
 // https://specs.opds.io/schema/properties.schema.json
 
-export function getNumberOfItems(properties: Properties): number | undefined {
-  return positiveNumberfromJSON(properties.otherProperties['numberOfItems']);
-}
+declare module '../Properties' {
+  export interface Properties {
+    /**
+     * Provides a hint about the expected number of items returned.
+     */
+    getNumberOfItems(): number | undefined;
+
+    /**
+     * The price of a publication is tied to its acquisition link.
+     */
+    getPrice(): Price | undefined;
+
+    /**
+     * Indirect acquisition provides a hint for the expected media type that will be acquired after
+     * additional steps.
+     */
+    getIndirectAcquisitions(): Array<Acquisition> | undefined;
+
+    /**
+     * Library-specific features when a specific book is unavailable but provides a hold list.
+     */
+    getHolds(): Holds | undefined;
 
-export function getPrice(properties: Properties): Price | undefined {
-  return Price.deserialize(properties.otherProperties['price']);
+    /**
+     * Library-specific feature that contains information about the copies that a library has acquired.
+     */
+    getCopies(): Copies | undefined;
+
+    /**
+     * Indicated the availability of a given resource.
+     */
+    getAvailability(): Availability | undefined;
+
+    /**
+     * Indicates that the linked resource supports authentication with the associated Authentication
+     * Document.
+     *
+     * See https://specs.opds.io/authentication-for-opds-1.0.html
+     */
+    getAuthenticate(): Link | undefined;
+  }
 }
 
-export function getIndirectAcquisitions(properties: Properties): Array<Acquisition> | undefined {
-  const json = properties.otherProperties['indirectAcquisition'];
+Properties.prototype.getNumberOfItems = function(): number | undefined {
+  return positiveNumberfromJSON(this.otherProperties['numberOfItems']);
+};
+
+Properties.prototype.getPrice = function(): Price | undefined {
+  return Price.deserialize(this.otherProperties['price']);
+};
+
+Properties.prototype.getIndirectAcquisitions = function():
+  | Array<Acquisition>
+  | undefined {
+  const json = this.otherProperties['indirectAcquisition'];
   if (!(json && Array.isArray(json))) return;
   return json
     .map<Acquisition>(item => Acquisition.deserialize(item) as Acquisition)
     .filter(x => x !== undefined);
-}
+};
 
-export function getHolds(properties: Properties): Holds | undefined {
-  return Holds.deserialize(properties.otherProperties['holds']);
-}
+Properties.prototype.getHolds = function(): Holds | undefined {
+  return Holds.deserialize(this.otherProperties['holds']);
+};
 
-export function getCopies(properties: Properties): Copies | undefined {
-  return Copies.deserialize(properties.otherProperties['copies']);
-}
+Properties.prototype.getCopies = function(): Copies | undefined {
+  return Copies.deserialize(this.otherProperties['copies']);
+};
 
-export function getAvailability(properties: Properties): Availability | undefined {
-  return Availability.deserialize(properties.otherProperties['availability']);
-}
+Properties.prototype.getAvailability = function(): Availability | undefined {
+  return Availability.deserialize(this.otherProperties['availability']);
+};
 
-export function getAuthenticate(properties: Properties): Link | undefined {
-  return Link.deserialize(properties.otherProperties['authenticate']);
-}
+Properties.prototype.getAuthenticate = function(): Link | undefined {
+  return Link.deserialize(this.otherProperties['authenticate']);
+};

package/src/publication/opds/Publication.ts

@@ -1,8 +1,14 @@
 import { Links } from '../Link.ts';
 import { Publication } from '../Publication.ts';
 
-// OPDS extensions for Publication.
+// OPDS extensions for [Publication]
 
-export function getImages(pub: Publication): Links | undefined {
-  return pub.linksWithRole('images');
+declare module '../Publication' {
+  export interface Publication {
+    getImages(): Links | undefined;
+  }
 }
+
+Publication.prototype.getImages = function(): Links | undefined {
+  return this.linksWithRole('images');
+};

package/src/publication/services/content/iterators/HTMLResourceContentIterator.ts

@@ -5,7 +5,6 @@ import { IllegalStateError, Iterator } from "../Iterator.ts";
 import { Attribute, AttributeKeys, AudioElement, Body, ContentElement, Footnote, Heading, ImageElement, TextElement, TextQuote, TextRole, TextSegment, VideoElement } from "../element/index.ts";
 import { appendNormalizedWhitespace, elementLanguage, isBlank, isInlineTag, srcRelativeToHref, trimUnicodeSpace, trimUnicodeSpaceEnd, trimUnicodeSpaceStart, trimmingTextLocator } from "./helpers.ts";
 import { getCssSelector } from "css-selector-generator";
-import { getCssSelector as locatorCssSelector } from "../../../html/Locations.ts";
 
 interface ElementWithDelta {
     element: ContentElement;
@@ -94,11 +93,10 @@ export class HTMLResourceContentIterator extends Iterator {
     private async parseElements(): Promise<ParsedElementRecipes> {
         const raw = await this.resource.readAsString();
         const doc = (new DOMParser()).parseFromString(raw!, this.locator.type as DOMParserSupportedType);
-        const startSel = locatorCssSelector(this.locator.locations);
         this.parser = new ContentParser(
             doc,
             this.locator,
-            startSel ? doc.querySelector(startSel) as Element : null,
+            this.locator.locations.getCssSelector() ? doc.querySelector(this.locator.locations.getCssSelector()!) as Element : null,
             this.beforeMaxLength
         );