@khanacademy/perseus 2.1.0 → 4.0.0

package/src/components/highlighting/ui/highlight-set-renderer.jsx

@@ -1,190 +0,0 @@
-/* eslint-disable react/no-unsafe */
-// @flow
-/**
- * Render a set of highlights. See HighlightRenderer for more details about how
- * each highlight is rendered.
- *
- * This component manages the state of the "Remove highlight" tooltip. To
- * determine the currently-hovered highlight, it calls the `isHovered` method
- * on each HighlightRenderer.
- */
-import * as i18n from "@khanacademy/wonder-blocks-i18n";
-import * as React from "react";
-
-import HighlightRenderer from "./highlight-renderer.jsx";
-import HighlightTooltip from "./highlight-tooltip.jsx";
-
-import type {DOMHighlightSet, Position, ZIndexes} from "./types.js";
-
-type HighlightSetRendererProps = {|
-    // Whether the highlights are user-editable. If false, highlights are
-    // read-only.
-    editable: boolean,
-
-    // A set of highlights to render.
-    highlights: DOMHighlightSet,
-
-    // This component's `offsetParent` element, which is the nearest ancestor
-    // with `position: relative`. This will enable us to choose the correct
-    // CSS coordinates to align highlights and tooltips with the target
-    // content.
-    offsetParent: Element,
-
-    // A callback indicating that the user would like to remove the highlight
-    // with the given key.
-    onRemoveHighlight: (highlightKey: string) => mixed,
-
-    // The z-indexes to use when rendering tooltips above content, and
-    // highlights below content.
-    zIndexes: ZIndexes,
-|};
-type HighlightSetRendererState = {
-    // If the user is currently hovering over a highlight, this field contains
-    // its key.
-    hoveredHighlightKey: ?string,
-    // If the user is currently hovering over the "Remove highlight" tooltip,
-    // this field contains the key of the corresponding highlight.
-    hoveringTooltipFor: ?string,
-    ...
-};
-
-class HighlightSetRenderer extends React.PureComponent<
-    HighlightSetRendererProps,
-    HighlightSetRendererState,
-> {
-    state: HighlightSetRendererState = {
-        hoveredHighlightKey: null,
-        hoveringTooltipFor: null,
-    };
-
-    // eslint-disable-next-line react/sort-comp
-    _highlightRenderers: {[highlightKey: string]: HighlightRenderer, ...} = {};
-
-    componentDidMount() {
-        this._updateEditListeners(false, this.props.editable);
-    }
-
-    UNSAFE_componentWillReceiveProps(nextProps: HighlightSetRendererProps) {
-        this._updateEditListeners(this.props.editable, nextProps.editable);
-
-        // If we were previously hovering over a highlight that has been
-        // removed, reset the hover state accordingly.
-        if (
-            this.state.hoveredHighlightKey != null &&
-            !(this.state.hoveredHighlightKey in nextProps.highlights)
-        ) {
-            this.setState({hoveredHighlightKey: null});
-        }
-
-        // Similarly, if we were previously hovering over the tooltip for a
-        // highlight that has been removed, reset the hover state accordingly.
-        if (
-            this.state.hoveringTooltipFor != null &&
-            !(this.state.hoveringTooltipFor in nextProps.highlights)
-        ) {
-            this.setState({hoveringTooltipFor: null});
-        }
-    }
-
-    componentWillUnmount() {
-        this._updateEditListeners(this.props.editable, false);
-    }
-
-    /**
-     * Given whether we were previously listening to mousemove events, and
-     * whether we will now listen to mousemove events, add or remove the
-     * listener accordingly.
-     */
-    _updateEditListeners(wasListening: boolean, willListen: boolean) {
-        if (!wasListening && willListen) {
-            window.addEventListener("mousemove", this._handleMouseMove);
-        } else if (wasListening && !willListen) {
-            window.removeEventListener("mousemove", this._handleMouseMove);
-
-            // Additionally, reset the hover state, to ensure that we don't
-            // keep old hover state around.
-            this.setState({
-                hoveredHighlightKey: null,
-                hoveringTooltipFor: null,
-            });
-        }
-    }
-
-    _handleMouseMove: (e: MouseEvent) => void = (e: MouseEvent) => {
-        const mouseClientPosition = {left: e.clientX, top: e.clientY};
-        const hoveredHighlightKey =
-            this._getHoveredHighlightKey(mouseClientPosition);
-        this.setState({hoveredHighlightKey});
-    };
-
-    _getHoveredHighlightKey(mouseClientPosition: Position): ?string {
-        // If we're hovering over the tooltip, the hovered highlight is the
-        // highlight that the tooltip is pointing to.
-        const {hoveringTooltipFor} = this.state;
-        if (typeof hoveringTooltipFor === "string") {
-            return hoveringTooltipFor;
-        }
-
-        // Otherwise, check each highlight renderer to see whether the current
-        // mouse position intersects any of the highlight rectangles.
-        const highlightKeys = Object.keys(this.props.highlights);
-        return highlightKeys.find((key) => {
-            const highlightRenderer = this._highlightRenderers[key];
-            return (
-                highlightRenderer &&
-                highlightRenderer.isHovered(mouseClientPosition)
-            );
-        });
-    }
-
-    _renderTooltip(): null | React.Node {
-        const {hoveredHighlightKey} = this.state;
-        if (hoveredHighlightKey == null) {
-            return null;
-        }
-
-        const hoveredHighlight = this.props.highlights[hoveredHighlightKey];
-
-        return (
-            <HighlightTooltip
-                label={i18n._("Remove highlight")}
-                focusNode={hoveredHighlight.domRange.endContainer}
-                focusOffset={hoveredHighlight.domRange.endOffset}
-                offsetParent={this.props.offsetParent}
-                onClick={() =>
-                    this.props.onRemoveHighlight(hoveredHighlightKey)
-                }
-                onMouseEnter={() =>
-                    this.setState({hoveringTooltipFor: hoveredHighlightKey})
-                }
-                onMouseLeave={() => this.setState({hoveringTooltipFor: null})}
-            />
-        );
-    }
-
-    render(): React.Element<"div"> {
-        return (
-            <div>
-                {Object.keys(this.props.highlights).map((key) => (
-                    <HighlightRenderer
-                        ref={(r) => {
-                            if (r) {
-                                this._highlightRenderers[key] = r;
-                            } else {
-                                delete this._highlightRenderers[key];
-                            }
-                        }}
-                        key={key}
-                        highlight={this.props.highlights[key]}
-                        highlightKey={key}
-                        offsetParent={this.props.offsetParent}
-                        zIndexes={this.props.zIndexes}
-                    />
-                ))}
-                {this.props.editable && this._renderTooltip()}
-            </div>
-        );
-    }
-}
-
-export default HighlightSetRenderer;

package/src/components/highlighting/ui/highlight-tooltip.jsx

@@ -1,143 +0,0 @@
-// @flow
-/**
- * A tooltip to point to the focus of a highlight.
- *
- * We use the NewTooltip component, which positions itself not by coordinate,
- * but by watching the position of a target DOM element. So, we render a 0x0
- * DOM element, absolute-position it to the position of the the highlight
- * focus, and point the tooltip at that 0x0 element.
- *
- * This technique enables NewTooltip to use its existing visibility-watching
- * and scroll-tracking logic to effectively "watch" the focus of this
- * highlight. So, we get lots of the repositioning logic for free! But we _do_
- * still have to notify the tooltip to remeasure itself when the highlight
- * focus _changes_.
- */
-import Spacing from "@khanacademy/wonder-blocks-spacing";
-import Tooltip from "@khanacademy/wonder-blocks-tooltip";
-import {StyleSheet, css} from "aphrodite";
-import * as React from "react";
-
-import {Log} from "../../../logging/log.js";
-
-import {getRelativeRect} from "./util.js";
-
-import type {Rect} from "./types.js";
-
-type HighlightTooltipProps = {|
-    label: string,
-    onClick: () => mixed,
-    onMouseEnter?: () => mixed,
-    onMouseLeave?: () => mixed,
-
-    focusNode: Node,
-    focusOffset: number,
-    offsetParent: Element,
-|};
-
-class HighlightTooltip extends React.PureComponent<HighlightTooltipProps> {
-    _getFocusRect(): ?Rect {
-        const {focusNode, focusOffset, offsetParent} = this.props;
-
-        // Get a range of *just* the focus point of the selection.
-        const focusRange = document.createRange();
-        focusRange.setStart(focusNode, focusOffset);
-        focusRange.setEnd(focusNode, focusOffset);
-
-        // Then, get the bounding box of the collapsed range. This will be a
-        // zero-width rectangle, but still have positioning information, which
-        // we can use the position the tooltip.
-        //
-        // NOTE(mdr): If we used getClientBoundingRect here instead, Safari
-        //     would return an unpositioned rect. But all tested browsers at
-        //     time of writing (latest Chrome, Firefox, Safari) return at least
-        //     one rectangle from getClientRects, and it's well-positioned.
-        const focusRect = focusRange.getClientRects()[0];
-
-        // NOTE(mdr): ...except in the case where the focus is between two
-        //     paragraphs, in which case the focus range has no client rects?
-        //     Not sure why, or in what browsers (only noticed in Chrome 60),
-        //     but let's catch that case and bail out.
-        // TODO(mdr): Instead, we should somehow walk back the range until we
-        //     find an appropriate position for the tooltip. Sounds tricky!
-        if (!focusRect) {
-            Log.log(
-                "[Highlighting] Known bug: Could not determine the focus " +
-                    'position, so did not show an "Add Highlight" tooltip. ' +
-                    "https://app.asana.com/0/329800276300868/413878480039713 " +
-                    "(see also /r/asana-links)",
-            );
-            return null;
-        }
-
-        // Compute the desired position of the tooltip relative to the offset
-        // parent.
-        const {left, top} = offsetParent.getBoundingClientRect();
-        const relativeFocusRect = getRelativeRect(
-            {
-                left: focusRect.left,
-                top: focusRect.top,
-                width: focusRect.width,
-                height: focusRect.height,
-            },
-            {left, top},
-        );
-
-        return relativeFocusRect;
-    }
-
-    render(): null | React.Node {
-        const focusRect = this._getFocusRect();
-        if (!focusRect) {
-            return null;
-        }
-
-        // using div instead of TooltipContent because
-        // TooltipContent wouldn't let me overwrite
-        // user-select and onClick
-        const content: $FlowFixMe = (
-            <div
-                className={css(styles.tooltipLabel)}
-                onClick={this.props.onClick}
-            >
-                {this.props.label}
-            </div>
-        );
-
-        const style = {
-            position: "absolute",
-            left: focusRect.left,
-            // offset the spacing WB provides around tooltips
-            top: `calc(${Math.round(focusRect.top)}px + 0.95em)`,
-            height: 0,
-        };
-
-        return (
-            <div
-                style={style}
-                onMouseEnter={this.props.onMouseEnter}
-                onMouseLeave={this.props.onMouseLeave}
-            >
-                <Tooltip content={content} opened={true}>
-                    <div />
-                </Tooltip>
-            </div>
-        );
-    }
-}
-
-const styles = StyleSheet.create({
-    tooltipLabel: {
-        // Unlike most tooltip contents, we don't want this label to be
-        // selectable. Selecting it is not only unhelpful, but dangerous: if
-        // the user accidentally selects the "Add highlight" tooltip text, then
-        // we lose our reference to the _actual_ text they want to highlight,
-        // and the "Add highlight" action fails.
-        userSelect: "none",
-        fontFamily: `"Lato", sans-serif`,
-        padding: `10px ${Spacing.medium_16}px`,
-        cursor: "pointer",
-    },
-});
-
-export default HighlightTooltip;

package/src/components/highlighting/ui/highlighting-ui.jsx

@@ -1,163 +0,0 @@
-// @flow
-/**
- * This component, given a set of DOMHighlights, draws highlight rectangles in
- * the same absolute position as the highlighted content, as computed by the
- * range's `getClientRects` method.
- *
- * TODO(mdr): Many things can affect the correct positioning of highlighting,
- *     and this component does not attempt to anticipate them. If we start
- *     using this highlighting library on content with a more dynamic layout,
- *     we should add a hook to allow the parent to `forceUpdate` the
- *     `HighlightingUI`.
- */
-import * as i18n from "@khanacademy/wonder-blocks-i18n";
-import * as React from "react";
-
-import {rangesOverlap} from "../ranges.js";
-
-import HighlightSetRenderer from "./highlight-set-renderer.jsx";
-import HighlightTooltip from "./highlight-tooltip.jsx";
-import SelectionTracker from "./selection-tracker.jsx";
-
-import type {TrackedSelection} from "./selection-tracker.jsx";
-import type {
-    DOMHighlight,
-    DOMHighlightSet,
-    DOMRange,
-    ZIndexes,
-} from "./types.js";
-
-type HighlightingUIProps = {|
-    // 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: (range: DOMRange) => ?DOMHighlight,
-
-    // A Node that contains the highlightable content.
-    contentNode: Node,
-
-    // Whether the highlights are user-editable. If false, highlights are
-    // read-only.
-    editable: boolean,
-
-    // A set of highlights to render.
-    highlights: DOMHighlightSet,
-
-    // This component's `offsetParent` element, which is the nearest ancestor
-    // with `position: relative`. This will enable us to choose the correct
-    // CSS coordinates to align highlights and tooltips with the target
-    // content.
-    offsetParent: Element,
-
-    // A callback indicating that the user would like to add the given
-    // highlight to the current set of highlights.
-    onAddHighlight: (range: DOMHighlight) => mixed,
-
-    // A callback indicating that the user would like to remove the highlight
-    // with the given key.
-    onRemoveHighlight: (highlightKey: string) => mixed,
-
-    // The z-indexes to use when rendering tooltips above content, and
-    // highlights below content.
-    zIndexes: ZIndexes,
-|};
-
-class HighlightingUI extends React.PureComponent<HighlightingUIProps> {
-    _handleAddHighlight(highlightToAdd: DOMHighlight) {
-        this.props.onAddHighlight(highlightToAdd);
-
-        // Deselect the newly-highlighted text, by collapsing the selection
-        // to the end of the range.
-        const selection = document.getSelection();
-        if (selection) {
-            selection.collapseToEnd();
-        }
-    }
-
-    _selectionIsValid(trackedSelection: ?TrackedSelection): boolean {
-        if (!trackedSelection) {
-            return false;
-        }
-
-        const {contentNode} = this.props;
-
-        // Create a range over the content node.
-        const contentRange = new Range();
-        contentRange.selectNodeContents(contentNode);
-
-        // Create a range over the focus position.
-        const focusRange = new Range();
-        focusRange.setStart(
-            trackedSelection.focusNode,
-            trackedSelection.focusOffset,
-        );
-        focusRange.collapse(true /* to start */);
-
-        // Determine whether the content range contains the focus, by checking
-        // whether they intersect. Because the focus range is a single point,
-        // intersection is equivalent to being fully contained.
-        const contentContainsFocus = rangesOverlap(contentRange, focusRange);
-
-        // If the content contains the focus, this is a valid selection. Some
-        // parts of the range might go beyond the content, but that's okay; the
-        // corresponding DOMHighlight is already trimmed to only contain valid
-        // words. We're just checking that the tooltip we render will be inside
-        // the content, because rendering a tooltip outside the content would
-        // be weird.
-        const selectionIsValid = contentContainsFocus;
-
-        return selectionIsValid;
-    }
-
-    render(): React.Node {
-        return (
-            <SelectionTracker
-                buildHighlight={this.props.buildHighlight}
-                enabled={this.props.editable}
-            >
-                {(trackedSelection, userIsMouseSelecting) => (
-                    <div>
-                        <HighlightSetRenderer
-                            editable={
-                                /* An existing highlight is editable when the
-                                 * component is in editable mode, and there's no
-                                 * selection in progress. */
-                                this.props.editable &&
-                                !this._selectionIsValid(trackedSelection)
-                            }
-                            highlights={this.props.highlights}
-                            offsetParent={this.props.offsetParent}
-                            onRemoveHighlight={this.props.onRemoveHighlight}
-                            zIndexes={this.props.zIndexes}
-                        />
-                        {this._selectionIsValid(trackedSelection) &&
-                            !userIsMouseSelecting && (
-                                <HighlightTooltip
-                                    label={i18n._("Add highlight")}
-                                    onClick={() =>
-                                        this._handleAddHighlight(
-                                            // TODO(mdr): We found a new Flow error when upgrading:
-                                            //     "proposedHighlight (Cannot get `trackedSelection.proposedHighlight` because property `proposedHighlight` is missing in null or undefined [1].)"
-                                            // $FlowFixMe[incompatible-use](0.57.3->0.75.0)
-                                            trackedSelection.proposedHighlight,
-                                        )
-                                    }
-                                    // TODO(mdr): We found a new Flow error when upgrading:
-                                    //     "focusNode (Cannot get `trackedSelection.focusNode` because property `focusNode` is missing in null or undefined [1].)"
-                                    // $FlowFixMe[incompatible-use](0.57.3->0.75.0)
-                                    focusNode={trackedSelection.focusNode}
-                                    // TODO(mdr): We found a new Flow error when upgrading:
-                                    //     "focusOffset (Cannot get `trackedSelection.focusOffset` because property `focusOffset` is missing in null or undefined [1].)"
-                                    // $FlowFixMe[incompatible-use](0.57.3->0.75.0)
-                                    focusOffset={trackedSelection.focusOffset}
-                                    offsetParent={this.props.offsetParent}
-                                />
-                            )}
-                    </div>
-                )}
-            </SelectionTracker>
-        );
-    }
-}
-
-export default HighlightingUI;

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

@@ -1,184 +0,0 @@
-/* eslint-disable react/no-unsafe */
-// @flow
-/**
- * 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.js";
-
-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,
-    // 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,
-        userIsMouseSelecting: boolean,
-    ) => React.Element<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,
-|};
-
-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,
-    |} {
-        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: 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};
-        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.Element<"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;