@readium/navigator-html-injectables 1.2.0

package/src/vendor/hypothesis/anchoring/html.ts

@@ -0,0 +1,134 @@
+import type {
+  MediaTimeSelector,
+  RangeSelector,
+  Selector,
+  TextPositionSelector,
+  TextQuoteSelector,
+} from './api-types';
+import {
+  MediaTimeAnchor,
+  RangeAnchor,
+  TextPositionAnchor,
+  TextQuoteAnchor,
+} from './types';
+
+type Options = {
+  hint?: number;
+};
+
+async function querySelector(
+  anchor: MediaTimeAnchor | RangeAnchor | TextPositionAnchor | TextQuoteAnchor,
+  options: Options
+) {
+  return anchor.toRange(options);
+}
+
+/**
+ * Anchor a set of selectors.
+ *
+ * This function converts a set of selectors into a document range.
+ * It encapsulates the core anchoring algorithm, using the selectors alone or
+ * in combination to establish the best anchor within the document.
+ *
+ * @param root - The root element of the anchoring context
+ * @param selectors - The selectors to try
+ */
+export function anchor(
+  root: Element,
+  selectors: Selector[],
+  options: Options = {}
+) {
+  let mediaTime: MediaTimeSelector | null = null;
+  let position: TextPositionSelector | null = null;
+  let quote: TextQuoteSelector | null = null;
+  let range: RangeSelector | null = null;
+
+  // Collect all the selectors
+  for (const selector of selectors) {
+    switch (selector.type) {
+      case 'TextPositionSelector':
+        position = selector;
+        options.hint = position.start; // TextQuoteAnchor hint
+        break;
+      case 'TextQuoteSelector':
+        quote = selector;
+        break;
+      case 'RangeSelector':
+        range = selector;
+        break;
+      case 'MediaTimeSelector':
+        mediaTime = selector;
+        break;
+    }
+  }
+
+  /**
+   * Assert the quote matches the stored quote, if applicable
+   */
+  const maybeAssertQuote = (range: Range) => {
+    if (quote?.exact && range.toString() !== quote.exact) {
+      throw new Error('quote mismatch');
+    } else {
+      return range;
+    }
+  };
+
+  // From a default of failure, we build up catch clauses to try selectors in
+  // order, from simple to complex.
+  let promise: Promise<Range> = Promise.reject('unable to anchor');
+
+  if (range) {
+    // Const binding assures TS that it won't be re-assigned when callback runs.
+    const range_ = range;
+    promise = promise.catch(() => {
+      const anchor = RangeAnchor.fromSelector(root, range_);
+      return querySelector(anchor, options).then(maybeAssertQuote);
+    });
+  }
+
+  if (position) {
+    const position_ = position;
+    promise = promise.catch(() => {
+      const anchor = TextPositionAnchor.fromSelector(root, position_);
+      return querySelector(anchor, options).then(maybeAssertQuote);
+    });
+  }
+
+  if (quote) {
+    const quote_ = quote;
+    promise = promise.catch(() => {
+      const anchor = TextQuoteAnchor.fromSelector(root, quote_);
+      return querySelector(anchor, options);
+    });
+  }
+
+  if (mediaTime) {
+    const mediaTime_ = mediaTime;
+    promise = promise.catch(() =>
+      MediaTimeAnchor.fromSelector(root, mediaTime_).toRange()
+    );
+  }
+
+  return promise;
+}
+
+export function describe(root: Element, range: Range) {
+  const types = [
+    MediaTimeAnchor,
+    RangeAnchor,
+    TextPositionAnchor,
+    TextQuoteAnchor,
+  ];
+  const result = [];
+  for (const type of types) {
+    try {
+      const anchor = type.fromRange(root, range);
+      if (anchor) {
+        result.push(anchor.toSelector());
+      }
+    } catch (error) {
+      // If resolving some anchor fails, we just want to skip it silently
+    }
+  }
+  return result;
+}

package/src/vendor/hypothesis/anchoring/match-quote.ts

@@ -0,0 +1,163 @@
+import approxSearch from '../../approx-string-match';
+import type { Match as StringMatch } from '../../approx-string-match';
+
+type Match = {
+  /** Start offset of match in text */
+  start: number;
+  /** End offset of match in text */
+  end: number;
+
+  /**
+   * Score for the match between 0 and 1.0, where 1.0 indicates a perfect match
+   * for the quote and context.
+   */
+  score: number;
+};
+
+/**
+ * Find the best approximate matches for `str` in `text` allowing up to
+ * `maxErrors` errors.
+ */
+function search(text: string, str: string, maxErrors: number): StringMatch[] {
+  // Do a fast search for exact matches. The `approx-string-match` library
+  // doesn't currently incorporate this optimization itself.
+  let matchPos = 0;
+  const exactMatches: StringMatch[] = [];
+  while (matchPos !== -1) {
+    matchPos = text.indexOf(str, matchPos);
+    if (matchPos !== -1) {
+      exactMatches.push({
+        start: matchPos,
+        end: matchPos + str.length,
+        errors: 0,
+      });
+      matchPos += 1;
+    }
+  }
+  if (exactMatches.length > 0) {
+    return exactMatches;
+  }
+
+  // If there are no exact matches, do a more expensive search for matches
+  // with errors.
+  return approxSearch(text, str, maxErrors);
+}
+
+/**
+ * Compute a score between 0 and 1.0 for the similarity between `text` and `str`.
+ */
+function textMatchScore(text: string, str: string) {
+  // `search` will return no matches if either the text or pattern is empty,
+  // otherwise it will return at least one match if the max allowed error count
+  // is at least `str.length`.
+  if (str.length === 0 || text.length === 0) {
+    return 0.0;
+  }
+
+  const matches = search(text, str, str.length);
+
+  // prettier-ignore
+  return 1 - (matches[0].errors / str.length);
+}
+
+type Context = {
+  /** Expected text before the quote */
+  prefix?: string;
+  /** Expected text after the quote */
+  suffix?: string;
+  /** Expected offset of match within text */
+  hint?: number;
+};
+
+/**
+ * Find the best approximate match for `quote` in `text`.
+ *
+ * @param text - Document text to search
+ * @param quote - String to find within `text`
+ * @param context - Context in which the quote originally appeared. This is
+ *        used to choose the best match.
+ * @return `null` if no match exceeding the minimum quality threshold was found.
+ */
+export function matchQuote(
+  text: string,
+  quote: string,
+  context: Context = {}
+): Match | null {
+  if (quote.length === 0) {
+    return null;
+  }
+
+  // Choose the maximum number of errors to allow for the initial search.
+  // This choice involves a tradeoff between:
+  //
+  //  - Recall (proportion of "good" matches found)
+  //  - Precision (proportion of matches found which are "good")
+  //  - Cost of the initial search and of processing the candidate matches [1]
+  //
+  // [1] Specifically, the expected-time complexity of the initial search is
+  //     `O((maxErrors / 32) * text.length)`. See `approx-string-match` docs.
+  const maxErrors = Math.min(256, quote.length / 2);
+
+  // Find the closest matches for `quote` in `text` based on edit distance.
+  const matches = search(text, quote, maxErrors);
+
+  if (matches.length === 0) {
+    return null;
+  }
+
+  /**
+   * Compute a score between 0 and 1.0 for a match candidate.
+   */
+  const scoreMatch = (match: StringMatch) => {
+    const quoteWeight = 50; // Similarity of matched text to quote.
+    const prefixWeight = 20; // Similarity of text before matched text to `context.prefix`.
+    const suffixWeight = 20; // Similarity of text after matched text to `context.suffix`.
+    const posWeight = 2; // Proximity to expected location. Used as a tie-breaker.
+
+    const quoteScore = 1 - match.errors / quote.length;
+
+    const prefixScore = context.prefix
+      ? textMatchScore(
+          text.slice(
+            Math.max(0, match.start - context.prefix.length),
+            match.start
+          ),
+          context.prefix
+        )
+      : 1.0;
+    const suffixScore = context.suffix
+      ? textMatchScore(
+          text.slice(match.end, match.end + context.suffix.length),
+          context.suffix
+        )
+      : 1.0;
+
+    let posScore = 1.0;
+    if (typeof context.hint === 'number') {
+      const offset = Math.abs(match.start - context.hint);
+      posScore = 1.0 - offset / text.length;
+    }
+
+    const rawScore =
+      quoteWeight * quoteScore +
+      prefixWeight * prefixScore +
+      suffixWeight * suffixScore +
+      posWeight * posScore;
+    const maxScore = quoteWeight + prefixWeight + suffixWeight + posWeight;
+    const normalizedScore = rawScore / maxScore;
+
+    return normalizedScore;
+  };
+
+  // Rank matches based on similarity of actual and expected surrounding text
+  // and actual/expected offset in the document text.
+  const scoredMatches = matches.map(m => ({
+    start: m.start,
+    end: m.end,
+    score: scoreMatch(m),
+  }));
+
+  // Choose match with the highest score.
+  scoredMatches.sort((a, b) => b.score - a.score);
+  return scoredMatches[0];
+}

package/src/vendor/hypothesis/anchoring/placeholder.ts

@@ -0,0 +1,59 @@
+/**
+ * CSS selector that will match the placeholder within a page/tile container.
+ */
+const placeholderSelector = '.annotator-placeholder';
+
+/**
+ * Create or return a placeholder element for anchoring.
+ *
+ * In document viewers such as PDF.js which only render a subset of long
+ * documents at a time, it may not be possible to anchor annotations to the
+ * actual text in pages which are off-screen. For these non-rendered pages,
+ * a "placeholder" element is created in the approximate X/Y location (eg.
+ * middle of the page) where the content will appear. Any highlights for that
+ * page are then rendered inside the placeholder.
+ *
+ * When the viewport is scrolled to the non-rendered page, the placeholder
+ * is removed and annotations are re-anchored to the real content.
+ *
+ * @param container - The container element for the page or tile which is not
+ *   rendered.
+ */
+export function createPlaceholder(container: HTMLElement) {
+  let placeholder = container.querySelector(placeholderSelector);
+  if (placeholder) {
+    return placeholder;
+  }
+  placeholder = document.createElement('span');
+  placeholder.classList.add('annotator-placeholder');
+  placeholder.textContent = 'Loading annotations...';
+  container.appendChild(placeholder);
+  return placeholder;
+}
+
+/**
+ * Return true if a page/tile container has a placeholder.
+ */
+export function hasPlaceholder(container: HTMLElement): boolean {
+  return container.querySelector(placeholderSelector) !== null;
+}
+
+/**
+ * Remove the placeholder element in `container`, if present.
+ */
+export function removePlaceholder(container: HTMLElement) {
+  container.querySelector(placeholderSelector)?.remove();
+}
+
+/**
+ * Return true if `node` is inside a placeholder element created with `createPlaceholder`.
+ *
+ * This is typically used to test if a highlight element associated with an
+ * anchor is inside a placeholder.
+ */
+export function isInPlaceholder(node: Node): boolean {
+  if (!node.parentElement) {
+    return false;
+  }
+  return node.parentElement.closest(placeholderSelector) !== null;
+}

package/src/vendor/hypothesis/anchoring/text-range.ts

@@ -0,0 +1,327 @@
+import { trimRange } from './trim-range';
+
+/**
+ * Return the combined length of text nodes contained in `node`.
+ */
+function nodeTextLength(node: Node): number {
+  switch (node.nodeType) {
+    case Node.ELEMENT_NODE:
+    case Node.TEXT_NODE:
+      // nb. `textContent` excludes text in comments and processing instructions
+      // when called on a parent element, so we don't need to subtract that here.
+
+      return node.textContent?.length ?? 0;
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Return the total length of the text of all previous siblings of `node`.
+ */
+function previousSiblingsTextLength(node: Node): number {
+  let sibling = node.previousSibling;
+  let length = 0;
+  while (sibling) {
+    length += nodeTextLength(sibling);
+    sibling = sibling.previousSibling;
+  }
+  return length;
+}
+
+/**
+ * Resolve one or more character offsets within an element to (text node,
+ * position) pairs.
+ *
+ * @param element
+ * @param offsets - Offsets, which must be sorted in ascending order
+ * @throws {RangeError}
+ */
+function resolveOffsets(
+  element: Element,
+  ...offsets: number[]
+): Array<{ node: Text; offset: number }> {
+  let nextOffset = offsets.shift();
+  const nodeIter = element.ownerDocument.createNodeIterator(
+    element,
+    NodeFilter.SHOW_TEXT
+  );
+  const results = [];
+
+  let currentNode = nodeIter.nextNode() as Text | null;
+  let textNode;
+  let length = 0;
+
+  // Find the text node containing the `nextOffset`th character from the start
+  // of `element`.
+  while (nextOffset !== undefined && currentNode) {
+    textNode = currentNode;
+    if (length + textNode.data.length > nextOffset) {
+      results.push({ node: textNode, offset: nextOffset - length });
+      nextOffset = offsets.shift();
+    } else {
+      currentNode = nodeIter.nextNode() as Text | null;
+      length += textNode.data.length;
+    }
+  }
+
+  // Boundary case.
+  while (nextOffset !== undefined && textNode && length === nextOffset) {
+    results.push({ node: textNode, offset: textNode.data.length });
+    nextOffset = offsets.shift();
+  }
+
+  if (nextOffset !== undefined) {
+    throw new RangeError('Offset exceeds text length');
+  }
+
+  return results;
+}
+
+/**
+ * When resolving a TextPosition, specifies the direction to search for the
+ * nearest text node if `offset` is `0` and the element has no text.
+ */
+export enum ResolveDirection {
+  FORWARDS = 1,
+  BACKWARDS,
+}
+
+/**
+ * Represents an offset within the text content of an element.
+ *
+ * This position can be resolved to a specific descendant node in the current
+ * DOM subtree of the element using the `resolve` method.
+ */
+export class TextPosition {
+  public element: Element;
+  public offset: number;
+
+  constructor(element: Element, offset: number) {
+    if (offset < 0) {
+      throw new Error('Offset is invalid');
+    }
+
+    /** Element that `offset` is relative to. */
+    this.element = element;
+
+    /** Character offset from the start of the element's `textContent`. */
+    this.offset = offset;
+  }
+
+  /**
+   * Return a copy of this position with offset relative to a given ancestor
+   * element.
+   *
+   * @param parent - Ancestor of `this.element`
+   */
+  relativeTo(parent: Element): TextPosition {
+    if (!parent.contains(this.element)) {
+      throw new Error('Parent is not an ancestor of current element');
+    }
+
+    let el = this.element;
+    let offset = this.offset;
+    while (el !== parent) {
+      offset += previousSiblingsTextLength(el);
+      el = el.parentElement!;
+    }
+
+    return new TextPosition(el, offset);
+  }
+
+  /**
+   * Resolve the position to a specific text node and offset within that node.
+   *
+   * Throws if `this.offset` exceeds the length of the element's text. In the
+   * case where the element has no text and `this.offset` is 0, the `direction`
+   * option determines what happens.
+   *
+   * Offsets at the boundary between two nodes are resolved to the start of the
+   * node that begins at the boundary.
+   *
+   * @param options.direction - Specifies in which direction to search for the
+   *                            nearest text node if `this.offset` is `0` and
+   *                            `this.element` has no text. If not specified an
+   *                            error is thrown.
+   *
+   * @throws {RangeError}
+   */
+  resolve(options: { direction?: ResolveDirection } = {}): {
+    node: Text;
+    offset: number;
+  } {
+    try {
+      return resolveOffsets(this.element, this.offset)[0];
+    } catch (err) {
+      if (this.offset === 0 && options.direction !== undefined) {
+        const tw = document.createTreeWalker(
+          this.element.getRootNode(),
+          NodeFilter.SHOW_TEXT
+        );
+        tw.currentNode = this.element;
+        const forwards = options.direction === ResolveDirection.FORWARDS;
+        const text = forwards
+          ? (tw.nextNode() as Text | null)
+          : (tw.previousNode() as Text | null);
+        if (!text) {
+          throw err;
+        }
+        return { node: text, offset: forwards ? 0 : text.data.length };
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * Construct a `TextPosition` that refers to the `offset`th character within
+   * `node`.
+   */
+  static fromCharOffset(node: Node, offset: number): TextPosition {
+    switch (node.nodeType) {
+      case Node.TEXT_NODE:
+        return TextPosition.fromPoint(node, offset);
+      case Node.ELEMENT_NODE:
+        return new TextPosition(node as Element, offset);
+      default:
+        throw new Error('Node is not an element or text node');
+    }
+  }
+
+  /**
+   * Construct a `TextPosition` representing the range start or end point (node, offset).
+   *
+   * @param node
+   * @param offset - Offset within the node
+   */
+  static fromPoint(node: Node, offset: number): TextPosition {
+    switch (node.nodeType) {
+      case Node.TEXT_NODE: {
+        if (offset < 0 || offset > (node as Text).data.length) {
+          throw new Error('Text node offset is out of range');
+        }
+
+        if (!node.parentElement) {
+          throw new Error('Text node has no parent');
+        }
+
+        // Get the offset from the start of the parent element.
+        const textOffset = previousSiblingsTextLength(node) + offset;
+
+        return new TextPosition(node.parentElement, textOffset);
+      }
+      case Node.ELEMENT_NODE: {
+        if (offset < 0 || offset > node.childNodes.length) {
+          throw new Error('Child node offset is out of range');
+        }
+
+        // Get the text length before the `offset`th child of element.
+        let textOffset = 0;
+        for (let i = 0; i < offset; i++) {
+          textOffset += nodeTextLength(node.childNodes[i]);
+        }
+
+        return new TextPosition(node as Element, textOffset);
+      }
+      default:
+        throw new Error('Point is not in an element or text node');
+    }
+  }
+}
+
+/**
+ * Represents a region of a document as a (start, end) pair of `TextPosition` points.
+ *
+ * Representing a range in this way allows for changes in the DOM content of the
+ * range which don't affect its text content, without affecting the text content
+ * of the range itself.
+ */
+export class TextRange {
+  public start: TextPosition;
+  public end: TextPosition;
+
+  constructor(start: TextPosition, end: TextPosition) {
+    this.start = start;
+    this.end = end;
+  }
+
+  /**
+   * Create a new TextRange whose `start` and `end` are computed relative to
+   * `element`. `element` must be an ancestor of both `start.element` and
+   * `end.element`.
+   */
+  relativeTo(element: Element): TextRange {
+    return new TextRange(
+      this.start.relativeTo(element),
+      this.end.relativeTo(element)
+    );
+  }
+
+  /**
+   * Resolve this TextRange to a (DOM) Range.
+   *
+   * The resulting DOM Range will always start and end in a `Text` node.
+   * Hence `TextRange.fromRange(range).toRange()` can be used to "shrink" a
+   * range to the text it contains.
+   *
+   * May throw if the `start` or `end` positions cannot be resolved to a range.
+   */
+  toRange(): Range {
+    let start;
+    let end;
+
+    if (
+      this.start.element === this.end.element &&
+      this.start.offset <= this.end.offset
+    ) {
+      // Fast path for start and end points in same element.
+      [start, end] = resolveOffsets(
+        this.start.element,
+        this.start.offset,
+        this.end.offset
+      );
+    } else {
+      start = this.start.resolve({
+        direction: ResolveDirection.FORWARDS,
+      });
+      end = this.end.resolve({ direction: ResolveDirection.BACKWARDS });
+    }
+
+    const range = new Range();
+    range.setStart(start.node, start.offset);
+    range.setEnd(end.node, end.offset);
+    return range;
+  }
+
+  /**
+   * Create a TextRange from a (DOM) Range
+   */
+  static fromRange(range: Range): TextRange {
+    const start = TextPosition.fromPoint(
+      range.startContainer,
+      range.startOffset
+    );
+    const end = TextPosition.fromPoint(range.endContainer, range.endOffset);
+    return new TextRange(start, end);
+  }
+
+  /**
+   * Create a TextRange representing the `start`th to `end`th characters in
+   * `root`
+   */
+  static fromOffsets(root: Element, start: number, end: number): TextRange {
+    return new TextRange(
+      new TextPosition(root, start),
+      new TextPosition(root, end)
+    );
+  }
+
+  /**
+   * Return a new Range representing `range` trimmed of any leading or trailing
+   * whitespace
+   */
+  static trimmedRange(range: Range): Range {
+    return trimRange(TextRange.fromRange(range).toRange());
+  }
+}