@khanacademy/perseus 3.0.0 → 4.0.0

package/src/components/graphie.tsx

@@ -0,0 +1,357 @@
+import $ from "jquery";
+import PropTypes from "prop-types";
+import * as React from "react";
+import ReactDOM from "react-dom";
+import _ from "underscore";
+
+import InteractiveUtil from "../interactive2/interactive-util";
+import {Errors, Log} from "../logging/log";
+import Util from "../util";
+import GraphUtils from "../util/graph-utils";
+
+import GraphieClasses from "./graphie-classes";
+import Movables from "./graphie-movables";
+
+const GraphieMovable = GraphieClasses.GraphieMovable;
+
+const createGraphie = GraphUtils.createGraphie;
+const {deepEq, nestedMap} = Util;
+const {assert} = InteractiveUtil;
+
+type Props = any;
+
+class Graphie extends React.Component<Props> {
+    static propTypes = {
+        addMouseLayer: PropTypes.bool,
+        box: PropTypes.arrayOf(PropTypes.number).isRequired,
+        children: PropTypes.node,
+        isMobile: PropTypes.bool,
+        onClick: PropTypes.func,
+        onMouseDown: PropTypes.func,
+        onMouseMove: PropTypes.func,
+        onMouseUp: PropTypes.func,
+        options: PropTypes.shape({
+            snapStep: PropTypes.arrayOf(PropTypes.number),
+        }),
+        range: PropTypes.arrayOf(PropTypes.arrayOf(PropTypes.number)),
+        responsive: PropTypes.bool,
+        setDrawingAreaAvailable: PropTypes.func,
+        setup: PropTypes.func.isRequired,
+    };
+
+    static defaultProps: any = {
+        range: [
+            [-10, 10],
+            [-10, 10],
+        ],
+        options: {},
+        responsive: false,
+        addMouseLayer: true,
+    };
+
+    componentDidMount() {
+        this._setupGraphie();
+        this._updateMovables();
+    }
+
+    shouldComponentUpdate(nextProps: Props): boolean {
+        // NOTE(jeresig): Prior to the React 16 upgrade this was using deepEq
+        // However it started to throw errors. I switched to use Underscore's
+        // isEqual method instead, hopefully having a similar effect.
+        return !_.isEqual(this.props, nextProps);
+    }
+
+    componentDidUpdate(prevProps: Props) {
+        // If someone changes the setup function passed in, we should
+        // technically setup graphie again. But that's definitely an
+        // anti-pattern, since it is most-likely caused by passing in an
+        // anonymous function rather than a "real" change, and re-rendering
+        // in that case would cause us to constantly re-setup graphie, which
+        // would have horrible performance implications. In order to avoid
+        // those, we just warn here.
+        if (this.props.setup !== prevProps.setup) {
+            Log.error(
+                "<Graphie> was given a new setup function. " +
+                    "This is a bad idea; please refactor your code to give " +
+                    "the same setup function reference to <Graphie> on " +
+                    "every render.",
+                Errors.Internal,
+            );
+        }
+        if (
+            !deepEq(this.props.options, prevProps.options) ||
+            !deepEq(this.props.box, prevProps.box) ||
+            !deepEq(this.props.range, prevProps.range)
+        ) {
+            this._setupGraphie();
+        }
+        this._updateMovables();
+    }
+
+    /**
+     * Allow parents of the <Graphie> component to grab a reference to the
+     * underlying graphie object using
+     * `this.refs.graphieComponent.getGraphie()`
+     *
+     * This shouldn't be necessary for 90% of cases, but the power is there.
+     * Use it for good and not evil.
+     */
+    getGraphie: () => any = () => {
+        // @ts-expect-error [FEI-5003] - TS2339 - Property '_graphie' does not exist on type 'Graphie'.
+        return this._graphie;
+    };
+
+    // bounds-checked range
+    _range: () => ReadonlyArray<[number, number]> = () => {
+        return _.map(this.props.range, (dimRange) => {
+            if (dimRange[0] >= dimRange[1]) {
+                return [-10, 10];
+            }
+            return dimRange;
+        });
+    };
+
+    _box: () => ReadonlyArray<number> = () => {
+        return _.map(this.props.box, (pixelDim) => {
+            // 340 = default size in the editor. exact value
+            // is arbitrary; this is just a safety check.
+            return pixelDim > 0 ? pixelDim : 340;
+        });
+    };
+
+    _scale: () => ReadonlyArray<number> = () => {
+        const box = this._box();
+        const range = this._range();
+        return _.map(box, (pixelDim, i) => {
+            const unitDim = range[i][1] - range[i][0];
+            return pixelDim / unitDim;
+        });
+    };
+
+    _setupGraphie: () => void = () => {
+        this._removeMovables();
+
+        // eslint-disable-next-line react/no-string-refs
+        const graphieDiv = ReactDOM.findDOMNode(this.refs.graphieDiv);
+        // @ts-expect-error [FEI-5003] - TS2769 - No overload matches this call. | TS2339 - Property 'empty' does not exist on type 'JQueryStatic'.
+        $(graphieDiv).empty();
+        // @ts-expect-error [FEI-5003] - TS2339 - Property '_graphie' does not exist on type 'Graphie'.
+        const graphie = (this._graphie = createGraphie(graphieDiv));
+
+        // This has to be called before addMouseLayer. You can re-init
+        // with graphInit later if you prefer
+        graphie.init({
+            range: this._range(),
+            scale: this._scale(),
+            isMobile: this.props.isMobile,
+        });
+        // Only add the mouselayer if we actually want one.
+        if (this.props.addMouseLayer) {
+            graphie.addMouseLayer({
+                onClick: this.props.onClick,
+                onMouseDown: this.props.onMouseDown,
+                onMouseUp: this.props.onMouseUp,
+                onMouseMove: this.props.onMouseMove,
+                setDrawingAreaAvailable: this.props.setDrawingAreaAvailable,
+            });
+        }
+
+        graphie.snap = this.props.options.snapStep || [1, 1];
+
+        if (this.props.responsive) {
+            // Overwrite fixed styles set in init()
+            // TODO(alex): Either make this component always responsive by
+            // itself, or always wrap it in other components so that it is.
+            // @ts-expect-error [FEI-5003] - TS2769 - No overload matches this call. | TS2554 - Expected 2 arguments, but got 1.
+            $(graphieDiv).css({width: "100%", height: "100%"});
+            graphie.raphael.setSize("100%", "100%");
+        }
+
+        this.props.setup(
+            graphie,
+            _.extend(
+                {
+                    range: this._range(),
+                    scale: this._scale(),
+                },
+                this.props.options,
+            ),
+        );
+    };
+
+    _removeMovables: () => void = () => {
+        // _.invoke works even when this._movables is undefined
+        // @ts-expect-error [FEI-5003] - TS2339 - Property '_movables' does not exist on type 'Graphie'.
+        _.invoke(this._movables, "remove");
+        // @ts-expect-error [FEI-5003] - TS2339 - Property '_movables' does not exist on type 'Graphie'.
+        this._movables = {};
+    };
+
+    // @ts-expect-error [FEI-5003] - TS2322 - Type '(children: readonly any[], options: any) => ReactElement<any, string | JSXElementConstructor<any>> | readonly ReactElement<any, string | JSXElementConstructor<any>>[]' is not assignable to type '(children: readonly any[], arg2: any) => ReactElement<any, string | JSXElementConstructor<any>>'.
+    _renderMovables: (
+        children: ReadonlyArray<any>,
+        arg2: any,
+    ) => React.ReactElement = (children, options) => {
+        // Each leaf of `children` is a movable descriptor created by a call to
+        // some `GraphieMovable`, such as `MovablePoint`.
+        //
+        // This function takes these descriptors and renders them into
+        // on-screen movables, or updates on-screen movables for
+        // descriptors when possible.
+        //
+        // If there is no movable with that key already, this descriptor is
+        // stored in this._movables and promoted to an on-screen movable by
+        // calling `child.add(graphie)`.
+        //
+        // If a movable of the same type with the same key exists already,
+        // we take `child.props` and give them to the already-existing
+        // on-screen movable, and call `movable.modify()`
+
+        const graphie = options.graphie;
+        const oldMovables = options.oldMovables;
+        const newMovables = options.newMovables; /* output parameter */
+
+        const renderChildren = (elem: any) => {
+            _.each(elem.movableProps, (prop) => {
+                // Render the children, and save the results of that
+                // render to the appropriate props
+                elem.props[prop] = this._renderMovables(
+                    elem.props[prop],
+                    options,
+                );
+            });
+        };
+
+        // Add/modify movables
+
+        // We want to keep track of whether we have added a new svg element,
+        // because if we have, then we need to call .toFront() on any svg
+        // elements occurring afterwards. If this happens, we set
+        // `areMovablesOutOfOrder` to true:
+        let areMovablesOutOfOrder = false;
+        // @ts-expect-error [FEI-5003] - TS2554 - Expected 3 arguments, but got 2.
+        return nestedMap(children, (childDescriptor) => {
+            if (!childDescriptor) {
+                // Still increment the key to avoid cascading key changes
+                // on hiding/unhiding children, i.e. by using
+                // {someBoolean && <MovablePoint />}
+                options.nextKey++;
+                // preserve the null/undefined in the resulting array
+                return childDescriptor;
+            }
+
+            // Instantiate the descriptor to turn it into a real Movable
+            const child = new childDescriptor.type(childDescriptor.props);
+            assert(
+                child instanceof GraphieMovable,
+                "All children of a Graphie component must be Graphie " +
+                    "movables",
+            );
+
+            // Give each child a key
+            const keyProp = childDescriptor.key;
+            const key = keyProp == null ? "_no_id_" + options.nextKey : keyProp;
+            options.nextKey++;
+            const ref = childDescriptor.ref;
+
+            // We render our children first. This allows us to replace any
+            // `movableProps` on our child with the on-screen movables
+            // corresponding with those descriptors.
+            renderChildren(child);
+
+            const prevMovable = oldMovables[key];
+            if (!prevMovable) {
+                // We're creating a new child
+                child.add(graphie);
+                areMovablesOutOfOrder = true;
+
+                newMovables[key] = child;
+            } else if (child.constructor === prevMovable.constructor) {
+                // We're updating an old child
+                prevMovable.props = child.props;
+                const modifyResult = prevMovable.modify(graphie);
+                if (modifyResult === "reordered") {
+                    areMovablesOutOfOrder = true;
+                }
+
+                newMovables[key] = prevMovable;
+            } else {
+                // We're destroying an old child and replacing it
+                // with a new child of a different type
+
+                // This generally is a bad idea, so warn about it if this
+                // is being caused by implicit keys
+                if (keyProp == null) {
+                    Log.error(
+                        "Replacing a <Graphie> child with a " +
+                            "child of a different type. Please add keys " +
+                            "to your <Graphie> children",
+                        Errors.Internal,
+                    );
+                }
+
+                prevMovable.remove();
+                child.add(graphie);
+                areMovablesOutOfOrder = true;
+
+                newMovables[key] = child;
+            }
+
+            if (areMovablesOutOfOrder) {
+                newMovables[key].toFront();
+            }
+
+            if (ref) {
+                // @ts-expect-error [FEI-5003] - TS2339 - Property 'movables' does not exist on type 'Graphie'.
+                this.movables[ref] = newMovables[key];
+            }
+
+            return newMovables[key];
+        });
+    };
+
+    // Sort of like react diffing, but for movables
+    _updateMovables: () => void = () => {
+        // @ts-expect-error [FEI-5003] - TS2339 - Property '_graphie' does not exist on type 'Graphie'.
+        const graphie = this._graphie;
+
+        // @ts-expect-error [FEI-5003] - TS2339 - Property '_movables' does not exist on type 'Graphie'.
+        const oldMovables = this._movables;
+        const newMovables: Record<string, any> = {};
+        // @ts-expect-error [FEI-5003] - TS2339 - Property '_movables' does not exist on type 'Graphie'.
+        this._movables = newMovables;
+        // @ts-expect-error [FEI-5003] - TS2339 - Property 'movables' does not exist on type 'Graphie'.
+        this.movables = {};
+
+        // @ts-expect-error [FEI-5003] - TS2345 - Argument of type 'ReactNode' is not assignable to parameter of type 'readonly any[]'.
+        this._renderMovables(this.props.children, {
+            nextKey: 1,
+            graphie: graphie,
+            oldMovables: oldMovables,
+            newMovables: newMovables,
+        });
+
+        // Remove any movables that no longer exist in the child array
+        _.each(oldMovables, (oldMovable, key) => {
+            if (!newMovables[key]) {
+                oldMovable.remove();
+            }
+        });
+    };
+
+    render(): React.ReactNode {
+        return (
+            <div className="graphie-container">
+                {/* eslint-disable-next-line react/no-string-refs */}
+                <div className="graphie" ref="graphieDiv" />
+            </div>
+        );
+    }
+}
+
+// Attach Graphie.createClass and Graphie.createSimpleClass
+_.extend(Graphie, GraphieClasses);
+// Attach the Movable react components for easy reference
+_.extend(Graphie, Movables);
+
+export default Graphie;

package/src/components/highlighting/highlightable-content.tsx

@@ -0,0 +1,243 @@
+/**
+ * The entry point for highlighting!
+ *
+ * Given a content node and a set of serialized highlights, this component
+ * renders the content with the given highlights applied. The content's DOM is
+ * not modified by this process, so any content should be safe to pass to this
+ * component.
+ *
+ * This component also renders controls for the user to add/remove/update
+ * highlights. When the user does so, this component will update the full set
+ * of highlights, serialize them, and call `onSerializedHighlightsUpdate` with
+ * new set of serialized highlights, which you can then persist and send back
+ * down to this component. Easy peasy!
+ */
+import {StyleSheet, css} from "aphrodite";
+import * as React from "react";
+
+import {
+    addHighlight,
+    buildHighlight,
+    deserializeHighlight,
+    serializeHighlight,
+} from "./highlights";
+import HighlightingUI from "./ui/highlighting-ui";
+import WordIndexer from "./word-indexer";
+
+import type {
+    DOMHighlight,
+    DOMHighlightSet,
+    SerializedHighlightSet,
+    DOMRange,
+} from "./types";
+
+type HighlightableContentProps = {
+    // The highlightable content itself. Highlights will be defined relative to
+    // the content specified here.
+    children?: React.ReactElement<any>;
+    // Whether the highlights are user-editable. If false, highlights are
+    // read-only.
+    editable: boolean;
+    // Whether highlighting is currently enabled. If false, highlights are not
+    // visible and are read-only (regardless of the `editable` prop), and this
+    // component is effectively a no-op.
+    //
+    // NOTE(mdr): The purpose of the `enabled` prop, as opposed to, say, just
+    //     *not* wrapping the content, is to enable quick toggles between
+    //     enabled/disabled while maintaining the same component structure.
+    //     Forcing React to rebuild the entire component tree is not kind!
+    enabled: boolean;
+    // When the user attempts to add/remove/update a highlight, this callback
+    // will be called with a newly-updated full set of highlights that reflects
+    // the user's intent.
+    onSerializedHighlightsUpdate: (
+        serializedHighlights: SerializedHighlightSet,
+    ) => unknown;
+    // The set of highlights to apply to the given content.
+    serializedHighlights: SerializedHighlightSet;
+};
+
+type HighlightableContentState = {
+    // A cached list of DOMRanges, each representing one of the content's
+    // semantic words. Sorted in document order.
+    wordRanges: ReadonlyArray<DOMRange>;
+};
+
+class HighlightableContent extends React.PureComponent<
+    HighlightableContentProps,
+    HighlightableContentState
+> {
+    // References to the mounted container and content divs.
+    _container: HTMLElement | null | undefined;
+    _content: HTMLElement | null | undefined;
+
+    state: HighlightableContentState = {
+        wordRanges: [],
+    };
+
+    _buildHighlight(highlightRange: DOMRange): DOMHighlight | null | undefined {
+        // TODO(mdr): If _buildHighlight starts getting called more often, we
+        //     might want to cache the DOMHighlightSet instead of recomputing
+        //     it here.
+        return buildHighlight(
+            this._getDOMHighlights(),
+            this.state.wordRanges,
+            highlightRange,
+        );
+    }
+
+    /**
+     * Take the highlights from props, and deserialize them into DOMHighlights,
+     * according to the latest cache of word ranges.
+     */
+    _getDOMHighlights(): DOMHighlightSet {
+        const {serializedHighlights} = this.props;
+        const {wordRanges} = this.state;
+
+        const domHighlights: Record<string, any> = {};
+        for (const key of Object.keys(serializedHighlights)) {
+            domHighlights[key] = deserializeHighlight(
+                serializedHighlights[key],
+                wordRanges,
+            );
+        }
+        return domHighlights;
+    }
+
+    /**
+     * Add the given DOMHighlight to the current set.
+     */
+    _handleAddHighlight: (highlight: DOMHighlight) => void = (
+        highlight: DOMHighlight,
+    ) => {
+        const newDomHighlights = addHighlight(
+            this._getDOMHighlights(),
+            highlight,
+        );
+
+        const newSerializedHighlights: Record<string, any> = {};
+        for (const key of Object.keys(newDomHighlights)) {
+            newSerializedHighlights[key] = serializeHighlight(
+                newDomHighlights[key],
+            );
+        }
+
+        this.props.onSerializedHighlightsUpdate(newSerializedHighlights);
+    };
+
+    /**
+     * Remove the given highlight from the list, and call our callback with the
+     * new set of highlights.
+     */
+    _handleRemoveHighlight: (keyToRemove: string) => void = (
+        keyToRemove: string,
+    ) => {
+        const {serializedHighlights} = this.props;
+        const newSerializedHighlights = {...serializedHighlights} as const;
+        // @ts-expect-error [FEI-5003] - TS2542 - Index signature in type '{ readonly [x: string]: SerializedHighlight; }' only permits reading.
+        delete newSerializedHighlights[keyToRemove];
+        this.props.onSerializedHighlightsUpdate(newSerializedHighlights);
+    };
+
+    /**
+     * When our WordIndexer sends us a new cache of word ranges, store it in
+     * our component state.
+     */
+    _handleWordsUpdate: (wordRanges: ReadonlyArray<DOMRange>) => void = (
+        wordRanges: ReadonlyArray<DOMRange>,
+    ) => {
+        this.setState({wordRanges});
+    };
+
+    render(): React.ReactNode {
+        const highlights = this._getDOMHighlights();
+
+        // NOTE(mdr): This lambda is rebuilt every time this component updates,
+        //     so every update to HighlightableContent triggers an update in
+        //     the child HighlightingUI and SelectionTracker, even if the
+        //     behavior hasn't changed.
+        //
+        //     Over-updating is preferable to under-updating here, because some
+        //     updates in this component's props/state *do* affect
+        //     `buildHighlight`'s behavior, and *should* trigger an update.
+        //
+        //     A more performant approach would be to cache this function
+        //     object until its implicitly-bound inputs change. If profiling
+        //     leads us to implement such caching, this draft might be a good
+        //     starting point: https://phabricator.khanacademy.org/D35623?id=170698
+        const buildHighlight = (r: DOMRange) => this._buildHighlight(r);
+
+        return (
+            <div
+                className={css(styles.container)}
+                ref={(container) => (this._container = container)}
+            >
+                <div>
+                    {this.props.enabled && this._container && this._content && (
+                        <HighlightingUI
+                            buildHighlight={buildHighlight}
+                            contentNode={this._content}
+                            editable={this.props.editable}
+                            highlights={highlights}
+                            offsetParent={this._container}
+                            zIndexes={{
+                                // The content has a z-index of 1, so, to
+                                // be below the content, use z-index of 0.
+                                //
+                                // 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...
+                                belowContent: 0,
+                            }}
+                            onAddHighlight={this._handleAddHighlight}
+                            onRemoveHighlight={this._handleRemoveHighlight}
+                        />
+                    )}
+                </div>
+                <div
+                    className={css(styles.content)}
+                    ref={(content) => (this._content = content)}
+                >
+                    <WordIndexer onWordsUpdate={this._handleWordsUpdate}>
+                        {this.props.children}
+                    </WordIndexer>
+                </div>
+            </div>
+        );
+    }
+}
+
+const styles = StyleSheet.create({
+    // We render content with z-index 1, and highlights with z-index 0, so that
+    // content will receive the browser's native pointer events. (Highlights
+    // have their own magic code to manage hover detection, despite being
+    // behind the content.)
+
+    container: {
+        // Position the container and give it a z-index, to scope the z-indexes
+        // inside by creating a stacking context.
+        // https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context
+        //
+        // This way, content's z-index of 1, and highlights' z-index of 0, and
+        // tooltips' z-index of 2 don't interact with anything external;
+        // external UI will see `HighlightableContent` as a single flat layer
+        // with a z-index of 0. This removes the need for us to coordinate our
+        // choices of z-index with external UI.
+        position: "relative",
+        zIndex: 0,
+    },
+
+    content: {
+        // NOTE(mdr): Creating a stacking context for content of z-index 1 may
+        //    be problematic if the content and external page want to
+        //    interleave layers between each other, e.g., if the application UI
+        //    wants to render something above some parts of our content, but
+        //    below other parts. It's not relevant for the current Passage-only
+        //    call site, but could be relevant someday…
+        position: "relative",
+        zIndex: 1,
+    },
+});
+
+export default HighlightableContent;