@khanacademy/perseus 0.0.1 → 0.2.1

package/src/logging/log_test.js

@@ -0,0 +1,41 @@
+// @flow
+
+import {testDependencies} from "../../../../testing/test-dependencies.js";
+import {setDependencies} from "../dependencies.js";
+
+import {Errors, Log} from "./log.js";
+
+describe("Perseus logging", () => {
+    it("should proxy log() calls to the logger provided through setDependencies", () => {
+        // Arrange
+        const logSpy = jest.spyOn(testDependencies.Log, "log");
+        setDependencies(testDependencies);
+
+        // Act
+        Log.log("test message", {a: 1, b: "two"});
+
+        // Assert
+        expect(logSpy).toHaveBeenCalledWith("test message", {a: 1, b: "two"});
+    });
+
+    it("should proxy error() calls to the logger provided through setDependencies", () => {
+        // Arrange
+        const errorSpy = jest.spyOn(testDependencies.Log, "error");
+        setDependencies(testDependencies);
+
+        // Act
+        Log.error("test error", Errors.NotAllowed, {
+            cause: new Error("Something baaad"),
+            loggedMetadata: {a: 1, b: "two"},
+        });
+
+        // Assert
+        expect(errorSpy).toHaveBeenCalledWith("test error", "NotAllowed", {
+            cause: expect.any(Error),
+            loggedMetadata: {
+                a: 1,
+                b: "two",
+            },
+        });
+    });
+});

package/src/mixins/changeable.jsx

@@ -0,0 +1,115 @@
+/* eslint-disable @babel/no-invalid-this */
+// @flow
+/**
+ * Changeable
+ *
+ * Adds a this.change() function to a component
+ *
+ * This.change takes prop changes as parameters, and calls
+ * this.props.onChange with the modified props.
+ */
+
+import PropTypes from "prop-types";
+import _ from "underscore";
+
+import {Errors} from "../logging/log.js";
+import {PerseusError} from "../perseus-error.js";
+
+import WIDGET_PROP_BLACKLIST from "./widget-prop-blacklist.js";
+
+import type {ChangeFn} from "../types.js";
+
+const USAGE =
+    "Usage:\n" +
+    "  this.change({propName: 5}, callback);\n" +
+    '  this.change("propName", 5, callback);\n' +
+    '  this.change("propName")';
+
+/**
+ * Primary helper function for this.change()
+ *
+ * Takes the parameters in a consistent style, once this.change() has
+ * figured out which way it was called.
+ */
+const _changeMultiple = function (component, newProps, callback) {
+    // Omit "default" props:
+    // ref and key come from react, and don't actually represent
+    //   the conceptual state of our component
+    // onChange comes from our parent to allow this modification,
+    //   and doesn't conceptually represent the state of our component
+    const currProps = _.omit(component.props, WIDGET_PROP_BLACKLIST);
+    const nextProps = _.extend(currProps, newProps);
+    component.props.onChange(nextProps, callback);
+};
+
+/**
+ * Helper function for changing a single prop
+ */
+const _changeSingle = function (component, propName: string, value, callback) {
+    if (value === undefined) {
+        // If called with a single prop name, return a lambda to change
+        // a single prop on the current object
+        return _.partial(_changeSingle, component, propName);
+    }
+    // If called with two values, change a single prop of the
+    // current object
+    const newProps = {};
+    newProps[propName] = value;
+    _changeMultiple(component, newProps, callback);
+};
+
+/**
+ * this.change()
+ *
+ * Can be called as follows:
+ * this.change(newProps, callback);
+ *
+ * this.change(propName, propValue, callback);
+ *
+ * this.change(propName) -> returns a lambda that takes a prop value to
+ * set and a callback to call after having set that value.
+ */
+// TODO(WEB-1727): use proper flow syntax for overloaded functions
+export const change: ChangeFn = function (
+    newPropsOrSinglePropName,
+    propValue,
+    callback,
+) {
+    if (_.isObject(newPropsOrSinglePropName) && callback === undefined) {
+        // Called with an object of multiple props to change
+        callback = propValue;
+        return _changeMultiple(
+            this,
+            newPropsOrSinglePropName, // object newProps
+            callback,
+        );
+    }
+    if (typeof newPropsOrSinglePropName === "string") {
+        // Called with a string propName of a single prop to change
+        return _changeSingle(
+            this,
+            newPropsOrSinglePropName, // string propName
+            propValue,
+            callback,
+        );
+    }
+    throw new PerseusError(
+        "Invalid types sent to this.change(): " +
+            _.toArray(arguments).join() +
+            "\n" +
+            USAGE,
+        Errors.Internal,
+    );
+};
+
+export const propTypes = {
+    onChange: PropTypes.func.isRequired,
+};
+
+export type ChangeableProps = {|
+    onChange: (
+        values: {[string]: any, ...},
+        callback?: ?() => mixed,
+        silent?: boolean,
+    ) => mixed,
+|};

package/src/mixins/editor-jsonify.jsx

@@ -0,0 +1,13 @@
+// @flow
+import _ from "underscore";
+
+import WIDGET_PROP_BLACKLIST from "./widget-prop-blacklist.js";
+
+const EditorJsonify = {
+    serialize: function (): $FlowFixMe {
+        // Omit props that get passed to all widgets
+        return _.omit(this.props, WIDGET_PROP_BLACKLIST);
+    },
+};
+
+export default EditorJsonify;

package/src/mixins/provide-keypad.jsx

@@ -0,0 +1,129 @@
+// @flow
+/**
+ * A mixin that renders a custom software keypad in additional to the base
+ * component. The base component will receive blur events when the keypad is
+ * dismissed and can access the keypad element itself so as to manage its
+ * activation and dismissal.
+ *
+ * TODO(charlie): This would make a nicer higher-order component, except that
+ * we need to expose methods on the base component (i.e., `ItemRenderer`). When
+ * `ItemRenderer` and friends are written as ES6 Classes, we can have them
+ * extend a `ProvideKeypad` component instead of using this mixin.
+ */
+
+import {Keypad} from "@khanacademy/math-input";
+import PropTypes from "prop-types";
+import * as React from "react";
+import ReactDOM from "react-dom";
+
+export type KeypadProps = {|
+    // An Aphrodite style object, to be applied to the keypad container.
+    // Note that, given our awkward structure of injecting the keypad, this
+    // style won't be applied or updated dynamically. Rather, it will only
+    // be applied in `componentDidMount`.
+    keypadStyle?: any,
+|};
+
+export type KeypadApiOptions = {|
+    customKeypad: boolean,
+    // eslint-disable-next-line flowtype/no-weak-types
+    nativeKeypadProxy: Function,
+|};
+
+// NOTE: This is not a real component.  It's a collection of methods used to
+// create and manage a Keypad instances.
+// TODO(LP-10789): replace this with a React Context object to pass information
+// between Perseus and the Keypad.
+const ProvideKeypad = {
+    propTypes: {
+        apiOptions: (PropTypes.shape({
+            customKeypad: PropTypes.bool,
+            nativeKeypadProxy: PropTypes.func,
+        }): React$PropType$Primitive<{
+            customKeypad?: boolean,
+            nativeKeypadProxy?: (...a: $ReadOnlyArray<any>) => mixed,
+            ...
+        }>),
+        // An Aphrodite style object, to be applied to the keypad container.
+        // Note that, given our awkward structure of injecting the keypad, this
+        // style won't be applied or updated dynamically. Rather, it will only
+        // be applied in `componentDidMount`.
+        keypadStyle: PropTypes.any,
+    },
+
+    getInitialState(): {|keypadElement: any | null|} {
+        // $FlowFixMe[object-this-reference]
+        const _this = this;
+        let keypadElement = null;
+        if (
+            _this.props.apiOptions &&
+            _this.props.apiOptions.customKeypad &&
+            _this.props.apiOptions.nativeKeypadProxy
+        ) {
+            keypadElement = _this.props.apiOptions.nativeKeypadProxy(
+                () => _this.blur && _this.blur(),
+            );
+        }
+        return {keypadElement};
+    },
+
+    componentDidMount() {
+        // $FlowFixMe[object-this-reference]
+        const _this = this;
+        if (
+            _this.props.apiOptions &&
+            _this.props.apiOptions.customKeypad &&
+            !_this.props.apiOptions.nativeKeypadProxy
+        ) {
+            // TODO(charlie): Render this and the wrapped component in the same
+            // React tree. We may also want to add this keypad asynchronously
+            // or on-demand in the future.
+            _this._keypadContainer = document.createElement("div");
+            document.body?.appendChild(_this._keypadContainer);
+
+            // TODO(LP-11406): Replace with React Portal
+            // eslint-disable-next-line no-restricted-syntax
+            ReactDOM.render(
+                <Keypad
+                    onElementMounted={(element) => {
+                        // NOTE(kevinb): The reason why this setState works is
+                        // b/c we're calling it manually from item-renderer.jsx
+                        // and we're manually setting the 'this' by using 'call'
+                        _this.setState({
+                            keypadElement: element,
+                        });
+                    }}
+                    onDismiss={() => {
+                        _this.blur && _this.blur();
+                    }}
+                    style={_this.props.keypadStyle}
+                />,
+                _this._keypadContainer,
+            );
+        }
+    },
+
+    componentWillUnmount() {
+        // $FlowFixMe[object-this-reference]
+        const _this = this;
+        if (_this._keypadContainer) {
+            ReactDOM.unmountComponentAtNode(_this._keypadContainer);
+            if (_this._keypadContainer.parentNode) {
+                // Note ChildNode.remove() isn't available in older Android
+                // webviews.
+                _this._keypadContainer.parentNode.removeChild(
+                    _this._keypadContainer,
+                );
+            }
+            _this._keypadContainer = null;
+        }
+    },
+
+    keypadElement(): any {
+        // $FlowFixMe[object-this-reference]
+        const _this = this;
+        return _this.state.keypadElement;
+    },
+};
+
+export default ProvideKeypad;

package/src/mixins/widget-jsonify-deprecated.jsx

@@ -0,0 +1,23 @@
+// @flow
+/* Free implementation of getUserInput. This should be used sparingly, since it
+ * just returns all the widget's props rather than picking out those which were
+ * input by the user.
+ */
+import _ from "underscore";
+
+import WIDGET_PROP_BLACKLIST from "./widget-prop-blacklist.js";
+
+const WidgetJsonifyDeprecated = {
+    getUserInput: function (): $FlowFixMe {
+        // Omit props that get passed to all widgets
+        return _.omit(this.props, WIDGET_PROP_BLACKLIST);
+    },
+
+    // Static version of `WidgetJsonifyDeprecated.getUserInput`
+    getUserInputFromProps: function (props: $FlowFixMe): $FlowFixMe {
+        // Omit props that get passed to all widgets
+        return _.omit(props, WIDGET_PROP_BLACKLIST);
+    },
+};
+
+export default WidgetJsonifyDeprecated;

package/src/mixins/widget-prop-blacklist.js

@@ -0,0 +1,36 @@
+// @flow
+/**
+ * These are things that widgets should exclude when serializing themselves.
+ *
+ * The use of this list needs to die. Basically, there are codepaths that
+ * blindly serialize the "props" of a widget so that it can pass around its
+ * info. Unfortunately, props aren't guaranteed to be serializable, and
+ * automatically serializing schemaless list of attributes causes issues (e.g.
+ * circular JSON structures sometimes).
+ *
+ * This blacklists things that we know don't need to be serialized.
+ */
+export default [
+    // standard props "added" by react
+    // (technically the renderer still adds them)
+    "key",
+    "ref",
+    // added by src/renderer.jsx
+    "containerSizeClass",
+    "widgetId",
+    "onChange",
+    "problemNum",
+    "apiOptions",
+    "questionCompleted",
+    "findWidgets",
+    // added by src/editor.jsx, for widgets removing themselves
+    // this is soooo not the right place for this, but alas.
+    "onRemove",
+    // also added by src/editor.jsx
+    "id",
+    // Callbacks and items for interaction handling
+    "onBlur",
+    "onFocus",
+    "trackInteraction",
+    "keypadElement",
+];

package/src/multi-items/__stories__/multi-renderer.stories.js

@@ -0,0 +1,88 @@
+// @flow
+
+import {View} from "@khanacademy/wonder-blocks-core";
+import * as i18n from "@khanacademy/wonder-blocks-i18n";
+import {HeadingSmall} from "@khanacademy/wonder-blocks-typography";
+import {StyleSheet} from "aphrodite";
+import * as React from "react";
+
+import {MultiItemRendererWithDebugUI} from "../../../../../testing/multi-item-renderer-with-debug-ui.jsx";
+import {question1} from "../__testdata__/multi-renderer_testdata.js";
+
+type StoryArgs = {||};
+
+type Story = {|
+    title: string,
+|};
+
+export const SingleItem = (args: StoryArgs): React.Node => {
+    const item = {
+        _multi: {
+            // $FlowFixMe[not-an-object]
+            ...question1._multi,
+            blurb: {
+                // $FlowFixMe[not-an-object]
+                // $FlowFixMe[prop-missing]
+                ...question1._multi.blurb,
+                content:
+                    "This is a short snippet to help you understand the context of the question. We call it the 'blurb'.",
+            },
+        },
+    };
+    return (
+        <MultiItemRendererWithDebugUI simpleItem={item}>
+            {({renderers}) => {
+                const {blurb, question, hints} = renderers;
+                return (
+                    <View>
+                        <View style={styles.section}>
+                            <HeadingSmall style={styles.heading}>
+                                {i18n.doNotTranslate("Blurb")}
+                            </HeadingSmall>
+                            {blurb}
+                        </View>
+                        <View style={styles.section}>
+                            <HeadingSmall style={styles.heading}>
+                                {i18n.doNotTranslate("Question")}
+                            </HeadingSmall>
+                            {question}
+                        </View>
+                        <View style={styles.section}>
+                            <HeadingSmall style={styles.heading}>
+                                {i18n.doNotTranslate("Hints")}
+                            </HeadingSmall>
+                            <View style={styles.hints}>
+                                {
+                                    // $FlowFixMe[prop-missing]
+                                    hints?.firstN(2)
+                                }
+                            </View>
+                        </View>
+                    </View>
+                );
+            }}
+        </MultiItemRendererWithDebugUI>
+    );
+};
+
+const styles = StyleSheet.create({
+    section: {
+        backgroundColor: "#F5F5F5",
+        padding: "5px",
+        borderWidth: "1px",
+        marginTop: "5px",
+        marginBottom: "5px",
+    },
+    heading: {
+        backgroundColor: "#A9A9A9",
+        margin: "-5px",
+        padding: "5px",
+    },
+    hints: {
+        marginLeft: "50px",
+    },
+});
+
+export default ({
+    title: "Perseus/Renderers/Multi Renderer",
+}: Story);

package/src/multi-items/__testdata__/multi-renderer_testdata.js

@@ -0,0 +1,174 @@
+// @flow
+
+import shapes from "../shapes.js";
+
+import type {Item} from "../item-types.js";
+import type {Shape} from "../shape-types.js";
+
+export const simpleQuestionShape: Shape = shapes.shape({
+    blurb: shapes.content,
+    question: shapes.content,
+    hints: shapes.hints,
+});
+
+// Shape: simpleQuestionShape
+export const question1: Item = {
+    _multi: {
+        blurb: {
+            __type: "content",
+            content: "",
+            images: {},
+            widgets: {},
+        },
+        hints: [
+            {
+                __type: "hint",
+                content:
+                    "If two triangles are congruent, then they have the same side lengths and angle measures.",
+                images: {},
+                replace: false,
+                widgets: {},
+            },
+            {
+                __type: "hint",
+                content:
+                    "A triangle congruent to triangle $ABC$ must also have side lengths of $12$, $14$ and $20$.",
+                images: {},
+                replace: false,
+                widgets: {},
+            },
+            {
+                __type: "hint",
+                content:
+                    "The following triangle is congruent to triangle $ABC$:\n\n* A triangle with side lengths of $12$, $14$, and $20$",
+                images: {},
+                replace: false,
+                widgets: {},
+            },
+        ],
+        question: {
+            __type: "content",
+            content:
+                "Triangle $ABC$ has side lengths of $12$, $14$, and $20$. Which of the following triangles is congruent to triangle $ABC$ ?\n\n[[☃ radio 1]]\n\nEnter the number 3 into this field: [[☃ input-number 1]]",
+            widgets: {
+                "radio 1": {
+                    alignment: "default",
+                    graded: true,
+                    options: {
+                        choices: [
+                            {
+                                clue: "Congruent triangles have the same side lengths.",
+                                content:
+                                    "A triangle with side lengths of $3$, $4$, and $5$",
+                                correct: false,
+                            },
+                            {
+                                clue: "Congruent triangles have the same side lengths.\n\nThis choice is similar to triangle $ABC$.",
+                                content:
+                                    "A triangle with side lengths of $6$, $7$, and $10$",
+                                correct: false,
+                            },
+                            {
+                                clue: "Congruent triangles have the same side lengths.",
+                                content:
+                                    "A triangle with side lengths of $10$, $12$, and $18$",
+                                correct: false,
+                                isNoneOfTheAbove: false,
+                            },
+                            {
+                                clue: "Congruent triangles have the same side lengths.",
+                                content:
+                                    "A triangle with side lengths of $12$, $14$, and $20$",
+                                correct: true,
+                                isNoneOfTheAbove: false,
+                            },
+                            {
+                                clue: "Congruent triangles have the same side lengths.\n\nThis choice is similar to triangle $ABC$.",
+                                content:
+                                    "A triangle with side lengths of $24$, $28$, and $40$",
+                                correct: false,
+                                isNoneOfTheAbove: false,
+                            },
+                        ],
+                        countChoices: false,
+                        deselectEnabled: false,
+                        displayCount: null,
+                        hasNoneOfTheAbove: false,
+                        multipleSelect: false,
+                        randomize: false,
+                    },
+                    static: false,
+                    type: "radio",
+                    version: {
+                        major: 1,
+                        minor: 0,
+                    },
+                },
+                "input-number 1": {
+                    type: "input-number",
+                    graded: true,
+                    options: {
+                        answerType: "number",
+                        value: "-42",
+                        simplify: "required",
+                        size: "normal",
+                        inexact: false,
+                        maxError: 0.1,
+                    },
+                },
+            },
+        },
+    },
+};
+
+const mockWidgetConfig = {
+    graded: true,
+    version: {major: 0, minor: 0},
+    static: false,
+    type: "mock-widget",
+    options: {static: false, smiling: true},
+    alignment: "default",
+};
+
+// Shape: simpleQuestionShape
+export const mockedQuestion1: Item = {
+    _multi: {
+        blurb: {
+            __type: "content",
+            content: "Here's a blurb [[☃ mock-widget 1]]",
+            images: {},
+            widgets: {
+                "mock-widget 1": mockWidgetConfig,
+            },
+        },
+        hints: [
+            {
+                __type: "hint",
+                content: "Hint #1 [[☃ mock-widget 2]]",
+                images: {},
+                replace: false,
+                widgets: {
+                    "mock-widget 2": mockWidgetConfig,
+                },
+            },
+            {
+                __type: "hint",
+                content: "Hint #1 [[☃ mock-widget 3]]",
+                images: {},
+                replace: false,
+                widgets: {
+                    "mock-widget 3": mockWidgetConfig,
+                },
+            },
+        ],
+        question: {
+            __type: "content",
+            content:
+                "What is the answer to this?\n\n[[☃ mock-widget 4]]\n\n[[☃ mock-widget 5]]",
+            widgets: {
+                "mock-widget 4": mockWidgetConfig,
+                "mock-widget 5": mockWidgetConfig,
+            },
+        },
+    },
+};