@khanacademy/perseus 0.0.1 → 0.1.0

package/src/components/new-tooltip/types.js

@@ -0,0 +1,183 @@
+// @flow
+type AriaLabelledBy = {|
+    // The unique identifier of a DOM node to use as a label.
+    // See aria-labelledby
+    id: string,
+|};
+
+type AriaSupport = {|
+    // The title of the tooltip.
+    // See documentation for aria-label and aria-labelledby.
+    title?: string | AriaLabelledBy,
+
+    // How assertive should the tooltip content be?
+    // Default is to not provide an aria-live attribute.
+    // See documentation for aria-live.
+    assertiveness?: "polite" | "assertive",
+|};
+
+export type NewTooltipSide = "top" | "bottom" | "left" | "right";
+
+export type OffsetAnchor = "bubble" | "arrow";
+
+export type NewTooltipProps = {|
+    // The content of the tooltip bubble.
+    content: React$Node,
+
+    // Which side of the target element to attach the tooltip to.
+    //
+    // This field is optional. In `defaultProps`, its value is "top".
+    side: NewTooltipSide,
+
+    // How much space to put between the tooltip bubble and the target element.
+    // (Or, if `offsetFrom` is "arrow", how much space to put between the
+    // tooltip _arrow_ and the target element.)
+    //
+    // Increasing this value moves the tooltip further away from the target
+    // element. Decreasing this value moves the tooltip closer to the target
+    // element, perhaps to the point of overlapping!
+    //
+    // This field is optional. In `defaultProps`, its value is 0.
+    offset: number,
+
+    // Whether the `offset` prop measures the distance between the tooltip
+    // _bubble_ and the target element, or the tooltip _arrow_ and the target
+    // element.
+    //
+    // If `offsetFrom` is "bubble", and `offset` is 0, then the edge of the
+    // tooltip bubble will exactly touch the edge of the target element, and
+    // the tooltip arrow will overlap the _inside_ of the target element.
+    //
+    // If `offsetFrom` is "arrow", and `offset` is 0, then the tip of the
+    // tooltip arrow will exactly touch the edge of the target element, and the
+    // target bubble won't overlap the target element at all.
+    //
+    // This field is optional. In `defaultProps`, its value is "bubble".
+    offsetFrom: OffsetAnchor,
+
+    // An invisible margin around the tooltip bubble, preventing it from
+    // touching the edges of the screen.
+    //
+    // This field is optional. In `defaultProps`, its value is 0.
+    tooltipMargin: number,
+
+    // Whether to have no padding between the tooltip content and the edge of
+    // the tooltip bubble.
+    //
+    // This field is optional. In `defaultProps`, its value is `false`.
+    noPadding: boolean,
+
+    // The tooltip's text color - or, if `inverted` is set, the tooltip's
+    // background color.
+    //
+    // This field is optional. In `defaultProps`, its value is gray17.
+    color: string,
+
+    // Whether to "invert" the colors of the tooltip - that is, swap the text
+    // color to white, and background color to gray17 (or the value of the
+    // `color` prop).
+    //
+    // This field is optional. In `defaultProps`, its value is `false`.
+    inverted: boolean,
+
+    // Whether the tooltip is dismissed. Optional.
+    //
+    // If provided, this becomes a "controlled component": the caller is
+    // responsible for managing dismissal state, and using the `onDismiss`
+    // callback to listen to changes. But the caller also has the option to
+    // change dismissal state themselves, in case they want to dismiss or
+    // undismiss the tooltip in response to another action at the call site.
+    //
+    // If not provided, this is an "uncontrolled component": dismissal state is
+    // managed by NewTooltip automatically. Most callers will want this default
+    // uncontrolled behavior :)
+    dismissed?: boolean,
+
+    // Whether to show a close button to dismiss the tooltip.
+    //
+    // This field is optional. In `defaultProps`, its value is `false`.
+    dismissOnClickClose: boolean,
+
+    // This callback is called when the tooltip is dismissed. Optional.
+    onDismiss?: () => mixed,
+
+    // A value passed to the data-test-id attribute of the tooltip bubble
+    testId?: string,
+
+    // Whether to show the tooltip on hover.
+    //
+    // This field is optional. In `defaultProps`, its value is `true`.
+    toggleOnHover: boolean,
+
+    // Whether to show the tooltip immediately on mount. If this flag is set,
+    // then the tooltip will remain open until it is dismissed, regardless of
+    // other state (like hover).
+    //
+    // This field is optional. In `defaultProps`, its value is `false`.
+    showOnMount: boolean,
+
+    // A media query to restrict this tooltip's visibility. If provided, this
+    // tooltip will only be visible when the media query is satisfied.
+    //
+    // This field is optional. If omitted, the tooltip's visibility will not
+    // depend on any media query.
+    //
+    // TODO(mdr): We're trying to solve a general styling API problem for
+    //     shared components. I wonder how conditioning the tooltip on media
+    //     query might fit into that long-term solution!
+    //
+    //     For now, though, we're sticking this onto the NewTooltip API in a
+    //     simplistic form, instead of waiting for a general solution to exist.
+    //     Otherwise, the way to get media-conditioned tooltips is to render
+    //     multiple copies of NewTooltip _and_ its children, which causes perf,
+    //     a11y, and window-resize-consistency problems.
+    media?: string,
+
+    // This callback is called when the tooltip is clicked. Optional.
+    //
+    // The clickable area includes the tooltip bubble, the tooltip bubble's
+    // contents, and the tooltip arrow. If a callback is provided, these areas
+    // will additionally be styled as clickable, i.e., `cursor: pointer`.
+    onClick?: () => mixed,
+
+    // This callback is called when the cursor enters the tooltip. Optional.
+    //
+    // The hoverable area includes the tooltip bubble, the tooltip bubble's
+    // contents, and the tooltip arrow. If a callback is provided, these areas
+    // will additionally be styled as clickable, i.e., `cursor: pointer`.
+    //
+    // If the cursor moves from the tooltip bubble to the tooltip arrow, or
+    // vice-versa, you may receive a pair of `onMouseLeave` and `onMouseEnter`
+    // calls. Beware! (Thankfully, if all you do is call `setState`, React's
+    // `setState` batching should protect you from unnecessary updates.)
+    onMouseEnter?: () => mixed,
+
+    // This callback is called when the cursor enters the tooltip. Optional.
+    //
+    // The hoverable area includes the tooltip bubble, the tooltip bubble's
+    // contents, and the tooltip arrow. If a callback is provided, these areas
+    // will additionally be styled as clickable, i.e., `cursor: pointer`.
+    //
+    // If the cursor moves from the tooltip bubble to the tooltip arrow, or
+    // vice-versa, you may receive a pair of `onMouseLeave` and `onMouseEnter`
+    // calls. Beware! (Thankfully, if all you do is call `setState`, React's
+    // `setState` batching should protect you from unnecessary updates.)
+    onMouseLeave?: () => mixed,
+
+    // Provide various ARIA values to support accessibility of this tooltip.
+    // All tooltips should probably provide a header label (string or id of
+    // a node).
+    //
+    // If no title or title node id is provided, the tooltip contents are
+    // specified as the label.
+    //
+    // This property can also be used to specify the aria-live assertiveness.
+    // Permanently visible tooltips that don't change their contents
+    // may not want this as it will call attention to the tooltip on first
+    // display, which isn't necessarily valuable.
+    //
+    // If the content DOES change but you don't want an initial
+    // assert on first display, consider using some custom aria-live within the
+    // content of the tooltip rather than this setting.
+    a11y?: AriaSupport,
+|};

package/src/components/new-tooltip/util.js

@@ -0,0 +1,27 @@
+// @flow
+/**
+ * Utility functions for the NewTooltip component.
+ */
+import Color from "@khanacademy/wonder-blocks-color";
+
+import type {NewTooltipProps} from "./types.js";
+
+/**
+ * Given a set of NewTooltipProps, return the `backgroundColor` and `textColor`
+ * of the tooltip. Used in TooltipArrow and TooltipBubble.
+ */
+export function getTooltipColors(tooltipProps: {
+    color: NewTooltipProps["color"],
+    inverted: NewTooltipProps["inverted"],
+    ...
+}): {|
+    backgroundColor: string,
+    textColor: string,
+|} {
+    const {color, inverted} = tooltipProps;
+
+    if (inverted) {
+        return {backgroundColor: color, textColor: Color.white};
+    }
+    return {backgroundColor: Color.white, textColor: color};
+}

package/src/components/number-input.jsx

@@ -0,0 +1,253 @@
+/* eslint-disable react/sort-comp */
+// @flow
+import classNames from "classnames";
+import $ from "jquery";
+import {number as knumber} from "kmath";
+import PropTypes from "prop-types";
+import * as React from "react";
+import ReactDOM from "react-dom";
+import _ from "underscore";
+
+import Util from "../util.js";
+import KhanMath from "../util/math.js";
+
+import type {Format} from "../util/math.js";
+
+const {firstNumericalParse, captureScratchpadTouchStart} = Util;
+const toNumericString = KhanMath.toNumericString;
+const getNumericFormat = KhanMath.getNumericFormat;
+
+/* An input box that accepts only numeric strings
+ *
+ * Calls onChange(value, format) for valid numbers.
+ * Reverts to the current value onBlur or on [ENTER],
+ *   but maintains the format (i.e. 3/2, 1 1/2, 150%)
+ * Accepts empty input and sends it to onChange as null
+ *   if no numeric placeholder is set.
+ * If given a checkValidity function, will turn
+ *   the background/outline red when invalid
+ * If useArrowKeys is set to true, up/down arrows will
+ *   increment/decrement integers
+ * Optionally takes a size ("mini", "small", "normal")
+ */
+class NumberInput extends React.Component<$FlowFixMe, $FlowFixMe> {
+    static propTypes = {
+        value: PropTypes.number,
+        format: PropTypes.string,
+        placeholder: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+        onChange: PropTypes.func.isRequired,
+        onFormatChange: PropTypes.func,
+        checkValidity: PropTypes.func,
+        size: PropTypes.string,
+        label: PropTypes.oneOf(["put your labels outside your inputs!"]),
+    };
+
+    static defaultProps: $FlowFixMe = {
+        value: null,
+        placeholder: null,
+        format: null,
+        onFormatChange: () => null,
+        checkValidity: () => true,
+        useArrowKeys: false,
+    };
+
+    state: $FlowFixMe = {
+        format: this.props.format,
+    };
+
+    render(): React.Node {
+        let classes = classNames({
+            "number-input": true,
+            "invalid-input": !this._checkValidity(this.props.value),
+            mini: this.props.size === "mini",
+            small: this.props.size === "small",
+            normal: this.props.size === "normal",
+        });
+        if (this.props.className != null) {
+            classes = classes + " " + this.props.className;
+        }
+
+        const {
+            // eslint-disable-next-line no-unused-vars
+            onFormatChange,
+            // eslint-disable-next-line no-unused-vars
+            checkValidity,
+            // eslint-disable-next-line no-unused-vars
+            useArrowKeys,
+            ...restProps
+        } = this.props;
+
+        return (
+            <input
+                {...restProps}
+                className={classes}
+                type="text"
+                // eslint-disable-next-line react/no-string-refs
+                ref="input"
+                onChange={this._handleChange}
+                onFocus={this._handleFocus}
+                onBlur={this._handleBlur}
+                onKeyPress={this._handleBlur}
+                onKeyDown={this._onKeyDown}
+                onTouchStart={captureScratchpadTouchStart}
+                defaultValue={toNumericString(
+                    this.props.value,
+                    this.state.format,
+                )}
+                value={undefined}
+            />
+        );
+    }
+
+    componentDidUpdate(prevProps: $FlowFixMe) {
+        if (!knumber.equal(this.getValue(), this.props.value)) {
+            this._setValue(this.props.value, this.state.format);
+        }
+    }
+
+    /* Return the current "value" of this input
+     * If empty, it returns the placeholder (if it is a number) or null
+     */
+    getValue: () => $FlowFixMe = () => {
+        return this.parseInputValue(
+            // $FlowFixMe[incompatible-use]
+            // $FlowFixMe[prop-missing]
+            ReactDOM.findDOMNode(this.refs.input).value, // eslint-disable-line react/no-string-refs
+        );
+    };
+
+    /* Return the current string value of this input */
+    getStringValue: () => string = () => {
+        // $FlowFixMe[incompatible-use]
+        // $FlowFixMe[prop-missing]
+        return ReactDOM.findDOMNode(this.refs.input).value.toString(); // eslint-disable-line react/no-string-refs
+    };
+
+    parseInputValue: ($FlowFixMe) => $FlowFixMe = (value) => {
+        if (value === "") {
+            const placeholder = this.props.placeholder;
+            return _.isFinite(placeholder) ? +placeholder : null;
+        }
+        const result = firstNumericalParse(value);
+        return _.isFinite(result) ? result : this.props.value;
+    };
+
+    /* Set text input focus to this input */
+    focus: () => void = () => {
+        // $FlowFixMe[incompatible-use]
+        // $FlowFixMe[prop-missing]
+        ReactDOM.findDOMNode(this.refs.input).focus(); // eslint-disable-line react/no-string-refs
+        this._handleFocus();
+    };
+
+    blur: () => void = () => {
+        // $FlowFixMe[incompatible-use]
+        // $FlowFixMe[prop-missing]
+        ReactDOM.findDOMNode(this.refs.input).blur(); // eslint-disable-line react/no-string-refs
+        this._handleBlur();
+    };
+
+    setSelectionRange: (number, number) => $FlowFixMe = (
+        selectionStart,
+        selectionEnd,
+    ) => {
+        // $FlowFixMe[incompatible-use]
+        // $FlowFixMe[prop-missing]
+        ReactDOM.findDOMNode(this).setSelectionRange(
+            selectionStart,
+            selectionEnd,
+        );
+    };
+
+    getSelectionStart: () => number = () => {
+        // $FlowFixMe[incompatible-use]
+        // $FlowFixMe[prop-missing]
+        return ReactDOM.findDOMNode(this).selectionStart;
+    };
+
+    getSelectionEnd: () => number = () => {
+        // $FlowFixMe[incompatible-use]
+        // $FlowFixMe[prop-missing]
+        return ReactDOM.findDOMNode(this).selectionEnd;
+    };
+
+    _checkValidity: ($FlowFixMe) => boolean = (value) => {
+        if (value == null) {
+            return true;
+        }
+
+        const val = firstNumericalParse(value);
+        const checkValidity = this.props.checkValidity;
+
+        return _.isFinite(val) && checkValidity(val);
+    };
+
+    _handleChange: (SyntheticInputEvent<>) => void = (e) => {
+        const text = e.target.value;
+        const value = this.parseInputValue(text);
+        const format = getNumericFormat(text);
+
+        this.props.onChange(value);
+        if (format) {
+            this.props.onFormatChange(value, format);
+            this.setState({format: format});
+        }
+    };
+
+    _handleFocus: () => void = () => {
+        if (this.props.onFocus) {
+            this.props.onFocus();
+        }
+    };
+
+    _handleBlur: (
+        e?: SyntheticFocusEvent<> | SyntheticKeyboardEvent<>,
+    ) => void = (e) => {
+        // Only continue on blur or "enter"
+        if (e && e.type === "keypress" && e.keyCode !== 13) {
+            return;
+        }
+
+        this._setValue(this.props.value, this.state.format);
+        if (this.props.onBlur) {
+            this.props.onBlur();
+        }
+    };
+
+    _onKeyDown: (SyntheticKeyboardEvent<>) => void = (e) => {
+        if (this.props.onKeyDown) {
+            this.props.onKeyDown(e);
+        }
+
+        if (
+            !this.props.useArrowKeys ||
+            !_.contains(["ArrowUp", "ArrowDown"], e.key)
+        ) {
+            return;
+        }
+
+        let val = this.getValue();
+        if (val !== Math.floor(val)) {
+            return; // bail if not an integer
+        }
+
+        if (e.key === "ArrowUp") {
+            val = val + 1;
+        } else if (e.key === "ArrowDown") {
+            val = val - 1;
+        }
+
+        if (this._checkValidity(val)) {
+            this.props.onChange(val);
+        }
+    };
+
+    _setValue: (number, Format) => void = (val, format) => {
+        // eslint-disable-next-line react/no-string-refs
+        $(ReactDOM.findDOMNode(this.refs.input)).val(
+            toNumericString(val, format),
+        );
+    };
+}
+
+export default NumberInput;

package/src/components/possible-answers.jsx

@@ -0,0 +1,36 @@
+// @flow
+/**
+ * In review mode (currently only visible in the sat-mission), NumericInput and
+ * InputNumber use this component to display the set of correct answers.
+ */
+
+import * as i18n from "@khanacademy/wonder-blocks-i18n";
+import PropTypes from "prop-types";
+import * as React from "react";
+import _ from "underscore";
+
+class PossibleAnswers extends React.Component<$FlowFixMe> {
+    static propTypes = {
+        answers: PropTypes.arrayOf(PropTypes.string),
+    };
+
+    render(): React.Node {
+        // It's redundant to show duplicate answers.
+        // So, remove duplicates from the given list of answer strings.
+        const answers = _.uniq(this.props.answers);
+
+        const answerComponents = _.map(answers, (answer) => {
+            // Plus, now that our answers are distinct, we can safely use the
+            // answer string as a key.
+            return <dd key={answer}>{answer}</dd>;
+        });
+        return (
+            <dl className="perseus-possible-answers">
+                <dt>{i18n.doNotTranslate("Correct Answer")}</dt>
+                {answerComponents}
+            </dl>
+        );
+    }
+}
+
+export default PossibleAnswers;

package/src/components/prop-check-box.jsx

@@ -0,0 +1,78 @@
+/* eslint-disable @babel/no-invalid-this, react/sort-comp */
+// @flow
+import createReactClass from "create-react-class";
+import PropTypes from "prop-types";
+import * as React from "react";
+import _ from "underscore";
+
+import {Errors} from "../logging/log.js";
+import {PerseusError} from "../perseus-error.js";
+
+/* A checkbox that syncs its value to props using the
+ * renderer's onChange method, and gets the prop name
+ * dynamically from its props list
+ */
+const PropCheckBox: any = createReactClass({
+    displayName: "PropCheckBox",
+
+    propTypes: {
+        labelAlignment: PropTypes.oneOf(["left", "right"]),
+    },
+
+    DEFAULT_PROPS: {
+        label: null,
+        onChange: null,
+        labelAlignment: "left",
+    },
+
+    getDefaultProps: function () {
+        return this.DEFAULT_PROPS;
+    },
+
+    propName: function () {
+        const propName = _.find(
+            _.keys(this.props),
+            function (localPropName) {
+                return !_.has(this.DEFAULT_PROPS, localPropName);
+            },
+            this,
+        );
+
+        if (!propName) {
+            throw new PerseusError(
+                "Attempted to create a PropCheckBox with no prop!",
+                Errors.InvalidInput,
+            );
+        }
+
+        return propName;
+    },
+
+    _labelAlignLeft: function () {
+        return this.props.labelAlignment === "left";
+    },
+
+    render: function () {
+        const propName = this.propName();
+        return (
+            <label>
+                {this._labelAlignLeft() && this.props.label}
+                <input
+                    type="checkbox"
+                    checked={this.props[propName]}
+                    onChange={this.toggle}
+                />
+                {!this._labelAlignLeft() && this.props.label}
+            </label>
+        );
+    },
+
+    toggle: function () {
+        const propName = this.propName();
+        const changes = {};
+        changes[propName] = !this.props[propName];
+        this.props.onChange(changes);
+    },
+});
+
+export default PropCheckBox;

package/src/components/range-input.jsx

@@ -0,0 +1,61 @@
+/* eslint-disable react/forbid-prop-types, react/sort-comp */
+// @flow
+import PropTypes from "prop-types";
+import * as React from "react";
+
+import NumberInput from "../components/number-input.jsx";
+
+const truth = () => true;
+
+/* A minor abstraction on top of NumberInput for ranges
+ *
+ */
+class RangeInput extends React.Component<$FlowFixMe> {
+    static propTypes = {
+        value: PropTypes.array.isRequired,
+        onChange: PropTypes.func.isRequired,
+        placeholder: PropTypes.array,
+        checkValidity: PropTypes.func,
+    };
+
+    static defaultProps: $FlowFixMe = {
+        placeholder: [null, null],
+    };
+
+    render(): React.Node {
+        const value = this.props.value;
+        const checkValidity = this.props.checkValidity || truth;
+
+        return (
+            <div className="range-input">
+                <NumberInput
+                    {...this.props}
+                    value={value[0]}
+                    checkValidity={(val) => checkValidity([val, value[1]])}
+                    // eslint-disable-next-line react/jsx-no-bind
+                    onChange={this.onChange.bind(this, 0)}
+                    placeholder={this.props.placeholder[0]}
+                />
+                <NumberInput
+                    {...this.props}
+                    value={value[1]}
+                    checkValidity={(val) => checkValidity([value[0], val])}
+                    // eslint-disable-next-line react/jsx-no-bind
+                    onChange={this.onChange.bind(this, 1)}
+                    placeholder={this.props.placeholder[1]}
+                />
+            </div>
+        );
+    }
+
+    onChange: (number, string) => void = (i, newVal) => {
+        const value = this.props.value;
+        if (i === 0) {
+            this.props.onChange([newVal, value[1]]);
+        } else {
+            this.props.onChange([value[0], newVal]);
+        }
+    };
+}
+
+export default RangeInput;