@khanacademy/perseus 19.1.5 → 19.1.6

package/src/components/graphie.tsx

@@ -1,400 +0,0 @@
-import $ from "jquery";
-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 {Graphie as GraphieDrawingContext} from "../util/graphie";
-
-import GraphieClasses from "./graphie-classes";
-import Movables from "./graphie-movables";
-
-import type {Coord} from "../interactive2/types";
-import type {Range, Size} from "../perseus-types";
-
-const GraphieMovable = GraphieClasses.GraphieMovable;
-
-const createGraphie = GraphUtils.createGraphie;
-const {deepEq, nestedMap} = Util;
-const {assert} = InteractiveUtil;
-
-type Props = {
-    addMouseLayer?: boolean;
-    box: Size;
-    range: [Coord, Coord];
-    ranges?: [Range, Range];
-    gridStep?: [number, number];
-    step?: [number, number];
-    scale?: [number, number];
-
-    isMobile?: boolean;
-    responsive?: boolean;
-
-    children?: React.ReactNode;
-
-    // TODO(LC-772) - type this prop!
-    options: any;
-
-    setDrawingAreaAvailable?: (boolean) => void;
-    setup: (
-        graphie: any,
-        options: {
-            range: [Coord, Coord];
-            scale: [number, number];
-        },
-    ) => void;
-
-    onClick?: (at: Coord) => void;
-    onMouseDown?: (at: Coord) => void;
-    onMouseMove?: (at: Coord) => void;
-    onMouseUp?: (at: Coord) => void;
-};
-
-type DefaultProps = {
-    range: Props["range"];
-    options: Props["options"];
-    responsive: Props["responsive"];
-    addMouseLayer: Props["addMouseLayer"];
-};
-
-interface Movable {
-    remove(): void;
-    props: unknown;
-    modify(graphie: GraphieDrawingContext): "reordered" | undefined;
-    toFront(): void;
-}
-
-class Graphie extends React.Component<Props> {
-    graphieDivRef = React.createRef<HTMLDivElement>();
-    _graphie: GraphieDrawingContext = new GraphieDrawingContext(
-        document.createElement("div"),
-    );
-    _movables: Record<string, Movable> = {};
-    movables: Record<string, Movable> = {};
-
-    static defaultProps: DefaultProps = {
-        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 = () => {
-        return this._graphie;
-    };
-
-    // bounds-checked range
-    _range: () => [Coord, Coord] = () => {
-        const boundsCheckRange = (range: Coord): Coord => {
-            if (range[0] >= range[1]) {
-                return [-10, 10];
-            }
-            return range;
-        };
-        return [
-            boundsCheckRange(this.props.range[0]),
-            boundsCheckRange(this.props.range[1]),
-        ];
-    };
-
-    _box: () => Size = () => {
-        const ensureMinSize = (pixelDim: number): number => {
-            // 340 = default size in the editor. exact value
-            // is arbitrary; this is just a safety check.
-            return pixelDim > 0 ? pixelDim : 340;
-        };
-
-        return [
-            ensureMinSize(this.props.box[0]),
-            ensureMinSize(this.props.box[1]),
-        ];
-    };
-
-    // @ts-expect-error -  TS2322: Type '() => number[]' is not assignable to type '() => Coord'.
-    _scale: () => Coord = () => {
-        const box = this._box();
-        const range = this._range();
-        return box.map((pixelDim, i) => {
-            const unitDim = range[i][1] - range[i][0];
-            return pixelDim / unitDim;
-        });
-    };
-
-    _setupGraphie: () => void = () => {
-        this._removeMovables();
-
-        const graphieDiv = ReactDOM.findDOMNode(this.graphieDivRef.current);
-        if (graphieDiv == null || graphieDiv instanceof Text) {
-            throw new Error("No graphie container div found");
-        }
-        graphieDiv.innerHTML = "";
-        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) {
-            // @ts-expect-error - TS2339: Property 'addMouseLayer' does not exist on type 'Graphie'.
-            graphie.addMouseLayer({
-                onClick: this.props.onClick,
-                onMouseDown: this.props.onMouseDown,
-                onMouseUp: this.props.onMouseUp,
-                onMouseMove: this.props.onMouseMove,
-                setDrawingAreaAvailable: this.props.setDrawingAreaAvailable,
-            });
-        }
-
-        // @ts-expect-error - TS2339: Property 'snap' does not exist on type 'Graphie'.
-        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.
-            $(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
-        _.invoke(this._movables, "remove");
-        this._movables = {};
-    };
-
-    // @ts-expect-error - 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: {
-            nextKey: number;
-            graphie: GraphieDrawingContext;
-            oldMovables: Record<string, Movable>;
-            newMovables: Record<string, Movable>;
-        },
-    ) => 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 - 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) {
-                this.movables[ref] = newMovables[key];
-            }
-
-            return newMovables[key];
-        });
-    };
-
-    // Sort of like react diffing, but for movables
-    _updateMovables: () => void = () => {
-        const graphie = this._graphie;
-
-        const oldMovables = this._movables;
-        const newMovables: Record<string, any> = {};
-        this._movables = newMovables;
-        this.movables = {};
-
-        // @ts-expect-error - 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">
-                <div className="graphie" ref={this.graphieDivRef} />
-            </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

@@ -1,240 +0,0 @@
-/**
- * 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 Props = {
-    // 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 State = {
-    // 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<Props, State> {
-    // References to the mounted container and content divs.
-    _container: HTMLElement | null | undefined;
-    _content: HTMLElement | null | undefined;
-
-    state: State = {
-        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 - 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;