@khanacademy/perseus 0.0.1 → 0.2.1

package/src/components/math-input.jsx

@@ -0,0 +1,282 @@
+/* eslint-disable react/sort-comp */
+// @flow
+import classNames from "classnames";
+import $ from "jquery";
+import MathQuill from "mathquill";
+import PropTypes from "prop-types";
+import * as React from "react";
+import ReactDOM from "react-dom";
+import _ from "underscore";
+
+import TexButtons from "./tex-buttons.jsx";
+
+const PT = PropTypes;
+
+// A WYSIWYG math input that calls `onChange(LaTeX-string)`
+class MathInput extends React.Component<$FlowFixMe, $FlowFixMe> {
+    mouseDown: boolean;
+
+    static propTypes = {
+        value: PT.string,
+        onChange: PT.func.isRequired,
+        convertDotToTimes: PT.bool,
+        buttonsVisible: PT.oneOf(["always", "never", "focused"]),
+        buttonSets: TexButtons.buttonSetsType.isRequired,
+        labelText: PropTypes.string,
+        onFocus: PT.func,
+        onBlur: PT.func,
+    };
+
+    static defaultProps: $FlowFixMe = {
+        value: "",
+        convertDotToTimes: false,
+        buttonsVisible: "focused",
+    };
+
+    state: $FlowFixMe = {focused: false};
+
+    render(): React.Node {
+        let className = classNames({
+            "perseus-math-input": true,
+
+            // mathquill usually adds these itself but react removes them when
+            // updating the component.
+            "mq-editable-field": true,
+            "mq-math-mode": true,
+        });
+
+        if (this.props.className) {
+            className = className + " " + this.props.className;
+        }
+
+        let buttons = null;
+        if (this._shouldShowButtons()) {
+            buttons = (
+                <TexButtons
+                    sets={this.props.buttonSets}
+                    className="math-input-buttons absolute"
+                    convertDotToTimes={this.props.convertDotToTimes}
+                    onInsert={this.insert}
+                />
+            );
+        }
+
+        return (
+            <div style={{display: "inline-block"}}>
+                <div style={{display: "inline-block"}}>
+                    <span
+                        className={className}
+                        // eslint-disable-next-line react/no-string-refs
+                        ref="mathinput"
+                        aria-label={this.props.labelText}
+                        onFocus={this.handleFocus}
+                        onBlur={this.handleBlur}
+                    />
+                </div>
+                <div style={{position: "relative"}} onBlur={this.handleBlur}>
+                    {buttons}
+                </div>
+            </div>
+        );
+    }
+
+    // handlers:
+    // keep track of two related bits of state:
+    // * this.state.focused - whether the buttons are currently shown
+    // * this.mouseDown - whether a mouse click is active that started in the
+    //   buttons div
+
+    handleFocus: () => void = () => {
+        this.setState({focused: true});
+        // TODO(joel) fix properly - we should probably allow onFocus handlers
+        // to this property, but we need to work correctly with them.
+        // if (this.props.onFocus) {
+        //     this.props.onFocus();
+        // }
+    };
+
+    handleMouseDown: (MouseEvent) => void = (event) => {
+        // $FlowFixMe[incompatible-use]
+        // $FlowFixMe[incompatible-call]
+        const focused = ReactDOM.findDOMNode(this).contains(event.target);
+        this.mouseDown = focused;
+        if (!focused) {
+            this.setState({focused: false});
+        }
+    };
+
+    handleMouseUp: (MouseEvent) => void = () => {
+        // this mouse click started in the buttons div so we should focus the
+        // input
+        if (this.mouseDown) {
+            this.focus();
+        }
+        this.mouseDown = false;
+    };
+
+    handleBlur: (SyntheticFocusEvent<>) => void = (e) => {
+        // TODO(michaelpolyak): Consider trapping focus within the button group.
+        // Focusing back on the input when TAB out of the last button in the
+        // group. This will probably require ESCAPE key handling to enable to
+        // close (blur) the button group in order to focus on next page element.
+        if (
+            !this.mouseDown &&
+            // $FlowFixMe[incompatible-use]
+            // $FlowFixMe[incompatible-call]
+            !ReactDOM.findDOMNode(this).contains(e.relatedTarget)
+        ) {
+            this.setState({focused: false});
+        }
+    };
+
+    _shouldShowButtons: () => boolean = () => {
+        if (this.props.buttonsVisible === "always") {
+            return true;
+        }
+        if (this.props.buttonsVisible === "never") {
+            return false;
+        }
+        return this.state.focused;
+    };
+
+    insert: ($FlowFixMe) => void = (value) => {
+        const input = this.mathField();
+        if (_(value).isFunction()) {
+            value(input);
+        } else if (value[0] === "\\") {
+            input.cmd(value).focus();
+        } else {
+            input.write(value).focus();
+        }
+        input.focus();
+    };
+
+    mathField: ($FlowFixMe) => $FlowFixMe = (options) => {
+        // The MathQuill API is now "versioned" through its own "InterVer"
+        // system.
+        // See: https://github.com/mathquill/mathquill/pull/459
+        const MQ = MathQuill.getInterface(2);
+
+        // MathQuill.MathField takes a DOM node, MathQuill-ifies it if it's
+        // seeing that node for the first time, then returns the associated
+        // MathQuill object for that node. It is stable - will always return
+        // the same object when called on the same DOM node.
+        // eslint-disable-next-line react/no-string-refs
+        return MQ.MathField(ReactDOM.findDOMNode(this.refs.mathinput), options);
+    };
+
+    componentWillUnmount() {
+        window.removeEventListener("mousedown", this.handleMouseDown);
+        window.removeEventListener("mouseup", this.handleMouseUp);
+    }
+
+    componentDidMount() {
+        window.addEventListener("mousedown", this.handleMouseDown);
+        window.addEventListener("mouseup", this.handleMouseUp);
+
+        let initialized = false;
+
+        // Initialize MathQuill.MathField instance
+        this.mathField({
+            // LaTeX commands that, when typed, are immediately replaced by the
+            // appropriate symbol. This does not include ln, log, or any of the
+            // trig functions; those are always interpreted as commands.
+            autoCommands: "pi theta phi sqrt nthroot",
+
+            // Pop the cursor out of super/subscripts on arithmetic operators
+            // or (in)equalities.
+            charsThatBreakOutOfSupSub: "+-*/=<>≠≤≥",
+
+            // Prevent excessive super/subscripts or fractions from being
+            // created without operands, e.g. when somebody holds down a key
+            supSubsRequireOperand: true,
+
+            // The name of this option is somewhat misleading, as tabbing in
+            // MathQuill breaks you out of a nested context (fraction/script)
+            // if you're in one, but moves focus to the next input if you're
+            // not. Spaces (with this option enabled) are just ignored in the
+            // latter case.
+            //
+            // TODO(alex): In order to allow inputting mixed numbers, we will
+            // have to accept spaces in certain cases. The desired behavior is
+            // still to escape nested contexts if currently in one, but to
+            // insert a space if not (we don't expect mixed numbers in nested
+            // contexts). We should also limit to one consecutive space.
+            spaceBehavesLikeTab: true,
+
+            handlers: {
+                edited: (mathField) => {
+                    // This handler is guaranteed to be called on change, but
+                    // unlike React it sometimes generates false positives.
+                    // One of these is on initialization (with an empty string
+                    // value), so we have to guard against that below.
+                    let value = mathField.latex();
+
+                    // Provide a MathQuill-compatible way to generate the
+                    // not-equals sign without pasting unicode or typing TeX
+                    value = value.replace(/<>/g, "\\ne");
+
+                    // Use the specified symbol to represent multiplication
+                    // TODO(alex): Add an option to disallow variables, in
+                    // which case 'x' should get converted to '\\times'
+                    if (this.props.convertDotToTimes) {
+                        value = value.replace(/\\cdot/g, "\\times");
+
+                        // Preserve cursor position in the common case:
+                        // typing '*' to insert a multiplication sign.
+                        // We do this by modifying internal MathQuill state
+                        // directly, instead of waiting for `.latex()` to be
+                        // called in `componentDidUpdate()`.
+                        const left = mathField.__controller.cursor[MathQuill.L];
+                        if (left && left.ctrlSeq === "\\cdot ") {
+                            mathField.__controller.backspace();
+                            mathField.cmd("\\times");
+                        }
+                    } else {
+                        value = value.replace(/\\times/g, "\\cdot");
+                    }
+
+                    if (initialized && this.props.value !== value) {
+                        this.props.onChange(value);
+                    }
+                },
+                enter: () => {
+                    // NOTE(kevinb): This isn't how answers to exercises are
+                    // submitted.  The actual mechanism for this can be found
+                    // in exercise-problem-template.jsx, see `handleSubmit`.
+
+                    // This handler is called when the user presses the enter
+                    // key. Since this isn't an actual <input> element, we have
+                    // to manually trigger the usually automatic form submit.
+                    // eslint-disable-next-line react/no-string-refs
+                    $(ReactDOM.findDOMNode(this.refs.mathinput)).submit();
+                },
+                upOutOf: (mathField) => {
+                    // This handler is called when the user presses the up
+                    // arrow key, but there is nowhere in the expression to go
+                    // up to (no numerator or exponent). For ease of use,
+                    // interpret this as an attempt to create an exponent.
+                    mathField.typedText("^");
+                },
+            },
+        });
+
+        // Ideally, we would be able to pass an initial value directly into
+        // the constructor above
+        this.mathField().latex(this.props.value);
+
+        initialized = true;
+    }
+
+    focus: () => void = () => {
+        this.mathField().focus();
+        this.setState({focused: true});
+    };
+
+    blur: () => void = () => {
+        this.mathField().blur();
+        this.setState({focused: false});
+    };
+}
+
+export default MathInput;

package/src/components/math-output.jsx

@@ -0,0 +1,128 @@
+/* eslint-disable react/sort-comp */
+// @flow
+import $ from "jquery";
+import PropTypes from "prop-types";
+import * as React from "react";
+import ReactDOM from "react-dom";
+import _ from "underscore";
+
+import {getDependencies} from "../dependencies.js";
+import {ClassNames as ApiClassNames} from "../perseus-api.jsx";
+import TexWrangler from "../tex-wrangler.js";
+
+const ModifyTex = TexWrangler.modifyTex;
+
+class MathOutput extends React.Component<$FlowFixMe, $FlowFixMe> {
+    static propTypes = {
+        value: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+        className: PropTypes.string,
+        labelText: PropTypes.string,
+        onFocus: PropTypes.func,
+        onBlur: PropTypes.func,
+    };
+
+    static defaultProps: $FlowFixMe = {
+        value: "",
+        onFocus: function () {},
+        onBlur: function () {},
+    };
+
+    state: $FlowFixMe = {
+        focused: false,
+        selectorNamespace: _.uniqueId("math-output"),
+    };
+
+    _getInputClassName: () => string = () => {
+        let className =
+            "math-output " +
+            ApiClassNames.INPUT +
+            " " +
+            ApiClassNames.INTERACTIVE;
+        if (this.state.focused) {
+            className += " " + ApiClassNames.FOCUSED;
+        }
+        if (this.props.className) {
+            className += " " + this.props.className;
+        }
+        return className;
+    };
+
+    _getDisplayValue: (string | number) => string = (value) => {
+        // Cast from (potentially a) number to string
+        let displayText;
+        if (value != null) {
+            displayText = "" + value;
+        } else {
+            displayText = "";
+        }
+        return ModifyTex(displayText);
+    };
+
+    render(): React.Node {
+        const divStyle = {
+            textAlign: "center",
+        };
+        const {TeX} = getDependencies();
+
+        return (
+            <span
+                // eslint-disable-next-line react/no-string-refs
+                ref="input"
+                className={this._getInputClassName()}
+                aria-label={this.props.labelText}
+                onMouseDown={this.focus}
+                onTouchStart={this.focus}
+            >
+                <div style={divStyle}>
+                    <TeX>{this._getDisplayValue(this.props.value)}</TeX>
+                </div>
+            </span>
+        );
+    }
+
+    getValue: () => string | number = () => {
+        return this.props.value;
+    };
+
+    focus: () => void = () => {
+        if (!this.state.focused) {
+            this.props.onFocus();
+            this._bindBlurHandler();
+            this.setState({
+                focused: true,
+            });
+        }
+    };
+
+    blur: () => void = () => {
+        if (this.state.focused) {
+            this.props.onBlur();
+            this._unbindBlurHandler();
+            this.setState({
+                focused: false,
+            });
+        }
+    };
+
+    _bindBlurHandler: () => void = () => {
+        $(document).bind("vclick." + this.state.selectorNamespace, (e) => {
+            // Detect whether the target has our React DOM node as a parent
+            const $closestWidget = $(e.target).closest(
+                ReactDOM.findDOMNode(this),
+            );
+            if (!$closestWidget.length) {
+                this.blur();
+            }
+        });
+    };
+
+    _unbindBlurHandler: () => void = () => {
+        $(document).unbind("." + this.state.selectorNamespace);
+    };
+
+    componentWillUnmount() {
+        this._unbindBlurHandler();
+    }
+}
+
+export default MathOutput;

package/src/components/multi-button-group.jsx

@@ -0,0 +1,137 @@
+// @flow
+
+import {css, StyleSheet} from "aphrodite";
+import * as React from "react";
+import * as ReactDOM from "react-dom";
+
+type Props = {|
+    // the initial values of the buttons selected, defaults to null (no
+    // selection).
+    values: ?$ReadOnlyArray<any>,
+    buttons: $ReadOnlyArray<{|
+        // the value returned when the button is selected
+        value: any,
+        // the content shown within the button, typically a string that gets
+        // rendered as the button's display text
+        content: React.Node,
+        // the title-text shown on hover
+        title?: string,
+    |}>,
+    // a function that is provided with the updated set of selected value
+    // (which it then is responsible for updating)
+    onChange: (values: any) => mixed,
+    // if false, at least one button must be selected at all times.
+    // defaults to true
+    allowEmpty?: boolean,
+|};
+
+type DefaultProps = {|
+    allowEmpty: Props["allowEmpty"],
+    values: Props["values"],
+|};
+
+/**
+ * MultiButtonGroup is an aesthetically pleasing group of buttons,
+ * which allows multiple buttons to be selected at the same time.
+ *
+ * NOTE: This component is almost identical to ./button-group.jsx except that
+ * this component allows multiple selection!
+ */
+class MultiButtonGroup extends React.Component<Props> {
+    static defaultProps: DefaultProps = {
+        values: [],
+        allowEmpty: true,
+    };
+
+    focus(): boolean {
+        // $FlowFixMe[prop-missing]
+        ReactDOM.findDOMNode(this)?.focus();
+        return true;
+    }
+
+    toggleSelect: (any) => void = (newValue: any) => {
+        const values = (this.props.values || []).slice(0);
+        const allowEmpty = this.props.allowEmpty;
+
+        if (
+            values.indexOf(newValue) >= 0 &&
+            (values.length > 1 || allowEmpty)
+        ) {
+            // If the value is already selected, unselect it
+            values.splice(values.indexOf(newValue), 1);
+        } else {
+            // Otherwise merge with other values and return
+            if (values.indexOf(newValue) < 0) {
+                values.push(newValue);
+            }
+        }
+
+        this.props.onChange(values);
+    };
+
+    render(): React.Element<"div"> {
+        const values = this.props.values || [];
+        const buttons = this.props.buttons.map((button, i) => {
+            const selected = values.indexOf(button.value) >= 0;
+            return (
+                <button
+                    title={button.title}
+                    type="button"
+                    id={"" + i}
+                    key={"" + i}
+                    ref={"button" + i}
+                    className={css(
+                        styles.buttonStyle,
+                        selected && styles.selectedStyle,
+                    )}
+                    onClick={() => this.toggleSelect(button.value)}
+                >
+                    {button.content || "" + button.value}
+                </button>
+            );
+        });
+
+        const outerStyle = {
+            display: "inline-block",
+        };
+        return <div style={outerStyle}>{buttons}</div>;
+    }
+}
+
+const styles = StyleSheet.create({
+    buttonStyle: {
+        backgroundColor: "white",
+        border: "1px solid #ccc",
+        borderLeft: "0",
+        cursor: "pointer",
+        margin: "0",
+        padding: "5px 10px",
+        position: "relative", // for hover
+
+        ":first-child": {
+            borderLeft: "1px solid #ccc",
+            borderTopLeftRadius: "3px",
+            borderBottomLeftRadius: "3px",
+        },
+
+        ":last-child": {
+            borderRight: "1px solid #ccc",
+            borderTopRightRadius: "3px",
+            borderBottomRightRadius: "3px",
+        },
+
+        ":hover": {
+            backgroundColor: "#ccc",
+        },
+
+        ":focus": {
+            zIndex: 2,
+        },
+    },
+
+    selectedStyle: {
+        backgroundColor: "#ddd",
+    },
+});
+
+export default MultiButtonGroup;

package/src/components/new-tooltip/README.md

@@ -0,0 +1,110 @@
+# `NewTooltip`: KA tooltip component
+
+Across the Khan Academy webapp, we use a shared "tooltip" UI element, to visually annotate page elements with additional information. This React component, `NewTooltip`, is designed to satisfy all of our tooltip needs! 😄
+
+**Warning: This component is WIP!** We're in the process of rolling out this tooltip to eventually replace the old `Tooltip` component. `NewTooltip` is currently is only used at a select few call sites. [Scroll down for details.](#warning-this-component-is-wip)
+
+## Usage
+
+To point a tooltip at an element, wrap it in a `NewTooltip` component:
+
+```jsx
+<NewTooltip content={i18n._("You should click on this!")}>
+    <button><$_>Assign to students</$_></button>
+</NewTooltip>
+```
+
+This will produce a tooltip that says "You should click on this!" when you hover over the wrapped button.
+
+You can also provide more advanced content:
+
+```jsx
+const content = <div className={css(styles.tooltipContent)}>
+    <p><$_>You should click on this!</$_></p>
+    <p><$_>It will help you!</$_></p>
+</div>;
+
+<NewTooltip content={content}>
+    <button>Assign to students</button>
+</NewTooltip>
+```
+
+There are also many styling, positioning, and behavioral options for the tooltip! See `types.js` for the list of options, and the [React Sandbox][fixtures] to see them in action.
+
+## Accessibility
+
+Unlike some other tooltip components on the web, this tooltip is a _visual_ element rather than a semantic element. Its use cases are relatively diverse:
+
+* Explaining a UI control
+* Illustrating a relationship between two permanent UI elements
+* Showing a transient UI element without disrupting the flow of the document
+* Prompting the user to take a secondary or blocking action (tooltip) before taking the main action (target)
+
+The key commonality is that the tooltip and its target are somehow _related_… but that's about it.
+
+**So, be sure to add your own ARIA attributes to tooltip targets and content!** Only you know the semantic relationship between your tooltip and target, so it's up to you to express it.
+
+## Package structure
+
+The two most important files in this package are:
+
+* `new-tooltip.jsx`: The entry point to our tooltip code. Manages high-level visibility state. Renders the tooltip's target element inline, and renders a `TooltipPortal` to get the tooltip content outside of any `overflow: hidden` containers.
+* `types.js`: Defines the props for `NewTooltip`.
+
+We also have a number of supporting files, as well:
+
+* React components
+    * `tooltip-portal.jsx`: Simulates a [React 16 portal][react-portal]. Creates a node near the root of the document, and renders a `TooltipPositioner` there, instead of inline with the target element.
+    * `tooltip-positioner.jsx`: Manages the position of the tooltip UI. Computes the position of the target element, and watches for changes. Renders a `TooltipBubble` and `TooltipArrow`, positioned to point at the target element.
+    * `tooltip-bubble.jsx`: The main tooltip "bubble" element. Renders the tooltip content.
+    * `tooltip-arrow.jsx`: The little triangle that points from the tooltip bubble to the target element.
+* Library files:
+    * `util.js`: Miscellaneous utility functions.
+
+Note that these components are relatively tightly coupled—for example, rather than specifying their individual data requirements, each tooltip component just forwards the entire set of `tooltipProps` to its child tooltip components. This enables faster iteration, but means that the child components aren't especially reusable.
+
+## Warning: This component is WIP!
+
+This is `NewTooltip`, a fork of the old `Tooltip`, in which we've built a brand new layout algorithm to address some key UX issues. Someday, `NewTooltip` will replace `Tooltip`, hooray! [See ADR #33 for details.][adr-33]
+
+`NewTooltip` is probably _feature-ready_ for most use cases on Khan Academy, but **general usage is not yet advised**. We're still developing our plan for the "Wonder Blocks" shared component rollout, and we want to keep call sites well-constrained until we know more. But, if you _need_ the features of `NewTooltip` today, maybe we can figure something out! Hit up the [#reusable-components][reusable-components] Slack channel.
+
+But, if you need a feature that hasn't been ported yet, maybe you'll want to continue to use `Tooltip`. (Or port the feature into `NewTooltip`? 😍)
+
+Here's the overall behavioral comparison right now. Especially valuable features are marked with a star (⭐️).
+
+| Feature                                      | `NewTooltip` | `Tooltip` |
+|----------------------------------------------|--------------|-----------|
+| ⭐️ **Basic tooltip functionality**           | ✅            | ✅        |
+| ⭐️ **Escape `overflow: hidden` containers**  | ✅            | ✅        |
+| ⭐️ **Attach to any side of the target**      | ✅            | ✅        |
+| ⭐️ **Configurable colors**                   | ✅            | ✅        |
+| ⭐️ **Dismiss on click**                      | ✅            | ✅        |
+| ⭐️ **Only show once per user lifetime**      | ✅            | ✅        |
+| Tweak position via the `offset` prop         | ✅            | ✅        |
+| Arrow center-aligned with bubble             | ✅            | ✅        |
+| ⭐️ **Auto-shift position to avoid wrapping** | ✅            | ❌        |
+| ⭐️ **Auto-reposition during scrolling**      | ✅            | ❌        |
+| ⭐️ **Update content without remounting**     | ✅            | ❌        |
+| ⭐️ **Media queries to show/hide tooltip**    | ✅            | ❌        |
+| Can specify offset from the _arrow_          | ✅            | ❌        |
+| Can specify margin around tooltip            | ✅            | ❌        |
+| ⭐️ **Can be used inside a modal**            | ✅            | ✅        |
+| Can target `position: fixed` elements        | ❌            | ✅        |
+| Auto-choose top or bottom anchoring          | ❌            | ✅        |
+| Try to left/right align tooltip with target  | ❌            | ✅        |
+| Manual positioning (left/top)                | ❌            | ✅        |
+| Dismiss on scroll/interaction/timer          | ❌            | ✅        |
+| Show tooltip when target gains focus         | ❌            | ✅        |
+
+> NOTE(mdr): It's possible that some of the old `Tooltip` features are also "especially valuable", and I just don't know about it yet! So far we've only used `NewTooltip` at GTP call sites, and they haven't needed many of these features, so it's not clear to me how broadly they're actually used. (We'll probably have to support most of the missing options eventually, but maybe not all, in case some of their use cases were addressed by the general positioning improvements?)
+
+Eventually, we'll roll out `NewTooltip` to all KA call sites, and upgrade it to support everything that the old `Tooltip` call sites need. So, no worries if you end up adding new `Tooltip` call sites; we'll help upgrade them soon! [For more details, see ADR #33.][adr-33]
+
+  [adr-33]: https://docs.google.com/document/d/1B4pMGWp344e96RmIbnsmUBiTbrizdbOvipe-9I_1iZQ/edit
+  [fixtures]: http://localhost:8081/react-sandbox/components/new-tooltip-package/new-tooltip.jsx.fixture.js
+  [react-portal]: https://reactjs.org/docs/portals.html
+  [reusable-components]: https://khanacademy.slack.com/messages/C4PE1QM5Y/
+
+Code-Owner: Frontend Infrastructure
+Crowdin-Category: _other_