@khanacademy/perseus 19.1.5 → 19.1.7

package/src/components/highlighting/highlights.ts

@@ -1,207 +0,0 @@
-/**
- * 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

@@ -1,304 +0,0 @@
-/**
- * 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

@@ -1,73 +0,0 @@
-/**
- * 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;
-};