@khanacademy/perseus 3.0.0 → 4.0.1

package/src/widgets/radio/choice.tsx

@@ -0,0 +1,358 @@
+/* eslint-disable react/no-unsafe */
+import Button from "@khanacademy/wonder-blocks-button";
+import Clickable from "@khanacademy/wonder-blocks-clickable";
+import Color from "@khanacademy/wonder-blocks-color";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {Strut} from "@khanacademy/wonder-blocks-layout";
+import {Popover, PopoverContent} from "@khanacademy/wonder-blocks-popover";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import {StyleSheet, css} from "aphrodite";
+import classNames from "classnames";
+import * as React from "react";
+import {useState, useEffect} from "react";
+import _ from "underscore";
+
+import Icon from "../../components/icon";
+import {ApiOptions, ClassNames} from "../../perseus-api";
+import mediaQueries from "../../styles/media-queries";
+
+import getA11yText from "./choice-a11y-text";
+import ChoiceIcon from "./choice-icon/choice-icon";
+import OptionStatus from "./option-status";
+import {getChoiceLetter} from "./util";
+
+import type {APIOptions} from "../../types";
+
+const intermediateCheckboxPadding = `16px 16px`;
+const intermediateCheckboxPaddingPhone = `12px 16px`;
+
+const ellipsisHorizontalIcon = {
+    path: "M27.218 6.82l0 13.578q0 2.852-1.984 4.836t-4.836 1.984l-13.578 0q-2.852 0-4.836-1.984t-1.984-4.836l0-13.578q0-2.852 1.984-4.836t4.836-1.984l13.578 0q2.852 0 4.836 1.984t1.984 4.836zm36.27 0l0 13.578q0 2.852-1.984 4.836t-4.836 1.984l-13.578 0q-2.852 0-4.836-1.984t-1.984-4.836l0-13.578q0-2.852 1.984-4.836t4.836-1.984l13.578 0q2.852 0 4.836 1.984t1.984 4.836zm36.27 0l0 13.578q0 2.852-1.984 4.836t-4.836 1.984l-13.578 0q-2.852 0-4.836-1.984t-1.984-4.836l0-13.578q0-2.852 1.984-4.836t4.836-1.984l13.578 0q2.852 0 4.836 1.984t1.984 4.836z",
+    width: 100,
+    height: 27.284,
+} as const;
+
+export type ChoiceProps = {
+    apiOptions?: APIOptions;
+    checked?: boolean;
+    rationale: React.ReactNode;
+    content: React.ReactNode;
+    correct?: boolean;
+    disabled?: boolean;
+    // This indicates the position of the choice relative to others
+    // (so that we can display a nice little (A), (B), etc. next to it)
+    // Also used to generate an id for each input.
+    pos: number;
+    reviewMode: boolean;
+    showRationale: boolean;
+    showCorrectness: boolean;
+    multipleSelect: boolean;
+    // Indicates whether the user has "crossed out" this choice, meaning
+    // that they don't think it's correct. This value does not affect
+    // scoring or other behavior; it's just a note for the user's
+    // reference.
+    crossedOut: boolean;
+    // Indicates that the user has previously selected this answer. These
+    // answers may be rendered orange in review, rather than grey if
+    // incorrect.
+    previouslyAnswered?: boolean;
+    // A callback indicating that this choice has changed. Its argument is
+    // an object with two keys: `checked` and `crossedOut`. Each contains a
+    // boolean value specifying the new checked and crossed-out value of
+    // this choice.
+    onChange?: (newValues: {checked: boolean; crossedOut: boolean}) => void;
+};
+
+type WithForwardRef = {
+    forwardedRef: React.ForwardedRef<HTMLButtonElement>;
+};
+
+type ChoicePropsWithForwardRef = ChoiceProps & WithForwardRef;
+
+// Note(TB): Received errors when using useUniqueIdWithMock
+// so created this workaround function. Will update when
+// useUniqueIdWithMock is available.
+// https://khanacademy.atlassian.net/browse/FEI-4861?atlOrigin=eyJpIjoiNDJlZWMwNjM1NWJhNDBkMWFjY2FmN2I0ZjcxZmQxOGUiLCJwIjoiaiJ9
+let id = 0;
+function uniqueId() {
+    return `choice-${id++}`;
+}
+
+const Choice: React.FC<ChoicePropsWithForwardRef> = function (
+    props,
+): React.ReactElement {
+    const {
+        disabled = false,
+        checked = false,
+        content,
+        crossedOut,
+        showCorrectness,
+        multipleSelect,
+        onChange = (newValues: {
+            checked: boolean;
+            crossedOut: boolean;
+        }): void => {},
+        reviewMode,
+        correct = false,
+        apiOptions = ApiOptions.defaults,
+        previouslyAnswered = false,
+        pos = 0,
+        showRationale = false,
+        rationale,
+        forwardedRef,
+    } = props;
+    const [isInputFocused, setIsInputFocused] = useState(false);
+
+    useEffect(() => {
+        if (isInputFocused && disabled) {
+            setIsInputFocused(false);
+        }
+    }, [disabled, isInputFocused, setIsInputFocused]);
+
+    // Call `this.props.onChange` with the given values. Any keys that are not
+    // specified will be filled in with the current value. (For example, if
+    // `checked` is specified but `crossedOut` is not, then `crossedOut` will
+    // be filled in with `this.props.crossedOut`.)
+    //
+    // This enables us to use shorthand inside this component, while
+    // maintaining a consistent API for the parent.
+    function sendChange(newValues: {checked?: boolean; crossedOut?: boolean}) {
+        const updatedChecked = newValues.checked ?? checked;
+        const updatedCrossedOut = newValues.crossedOut ?? crossedOut;
+        onChange({checked: updatedChecked, crossedOut: updatedCrossedOut});
+    }
+
+    const descriptionClassName = classNames(
+        "description",
+        css(styles.description),
+    );
+
+    const rationaleClassName = classNames(
+        "perseus-radio-rationale-content",
+        css(styles.rationale),
+    );
+
+    // We want to show the choices as dimmed out when the choices are disabled.
+    // However, we don't want to do this when we're in review mode in the
+    // content library.
+    const showDimmed = (!reviewMode && apiOptions.readOnly) || crossedOut;
+
+    const letter = getChoiceLetter(pos);
+    const a11yText = getA11yText(
+        letter,
+        checked,
+        correct,
+        crossedOut,
+        showCorrectness,
+    );
+    const choiceId = uniqueId();
+
+    return (
+        <div
+            style={{
+                // @ts-expect-error [FEI-5003] - TS2322 - Type '{ dispay: string; flexDirection: "column"; color: string; }' is not assignable to type 'Properties<string | number, string & {}>'.
+                dispay: "flex",
+                flexDirection: "column",
+                color: Color.offBlack,
+            }}
+            className={descriptionClassName}
+        >
+            <div
+                style={{
+                    display: "flex",
+                    flexDirection: "row",
+                    opacity: showDimmed ? 0.5 : 1.0,
+                }}
+            >
+                <div className="perseus-sr-only">
+                    <input
+                        type={multipleSelect ? "checkbox" : "radio"}
+                        id={choiceId}
+                        checked={checked}
+                        onClick={() => {
+                            // If we're checking a crossed-out option, let's
+                            // also uncross it.
+                            sendChange({
+                                checked: !checked,
+                                crossedOut: false,
+                            });
+                        }}
+                        onChange={() => {}}
+                        disabled={disabled || apiOptions.readOnly}
+                        tabIndex={-1}
+                        className={ClassNames.RADIO.OPTION_CONTENT}
+                    />
+                    <label htmlFor={choiceId}>
+                        {a11yText} &nbsp; {content}
+                    </label>
+                </div>
+                <Clickable
+                    onClick={() => {
+                        // If we're checking a crossed-out option, let's
+                        // also uncross it.
+                        sendChange({
+                            checked: !checked,
+                            crossedOut: false,
+                        });
+                    }}
+                    disabled={disabled || apiOptions.readOnly}
+                    style={{flex: 1, color: Color.offBlack, userSelect: "text"}}
+                    ref={forwardedRef as any}
+                    aria-hidden="true"
+                >
+                    {({hovered, focused, pressed}) => (
+                        <div
+                            style={{
+                                display: "flex",
+                                flexDirection: "row",
+                                justifyContent: "center",
+                                alignContent: "center",
+                                paddingTop: Spacing.xSmall_8,
+                                paddingBottom: Spacing.xSmall_8,
+                                paddingLeft: Spacing.xSmall_8,
+                            }}
+                        >
+                            <ChoiceIcon
+                                pos={pos}
+                                correct={correct}
+                                crossedOut={crossedOut}
+                                pressed={pressed}
+                                focused={focused}
+                                checked={checked}
+                                hovered={hovered}
+                                showCorrectness={showCorrectness}
+                                multipleSelect={multipleSelect}
+                                reviewMode={reviewMode}
+                                previouslyAnswered={previouslyAnswered}
+                            />
+                            <span
+                                style={{
+                                    paddingLeft: Spacing.small_12,
+                                    textAlign: "left",
+                                    flex: 1,
+                                    paddingTop: 4,
+                                }}
+                            >
+                                <div>
+                                    <OptionStatus
+                                        checked={checked}
+                                        correct={correct}
+                                        crossedOut={crossedOut}
+                                        previouslyAnswered={previouslyAnswered}
+                                        reviewMode={reviewMode}
+                                    />
+                                </div>
+                                <div>{content}</div>
+                            </span>
+                        </div>
+                    )}
+                </Clickable>
+
+                {apiOptions.crossOutEnabled && !reviewMode && (
+                    <Popover
+                        dismissEnabled
+                        content={({close}) => (
+                            <PopoverContent
+                                title="Cross out"
+                                content="Cross out option"
+                                closeButtonVisible
+                                actions={
+                                    <View>
+                                        <Strut size={Spacing.medium_16} />
+                                        <Button
+                                            kind="primary"
+                                            aria-label={`Cross out Choice ${getChoiceLetter(
+                                                pos,
+                                            )}`}
+                                            disabled={
+                                                apiOptions.readOnly ||
+                                                reviewMode
+                                            }
+                                            onClick={() => {
+                                                if (!crossedOut) {
+                                                    // If we're crossing
+                                                    // out a checked
+                                                    // option, let's also
+                                                    // uncheck it.
+                                                    sendChange({
+                                                        checked: false,
+                                                        crossedOut: true,
+                                                    });
+                                                } else {
+                                                    sendChange({
+                                                        crossedOut: false,
+                                                    });
+                                                }
+                                                close();
+                                            }}
+                                        >
+                                            {crossedOut
+                                                ? "Bring back"
+                                                : "Cross out"}
+                                        </Button>
+                                    </View>
+                                }
+                            />
+                        )}
+                    >
+                        {({open}) => (
+                            <Clickable
+                                onClick={open}
+                                aria-label={`Open menu for Choice ${getChoiceLetter(
+                                    pos,
+                                )}`}
+                                style={{
+                                    alignSelf: "center",
+                                    padding: "5px",
+                                    display: "flex",
+                                    justifyContent: "center",
+                                    alignItems: "center",
+                                    marginLeft: "10px",
+                                }}
+                            >
+                                {({hovered, focused, pressed}) => (
+                                    <Icon
+                                        icon={ellipsisHorizontalIcon}
+                                        size={3}
+                                        color={Color.offBlack64}
+                                    />
+                                )}
+                            </Clickable>
+                        )}
+                    </Popover>
+                )}
+            </div>
+
+            {showRationale && (
+                <div
+                    className={rationaleClassName}
+                    data-test-id={`perseus-radio-rationale-content-${pos}`}
+                >
+                    {rationale}
+                </div>
+            )}
+        </div>
+    );
+};
+
+const styles = StyleSheet.create({
+    description: {
+        display: "inline-block",
+        width: "100%",
+    },
+
+    rationale: {
+        display: "block",
+        padding: intermediateCheckboxPadding,
+        paddingTop: 0,
+        marginLeft: 54,
+        [mediaQueries.smOrSmaller]: {
+            padding: intermediateCheckboxPaddingPhone,
+            paddingTop: 0,
+        },
+    },
+});
+
+export default React.forwardRef<HTMLButtonElement, ChoiceProps>(
+    (props, ref) => <Choice {...props} forwardedRef={ref} />,
+);

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

@@ -0,0 +1,57 @@
+/**
+ * Renders a circular selection ring around the child.
+ */
+
+import {StyleSheet, css} from "aphrodite";
+import * as React from "react";
+
+import * as styleConstants from "../../styles/constants";
+
+type Props = {
+    children?: React.ReactNode;
+    // 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;
+    // Whether a user can select multiple options or not
+    multipleSelect: boolean;
+};
+
+const FocusRing: React.FC<Props> = function (props): React.ReactElement {
+    const {visible, color, children, multipleSelect} = props;
+
+    const borderColor = visible ? color : "transparent";
+    const borderRadius = multipleSelect ? 5 : "50%";
+    const style = {
+        borderColor,
+        borderRadius,
+    } as const;
+    return (
+        <span
+            data-test-id="focus-ring"
+            className={css(styles.ring)}
+            style={style}
+        >
+            {children}
+        </span>
+    );
+};
+
+FocusRing.defaultProps = {
+    visible: true,
+    color: styleConstants.kaGreen,
+    multipleSelect: false,
+};
+
+const styles = StyleSheet.create({
+    ring: {
+        margin: "auto",
+        display: "inline-block",
+        borderWidth: 2,
+        padding: 2,
+        borderStyle: "solid",
+    },
+});
+
+export default FocusRing;

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

@@ -0,0 +1,100 @@
+/**
+ * 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 Color from "@khanacademy/wonder-blocks-color";
+import * as i18n from "@khanacademy/wonder-blocks-i18n";
+import {StyleSheet, css} from "aphrodite";
+import * as React from "react";
+
+type OptionStatusProps = {
+    // 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;
+    reviewMode: boolean;
+};
+
+function renderText(
+    checked: boolean,
+    correct: boolean,
+    crossedOut: boolean,
+): string {
+    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");
+}
+
+const OptionStatus: React.FC<OptionStatusProps> = function (
+    props,
+): React.ReactElement {
+    const {checked, correct, crossedOut, previouslyAnswered, reviewMode} =
+        props;
+
+    // Option status is shown only in review mode, or for incorrectly
+    // answered items.
+    if (!reviewMode && !previouslyAnswered) {
+        // @ts-expect-error [FEI-5003] - TS2322 - Type 'null' is not assignable to type 'ReactElement<any, string | JSXElementConstructor<any>>'.
+        return null;
+    }
+
+    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)}>
+            {renderText(checked, correct, crossedOut)}
+        </div>
+    );
+};
+
+const styles = StyleSheet.create({
+    text: {
+        alignItems: "center",
+        display: "flex",
+        fontSize: 12,
+        height: 32,
+        textTransform: "uppercase",
+    },
+    correct: {
+        color: Color.green,
+    },
+    incorrectAnswered: {
+        color: Color.red,
+    },
+    incorrect: {
+        color: Color.offBlack64,
+    },
+});
+
+export default OptionStatus;

package/src/widgets/radio/util.test.ts

@@ -0,0 +1,18 @@
+import {getChoiceLetter} from "./util";
+
+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(" ");
+        }
+    });
+});

package/src/widgets/radio/util.ts

@@ -0,0 +1,31 @@
+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 " ";
+}