@khanacademy/perseus 0.0.1 → 0.2.1

package/src/index.js

@@ -1,4 +1,151 @@
 // @flow
-import * as i18n from "@khanacademy/wonder-blocks-i18n";
+/**
+ * Main entry point
+ */
 
-export const foo = (): string => i18n._("foo");
+import version from "./version.js";
+
+export {default as init} from "./init.js";
+
+export {ApiOptions, ClassNames} from "./perseus-api.jsx";
+
+export const apiVersion = version.apiVersion;
+export const itemDataVersion = version.itemDataVersion;
+export {default as itemVersion} from "./item-version.js";
+
+/**
+ * Renderers
+ */
+export {default as ArticleRenderer} from "./article-renderer.jsx";
+export {default as ItemRenderer} from "./item-renderer.jsx";
+export {default as ServerItemRenderer} from "./server-item-renderer.jsx";
+export {default as HintsRenderer} from "./hints-renderer.jsx";
+export {default as HintRenderer} from "./hint-renderer.jsx";
+export {default as Renderer} from "./renderer.jsx";
+
+/**
+ * Widgets
+ */
+export * as Widgets from "./widgets.js";
+export {default as widgets} from "./all-widgets.js";
+export {Expression} from "./widgets/expression.jsx";
+export {default as InputNumber} from "./widgets/input-number.jsx";
+export {default as NumericInput} from "./widgets/numeric-input.jsx";
+export {default as Radio} from "./widgets/radio.jsx";
+export {default as BaseRadio} from "./widgets/radio/base-radio.jsx";
+export {default as Categorizer} from "./widgets/categorizer.jsx";
+export {default as InteractiveGraphWidget} from "./widgets/interactive-graph.jsx";
+export {default as TransformerWidget} from "./widgets/transformer.jsx";
+export {default as MatrixWidget} from "./widgets/matrix.jsx";
+export {default as TableWidget} from "./widgets/table.jsx";
+export {default as PlotterWidget} from "./widgets/plotter.jsx";
+export {default as GrapherWidget} from "./widgets/grapher.jsx";
+
+export {default as ArrowPicker} from "./widgets/interaction/arrow-picker.jsx";
+export {default as ColorPicker} from "./widgets/interaction/color-picker.jsx";
+export {default as DashPicker} from "./widgets/interaction/dash-picker.jsx";
+export {default as ElementContainer} from "./widgets/interaction/element-container.jsx";
+export * as GrapherUtil from "./widgets/grapher/util.jsx";
+
+/**
+ * Misc
+ */
+export * as components from "./components.js";
+export * as constants from "./components/constants.js";
+// TODO(FEI-4504): Replace globalStyles with wonder-blocks where possible
+export * as globalStyles from "./styles/global-styles.js";
+// TODO(FEI-4504): Replace globalStyles with wonder-blocks where possible
+export * as globalConstants from "./styles/global-constants.js";
+export * as icons from "./icon-paths.js";
+export * as Dependencies from "./dependencies.js";
+export {Errors, Log} from "./logging/log.js";
+export {PerseusError} from "./perseus-error.js";
+export {default as JiptParagraphs} from "./jipt-paragraphs.js";
+export {default as KeypadContext} from "./keypad-context.js";
+export {default as KhanMath} from "./util/math.js";
+export {default as LoadingContext} from "./loading-context.js";
+export {default as mediaQueries} from "./styles/media-queries.js";
+export {default as PerseusMarkdown} from "./perseus-markdown.jsx";
+export {traverse} from "./traversal.jsx";
+export {isItemRenderableByVersion} from "./renderability.jsx";
+export {violatingWidgets} from "./a11y.js";
+export {interactiveSizes} from "./styles/constants.js";
+export {displaySigFigs} from "./sigfigs.jsx";
+
+/**
+ * Util
+ */
+export {default as Util} from "./util.js";
+export {default as KhanColors} from "./util/colors.js";
+export {default as preprocessTex} from "./util/katex-preprocess.js";
+export {registerAllWidgetsForTesting} from "./util/register-all-widgets-for-testing.js";
+export * as SizingUtils from "./util/sizing-utils.js";
+
+/**
+ * Mixins
+ */
+export * as Changeable from "./mixins/changeable.jsx";
+export {default as EditorJsonify} from "./mixins/editor-jsonify.jsx";
+export {default as WidgetJsonifyDeprecated} from "./mixins/widget-jsonify-deprecated.jsx";
+export {default as WIDGET_PROP_BLACKLIST} from "./mixins/widget-prop-blacklist.js";
+
+/**
+ * Types
+ */
+export type {PerseusOptions} from "./init.js";
+export type {ILogger, LogErrorOptions, ErrorKind} from "./logging/log.js";
+export type {ServerItemRenderer as ServerItemRendererComponent} from "./server-item-renderer.jsx";
+export type {
+    Alignment,
+    APIOptions,
+    APIOptionsWithDefaults,
+    ChangeHandler,
+    DeviceType,
+    DomInsertCheckFn,
+    EditorMode,
+    Hint,
+    ImageDict,
+    ImageUploader,
+    JiptLabelStore,
+    JiptRenderer,
+    KEScore,
+    LinterContextProps,
+    PerseusDependencies,
+    PerseusScore,
+    RendererInterface,
+    Version,
+    WidgetDict,
+    WidgetExports,
+    WidgetInfo,
+} from "./types.js";
+export type {InputNumberWidget, PerseusRenderer} from "./perseus-types.js";
+export type {Format} from "./util/math.js";
+export type {Coord} from "./interactive2/types.js";
+export type {MarkerType} from "./widgets/label-image/types.js";
+
+/**
+ * Multi-items
+ */
+export {default as MultiItems} from "./multi-items.js";
+export {buildEmptyItemTreeForShape, itemToTree} from "./multi-items/items.js";
+export {default as shapes} from "./multi-items/shapes.js";
+export {buildMapper} from "./multi-items/trees.js";
+
+export type {
+    ContentNode,
+    HintNode,
+    Item,
+    ItemTree,
+    ItemObjectNode,
+    ItemArrayNode,
+    TagsNode,
+} from "./multi-items/item-types.js";
+export type {
+    Shape,
+    ArrayShape,
+    ObjectShape,
+    ContentShape,
+    HintShape,
+    TagsShape,
+} from "./multi-items/shape-types.js";
+export type {Path} from "./multi-items/trees.js";

package/src/init.js

@@ -0,0 +1,49 @@
+// @flow
+import basicWidgets from "./basic-widgets.js";
+import extraWidgets from "./extra-widgets.js";
+import * as Widgets from "./widgets.js";
+
+declare var MathJax: any;
+
+export type PerseusOptions = {|
+    skipMathJax: boolean,
+|};
+
+/**
+ * This should be called by all clients, specifying whether extra widgets are
+ * needed via `loadExtraWidgets`. It is idempotent, so it's not a problem to
+ * call it multiple times.
+ *
+ * skipMathJax:
+ *   If false/undefined, MathJax will be configured, and the
+ *   promise will wait for MathJax to load (if it hasn't already).
+ */
+const init = function (options: PerseusOptions): Promise<void> {
+    Widgets.registerWidgets(basicWidgets);
+    Widgets.registerWidgets(extraWidgets);
+
+    // Pass skipMathJax: true if MathJax is already loaded and configured.
+    const skipMathJax = options.skipMathJax;
+
+    if (skipMathJax) {
+        return Promise.resolve();
+    }
+
+    return new Promise((resolve, reject) => {
+        MathJax.Hub.Config({
+            messageStyle: "none",
+            skipStartupTypeset: "none",
+            "HTML-CSS": {
+                availableFonts: ["TeX"],
+                imageFont: null,
+                scale: 100,
+                showMathMenu: false,
+            },
+        });
+
+        MathJax.Hub.Configured();
+        MathJax.Hub.Queue(resolve);
+    });
+};
+
+export default init;

package/src/interaction-tracker.js

@@ -0,0 +1,60 @@
+// @flow
+
+/**
+ * This alternate version of `.track` does nothing as an optimization.
+ */
+function _noop() {}
+
+/**
+ * Wrapper for the trackInteraction apiOption.
+ */
+class InteractionTracker {
+    _tracked: boolean;
+    setting: string;
+    track: (extraData?: any) => void;
+    // eslint-disable-next-line flowtype/no-weak-types
+    trackApi: Function;
+    widgetID: string;
+    widgetType: string;
+
+    constructor(
+        // eslint-disable-next-line flowtype/no-weak-types
+        trackApi: Function, // original apiOptions.trackInteraction
+        widgetType: string,
+        widgetID: string,
+        setting: "" | "all", // "" means track once
+    ) {
+        if (!trackApi) {
+            this.track = _noop;
+        } else {
+            this._tracked = false;
+            this.trackApi = trackApi;
+            this.widgetType = widgetType;
+            this.widgetID = widgetID;
+            this.setting = setting;
+            this.track = this._track;
+        }
+    }
+
+    /**
+     * Function that actually calls the API to mark the interaction. This is
+     * private. The public version is just `.track` and is bound to this object
+     * for easy use in other context.
+     *
+     * @param extraData Any extra data to track about the event.
+     * @private
+     */
+    _track: (extraData: mixed) => void = (extraData: mixed) => {
+        if (this._tracked && !this.setting) {
+            return;
+        }
+        this._tracked = true;
+        this.trackApi({
+            type: this.widgetType,
+            id: this.widgetID,
+            ...extraData,
+        });
+    };
+}
+
+export default InteractionTracker;

package/src/interactive2/__tests__/movable-mock.js

@@ -0,0 +1,48 @@
+// @flow
+/**
+ * Create a Mocked Movable
+ */
+
+import _ from "underscore";
+
+import Movable from "../movable.js";
+
+const createMock = function (): $FlowFixMe {
+    // $FlowFixMe[invalid-constructor]
+    const movable = new Movable(null, {
+        mouseTarget: null,
+    });
+    // $FlowFixMe[prop-missing]
+    movable.modify = function (options) {
+        // $FlowFixMe[prop-missing]
+        Movable.prototype.modify.call(movable, _.omit(options, "mouseTarget"));
+    };
+    _.each(
+        ["onMoveStart", "onMove", "onMoveEnd", "onClick"],
+        function (eventName) {
+            movable[eventName] = function (coord, prevCoord) {
+                this._fireEvent(this.state[eventName], coord, prevCoord);
+            };
+        },
+    );
+    // $FlowFixMe[prop-missing]
+    movable.move = function () {
+        const args = _.toArray(arguments);
+        const startPoint = _.first(args);
+        // TODO(jack): Move these into onMoveStart, onMove, and onMoveEnd
+        movable.state.isMouseOver = true;
+        movable.state.isHovering = true;
+        movable.onMoveStart(startPoint, startPoint);
+        _.each(_.rest(args), function (point, i) {
+            movable.state.isDragging = true;
+            movable.onMove(point, args[i]);
+        });
+        movable.onMoveEnd(_.last(args), startPoint);
+        movable.state.dragging = false;
+        movable.state.isMouseOver = false;
+        movable.state.isHovering = false;
+    };
+    return movable;
+};
+
+export default createMock;

package/src/interactive2/__tests__/movable-point_test.js

@@ -0,0 +1,146 @@
+// @flow
+// System requires
+import _ from "underscore";
+
+// Interactive2 requires
+import MovablePoint from "../movable-point.jsx";
+
+import _createMockMovable from "./movable-mock.js";
+
+// Create a testable MovablePoint with a mocked out Movable
+const createPoint = function (options) {
+    const movable = _createMockMovable();
+    // $FlowFixMe[invalid-constructor]
+    const point = new MovablePoint(
+        null,
+        movable,
+        _.extend(options, {
+            static: true,
+            draw: null,
+            showHairlines: () => {},
+            hideHairlines: () => {},
+
+            // Mock visibleShape which is only added when a movable point is used
+            // with a shape.
+            // TODO(kevinb): update MovablePoint to require a visibleShape
+            visibleShape: {
+                wrapper: {},
+            },
+        }),
+    );
+    return {
+        movable: movable,
+        point: point,
+
+        /**
+         * Convenience function to fill in the no-drawing defaults
+         * for a modify call
+         */
+        modify: function (options) {
+            point.modify(
+                _.extend(
+                    {
+                        static: true,
+                        draw: null,
+                    },
+                    options,
+                ),
+            );
+        },
+    };
+};
+
+describe("MovablePoint", function () {
+    describe("add", function () {
+        it("should snap to the grid when a snap is specified", function () {
+            const point = createPoint({
+                coord: [1.1, 1.1],
+                // $FlowFixMe[prop-missing]
+                constraints: MovablePoint.constraints.snap([1, 1]),
+            }).point;
+
+            expect(point.coord()).toEqual([1, 1]);
+        });
+    });
+
+    describe("modify", function () {
+        it("should reset the point's size", function () {
+            const defaultPointSize = createPoint({
+                coord: [1, 1], // uses the default pointSize
+            }).point.pointSize();
+
+            // verify that 10 was not, in fact, the default, or we should
+            // change 10 to something else
+            expect(defaultPointSize).not.toEqual(10);
+
+            const handle = createPoint({
+                coord: [0, 0],
+                pointSize: 10, // arbitrary size larger than the default
+            });
+            expect(handle.point.pointSize()).toBe(10);
+
+            handle.modify({
+                coord: [0, 0], // reset to the default pointSize
+            });
+            expect(handle.point.pointSize()).toBe(defaultPointSize);
+        });
+
+        it("should allow you to change the point's size", function () {
+            const handle = createPoint({
+                coord: [0, 0],
+                pointSize: 5,
+            });
+            expect(handle.point.pointSize()).toBe(5);
+
+            handle.modify({
+                pointSize: 6,
+            });
+            expect(handle.point.pointSize()).toBe(6);
+        });
+    });
+
+    describe("onMove", function () {
+        it("should be called when movable is moved", function () {
+            let movedToCoord;
+            const handle = createPoint({
+                coord: [1, 2],
+                onMove: function (newCoord, prevCoord) {
+                    expect(prevCoord).toEqual([1, 2]);
+                    movedToCoord = newCoord;
+                },
+            });
+            // move mouse from [2.5, 4] to [3, 4]
+            handle.movable.move([2.5, 4], [3, 4]);
+            expect(movedToCoord).toEqual([3, 4]);
+            expect(handle.point.coord()).toEqual([3, 4]);
+        });
+    });
+
+    describe("onClick", function () {
+        it("should be called if the point didn't move", function () {
+            let clickCoord;
+            const handle = createPoint({
+                coord: [1, 2],
+                onClick: function (coord) {
+                    clickCoord = coord;
+                },
+            });
+            // move mouse from [1, 2] to [1, 2]
+            handle.movable.move([1, 2], [1, 2]);
+            expect(clickCoord).toEqual([1, 2]);
+            expect(handle.point.coord()).toEqual([1, 2]);
+        });
+
+        it("should not be called if the point did move", function () {
+            const handle = createPoint({
+                coord: [1, 2],
+                onClick: function (coord) {
+                    expect(false).toBeTruthy();
+                },
+            });
+            // move mouse from [1, 2] to [3, 4]
+            handle.movable.move([1, 2], [3, 4]);
+            expect(handle.point.coord()).toEqual([3, 4]);
+        });
+    });
+});

package/src/interactive2/interactive-util.js

@@ -0,0 +1,152 @@
+// @flow
+/**
+ * Utility functions for writing Interactive2 movablethings
+ */
+
+import _ from "underscore";
+
+import {Errors} from "../logging/log.js";
+import {PerseusError} from "../perseus-error.js";
+
+import MovableHelperMethods from "./movable-helper-methods.js";
+
+/**
+ * Compute the correct vendor-prefixed `transform`.
+ */
+let prefixedTransform = null;
+function computePrefixedTransform(): ?string {
+    // Temporary element for testing prefix validity
+    const el = document.createElement("div");
+
+    const prefixes = [
+        "transform",
+        "msTransform",
+        "MozTransform",
+        "WebkitTransform",
+        "OTransform",
+    ];
+    let correctPrefix = null;
+    _.each(prefixes, function (prefix) {
+        if (typeof el.style[prefix] !== "undefined") {
+            correctPrefix = prefix;
+        }
+    });
+
+    return correctPrefix;
+}
+
+/**
+ * Compute whether the browser can use 3d transforms by trying to use the
+ * translateZ transformation.
+ */
+let canUse3dTransform = null;
+function computeCanUse3dTransform(): boolean {
+    const el = document.createElement("div");
+
+    const prefix = InteractiveUtil.getPrefixedTransform();
+
+    // Prefix could be null.
+    // $FlowFixMe[incompatible-type]
+    el.style[prefix] = "translateZ(0px)";
+    // $FlowFixMe[incompatible-type]
+    return !!el.style[prefix];
+}
+
+const InteractiveUtil = {
+    assert: function (isTrue: boolean, message?: string) {
+        if (!isTrue) {
+            throw new PerseusError(
+                "Assertion Error" + (message ? ": " + message : ""),
+                Errors.Internal,
+            );
+        }
+    },
+
+    /**
+     * Create getters for this.state, based on the default state, `defaults`
+     */
+    createGettersFor: function (Class: $FlowFixMe, defaults: {...}) {
+        _.each(_.keys(defaults), function (key) {
+            if (Class.prototype[key] === undefined) {
+                Class.prototype[key] = function () {
+                    return this.state[key];
+                };
+            }
+        });
+    },
+
+    /**
+     * Add MovableHelperMethods methods to a MovableThing class
+     */
+    addMovableHelperMethodsTo: function (Class: $FlowFixMe) {
+        _.each(MovableHelperMethods, function (methodFunc, methodName) {
+            if (Class.prototype[methodName] === undefined) {
+                Class.prototype[methodName] = methodFunc;
+            }
+        });
+    },
+
+    /**
+     * Turn a function or an array of functions into an array of functions
+     */
+    arrayify: function (
+        funcOrArray:
+            | ((...args: $ReadOnlyArray<mixed>) => mixed)
+            | $ReadOnlyArray<mixed>,
+    ): $ReadOnlyArray<mixed> {
+        if (funcOrArray == null) {
+            return [];
+        }
+        if (_.isArray(funcOrArray)) {
+            return _.filter(_.flatten(funcOrArray), _.identity);
+        }
+        return [funcOrArray];
+    },
+
+    /**
+     * Convert all function-or-array arguments to arrays of functions
+     */
+    normalizeOptions: function (
+        arrayOptionNames: $ReadOnlyArray<string>,
+        options: {...},
+    ): {...} {
+        // TODO(jack): Having to clone here is annoying; this
+        // function should really just modify this.state in place
+        // (and maybe be a function on MovableHelperMethods to get access
+        // to this.state), which would also be nicer because we could
+        // normalizeOptions once in this.modify
+        const result = _.clone(options);
+        _.each(arrayOptionNames, function (eventName) {
+            const funcOrArray = options[eventName];
+            // Only propagate values which were set; not present values
+            // shouldn't be added to options because we'd like them to
+            // fall through to defaults
+            if (funcOrArray !== undefined) {
+                const funcArray = InteractiveUtil.arrayify(funcOrArray);
+                result[eventName] = funcArray;
+            }
+        });
+        return result;
+    },
+
+    /**
+     * Get the correct vendor-prefixed `transform`.
+     */
+    getPrefixedTransform: function (): ?string {
+        // Cache result to avoid re-computation
+        prefixedTransform = prefixedTransform || computePrefixedTransform();
+        return prefixedTransform;
+    },
+
+    /**
+     * Get whether the browser can use 3d transforms.
+     */
+    getCanUse3dTransform: function (): boolean {
+        if (canUse3dTransform == null) {
+            canUse3dTransform = computeCanUse3dTransform();
+        }
+        return canUse3dTransform;
+    },
+};
+
+export default InteractiveUtil;