@khanacademy/perseus 2.1.0 → 4.0.0

package/src/loading-context.js

@@ -1,20 +0,0 @@
-// @flow
-/**
- * A React context for signaling when all of the components in a Perseus
- * renderer is fully rendered.  This means that all images and math have
- * finished loading/rendering.
- *
- * Currently only used by ServerItemRender to indicate when the question
- * renderer is fully rendered.
- */
-import * as React from "react";
-
-type Context = {onRendered: (isRendered: boolean) => void, ...};
-
-const defaultContext: Context = {
-    onRendered: (isRendered: boolean) => {},
-};
-
-const context: React.Context<Context> = React.createContext(defaultContext);
-
-export default context;

package/src/logging/log.js

@@ -1,107 +0,0 @@
-// @flow
-
-import {getDependencies} from "../dependencies.js";
-
-import type {Metadata} from "@khanacademy/wonder-stuff-core";
-
-// TODO(LP-11481): Change the primary API we use for logging in Perseus to use
-// getDependencies() internally... simplify usage to just using a "singleton"
-// which get's the injected logger.
-
-/**
- * @typedef {Object} Errors utility for referencing the Perseus error taxonomy.
- */
-export const Errors = Object.freeze({
-    /**
-     * @property {ErrorKind} Unknown The kind of error is not known.
-     */
-    Unknown: "Unknown",
-    /**
-     * @property {ErrorKind} Internal The error is internal to the executing code.
-     */
-    Internal: "Internal",
-    /**
-     * @property {ErrorKind} InvalidInput There was a problem with the provided
-     * input, such as the wrong format or a null value.
-     */
-    InvalidInput: "InvalidInput",
-    /**
-     * @property {ErrorKind} NotAllowed There was a problem due to the state of
-     * the system not matching the requested operation or input. For example,
-     * trying to create a username that is valid, but is already taken by
-     * another user. Use {@link InvalidInput} instead when the input isn't
-     * valid regardless of the state of the system. Use {@link NotFound} when
-     * the failure is due to not being able to find a resource.
-     */
-    NotAllowed: "NotAllowed",
-    /**
-     * @property {ErrorKind} TransientService There was a problem when making a
-     * request to a service.
-     */
-    TransientService: "TransientService",
-    /**
-     * @property {ErrorKind} Service There was a non-transient problem when
-     * making a request to service.
-     */
-    Service: "Service",
-});
-
-/**
- * @type {ErrorKind} The kind of error being reported
- */
-export type ErrorKind = $Values<typeof Errors>;
-
-export type LogErrorOptions = {|
-    // The cause of the error.
-    cause?: ?Error,
-    // Extra metadata about the error that is safe and small enough to send to
-    // external log systems (think Sentry).
-    loggedMetadata?: ?Metadata,
-    // Extra metadata about the error. Any data included in this key is
-    // explicitly marked to _not_ be delivered to any configured logging
-    // systems.
-    metadata?: ?Metadata,
-|};
-
-/**
- * Provides logging infrastructure for Perseus
- */
-export interface ILogger {
-    // Logs a message
-    log(
-        // NOTE: Prefer including any data that varies in the `extra` parameter
-        // instead of including it in the message. This makes it easier for error
-        // logging platforms to group like errors together.
-        message: string,
-        extra?: ?Metadata,
-    ): void;
-
-    // Logs an error with a message
-    error(
-        // NOTE: Prefer including any data that varies in the `extra` parameter
-        // instead of including it in the message. This makes it easier for error
-        // logging platforms to group like errors together.
-        message: string,
-        kind: ErrorKind,
-        extra?: LogErrorOptions,
-    ): void;
-}
-
-export const Log: ILogger = {
-    // Logs a message
-    log: (message: string, extra?: ?Metadata) => {
-        getDependencies().Log.log(message, extra);
-    },
-
-    // Logs an error with a message
-    error: (
-        // NOTE: Prefer including any data that varies in the `extra` parameter
-        // instead of including it in the message. This makes it easier for error
-        // logging platforms to group like errors together.
-        message: string,
-        kind: ErrorKind,
-        extra?: LogErrorOptions,
-    ) => {
-        getDependencies().Log.error(message, kind, extra);
-    },
-};

package/src/logging/log_test.js

@@ -1,41 +0,0 @@
-// @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/__tests__/widget-prop-denylist_test.js

@@ -1,23 +0,0 @@
-// @flow
-
-import {removeDenylistProps} from "../widget-prop-denylist.js";
-
-describe("removeDenylistProps", () => {
-    it("removes props that are in denylist from input", () => {
-        // Arrange
-        const props = {
-            // These props are not on the denylist
-            foo: "bar",
-            gandalf: "awesome",
-            // These props are on the denylist
-            key: "f-sharp",
-            id: 42,
-        };
-
-        // Act
-        const result = removeDenylistProps(props);
-
-        // Assert
-        expect(result).toStrictEqual({foo: "bar", gandalf: "awesome"});
-    });
-});

package/src/mixins/changeable.jsx

@@ -1,115 +0,0 @@
-/* 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_DENYLIST from "./widget-prop-denylist.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_DENYLIST);
-    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

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

package/src/mixins/provide-keypad.jsx

@@ -1,131 +0,0 @@
-// @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";
-
-import reactRender from "../util/react-render.js";
-
-import type {CSSProperties} from "aphrodite";
-
-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?: CSSProperties,
-|};
-
-export type KeypadApiOptions = {|
-    customKeypad: boolean,
-    // eslint-disable-next-line ft-flow/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);
-
-            reactRender(
-                <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

@@ -1,23 +0,0 @@
-// @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_DENYLIST from "./widget-prop-denylist.js";
-
-const WidgetJsonifyDeprecated = {
-    getUserInput: function (): $FlowFixMe {
-        // Omit props that get passed to all widgets
-        return _.omit(this.props, WIDGET_PROP_DENYLIST);
-    },
-
-    // Static version of `WidgetJsonifyDeprecated.getUserInput`
-    getUserInputFromProps: function (props: $FlowFixMe): $FlowFixMe {
-        // Omit props that get passed to all widgets
-        return _.omit(props, WIDGET_PROP_DENYLIST);
-    },
-};
-
-export default WidgetJsonifyDeprecated;

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

@@ -1,49 +0,0 @@
-// @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 blocks things that we know don't need to be serialized.
- */
-
-const denylist = [
-    // 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",
-];
-
-export const removeDenylistProps = (props: Object): Object => {
-    const newProps = {...props};
-    for (const prop of denylist) {
-        if (prop in newProps) {
-            delete newProps[prop];
-        }
-    }
-    return newProps;
-};
-
-export default denylist;

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

@@ -1,88 +0,0 @@
-// @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);