@khanacademy/perseus 0.0.1 → 0.2.1

package/src/widgets/radio/cross-out-tooltip.jsx

@@ -0,0 +1,129 @@
+// @flow
+/**
+ * The tooltip that appears when you open the `CrossOutMenu` on desktop,
+ * enabling the user to toggle a choice's `crossedOut` state.
+ */
+import * as React from "react";
+
+import NewTooltip from "../../components/new-tooltip/new-tooltip.jsx";
+import mediaQueries from "../../styles/media-queries.js";
+
+import CrossOutButton, {type CrossOutButtonProps} from "./cross-out-button.jsx";
+
+export type CrossOutTooltipProps = {
+    children: React$Element<any>,
+    dismissed: boolean,
+    onDismiss: () => void,
+    // Props to pass directly to the CrossOutButton.
+    buttonProps: CrossOutButtonProps,
+    ...
+};
+
+export default class CrossOutTooltip extends React.PureComponent<CrossOutTooltipProps> {
+    /**
+     * When you press Tab or Shift-Tab from the tooltip button, we call this
+     * handler to dismiss the tooltip and bring you back to the menu button.
+     */
+    _handleKeyDown: (e: SyntheticKeyboardEvent<HTMLElement>) => void = (
+        e: SyntheticKeyboardEvent<HTMLElement>,
+    ) => {
+        // We don't need to check for the shift key _also_ being applied; we
+        // can just listen for all keystrokes where the primary key is Tab.
+        if (e.key === "Tab") {
+            this.props.onDismiss();
+            e.preventDefault();
+        }
+    };
+
+    _renderTooltipContent(): React.Element<"div"> {
+        return (
+            // The button is the main semantic click target of the tooltip,
+            // which can receive tab focus (and automatically does when the
+            // flag `usingKeyboardFocus` is set!). However, the entire tooltip
+            // serves as a click target as well; see the <NewTooltip />.
+            <div onKeyDown={this._handleKeyDown}>
+                <CrossOutButton {...this.props.buttonProps} />
+            </div>
+        );
+    }
+
+    render(): React.Element<"div"> {
+        return (
+            <div>
+                <NewTooltip
+                    content={this._renderTooltipContent()}
+                    offsetFrom="arrow"
+                    offset={10}
+                    dismissed={this.props.dismissed}
+                    showOnMount={true}
+                    toggleOnHover={false}
+                    onClick={() => this.props.buttonProps.onClick()}
+                    // On smOrSmaller, hide this tooltip, and use the slide
+                    // panel in `CrossOutMenuWrapper` instead.
+                    media={mediaQueries.mdOrLarger}
+                >
+                    {this.props.children}
+                </NewTooltip>
+
+                {/* If the menu is open, register global dismissal handlers
+                 * that listen for clicks elsewhere in the page, or Escape
+                 * keypresses. This component renders nothing; it just
+                 * registers/unregisters handlers on mount/unmount. */}
+                {!this.props.dismissed && (
+                    <GlobalDismissalHandlers onDismiss={this.props.onDismiss} />
+                )}
+            </div>
+        );
+    }
+}
+
+/**
+ * A component that, when mounted, listens for dismissal-y events: clicking
+ * anywhere on the page, or pressing the Escape key. We handle these events by
+ * calling `onDismiss`.
+ *
+ * HACK(mdr): To generalize this component, we probably should ignore clicks
+ *     inside the tooltip itself. However, conveniently, the `onClick` handler
+ *     we receive from CrossOutMenu includes dismissal anyway. So, it's safe to
+ *     dismiss on _any_ click, not just those outside the tooltip.
+ */
+class GlobalDismissalHandlers extends React.PureComponent<{
+    onDismiss: () => void,
+    ...
+}> {
+    componentDidMount() {
+        // Register these listeners after a tick, so they don't catch the click
+        // or keypress that _caused_ the tooltip to mount.
+        // TODO(jeff, CP-3128): Use Wonder Blocks Timing API
+        // eslint-disable-next-line no-restricted-syntax
+        setTimeout(() => {
+            window.addEventListener("click", this._handleGlobalClick);
+            window.addEventListener("keyup", this._handleGlobalKeyup);
+        }, 0);
+    }
+
+    componentWillUnmount() {
+        window.removeEventListener("click", this._handleGlobalClick);
+        window.removeEventListener("keyup", this._handleGlobalKeyup);
+    }
+
+    /**
+     * On clicking anywhere, trigger dismissal.
+     */
+    _handleGlobalClick = () => {
+        this.props.onDismiss();
+    };
+
+    /**
+     * If the key was Escape, trigger dismissal.
+     */
+    _handleGlobalKeyup = (e: KeyboardEvent) => {
+        if (e.key === "Escape") {
+            this.props.onDismiss();
+        }
+    };
+
+    render(): React.Node {
+        return null;
+    }
+}

package/src/widgets/radio/focus-ring.jsx

@@ -0,0 +1,51 @@
+// @flow
+/**
+ * Renders a circular selection ring around the child.
+ */
+
+import {StyleSheet, css} from "aphrodite";
+import * as React from "react";
+
+import * as styleConstants from "../../styles/constants.js";
+
+class FocusRing extends React.Component<{
+    children?: any,
+    // Whether the focus ring is visible. Allows for positioning
+    // the child identically regardless of whether the ring is visible.
+    visible: boolean,
+    // Color of the focus ring
+    color: string,
+    ...
+}> {
+    static defaultProps: {|color: string, visible: boolean|} = {
+        visible: true,
+        color: styleConstants.kaGreen,
+    };
+
+    render(): React.Element<"span"> {
+        const borderColor = this.props.visible
+            ? this.props.color
+            : "transparent";
+        const style = {
+            borderColor: borderColor,
+        };
+        return (
+            <span className={css(styles.ring)} style={style}>
+                {this.props.children}
+            </span>
+        );
+    }
+}
+
+const styles = StyleSheet.create({
+    ring: {
+        margin: "auto",
+        display: "inline-block",
+        borderRadius: "50%",
+        borderWidth: 2,
+        padding: 2,
+        borderStyle: "solid",
+    },
+});
+
+export default FocusRing;

package/src/widgets/radio/option-status.jsx

@@ -0,0 +1,89 @@
+// @flow
+/**
+ * Renders text indicating whether the choice was correct or
+ * not and whether the choice was selected or not.
+ * This information is redundant with that provided in the
+ * ChoiceIcon visualizations but is meant to make the distinctions
+ * between the states more immediately clear to users.
+ */
+
+import * as i18n from "@khanacademy/wonder-blocks-i18n";
+import {StyleSheet, css} from "aphrodite";
+import * as React from "react";
+
+import * as styleConstants from "../../styles/constants.js";
+
+class OptionStatus extends React.Component<{
+    // Was this option the correct answer?
+    correct: boolean,
+    // Did the user select this option as the answer?
+    checked: boolean,
+    // Did the user cross out this option?
+    crossedOut: boolean,
+    // Did the user select this option as the answer earlier?
+    previouslyAnswered: boolean,
+    ...
+}> {
+    _renderText(): string {
+        const {checked, correct, crossedOut} = this.props;
+        if (correct) {
+            // For correct answers, we surface checked _or_ crossedOut state,
+            // because any interaction with the correct answer is noteworthy!
+            if (checked) {
+                return i18n._("Correct (selected)");
+            }
+            if (crossedOut) {
+                return i18n._("Correct (but you crossed it out)");
+            }
+            return i18n._("Correct");
+        }
+        // But, for incorrect answers, we only surface checked state,
+        // because crossing out an incorrect answer is not noteworthy.
+        if (checked) {
+            return i18n._("Incorrect (selected)");
+        }
+        return i18n._("Incorrect");
+    }
+
+    render(): React.Element<"div"> {
+        const {checked, correct, previouslyAnswered} = this.props;
+
+        let textStyle;
+        if (correct) {
+            textStyle = styles.correct;
+        } else {
+            if (checked || previouslyAnswered) {
+                textStyle = styles.incorrectAnswered;
+            } else {
+                textStyle = styles.incorrect;
+            }
+        }
+
+        return (
+            <div className={css(styles.text, textStyle)}>
+                {this._renderText()}
+            </div>
+        );
+    }
+}
+
+const styles = StyleSheet.create({
+    text: {
+        alignItems: "center",
+        display: "flex",
+        fontSize: 12,
+        height: 32,
+        textTransform: "uppercase",
+    },
+    correct: {
+        color: styleConstants.kaGreen,
+    },
+    incorrectAnswered: {
+        color: styleConstants.warning1,
+    },
+    incorrect: {
+        color: styleConstants.gray68,
+    },
+});
+
+export default OptionStatus;

package/src/widgets/radio/toggleable-radio-button.jsx

@@ -0,0 +1,133 @@
+// @flow
+import PropTypes from "prop-types";
+import * as React from "react";
+import _ from "underscore";
+
+/**
+ * A radio button that can be unchecked by clicking it again.
+ *
+ * This component behaves much like a checkbox in that when you click it again
+ * (or hit space bar or select it in some other way), it will become unchecked.
+ * (Hopefully) it behaves exactly like a radio button in every other way though
+ * (arrow keys can still be used to select it within a group for example).
+ *
+ * Here's a summary of which of our event handlers fire for each way to select
+ * or deselect the button:
+ *
+ * - Clicking a button: handleClick, handleChange
+ * - Pressing spacebar with button focussed: handleKeyDown, handleKeyUp (we
+ *   suppress the default behavior of some browsers to synthesize a click event
+ *   here).
+ * - When radio button A is selected, pressing down arrow to select B:
+ *   handleKeyDown (A), handleClick (B), handleChange (B), handleKeyUp (B)
+ * - Clicking with mac screenreader: handleClick, handleChange
+ */
+class ToggleableRadioButton extends React.Component<$FlowFixMe, $FlowFixMe> {
+    _inputElement: ?HTMLInputElement;
+
+    static propTypes = {
+        // Whether the radio button should be checked or unchecked (this is a
+        // controlled component).
+        checked: PropTypes.bool.isRequired,
+
+        // A ref function to attach to the <input> element.
+        inputRef: PropTypes.func,
+
+        // A function that will be called whenever the radio button is checked
+        // or unchecked. It's possible for this to be called twice for a single
+        // checking or unchecking.
+        onChecked: PropTypes.func.isRequired,
+
+        // Callbacks for when the user presses the up/left arrow or down/right
+        // arrow (respectively) to navigate between choices. When called, the
+        // parent finds the prev/next choice, focuses the input, and checks the
+        // radio button if appropriate. (The reason we have custom behavior is
+        // that we actually _don't_ want to auto-select crossed-out choices!)
+        goToPrevChoice: PropTypes.func.isRequired,
+        goToNextChoice: PropTypes.func.isRequired,
+    };
+
+    handleClick: (SyntheticMouseEvent<>) => void = (event) => {
+        this.props.onChecked(!this.props.checked);
+
+        // NOTE(johnsullivan): Preventing default would make sense to do here
+        //     because we're fully controlling the state of the check box and
+        //     don't really want it to be (un)checked accidently. React
+        //     requires that we *don't* call preventDefault from the onClick or
+        //     onChecked handlers of a controlled component though.
+    };
+
+    handleKeyUp: (SyntheticKeyboardEvent<>) => void = (event) => {
+        // Make hitting the spacebar with the element selected equivalent to
+        // clicking it. Some browsers do this as part of the radio button's
+        // default behavior, but since some browsers don't we normalize the
+        // behavior here.
+        if (event.key === " ") {
+            this.props.onChecked(!this.props.checked);
+            event.preventDefault();
+        }
+    };
+
+    handleChange: (SyntheticInputEvent<>) => void = (event) => {
+        // If the checkbox is going from unchecked to checked, we'll handle it
+        // here.
+        // NOTE(johnsullivan): The onClick/onKeyUp handler most likely *also*
+        //     handled this, but we're being defensive against browsers/devices
+        //     that might not call those handlers like we'd expect. It's
+        //     unclear to me whether this is strictly necessary.
+        if (!this.props.checked && event.target.checked) {
+            this.props.onChecked(true);
+        }
+    };
+
+    handleKeyDown: (SyntheticKeyboardEvent<>) => void = (event) => {
+        // This is necessary in order to prevent IE9 from creating a duplicate
+        // click event on the radio button when the space bar is hit.
+        if (event.key === " ") {
+            event.preventDefault();
+        } else if (event.key === "ArrowUp" || event.key === "ArrowLeft") {
+            this.props.goToPrevChoice();
+            event.preventDefault();
+        } else if (event.key === "ArrowDown" || event.key === "ArrowRight") {
+            this.props.goToNextChoice();
+            event.preventDefault();
+        }
+    };
+
+    /**
+     * We keep a reference to the input element ourselves, and provide it to
+     * the parent, too.
+     */
+    handleRef: (HTMLInputElement) => void = (inputElement) => {
+        this._inputElement = inputElement;
+        this.props.inputRef && this.props.inputRef(inputElement);
+    };
+
+    render(): React.Node {
+        const {
+            // eslint-disable-next-line no-unused-vars
+            inputRef,
+            // eslint-disable-next-line no-unused-vars
+            onChecked,
+            // eslint-disable-next-line no-unused-vars
+            goToPrevChoice,
+            // eslint-disable-next-line no-unused-vars
+            goToNextChoice,
+            ...otherProps
+        } = this.props;
+
+        return (
+            <input
+                {...otherProps}
+                type="radio"
+                onChange={this.handleChange}
+                onClick={this.handleClick}
+                onKeyDown={this.handleKeyDown}
+                onKeyUp={this.handleKeyUp}
+                ref={this.handleRef}
+            />
+        );
+    }
+}
+
+export default ToggleableRadioButton;

package/src/widgets/radio/util.js

@@ -0,0 +1,32 @@
+// @flow
+import * as i18n from "@khanacademy/wonder-blocks-i18n";
+
+/**
+ * Given a choice's position in the radio widget, return the corresponding
+ * "choice letter". (For example, in English, `getChoiceLetter(0)` is "A",
+ * `getChoiceLetter(1)` is "B", etc.)
+ */
+export function getChoiceLetter(pos: number): string {
+    /* I18N: This is a list of single-character labels that will appear in
+     * front of multiple-choice options. For instance, a multiple-choice
+     * question with three options would display
+     *  (A) first option
+     *  (B) second option
+     *  (C) third option
+     * There must be spaces between each of the different characters. The
+     * characters will show up next to options in the order that they are
+     * listed here. Most multiple choice questions have 5 or fewer options.
+     */
+    const lettersString = i18n._(
+        "A B C D E F G H I J K L M N O P Q R S T U V W X Y Z",
+    );
+
+    const letters = lettersString.split(" ");
+
+    if (pos < letters.length) {
+        // If the position we need is listed in the localized string, use that.
+        return letters[pos];
+    }
+    // If we're out of letters, give up and return a space.
+    return " ";
+}

package/src/widgets/radio/util_test.js

@@ -0,0 +1,19 @@
+// @flow
+import {getChoiceLetter} from "./util.js";
+
+describe("getChoiceLetter (in English)", () => {
+    it("returns the first 5 letters for most questions", () => {
+        expect(getChoiceLetter(0)).toEqual("A");
+        expect(getChoiceLetter(1)).toEqual("B");
+        expect(getChoiceLetter(2)).toEqual("C");
+        expect(getChoiceLetter(3)).toEqual("D");
+        expect(getChoiceLetter(4)).toEqual("E");
+    });
+
+    it("returns Z as the last letter, then spaces afterwards", () => {
+        expect(getChoiceLetter(25)).toEqual("Z");
+        for (let i = 26; i < 100; i++) {
+            expect(getChoiceLetter(i)).toEqual(" ");
+        }
+    });
+});