@khanacademy/perseus 3.0.0 → 4.0.0

package/src/components/highlighting/ui/highlight-renderer.tsx

@@ -0,0 +1,175 @@
+/* eslint-disable react/no-unsafe */
+/**
+ * This component, given a single DOMHighlight, draws highlight rectangles in
+ * the same absolute position as the highlighted content, as computed via
+ * `getClientRects`.
+ *
+ * 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
+ *     `HighlightRenderer`.
+ */
+import {StyleSheet, css} from "aphrodite";
+import * as React from "react";
+
+import {
+    getClientRectsForTextInRange,
+    getRelativePosition,
+    getRelativeRect,
+} from "./util";
+
+import type {DOMHighlight, Position, Rect, ZIndexes} from "./types";
+
+type HighlightRendererProps = {
+    // The DOMHighlight to render.
+    highlight: DOMHighlight;
+    // A unique key corresponding to the given `highlight`.
+    highlightKey: string;
+    // 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;
+    // The z-indexes to use when rendering tooltips above content, and
+    // highlights below content.
+    zIndexes: ZIndexes;
+};
+
+type HighlightRendererState = {
+    // The set of rectangles that cover this highlight's content, relative to
+    // the offset parent. This cache is updated on mount and on changes to
+    // the `highlight` and `offsetParent` props.
+    //
+    // We perform this caching because HighlightSetRenderer uses this
+    // component's `isHovered` function to access the rectangles every time the
+    // user's mouse moves, in order to check the hover state, and recomputing
+    // them on every mousemove seems like it could be expensive on older
+    // devices (though tbf that's just a gut instinct, not the result of
+    // testing on older devices).
+    cachedHighlightRects: ReadonlyArray<Rect>;
+};
+
+class HighlightRenderer extends React.PureComponent<
+    HighlightRendererProps,
+    HighlightRendererState
+> {
+    state: HighlightRendererState = {
+        cachedHighlightRects: this._computeRects(this.props),
+        // @ts-expect-error [FEI-5003] - TS2322 - Type '{ cachedHighlightRects: readonly Rect[]; tooltipIsHovered: boolean; }' is not assignable to type 'HighlightRendererState'.
+        tooltipIsHovered: false,
+    };
+
+    UNSAFE_componentWillReceiveProps(nextProps: HighlightRendererProps) {
+        if (
+            this.props.highlight !== nextProps.highlight ||
+            this.props.offsetParent !== nextProps.offsetParent
+        ) {
+            this.setState({
+                cachedHighlightRects: this._computeRects(nextProps),
+            });
+        }
+    }
+
+    /**
+     * Compute the set of rectangles that cover the highlighted content, with
+     * coordinates relative to the offset parent. That way, we can use them
+     * for CSS positioning.
+     */
+    _computeRects(props: HighlightRendererProps): ReadonlyArray<Rect> {
+        const {highlight, offsetParent} = props;
+
+        // Get the set of rectangles that covers the range's text, relative to
+        // the offset parent.
+        const clientRects = getClientRectsForTextInRange(highlight.domRange);
+        const {left, top} = offsetParent.getBoundingClientRect();
+        const relativeRects = clientRects.map((rect) =>
+            getRelativeRect(rect, {left, top}),
+        );
+
+        return relativeRects;
+    }
+
+    /**
+     * Return whether the given mouse position (coordinates relative to this
+     * component's offset parent) is hovering over the given rectangle
+     * (coordinates also relative to this component's offset parent).
+     */
+    _rectIsHovered(rect: Rect, mouseOffsetPosition: Position): boolean {
+        const positionWithinRect = getRelativePosition(mouseOffsetPosition, {
+            left: rect.left,
+            top: rect.top,
+        });
+
+        return (
+            0 <= positionWithinRect.left &&
+            positionWithinRect.left < rect.width &&
+            0 <= positionWithinRect.top &&
+            positionWithinRect.top < rect.height
+        );
+    }
+
+    /**
+     * Return whether the given mouse position (coordinates relative to the
+     * viewport) is hovering over this highlight.
+     */
+    isHovered(mouseClientPosition?: Position | null): boolean {
+        if (!mouseClientPosition) {
+            return false;
+        }
+
+        const {offsetParent} = this.props;
+        const {cachedHighlightRects} = this.state;
+
+        // Convert the client-relative mouse coordinates to be relative to the
+        // offset parent. That way, we can compare them to the cached highlight
+        // rectangles.
+        const {left, top} = offsetParent.getBoundingClientRect();
+        const mouseOffsetPosition = getRelativePosition(mouseClientPosition, {
+            left,
+            top,
+        });
+
+        return cachedHighlightRects.some((rect) =>
+            this._rectIsHovered(rect, mouseOffsetPosition),
+        );
+    }
+
+    render(): React.ReactNode {
+        const rects = this.state.cachedHighlightRects;
+
+        return (
+            <div>
+                {rects.map((rect, index) => (
+                    <div
+                        key={index}
+                        className={css(styles.highlightRect)}
+                        style={{
+                            // NOTE(mdr): We apply `position: absolute` here
+                            //     rather than in Aphrodite styles, because
+                            //     Aphrodite styles are delayed. If this
+                            //     element temporarily has `position: static`,
+                            //     then it'll displace the content, and other
+                            //     highlights rendering during this update will
+                            //     measure the displaced content instead, oops!
+                            position: "absolute",
+                            width: rect.width,
+                            height: rect.height,
+                            top: rect.top,
+                            left: rect.left,
+                            zIndex: this.props.zIndexes.belowContent,
+                        }}
+                    />
+                ))}
+            </div>
+        );
+    }
+}
+
+const styles = StyleSheet.create({
+    highlightRect: {
+        background: "#fffabe", // highlighter yellow :)
+    },
+});
+
+export default HighlightRenderer;

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

@@ -0,0 +1,188 @@
+/* eslint-disable react/no-unsafe */
+/**
+ * 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";
+import HighlightTooltip from "./highlight-tooltip";
+
+import type {DOMHighlightSet, Position, ZIndexes} from "./types";
+
+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) => unknown;
+    // 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 | null | undefined;
+    // If the user is currently hovering over the "Remove highlight" tooltip,
+    // this field contains the key of the corresponding highlight.
+    hoveringTooltipFor: string | null | undefined;
+};
+
+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} as const;
+        const hoveredHighlightKey =
+            this._getHoveredHighlightKey(mouseClientPosition);
+        this.setState({hoveredHighlightKey});
+    };
+
+    _getHoveredHighlightKey(
+        mouseClientPosition: Position,
+    ): string | null | undefined {
+        // 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.ReactNode {
+        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.ReactNode {
+        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.tsx

@@ -0,0 +1,141 @@
+/**
+ * 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";
+
+import {getRelativeRect} from "./util";
+
+import type {Rect} from "./types";
+
+type HighlightTooltipProps = {
+    label: string;
+    onClick: () => unknown;
+    onMouseEnter?: () => unknown;
+    onMouseLeave?: () => unknown;
+    focusNode: Node;
+    focusOffset: number;
+    offsetParent: Element;
+};
+
+class HighlightTooltip extends React.PureComponent<HighlightTooltipProps> {
+    _getFocusRect(): Rect | null | undefined {
+        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.ReactNode {
+        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: any = (
+            <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,
+        } as const;
+
+        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.tsx

@@ -0,0 +1,153 @@
+/**
+ * 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";
+
+import HighlightSetRenderer from "./highlight-set-renderer";
+import HighlightTooltip from "./highlight-tooltip";
+import SelectionTracker from "./selection-tracker";
+
+import type {TrackedSelection} from "./selection-tracker";
+import type {DOMHighlight, DOMHighlightSet, DOMRange, ZIndexes} from "./types";
+
+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 | null | undefined;
+    // 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) => unknown;
+    // A callback indicating that the user would like to remove the highlight
+    // with the given key.
+    onRemoveHighlight: (highlightKey: string) => unknown;
+    // 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 | null): 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.ReactNode {
+        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)
+                                            // @ts-expect-error [FEI-5003] - TS2533 - Object is possibly 'null' or 'undefined'.
+                                            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)
+                                    // @ts-expect-error [FEI-5003] - TS2533 - Object is possibly 'null' or 'undefined'.
+                                    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)
+                                    // @ts-expect-error [FEI-5003] - TS2533 - Object is possibly 'null' or 'undefined'.
+                                    focusOffset={trackedSelection.focusOffset}
+                                    offsetParent={this.props.offsetParent}
+                                />
+                            )}
+                    </div>
+                )}
+            </SelectionTracker>
+        );
+    }
+}
+
+export default HighlightingUI;