@khanacademy/perseus 3.0.0 → 4.0.0

package/src/components/highlighting/highlights.ts

@@ -0,0 +1,207 @@
+/**
+ * Utility functions for manipulating highlights.
+ */
+
+import {Errors} from "../../logging/log";
+import {PerseusError} from "../../perseus-error";
+
+import {
+    findFirstAndLastWordIndexes,
+    unionRanges,
+    spanRanges,
+    rangeIncludes,
+} from "./ranges";
+
+import type {
+    DOMHighlight,
+    DOMHighlightSet,
+    SerializedHighlight,
+    DOMRange,
+} from "./types";
+
+/**
+ * Given a list of DOMHighlights, return a new list that also includes the
+ * given DOMRange as a new DOMHighlight. If the DOMHighlight intersects
+ * existing DOMHighlights, the other Highlights are removed and their ranges
+ * are merged into the new DOMHighlight.
+ */
+export function addHighlight(
+    existingHighlights: DOMHighlightSet,
+    newHighlight: DOMHighlight,
+): DOMHighlightSet {
+    const newHighlights: Record<string, any> = {};
+
+    // Merge the new highlight with any existing highlights that intersect it.
+    let mergedDomRange = newHighlight.domRange;
+    let mergedFirstWordIndex = newHighlight.firstWordIndex;
+    let mergedLastWordIndex = newHighlight.lastWordIndex;
+    for (const key of Object.keys(existingHighlights)) {
+        const h = existingHighlights[key];
+        const newMergedDomRange = unionRanges(h.domRange, mergedDomRange);
+        if (newMergedDomRange) {
+            // This highlight's range was successfully merged into the new
+            // highlight. Update `mergedDomRange`, and *don't* add it to the
+            // new set of highlights.
+            mergedDomRange = newMergedDomRange;
+            mergedFirstWordIndex = Math.min(
+                h.firstWordIndex,
+                mergedFirstWordIndex,
+            );
+            mergedLastWordIndex = Math.max(
+                h.lastWordIndex,
+                mergedLastWordIndex,
+            );
+        } else {
+            // This highlight's range can't be merged into the new highlight.
+            // Add it to the new set of highlights.
+            newHighlights[key] = h;
+        }
+    }
+
+    const newMergedHighlight = {
+        firstWordIndex: mergedFirstWordIndex,
+        lastWordIndex: mergedLastWordIndex,
+        domRange: mergedDomRange,
+    } as const;
+
+    // Add the newly-merged highlight to the set of highlights, under a new,
+    // unique key.
+    const existingKeys = Object.keys(newHighlights);
+    const newKey = createNewUniqueKey(existingKeys);
+    newHighlights[newKey] = newMergedHighlight;
+
+    return newHighlights;
+}
+
+/**
+ * Given a DOMRange and a list of word ranges, build a corresponding
+ * DOMHighlight.
+ *
+ * If the DOMRange is not a valid highlight given the word ranges, return null.
+ */
+export function buildHighlight(
+    existingHighlights: DOMHighlightSet,
+    wordRanges: ReadonlyArray<DOMRange>,
+    newHighlightRange: DOMRange,
+): DOMHighlight | null | undefined {
+    // If any existing highlight fully contains the new highlight range, it's
+    // redundant and therefore not valid to build this as a highlight.
+    // Return null.
+    //
+    // NOTE(mdr): Really, our goal is to determine whether the new range's
+    //     content is already fully highlighted, so you could imagine this
+    //     logic not catching the case where a range's contents are fully
+    //     highlighted, but by multiple ranges.
+    //
+    //     However, words aren't actually adjacent; they have spaces between
+    //     them. So, even if each word in the range is currently highlighted,
+    //     the space between a pair of words will only be highlighted if
+    //     they're included in the same highlight range.
+    //
+    //     Therefore, if this new range isn't fully contained by an existing
+    //     highlight, then there's at *least* an unhighlighted space within the
+    //     range. In that case, it makes sense to offer this as a new highlight
+    //     that, when added, will merge with the highlights that it intersects.
+    for (const key of Object.keys(existingHighlights)) {
+        const existingHighlightRange = existingHighlights[key].domRange;
+        if (rangeIncludes(existingHighlightRange, newHighlightRange)) {
+            return null;
+        }
+    }
+
+    // If the new highlight range doesn't span two words from the content, it's
+    // not valid to build this as a highlight. Return null.
+    const indexes = findFirstAndLastWordIndexes(newHighlightRange, wordRanges);
+    if (!indexes) {
+        return null;
+    }
+
+    const [firstWordIndex, lastWordIndex] = indexes;
+    const firstWord = wordRanges[firstWordIndex];
+    const lastWord = wordRanges[lastWordIndex];
+    return {
+        firstWordIndex,
+        lastWordIndex,
+        domRange: spanRanges(firstWord, lastWord),
+    };
+}
+
+/**
+ * Given a list of keys, return a new unique key that is not in the list.
+ */
+function createNewUniqueKey(existingKeys: ReadonlyArray<string>): string {
+    // The base of the key is the current time, in milliseconds since epoch.
+    const base = `${new Date().getTime()}`;
+    if (!existingKeys.includes(base)) {
+        return base;
+    }
+
+    // But, if the user is a fast-clicker or time-traveler or something, and
+    // already has a highlight from this millisecond, then let's attach a
+    // suffix and keep incrementing it until we find an unused suffix.
+    let suffix = 0;
+    let key;
+    do {
+        key = `${base}-${suffix}`;
+        suffix++;
+    } while (existingKeys.includes(key));
+
+    return key;
+}
+
+/**
+ * Given a SerializedHightlight and the current set of word ranges, return a
+ * DOMHighlight representing the SerializedHighlight.
+ *
+ * If the SerializedHighlight is not valid given the list of word ranges, throw
+ * an error.
+ */
+export function deserializeHighlight(
+    serializedHighlight: SerializedHighlight,
+    wordRanges: ReadonlyArray<DOMRange>,
+): DOMHighlight {
+    const {firstWordIndex, lastWordIndex} = serializedHighlight.range;
+
+    const firstWord = wordRanges[firstWordIndex];
+    if (!firstWord) {
+        throw new PerseusError(
+            `first word index ${firstWord} is out of bounds: ` +
+                `must be 0–${wordRanges.length - 1} inclusive`,
+            Errors.InvalidInput,
+            {metadata: {firstWord, wordRanges: JSON.stringify(wordRanges)}},
+        );
+    }
+
+    const lastWord = wordRanges[lastWordIndex];
+    if (!lastWord) {
+        throw new PerseusError(
+            `last word index ${lastWord} is out of bounds: ` +
+                `must be 0–${wordRanges.length - 1} inclusive`,
+            Errors.InvalidInput,
+            {metadata: {lastWord, wordRanges: JSON.stringify(wordRanges)}},
+        );
+    }
+
+    return {
+        firstWordIndex,
+        lastWordIndex,
+        domRange: spanRanges(firstWord, lastWord),
+    };
+}
+
+/**
+ * Return a SerializedHighlight representing the given DOMHighlight.
+ */
+export function serializeHighlight(
+    highlight: DOMHighlight,
+): SerializedHighlight {
+    const {firstWordIndex, lastWordIndex} = highlight;
+
+    return {
+        range: {
+            type: "word-indexes",
+            firstWordIndex,
+            lastWordIndex,
+        },
+    };
+}

package/src/components/highlighting/ranges.ts

@@ -0,0 +1,304 @@
+/**
+ * Utility functions for manipulating ranges of highlightable content.
+ */
+
+import type {DOMRange} from "./types";
+
+/**
+ * Given two DOMRange objects, and a choice of start/end point for each, compare
+ * the two chosen points. Return -1 if a's comes first in the document, return
+ * 1 if b's comes first in the document, or 0 if they represent the same point
+ * in the document.
+ *
+ * NOTE(mdr): This function exists primarily to cover over some confusing parts
+ *     of the DOM's `compareBoundaryPoints` API, and to cover over a Flow bug
+ *     documented here: https://github.com/facebook/flow/issues/3734.
+ */
+function compareRangeBoundaryPoints(
+    a: DOMRange,
+    whichA: "start" | "end",
+    b: DOMRange,
+    whichB: "start" | "end",
+): number {
+    let mode;
+    if (whichA === "start" && whichB === "start") {
+        mode = Range.START_TO_START;
+    } else if (whichA === "start" && whichB === "end") {
+        // NOTE(mdr): Confusingly, the correct constant here is actually
+        //     `END_TO_START`, which is the reverse of what you'd expect.
+        mode = Range.END_TO_START;
+    } else if (whichA === "end" && whichB === "start") {
+        // NOTE(mdr): Confusingly, the correct constant here is actually
+        //     `START_TO_END`, which is the reverse of what you'd expect.
+        mode = Range.START_TO_END;
+    } else {
+        mode = Range.END_TO_END;
+    }
+    return a.compareBoundaryPoints(mode, b);
+}
+
+/**
+ * Given two DOMRanges, return a DOMRange whose start point comes from A, and
+ * whose end point comes from B.
+ */
+export function spanRanges(a: DOMRange, b: DOMRange): DOMRange {
+    const range = a.cloneRange();
+    range.setEnd(b.endContainer, b.endOffset);
+    return range;
+}
+
+/**
+ * Given two DOMRanges, return whether they overlap.
+ *
+ * We here treat ranges like closed intervals: the boundary points are
+ * considered to be included in the range, and, if a ends exactly where b
+ * starts, they are considered to overlap.
+ */
+export function rangesOverlap(a: DOMRange, b: DOMRange): boolean {
+    // Two ranges do *not* overlap iff one ends before the other begins.
+    const rangesDoNotOverlap =
+        compareRangeBoundaryPoints(a, "end", b, "start") < 0 ||
+        compareRangeBoundaryPoints(b, "end", a, "start") < 0;
+    return !rangesDoNotOverlap;
+}
+
+/**
+ * Given two DOMRanges, return whether the first includes the second: whether
+ * all points that B contains are also contained by A.
+ */
+export function rangeIncludes(a: DOMRange, b: DOMRange): boolean {
+    const rangeIsIncluded =
+        compareRangeBoundaryPoints(a, "start", b, "start") <= 0 &&
+        compareRangeBoundaryPoints(a, "end", b, "end") >= 0;
+    return rangeIsIncluded;
+}
+
+/**
+ * Given two DOMRanges, intersect them: return a range that contains all points
+ * that both A contains and B contains, and contains no other points.
+ *
+ * If A and B do not overlap, no intersection exists; return null.
+ */
+export function intersectRanges(
+    a: DOMRange,
+    b: DOMRange,
+): DOMRange | null | undefined {
+    if (!rangesOverlap(a, b)) {
+        return null;
+    }
+
+    // Find the range with the latest start point, and the range with the
+    // earliest end point.
+    const starter =
+        compareRangeBoundaryPoints(a, "start", b, "start") > 0 ? a : b;
+    const ender = compareRangeBoundaryPoints(a, "end", b, "end") < 0 ? a : b;
+
+    return spanRanges(starter, ender);
+}
+
+/**
+ * Given two DOMRanges, union them: return a range that contains all points
+ * that either A contains or B contains, and contains no other points.
+ *
+ * If A and B do not overlap, no union exists; return null.
+ */
+export function unionRanges(
+    a: DOMRange,
+    b: DOMRange,
+): DOMRange | null | undefined {
+    if (!rangesOverlap(a, b)) {
+        return null;
+    }
+
+    // Find the range with the earliest start point, and the range with the
+    // latest end point.
+    const starter =
+        compareRangeBoundaryPoints(a, "start", b, "start") < 0 ? a : b;
+    const ender = compareRangeBoundaryPoints(a, "end", b, "end") > 0 ? a : b;
+
+    return spanRanges(starter, ender);
+}
+
+/**
+ * Given a list of word ranges, and a selection range, binary search the list
+ * and return the index of the goal word, or -1 if no satisfactory goal word
+ * exists in the list.
+ *
+ * If `goal` is "first", return the index of the first word whose end point is
+ * after the selection's start point.
+ *
+ * If `goal` is "last", return the index of the last word whose start point is
+ * before the selection's end point.
+ */
+function findBoundaryWordIndex(
+    selectionRange: DOMRange,
+    wordRanges: ReadonlyArray<DOMRange>,
+    goal: "first" | "last",
+    initialLowerBound: number,
+    initialUpperBound: number,
+): number {
+    let bestValidWordIndex = -1;
+    let lowerBound = initialLowerBound;
+    let upperBound = initialUpperBound;
+    let iterationCount = 0;
+    while (lowerBound <= upperBound) {
+        iterationCount++;
+        if (iterationCount > wordRanges.length * 2) {
+            throw new Error(
+                `Assertion error: Binary search isn't terminating? ` +
+                    `lower=${lowerBound}, upper=${upperBound}`,
+            );
+        }
+
+        const mid = Math.floor((lowerBound + upperBound) / 2);
+
+        if (goal === "first") {
+            const rangeComparison = compareRangeBoundaryPoints(
+                wordRanges[mid],
+                "end",
+                selectionRange,
+                "start",
+            );
+            if (rangeComparison <= 0) {
+                // If this word's end point is before or equal to the
+                // selection's start point, then this word is not a valid
+                // candidate, nor are any of the words before it.
+                //
+                // Update our bounds to look for a valid word after this one.
+                lowerBound = mid + 1;
+            } else {
+                // If this word's end point is after the selection's start
+                // point, then this word is valid, and is, by nature of the
+                // search, the earliest valid word we're aware of.
+                //
+                // Update our bounds to look for a better valid word before
+                // this one.
+                bestValidWordIndex = mid;
+                upperBound = mid - 1;
+            }
+        } else {
+            const rangeComparison = compareRangeBoundaryPoints(
+                wordRanges[mid],
+                "start",
+                selectionRange,
+                "end",
+            );
+            if (rangeComparison >= 0) {
+                // If this word's start point is after or equal to the
+                // selection's end point, then this word is not a valid
+                // candidate, nor are any of the words after it.
+                //
+                // Update our bounds to look for a valid word before this one.
+                upperBound = mid - 1;
+            } else {
+                // If this word's start point is before the selection's end
+                // point, then this word is valid, and is, by nature of the
+                // search, the latest valid word we're aware of.
+                //
+                // Update our bounds to look for a better valid word after
+                // this one.
+                bestValidWordIndex = mid;
+                lowerBound = mid + 1;
+            }
+        }
+    }
+
+    return bestValidWordIndex;
+}
+
+/**
+ * Given a list of word ranges, and a selection range, binary search the list
+ * and return the indexes of the first and last words that the selection
+ * intersects, or `null` if the range includes no words.
+ */
+export function findFirstAndLastWordIndexes(
+    selectionRange: DOMRange,
+    wordRanges: ReadonlyArray<DOMRange>,
+): [number, number] | null | undefined {
+    // Find the first word whose end point is after the selection's start
+    // point.
+    //
+    // Note that this does *not* alone prove that this word is *intersected* by
+    // the current range; to intersect, the first word's start point must also
+    // be before the selection's end point. This is proven by the success of
+    // the second search.
+    //
+    // (For example, imagine highlighting the space between two words. This
+    // search would return the first word after the selection, despite not
+    // intersecting the selection.)
+    const firstWordIndex = findBoundaryWordIndex(
+        selectionRange,
+        wordRanges,
+        "first",
+        0,
+        wordRanges.length - 1,
+    );
+    if (firstWordIndex < 0) {
+        return null;
+    }
+
+    // Find the last word whose start point is before the selection's end
+    // point.
+    //
+    // Start the search with our candidate first word, because, while we don't
+    // know whether our candidate first word intersects the selection, we *do*
+    // know that no *earlier* word intersects the selection, or else it would
+    // have been yielded as the candidate first word instead.
+    const lastWordIndex = findBoundaryWordIndex(
+        selectionRange,
+        wordRanges,
+        "last",
+        firstWordIndex,
+        wordRanges.length - 1,
+    );
+    if (lastWordIndex < 0) {
+        return null;
+    }
+
+    // Now, we have discovered a candidate first word F, and a candidate last
+    // word L. Let's prove that these are indeed the first and last intersected
+    // words of the selection S.
+    //
+    // Syntax: Let A1 and A2 represent the start and end point of range A.
+    //
+    // Definition: A1 <= A2 for any range A.
+    //
+    // Theorem 1: Two ranges A and B intersect iff A1 <= B2 and B1 <= A2.
+    // Proof: See http://www.rgrjr.com/emacs/overlap.html, and extend the
+    //     result to closed intervals by also accepting equality.
+    //
+    // Given 1: F1 <= L1 and F2 <= L2. That is, either the first and last word
+    //     are the same, or the last word comes after, because we provided
+    //     `firstWordIndex` as the lower bound when search for L.
+    // Given 2: S1 <= F2, and no earlier word's end point is >= S1, because
+    //     F was returned by `findBoundaryWordIndex` with goal "first".
+    // Given 3: L1 <= S2, and no later word's start point is <= S2, because
+    //     L was returned by `findBoundaryWordIndex` with goal "last".
+    //
+    // Conclusion 1: F intersects S.
+    // Proof: By Theorem 1, we must show that F1 <= S2 and S1 <= F2.
+    //     F1 <= L1 <= S2, by Given 1 and Given 3.
+    //     S1 <= F2, by Given 2. QED.
+    //
+    // Conclusion 2: L intersects S.
+    // Proof: By Theorem 1, we must show that L1 <= S2 and S1 <= L2.
+    //     L1 <= S2 by Given 3.
+    //     S1 <= F2 <= L2, by Given 1 and Given 2. QED.
+    //
+    // Conclusion 3: No word earlier than F intersects S.
+    // Proof: Consider some word W earlier than F.
+    //     W2 < S1, by Given 2. Therefore, it's false that S1 <= W2.
+    //     Therefore, W and S do not intersect, by Theorem 1. QED.
+    //
+    // Conclusion 4: No word later than L intersects S.
+    // Proof: Consider some word W later than L.
+    //     W1 > S2, by Given 2. Therefore, it's false that W1 <= S2.
+    //     Therefore, W and S do not intersect, by Theorem 1, QED.
+    //
+    // Therefore, while neither of these two searches alone proves that F is
+    // the first intersected word of S, or that L is the last intersected word
+    // of S, the implications of the two searches are sufficient proof when
+    // combined. Return these two indexes with confidence, hooray!
+
+    return [firstWordIndex, lastWordIndex];
+}

package/src/components/highlighting/types.ts

@@ -0,0 +1,73 @@
+/**
+ * A range of highlightable content, defined relative to the current DOM.
+ *
+ * This is actually just the built-in DOM type Range, aliased for consistency
+ * with DOMHighlight and SerializedHighlight.
+ * https://developer.mozilla.org/en-US/docs/Web/API/Range
+ *
+ * A DOMRange is inherently coupled to a particular DOM session, and must be
+ * serialized into a SerializedRange before being persisted.
+ */
+export type DOMRange = Range;
+
+/**
+ * A range of highlightable content, serialized into a DOM-independent format
+ * so that it can be restored in subsequent browser sessions.
+ *
+ * We currently serialize ranges by the index of the first highlighted word and
+ * index of the last highlighted word, each with respect to the full body of
+ * the highlightable content.
+ *
+ * TODO(mdr): Word index serialization is fragile in environments where the
+ *     highlightable content is liable to change. Currently, our only call
+ *     sites is the test prep app, which saves Perseus state against a
+ *     particular *version* of a Perseus item, so it's impossible for the
+ *     content to change - but, if we try to generalize further, we'll need to
+ *     create new types of range serialization that are more robust to change.
+ *     (Maybe some quoted text, and we scan the content for matches?)
+ *
+ *     Note, too, that changes to the definition of "word" are liable to break
+ *     already-persisted word-index ranges, too. If we significantly change the
+ *     definition, we should consider adding a versioning field here - even if
+ *     we don't support *all* historical word implementations, we still might
+ *     want to hide old highlights altogether if our word definition has
+ *     changed sufficiently radically.
+ */
+export type SerializedRange = {
+    type: "word-indexes";
+    firstWordIndex: number;
+    lastWordIndex: number;
+};
+
+/**
+ * A highlight, defined relative to the current DOM.
+ *
+ * A DOMHighlight, by depending on DOMRange, is inherently coupled to a
+ * particular DOM session, and must be serialized into a SerializedRange before
+ * being persisted.
+ */
+export type DOMHighlight = {
+    // A range that specifies this highlight's target content, both in terms of
+    // the first and last word, and in terms of the DOM for caching purposes.
+    firstWordIndex: number;
+    lastWordIndex: number;
+    // TODO(mdr): Things like color will go here, too :)
+    domRange: DOMRange;
+};
+export type DOMHighlightSet = {
+    [key: string]: DOMHighlight;
+};
+
+/**
+ * A highlight, serialized into a DOM-independent format so that it can be
+ * restored in subsequent browser sessions.
+ */
+export type SerializedHighlight = {
+    // A range that specifies this highlight's target content, in a
+    // DOM-independent format.
+    // TODO(mdr): Things like color will go here, too :)
+    range: SerializedRange;
+};
+export type SerializedHighlightSet = {
+    [key: string]: SerializedHighlight;
+};