@khanacademy/perseus 19.1.5 → 19.1.6

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

@@ -1,186 +0,0 @@
-/* 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 Props = {
-    // 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 State = {
-    // 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<Props, State> {
-    state: State = {
-        mouseState: "up",
-        trackedSelection: null,
-    };
-
-    componentDidMount() {
-        this._updateListeners(false, this.props.enabled);
-    }
-
-    componentDidUpdate(prevProps: Props) {
-        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 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

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

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

@@ -1,152 +0,0 @@
-/**
- * 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 Props = {
-    // 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<Props> {
-    _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 - 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 - TS2345 - Argument of type 'string | null' is not assignable to parameter of type 'string'.
-                while ((wordMatch = wordPattern.exec(text)) !== null) {
-                    const startOffset = wordMatch.index;
-                    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 - TS2531 - Object is possibly 'null'.
-                        range = node.ownerDocument.createRange();
-                        range.setStart(node, startOffset);
-                        range.setEnd(node, endOffset);
-                        index.push(range);
-                    }
-
-                    // @ts-expect-error - 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;

package/src/components/hud.tsx

@@ -1,167 +0,0 @@
-import {StyleSheet, css} from "aphrodite";
-import * as React from "react";
-
-import * as constants from "../styles/constants";
-
-// Displays a stylized open eye: lint warnings are visible
-const VisibleIcon = () => (
-    <svg
-        width="24"
-        height="24"
-        viewBox="0 0 24 24"
-        className={css(styles.icon)}
-    >
-        <defs>
-            <path
-                id="a"
-                d={
-                    "M7.401 10.035c-1.424.748-2.599 1.905-3.544 " +
-                    "3.48a1 1 0 0 1-1.714-1.03C4.325 8.849 7.652 7 " +
-                    "12 7c4.348 0 7.675 1.848 9.857 5.486a1 1 0 0 " +
-                    "1-1.714 1.028c-.945-1.574-2.12-2.73-3.544-" +
-                    "3.48a5 5 0 1 1-9.198 0zM12 15a3 3 0 1 0 0-6 3 3 " +
-                    "0 0 0 0 6z"
-                }
-            />
-        </defs>
-        <g fill="none" fillRule="evenodd">
-            <path fill="none" d="M0 0h24v24H0z" />
-            <mask id="b" fill="#fff">
-                <use href="#a" />
-            </mask>
-            <use fill="#fff" fillRule="nonzero" href="#a" />
-            <g fill="#fff" mask="url(#b)">
-                <path d="M0 0h24v24H0z" />
-            </g>
-        </g>
-    </svg>
-);
-
-// Displays a stylized eye with a line through it: I don't want to see lint
-const HiddenIcon = () => (
-    <svg
-        width="24"
-        height="24"
-        viewBox="0 0 24 24"
-        className={css(styles.icon)}
-    >
-        <defs>
-            <path
-                id="a"
-                d={
-                    "M8.794 7.38C9.791 7.127 10.86 7 12 7c4.348 0 " +
-                    "7.675 1.848 9.857 5.486a1 1 0 0 1-1.714 " +
-                    "1.028c-.945-1.574-2.12-2.73-3.544-3.48.258." +
-                    "604.401 1.268.401 1.966 0 1.02-.305 " +
-                    "1.967-.828 2.757l2.535 2.536a1 1 0 0 " +
-                    "1-1.414 1.414l-12-12a1 1 0 0 1 " +
-                    "1.414-1.414L8.794 7.38zm5.914 5.913a3 3 0 0 " +
-                    "0-4.001-4.001l4 4.001zM6.072 8.486l2.976 " +
-                    "2.976a3 3 0 0 0 3.49 3.49l1.579 1.58A5 5 0 " +
-                    "0 1 7.4 10.035c-1.424.747-2.599 1.904-3.544 " +
-                    "3.478a1 1 0 0 1-1.714-1.028c1.049-1.75 " +
-                    "2.363-3.085 3.929-4z"
-                }
-            />
-        </defs>
-        <g fill="none" fillRule="evenodd">
-            <path fill="none" d="M0 0h24v24H0z" />
-            <mask id="b" fill="#fff">
-                <use href="#a" />
-            </mask>
-            <use fill="#fff" fillRule="nonzero" href="#a" />
-            <g fill="#fff" mask="url(#b)">
-                <path d="M0 0h24v24H0z" />
-            </g>
-        </g>
-    </svg>
-);
-
-type Props = {
-    message: string;
-    enabled: boolean;
-    onClick: () => void;
-    fixedPosition?: boolean;
-};
-
-const HUD = ({message, enabled, onClick, fixedPosition = true}: Props) => {
-    let state;
-    let icon;
-    if (enabled) {
-        state = styles.enabled;
-        icon = <VisibleIcon />;
-    } else {
-        state = styles.disabled;
-        icon = <HiddenIcon />;
-    }
-
-    return (
-        <button
-            className={css(
-                styles.hud,
-                fixedPosition && styles.hudFixedPosition,
-                state,
-            )}
-            onClick={(e) => {
-                onClick();
-            }}
-        >
-            {icon}
-            {message}
-        </button>
-    );
-};
-
-const styles = StyleSheet.create({
-    hud: {
-        boxSizing: "border-box",
-        height: 36,
-        padding: "9px 16px",
-        borderRadius: 18,
-        fontFamily: constants.boldFontFamily,
-        fontSize: "15px",
-        lineHeight: "18px",
-        color: constants.white,
-        userSelect: "none",
-        borderWidth: 0, // <button> gives us a border by default
-    },
-
-    // We want to render the element in-place in our fixtures, so allow us to
-    // render in the bottom corner in production and in-place in testing.
-    hudFixedPosition: {
-        bottom: 20,
-        position: "fixed",
-        right: 20,
-        zIndex: 1,
-    },
-
-    icon: {
-        width: 24,
-        height: 24,
-        marginRight: 8,
-        marginTop: -3,
-        verticalAlign: "middle",
-    },
-
-    enabled: {
-        backgroundColor: constants.warningColor,
-        ":hover": {
-            backgroundColor: constants.warningColorHover,
-        },
-        ":active": {
-            backgroundColor: constants.warningColorActive,
-        },
-    },
-
-    disabled: {
-        backgroundColor: constants.gray76,
-        ":hover": {
-            backgroundColor: "#a1a5a9", // in between those two grays
-        },
-        ":active": {
-            backgroundColor: constants.gray68,
-        },
-    },
-});
-
-export default HUD;