@khanacademy/perseus 3.0.0 → 4.0.0

package/src/components/highlighting/ui/selection-tracker.tsx

@@ -0,0 +1,189 @@
+/* eslint-disable react/no-unsafe */
+/**
+ * Tracks the user's current selection, and exposes it to the subtree using the
+ * function-as-children pattern.
+ */
+import * as React from "react";
+
+import type {DOMHighlight, DOMRange} from "./types";
+
+export type TrackedSelection = {
+    // The focus of the current selection - that is, the boundary point of the
+    // selection that the user is dragging around.
+    //
+    // We don't simply track the full `Selection` object, which contains all of
+    // this focus and range information and more, because the browser reuses
+    // the global `Selection` object and mutates it, which breaks our
+    // `shouldComponentUpdate` checks.
+    focusNode: Node;
+    focusOffset: number;
+    // If the current selection maps to a valid new highlight, we cache the
+    // highlight object here.
+    proposedHighlight: DOMHighlight;
+};
+
+type SelectionTrackerProps = {
+    // A function that builds a DOMHighlight from the given DOMRange, if
+    // possible. If it would not currently be valid to add a highlight over the
+    // given DOMRange, returns null.
+    buildHighlight: (domRange: DOMRange) => DOMHighlight | null | undefined;
+    // The function-as-children pattern: passes the tracked selection, and
+    // whether the user is currently using their mouse to select, down the
+    // tree.
+    children?: (
+        trackedSelection: TrackedSelection | null | undefined,
+        userIsMouseSelecting: boolean,
+    ) => React.ReactElement<any>;
+    // If false, will not track selections.
+    enabled: boolean;
+};
+
+type SelectionTrackerState = {
+    // The current state of the mouse button. We distinguish between down,
+    // down and the selection has changed since going down, and up.
+    mouseState: "down" | "down-and-selecting" | "up";
+    // The current TrackedSelection, if any.
+    trackedSelection: TrackedSelection | null | undefined;
+};
+
+class SelectionTracker extends React.PureComponent<
+    SelectionTrackerProps,
+    SelectionTrackerState
+> {
+    state: SelectionTrackerState = {
+        mouseState: "up",
+        trackedSelection: null,
+    };
+
+    componentDidMount() {
+        this._updateListeners(false, this.props.enabled);
+    }
+
+    componentDidUpdate(prevProps: SelectionTrackerProps) {
+        if (this.props.buildHighlight !== prevProps.buildHighlight) {
+            // The highlight-building function changed, so the
+            // proposedHighlight we built with it might be different, or no
+            // longer be valid. Update accordingly.
+            this._updateTrackedSelection();
+        }
+
+        this._updateListeners(prevProps.enabled, this.props.enabled);
+    }
+
+    componentWillUnmount() {
+        this._updateListeners(this.props.enabled, false);
+    }
+
+    _updateListeners(wasListening: boolean, willListen: boolean) {
+        if (!wasListening && willListen) {
+            window.addEventListener("mousedown", this._handleMouseDown);
+            window.addEventListener("mouseup", this._handleMouseUp);
+            document.addEventListener(
+                "selectionchange",
+                this._handleSelectionChange,
+            );
+        } else if (wasListening && !willListen) {
+            window.removeEventListener("mousedown", this._handleMouseDown);
+            window.removeEventListener("mouseup", this._handleMouseUp);
+            document.removeEventListener(
+                "selectionchange",
+                this._handleSelectionChange,
+            );
+
+            // Additionally, reset the state, to guard against errors where we
+            // re-enter listening mode and have stale values stored.
+            this.setState({
+                mouseState: "up",
+                trackedSelection: null,
+            });
+        }
+    }
+
+    /**
+     * Get the current selection focus and range, if present and non-collapsed.
+     *
+     * Otherwise, if there is no current selection or it's collapsed, return
+     * null.
+     */
+    _computeFocusAndRange():
+        | {
+              focusNode: Node;
+              focusOffset: number;
+              range: DOMRange;
+          }
+        | null
+        | undefined {
+        const selection = document.getSelection();
+        if (!selection || selection.rangeCount === 0) {
+            return null;
+        }
+
+        const range = selection.getRangeAt(0);
+        if (range.collapsed) {
+            return null;
+        }
+
+        // NOTE(mdr): The focus node is guaranteed to exist, because
+        //     there's a range, but the Flow type annotations for
+        //     Selection don't know that. Cast it ourselves.
+        const focusNode: Node = selection.focusNode as any;
+        const focusOffset = selection.focusOffset;
+        return {focusNode, focusOffset, range};
+    }
+
+    /**
+     * Compute and update the TrackedSelection to reflect the document state.
+     */
+    _updateTrackedSelection(): void {
+        const focusAndRange = this._computeFocusAndRange();
+        if (!focusAndRange) {
+            this.setState({trackedSelection: null});
+            return;
+        }
+
+        const {focusNode, focusOffset, range} = focusAndRange;
+        const proposedHighlight = this.props.buildHighlight(range);
+        if (!proposedHighlight) {
+            this.setState({trackedSelection: null});
+            return;
+        }
+
+        const trackedSelection = {
+            focusNode,
+            focusOffset,
+            proposedHighlight,
+        } as const;
+        this.setState({trackedSelection});
+    }
+
+    _handleSelectionChange: () => void = () => {
+        this._updateTrackedSelection();
+
+        if (this.state.mouseState === "down") {
+            this.setState({
+                mouseState: "down-and-selecting",
+            });
+        }
+    };
+
+    _handleMouseDown: () => void = () => {
+        this.setState({mouseState: "down"});
+    };
+
+    _handleMouseUp: () => void = () => {
+        this.setState({mouseState: "up"});
+    };
+
+    render(): null | React.ReactElement<React.ComponentProps<"div">> {
+        const {mouseState, trackedSelection} = this.state;
+        const userIsMouseSelecting = mouseState === "down-and-selecting";
+
+        return this.props.children ? (
+            <div>
+                {this.props.children(trackedSelection, userIsMouseSelecting)}
+            </div>
+        ) : null;
+    }
+}
+
+export default SelectionTracker;

package/src/components/highlighting/ui/types.ts

@@ -0,0 +1,21 @@
+// Import the DOM-related types from the parent directory, and re-export them
+// to the UI code.
+import type {DOMHighlight, DOMHighlightSet, DOMRange} from "../types";
+
+export type {DOMHighlight, DOMHighlightSet, DOMRange};
+
+export type Position = {
+    left: number;
+    top: number;
+};
+
+export type Rect = Position & {
+    width: number;
+    height: number;
+};
+
+// TODO(mdr): Is this way of passing around `z-index: 0` actually worth the
+//     trouble? We used to have more, but now we don't need them...
+export type ZIndexes = {
+    belowContent: number;
+};

package/src/components/highlighting/ui/util.ts

@@ -0,0 +1,165 @@
+/**
+ * Utility functions for highlighting UI.
+ */
+import {rangesOverlap, intersectRanges} from "../ranges";
+
+import type {DOMRange, Position, Rect} from "./types";
+
+/**
+ * Given two positions relative to the same origin, return `child`'s position
+ * relative to `parent`'s position.
+ */
+export function getRelativePosition(
+    child: Position,
+    parent: Position,
+): Position {
+    return {
+        left: child.left - parent.left,
+        top: child.top - parent.top,
+    };
+}
+
+/**
+ * `getRelativePosition`, but for Rects.
+ *
+ * Given a rectangle and a position relative to the same origin, return a new
+ * rectangle of the same size, whose position is relative to the given
+ * position.
+ */
+export function getRelativeRect(
+    {left, top, width, height}: Rect,
+    parent: Position,
+): Rect {
+    return {
+        ...getRelativePosition({left, top}, parent),
+        width,
+        height,
+    };
+}
+
+/**
+ * Given a DOMRange, return a list of client-relative rects that cover the text
+ * inside the DOMRange.
+ *
+ * This behaves differently than the browser's built-in `getClientRects` method
+ * for DOMRanges, because this method only gets rects for the *text* nodes,
+ * whereas the browser's method will also return rects for any fully-contained
+ * *element* nodes.
+ *
+ * For example, if an entire paragraph is selected, then `getClientRects` will
+ * return a rectangle that covers the entire paragraph block, whereas this
+ * method will only return rectangles for the text inside the paragraph.
+ */
+export function getClientRectsForTextInRange(
+    range: DOMRange,
+): ReadonlyArray<Rect> {
+    const mutableRects = [];
+    addClientRectsForTextInNodeAndRange(
+        range.commonAncestorContainer,
+        range,
+        mutableRects,
+    );
+    return mutableRects;
+}
+
+/**
+ * A helper method for getClientRectsForTextInRange.
+ *
+ * Given a node and a range, find text that is contained within both the node
+ * and the range by recursing down the node's subtree, and push the text's
+ * client rects onto the given `mutableRects` array.
+ */
+function addClientRectsForTextInNodeAndRange(
+    node: Node,
+    range: DOMRange,
+    mutableRects: Array<Rect>,
+): void {
+    const nodeContentsRange = new Range();
+    nodeContentsRange.selectNodeContents(node);
+
+    if (node.nodeType === Node.TEXT_NODE) {
+        // Get the text that appears both in this text node and in the range
+        // we're searching.
+        const intersectedRange = intersectRanges(range, nodeContentsRange);
+        if (intersectedRange) {
+            addClientRectsForText(node, intersectedRange, mutableRects);
+        }
+    } else if (node.nodeType === Node.ELEMENT_NODE) {
+        // Don't bother deep-traversing a node that doesn't even overlap the
+        // range we're searching.
+        if (!rangesOverlap(range, nodeContentsRange)) {
+            return;
+        }
+
+        // NOTE(mdr): Safari returns a non-iterable `childNodes` object, so
+        //     convert it to an array.
+        for (const child of Array.from(node.childNodes)) {
+            // TODO(mdr): If this parent has overflow: hidden, bound the child
+            //     rects accordingly. This would allow us to remove the hack
+            //     we added to .perseus-sr-only.
+            addClientRectsForTextInNodeAndRange(child, range, mutableRects);
+        }
+    }
+}
+
+/**
+ * Given a DOMRange of text fully contained by the given `textNode`, compute
+ * rectangles that visually cover the range, and push them onto the given
+ * `mutableRects` array.
+ *
+ * This function adjusts the rectangles to the line height of the text, to
+ * match the visual behavior of native text selection, and remove annoying gaps
+ * between lines that disrupt hover behavior.
+ */
+function addClientRectsForText(
+    textNode: Node,
+    textRange: DOMRange,
+    mutableRects: Array<Rect>,
+): void {
+    const parentElement = textNode.parentElement;
+    // @ts-expect-error [FEI-5003] - TS2345 - Argument of type 'HTMLElement | null' is not assignable to parameter of type 'Element'.
+    const computedStyle = window.getComputedStyle(parentElement);
+
+    // NOTE(mdr): I'm not sure how computed line height works in all contexts
+    //     in all browsers. It's valid to specify line height as a ratio,
+    //     relative to font size. Latest Chrome seems to transform this into a
+    //     px value, but maybe some browsers don't, so I'm being defensive here
+    //     and only using the computed line height if it's explicitly a px
+    //     value. We could also handle other browsers by computing font size
+    //     and doing the math ourselves, but let's punt that until we need it.
+    let lineHeight = null;
+    if (
+        typeof computedStyle.lineHeight === "string" &&
+        computedStyle.lineHeight.endsWith("px")
+    ) {
+        const parsedLineHeight = parseFloat(computedStyle.lineHeight);
+        if (!isNaN(parsedLineHeight)) {
+            // @ts-expect-error [FEI-5003] - TS2322 - Type 'number' is not assignable to type 'null'.
+            lineHeight = parsedLineHeight;
+        }
+    }
+
+    // NOTE(mdr): Safari returns a non-iterable `getClientRects` object, so
+    //     convert it to an array.
+    const boundingRects = Array.from(textRange.getClientRects());
+
+    for (const boundingRect of boundingRects) {
+        const rect: Rect = {
+            left: boundingRect.left,
+            top: boundingRect.top,
+            height: boundingRect.height,
+            width: boundingRect.width,
+        };
+
+        // Adjust the rectangle according to the text's line height. It should
+        // keep the same bottom coordinate, so the top coordinate will move
+        // accordingly.
+        if (lineHeight !== null) {
+            const heightIncrease = lineHeight - rect.height;
+            rect.top -= heightIncrease;
+            rect.height = lineHeight;
+        }
+
+        mutableRects.push(rect);
+    }
+}

package/src/components/highlighting/word-indexer.tsx

@@ -0,0 +1,156 @@
+/**
+ * This component, whenever its content updates, traverses the DOM to find
+ * semantic words and send the corresponding DOMRanges to the caller via a
+ * callback.
+ *
+ * A "word" here is a sequence of non-whitespace text characters, uninterrupted
+ * by the start/end of a non-inline element. That is, a word can span across
+ * text nodes and inline tags like <b>, but cannot span across block
+ * paragraphs.
+ *
+ * The words yielded by WordIndexer are sorted in document order, which makes
+ * them amenable to binary search - see `findBoundaryWordIndex` in ranges.js.
+ */
+import * as React from "react";
+
+import {Errors} from "../../logging/log";
+import {PerseusError} from "../../perseus-error";
+
+import type {DOMRange} from "./types";
+
+type WordIndexerProps = {
+    // The content to display and traverse in search of words.
+    children?: React.ReactElement<any>;
+    // After each mount and update, this callback is called with the list of
+    // word ranges in `children`'s DOM, sorted in document order.
+    onWordsUpdate: (wordRanges: ReadonlyArray<DOMRange>) => unknown;
+};
+
+class WordIndexer extends React.PureComponent<WordIndexerProps> {
+    _container: HTMLElement | null | undefined;
+    /* eslint-enable react/sort-comp */
+
+    componentDidMount() {
+        this._sendWordsUpdate();
+    }
+
+    componentDidUpdate() {
+        this._sendWordsUpdate();
+    }
+
+    _sendWordsUpdate() {
+        this.props.onWordsUpdate(this._getWordRanges());
+    }
+
+    _getWordRanges(): ReadonlyArray<DOMRange> {
+        const container = this._container;
+
+        if (!container) {
+            throw new PerseusError(
+                "invariant violation: `this._container` is not defined, but " +
+                    "this method is only called after mount/update",
+                Errors.NotAllowed,
+            );
+        }
+
+        // Create a TreeWalker that visits text nodes and element nodes.
+        // We select the types of nodes we're interested in by bitwise-ORing
+        // the desired filters together.
+        const treeWalker = container.ownerDocument.createTreeWalker(
+            container,
+            NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT,
+            () => NodeFilter.FILTER_ACCEPT,
+            // @ts-expect-error [FEI-5003] - TS2554 - Expected 1-3 arguments, but got 4.
+            false,
+        );
+
+        // Traverse the container's descendant text nodes in DOM order,
+        // indexing the words we find.
+        const index: Array<Range> = [];
+        let trailingWordRange = null;
+        while (treeWalker.nextNode()) {
+            const node = treeWalker.currentNode;
+
+            if (node.nodeType === Node.ELEMENT_NODE) {
+                const element: Element = node as any;
+                if (getComputedStyle(element).display !== "inline") {
+                    // Block-level elements interrupt text words, so set the
+                    // current trailing word to `null`.
+                    //
+                    // This includes exiting one paragraph to visit another,
+                    // but also includes text interrupted by inline-block
+                    // elements.
+                    //
+                    // TODO(mdr): Is this behavior *generalizably* correct?
+                    // TODO(mdr): I don't *fully* understand the performance
+                    //     implications of `getComputedStyle`, but I think it's
+                    //     gonna be nbd at the current call sites. If we try to
+                    //     generalize to frequently-updating content, we might
+                    //     want to watch this as a potential performance
+                    //     bottleneck.
+                    trailingWordRange = null;
+                }
+            } else if (node.nodeType === Node.TEXT_NODE) {
+                const text = node.nodeValue;
+
+                // A "word" is here simply defined as a maximal-length
+                // substring of non-space characters.
+                //
+                // Loop over all the words in the string, by repeatedly calling
+                // `wordPattern.exec(text)`.
+                const wordPattern = /\S+/g;
+                let wordMatch;
+                let newTrailingWordRange = null;
+                // @ts-expect-error [FEI-5003] - TS2345 - Argument of type 'string | null' is not assignable to parameter of type 'string'.
+                while ((wordMatch = wordPattern.exec(text)) !== null) {
+                    // TODO(mdr): We found a new Flow error when upgrading:
+                    //     "index (Cannot get `wordMatch.index` because property `index` is missing in null [1].)"
+                    const startOffset = wordMatch.index;
+                    // TODO(mdr): We found a new Flow error when upgrading:
+                    //     "index (Cannot get `wordMatch.index` because property `index` is missing in null [1].)", "0 (Cannot get `wordMatch[0]` because an indexer property is missing in null [1].)"
+                    const endOffset = wordMatch.index + wordMatch[0].length;
+
+                    let range;
+                    if (startOffset === 0 && trailingWordRange) {
+                        // This word is at the start of this text node, and
+                        // there's a trailing word from the previous text node,
+                        // and there was no non-inline element between them.
+                        // This word and the trailing word are probably
+                        // intended to be two parts of the same word.
+                        //
+                        // So, instead of creating a new word range, we add
+                        // this word to the previous range by extending it.
+                        range = trailingWordRange;
+                        range.setEnd(node, endOffset);
+                    } else {
+                        // Otherwise, start a new word range here, and add it
+                        // to the list.
+                        // @ts-expect-error [FEI-5003] - TS2531 - Object is possibly 'null'.
+                        range = node.ownerDocument.createRange();
+                        range.setStart(node, startOffset);
+                        range.setEnd(node, endOffset);
+                        index.push(range);
+                    }
+
+                    // @ts-expect-error [FEI-5003] - TS2531 - Object is possibly 'null'.
+                    if (endOffset === text.length) {
+                        newTrailingWordRange = range;
+                    }
+                }
+                trailingWordRange = newTrailingWordRange;
+            }
+        }
+
+        return index;
+    }
+
+    render(): React.ReactNode {
+        return (
+            <div ref={(container) => (this._container = container)}>
+                {this.props.children}
+            </div>
+        );
+    }
+}
+
+export default WordIndexer;