@readium/navigator-html-injectables 1.2.0

package/types/src/vendor/approx-string-match/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Implementation of Myers' online approximate string matching algorithm [1],
+ * with additional optimizations suggested by [2].
+ *
+ * This has O((k/w) * n) expected-time where `n` is the length of the
+ * text, `k` is the maximum number of errors allowed (always <= the pattern
+ * length) and `w` is the word size. Because JS only supports bitwise operations
+ * on 32 bit integers, `w` is 32.
+ *
+ * As far as I am aware, there aren't any online algorithms which are
+ * significantly better for a wide range of input parameters. The problem can be
+ * solved faster using "filter then verify" approaches which first filter out
+ * regions of the text that cannot match using a "cheap" check and then verify
+ * the remaining potential matches. The verify step requires an algorithm such
+ * as this one however.
+ *
+ * The algorithm's approach is essentially to optimize the classic dynamic
+ * programming solution to the problem by computing columns of the matrix in
+ * word-sized chunks (ie. dealing with 32 chars of the pattern at a time) and
+ * avoiding calculating regions of the matrix where the minimum error count is
+ * guaranteed to exceed the input threshold.
+ *
+ * The paper consists of two parts, the first describes the core algorithm for
+ * matching patterns <= the size of a word (implemented by `advanceBlock` here).
+ * The second uses the core algorithm as part of a larger block-based algorithm
+ * to handle longer patterns.
+ *
+ * [1] G. Myers, “A Fast Bit-Vector Algorithm for Approximate String Matching
+ * Based on Dynamic Programming,” vol. 46, no. 3, pp. 395–415, 1999.
+ *
+ * [2] Šošić, M. (2014). An simd dynamic programming c/c++ library (Doctoral
+ * dissertation, Fakultet Elektrotehnike i računarstva, Sveučilište u Zagrebu).
+ */
+/**
+ * Represents a match returned by a call to `search`.
+ */
+export interface Match {
+    /** Start offset of match in text. */
+    start: number;
+    /** End offset of match in text. */
+    end: number;
+    /**
+     * The number of differences (insertions, deletions or substitutions) between
+     * the pattern and the approximate match in the text.
+     */
+    errors: number;
+}
+/**
+ * Search for the closest matches for `pattern` in `text`.
+ *
+ * Returns all matches that have the lowest number of errors, or an empty
+ * array if no match was found with `maxErrors` or fewer errors.
+ */
+export default function search(text: string, pattern: string, maxErrors: number): Match[];

package/types/src/vendor/hypothesis/anchoring/api-types.d.ts

@@ -0,0 +1,266 @@
+import type { ClientAnnotationData } from '../types/shared';
+/**
+ * Type definitions for objects returned from the Hypothesis API.
+ *
+ * The canonical reference is the API documentation at
+ * https://h.readthedocs.io/en/latest/api-reference/
+ */
+/**
+ * Metadata specifying how to call an API route.
+ */
+export type RouteMetadata = {
+    /** HTTP method */
+    method: string;
+    /** URL template */
+    url: string;
+    /** Description of API route */
+    desc: string;
+};
+/** A nested map of API route name to route metadata. */
+export type RouteMap = {
+    [key: string]: RouteMap | RouteMetadata;
+};
+/**
+ * Structure of the API index response (`/api`).
+ */
+export type IndexResponse = {
+    links: RouteMap;
+};
+/**
+ * Structure of the Hypothesis links response (`/api/links`).
+ *
+ * This is a map of link name (eg. "account.settings") to URL. The URL may
+ * include ":"-prefixed placeholders/variables.
+ */
+export type LinksResponse = Record<string, string>;
+/**
+ * Selector which indicates the time range within a video or audio file that
+ * an annotation refers to.
+ */
+export type MediaTimeSelector = {
+    type: 'MediaTimeSelector';
+    /** Offset from start of media in seconds. */
+    start: number;
+    /** Offset from start of media in seconds. */
+    end: number;
+};
+/**
+ * Selector which identifies a document region using the selected text plus
+ * the surrounding context.
+ */
+export type TextQuoteSelector = {
+    type: 'TextQuoteSelector';
+    exact: string;
+    prefix?: string;
+    suffix?: string;
+};
+/**
+ * Selector which identifies a document region using UTF-16 character offsets
+ * in the document body's `textContent`.
+ */
+export type TextPositionSelector = {
+    type: 'TextPositionSelector';
+    start: number;
+    end: number;
+};
+/**
+ * Selector which identifies a document region using XPaths and character offsets.
+ */
+export type RangeSelector = {
+    type: 'RangeSelector';
+    startContainer: string;
+    endContainer: string;
+    startOffset: number;
+    endOffset: number;
+};
+/**
+ * Selector which identifies the Content Document within an EPUB that an
+ * annotation was made in.
+ */
+export type EPUBContentSelector = {
+    type: 'EPUBContentSelector';
+    /**
+     * URL of the content document. This should be an absolute HTTPS URL if
+     * available, but may be relative to the root of the EPUB.
+     */
+    url: string;
+    /**
+     * EPUB Canonical Fragment Identifier for the table of contents entry that
+     * corresponds to the content document.
+     */
+    cfi?: string;
+    /** Title of the content document. */
+    title?: string;
+};
+/**
+ * Selector which identifies the page of a document that an annotation was made
+ * on.
+ *
+ * This selector is only applicable for document types where the association of
+ * content and page numbers can be done in a way that is independent of the
+ * viewer and display settings. This includes inherently paginated documents
+ * such as PDFs, but also content such as EPUBs when they include information
+ * about the location of page breaks in printed versions of a book. It does
+ * not include ordinary web pages or EPUBs without page break information
+ * however.
+ */
+export type PageSelector = {
+    type: 'PageSelector';
+    /** The zero-based index of the page in the document's page sequence. */
+    index: number;
+    /**
+     * Either the page number that is displayed on the page, or the 1-based
+     * number of the page in the document's page sequence, if the pages do not
+     * have numbers on them.
+     */
+    label?: string;
+};
+/**
+ * Serialized representation of a region of a document which an annotation
+ * pertains to.
+ */
+export type Selector = TextQuoteSelector | TextPositionSelector | RangeSelector | EPUBContentSelector | MediaTimeSelector | PageSelector;
+/**
+ * An entry in the `target` field of an annotation which identifies the document
+ * and region of the document that it refers to.
+ */
+export type Target = {
+    /** URI of the document */
+    source: string;
+    /** Region of the document */
+    selector?: Selector[];
+};
+export type UserInfo = {
+    display_name: string | null;
+};
+export type APIAnnotationData = {
+    /**
+     * The server-assigned ID for the annotation. This is only set once the
+     * annotation has been saved to the backend.
+     */
+    id?: string;
+    references?: string[];
+    created: string;
+    flagged?: boolean;
+    group: string;
+    updated: string;
+    tags: string[];
+    text: string;
+    uri: string;
+    user: string;
+    hidden: boolean;
+    document: {
+        title: string;
+    };
+    permissions: {
+        read: string[];
+        update: string[];
+        delete: string[];
+    };
+    /**
+     * The document and region this annotation refers to.
+     *
+     * The Hypothesis API structure allows for multiple targets, but the h
+     * server only supports one target per annotation.
+     */
+    target: Target[];
+    moderation?: {
+        flagCount: number;
+    };
+    links: {
+        /**
+         * A "bouncer" URL that takes the user to see the annotation in context
+         */
+        incontext?: string;
+        /** URL to view the annotation by itself. */
+        html?: string;
+    };
+    user_info?: UserInfo;
+};
+export type Annotation = ClientAnnotationData & APIAnnotationData;
+/**
+ * An annotation which has been saved to the backend and assigned an ID.
+ */
+export type SavedAnnotation = Annotation & {
+    id: string;
+};
+export type Profile = {
+    userid: string | null;
+    preferences: {
+        show_sidebar_tutorial?: boolean;
+    };
+    features: Record<string, boolean>;
+    user_info?: UserInfo;
+};
+export type Organization = {
+    name: string;
+    logo: string;
+    id: string;
+    default?: boolean;
+};
+export type GroupScopes = {
+    enforced: boolean;
+    uri_patterns: string[];
+};
+export type Group = {
+    /** The "pubid" of the group, unique per authority. */
+    id: string;
+    /** Fully-qualified ID with authority. */
+    groupid?: string;
+    type: 'private' | 'open';
+    /**
+     * Note: This field is nullable in the API, but we assign a default organization in the client.
+     */
+    organization: Organization;
+    scopes: GroupScopes | null;
+    links: {
+        html?: string;
+    };
+    logo: string;
+    isMember: boolean;
+    isScopedToUri: boolean;
+    name: string;
+    canLeave: boolean;
+};
+/**
+ * All Groups have an `id`, which is a server-assigned identifier. This is the
+ * primary field used to identify a Group.
+ *
+ * In some cases, specifically LMS, it is necessary for an outside service to
+ * be able to specify its own identifier. This gets stored in the `groupid`
+ * field of a Group. Only some Groups have a `groupid`.
+ *
+ * Application logic operates on `id`s, but we may receive `groupid`s in some
+ * cases from outside sevices, e.g. the `changeFocusModeUser` RPC method.
+ */
+export type GroupIdentifier = NonNullable<Group['id'] | Group['groupid']>;
+/**
+ * Query parameters for an `/api/search` API call.
+ *
+ * This type currently includes params that we've actually used.
+ *
+ * See https://h.readthedocs.io/en/latest/api-reference/#tag/annotations/paths/~1search/get
+ * for the complete list and usage of each.
+ */
+export type SearchQuery = {
+    limit?: number;
+    uri?: string[];
+    group?: string;
+    order?: string;
+    references?: string;
+    search_after?: string;
+    sort?: string;
+    /** Undocument param that causes replies to be returned in a separate `replies` field. */
+    _separate_replies?: boolean;
+};
+/**
+ * Response to an `/api/search` API call.
+ *
+ * See https://h.readthedocs.io/en/latest/api-reference/#tag/annotations/paths/~1search/get
+ */
+export type SearchResponse = {
+    total: number;
+    rows: Annotation[];
+    /** Undocumented property that is populated if `_separate_replies` query param was specified. */
+    replies?: Annotation[];
+};

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

@@ -0,0 +1,17 @@
+import type { MediaTimeSelector, RangeSelector, Selector, TextPositionSelector, TextQuoteSelector } from './api-types';
+type Options = {
+    hint?: number;
+};
+/**
+ * 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 declare function anchor(root: Element, selectors: Selector[], options?: Options): Promise<Range>;
+export declare function describe(root: Element, range: Range): (MediaTimeSelector | TextQuoteSelector | TextPositionSelector | RangeSelector)[];
+export {};

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

@@ -0,0 +1,30 @@
+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;
+};
+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 declare function matchQuote(text: string, quote: string, context?: Context): Match | null;
+export {};

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

@@ -0,0 +1,32 @@
+/**
+ * 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 declare function createPlaceholder(container: HTMLElement): Element;
+/**
+ * Return true if a page/tile container has a placeholder.
+ */
+export declare function hasPlaceholder(container: HTMLElement): boolean;
+/**
+ * Remove the placeholder element in `container`, if present.
+ */
+export declare function removePlaceholder(container: HTMLElement): void;
+/**
+ * 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 declare function isInPlaceholder(node: Node): boolean;

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

@@ -0,0 +1,103 @@
+/**
+ * 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 declare enum ResolveDirection {
+    FORWARDS = 1,
+    BACKWARDS = 2
+}
+/**
+ * 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 declare class TextPosition {
+    element: Element;
+    offset: number;
+    constructor(element: Element, offset: number);
+    /**
+     * Return a copy of this position with offset relative to a given ancestor
+     * element.
+     *
+     * @param parent - Ancestor of `this.element`
+     */
+    relativeTo(parent: Element): TextPosition;
+    /**
+     * 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;
+    };
+    /**
+     * Construct a `TextPosition` that refers to the `offset`th character within
+     * `node`.
+     */
+    static fromCharOffset(node: Node, offset: number): TextPosition;
+    /**
+     * 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;
+}
+/**
+ * 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 declare class TextRange {
+    start: TextPosition;
+    end: TextPosition;
+    constructor(start: TextPosition, end: TextPosition);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Create a TextRange from a (DOM) Range
+     */
+    static fromRange(range: Range): TextRange;
+    /**
+     * Create a TextRange representing the `start`th to `end`th characters in
+     * `root`
+     */
+    static fromOffsets(root: Element, start: number, end: number): TextRange;
+    /**
+     * Return a new Range representing `range` trimmed of any leading or trailing
+     * whitespace
+     */
+    static trimmedRange(range: Range): Range;
+}

package/types/src/vendor/hypothesis/anchoring/trim-range.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Return a new DOM Range that adjusts the start and end positions of `range` as
+ * needed such that:
+ *
+ * - `startContainer` and `endContainer` text nodes both contain at least one
+ *   non-whitespace character within the Range's text content
+ * - `startOffset` and `endOffset` both reference non-whitespace characters,
+ *   with `startOffset` immediately before the first non-whitespace character
+ *   and `endOffset` immediately after the last
+ *
+ * Whitespace characters are those that are removed by `String.prototype.trim()`
+ *
+ * @param range - A DOM Range that whose `startContainer` and `endContainer` are
+ *   both text nodes, and which contains at least one non-whitespace character.
+ * @throws {RangeError}
+ */
+export declare function trimRange(range: Range): Range;

package/types/src/vendor/hypothesis/anchoring/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * This module exports a set of classes for converting between DOM `Range`
+ * objects and different types of selectors. It is mostly a thin wrapper around a
+ * set of anchoring libraries. It serves two main purposes:
+ *
+ *  1. Providing a consistent interface across different types of anchors.
+ *  2. Insulating the rest of the code from API changes in the underlying anchoring
+ *     libraries.
+ */
+import type { MediaTimeSelector, RangeSelector, TextPositionSelector, TextQuoteSelector } from './api-types';
+/**
+ * Converts between `RangeSelector` selectors and `Range` objects.
+ */
+export declare class RangeAnchor {
+    root: Node;
+    range: Range;
+    /**
+     * @param root - A root element from which to anchor.
+     * @param range - A range describing the anchor.
+     */
+    constructor(root: Node, range: Range);
+    /**
+     * @param root - A root element from which to anchor.
+     * @param range - A range describing the anchor.
+     */
+    static fromRange(root: Node, range: Range): RangeAnchor;
+    /**
+     * Create an anchor from a serialized `RangeSelector` selector.
+     *
+     * @param root - A root element from which to anchor.
+     */
+    static fromSelector(root: Element, selector: RangeSelector): RangeAnchor;
+    toRange(): Range;
+    toSelector(): RangeSelector;
+}
+/**
+ * Converts between `TextPositionSelector` selectors and `Range` objects.
+ */
+export declare class TextPositionAnchor {
+    root: Element;
+    start: number;
+    end: number;
+    constructor(root: Element, start: number, end: number);
+    static fromRange(root: Element, range: Range): TextPositionAnchor;
+    static fromSelector(root: Element, selector: TextPositionSelector): TextPositionAnchor;
+    toSelector(): TextPositionSelector;
+    toRange(): Range;
+}
+type QuoteMatchOptions = {
+    /** Expected position of match in text. See `matchQuote`. */
+    hint?: number;
+};
+export type TextQuoteAnchorContext = {
+    prefix?: string;
+    suffix?: string;
+};
+/**
+ * Converts between `TextQuoteSelector` selectors and `Range` objects.
+ */
+export declare class TextQuoteAnchor {
+    root: Element;
+    exact: string;
+    context: TextQuoteAnchorContext;
+    /**
+     * @param root - A root element from which to anchor.
+     */
+    constructor(root: Element, exact: string, context?: TextQuoteAnchorContext);
+    /**
+     * Create a `TextQuoteAnchor` from a range.
+     *
+     * Will throw if `range` does not contain any text nodes.
+     */
+    static fromRange(root: Element, range: Range): TextQuoteAnchor;
+    static fromSelector(root: Element, selector: TextQuoteSelector): TextQuoteAnchor;
+    toSelector(): TextQuoteSelector;
+    toRange(options?: QuoteMatchOptions): Range;
+    toPositionAnchor(options?: QuoteMatchOptions): TextPositionAnchor;
+}
+export declare class MediaTimeAnchor {
+    root: Element;
+    /** Offset from start of media in seconds. */
+    start: number;
+    /** Offset from end of media in seconds. */
+    end: number;
+    constructor(root: Element, start: number, end: number);
+    /**
+     * Return a {@link MediaTimeAnchor} that represents a range, or `null` if
+     * no time range information is present on elements in the range.
+     */
+    static fromRange(root: Element, range: Range): MediaTimeAnchor | null;
+    /**
+     * Convert this anchor to a DOM range.
+     *
+     * This returned range will start from the beginning of the element whose
+     * associated time range includes `start` and continue to the end of the
+     * element whose associated time range includes `end`.
+     */
+    toRange(): Range;
+    static fromSelector(root: Element, selector: MediaTimeSelector): MediaTimeAnchor;
+    toSelector(): MediaTimeSelector;
+}
+export {};

package/types/src/vendor/hypothesis/anchoring/xpath.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A simple XPath generator which can generate XPaths of the form
+ * /tag[index]/tag[index].
+ *
+ * @param node - The node to generate a path to
+ * @param root - Root node to which the returned path is relative
+ */
+export declare function xpathFromNode(node: Node, root: Node): string;
+/**
+ * Finds an element node using an XPath relative to `root`
+ *
+ * Example:
+ *   node = nodeFromXPath('/main/article[1]/p[3]', document.body)
+ */
+export declare function nodeFromXPath(xpath: string, root?: Element): Node | null;

package/types/src/vendor/hypothesis/types/shared.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Clusters provide the client application a mechanism for categorizing
+ * annotations so that their drawn anchor highlights may be styled distinctively
+ * in the annotated document. An annotation can only belong to one cluster.
+ */
+export type HighlightCluster = 'other-content' | 'user-annotations' | 'user-highlights';
+/**
+ * Annotation properties not present on API objects, but added by the client
+ */
+export type ClientAnnotationData = {
+    $cluster?: HighlightCluster;
+    /**
+     * Client-side identifier: set even if annotation does not have a
+     * server-provided `id` (i.e. is unsaved)
+     */
+    $tag: string;
+    /**
+     * Flag indicating whether waiting for the annotation to anchor timed out
+     */
+    $anchorTimeout?: boolean;
+    /**
+     * Flag indicating that this annotation was created using the "Highlight" button,
+     * as opposed to "Annotate".
+     */
+    $highlight?: boolean;
+    /**
+     * Flag indicating that this annotation was not found in the document.
+     * It is initially `undefined` while anchoring is in progress and then set to
+     * `true` if anchoring failed or `false` if it succeeded.
+     */
+    $orphan?: boolean;
+};