@khanacademy/perseus 19.1.2 → 19.1.4

package/dist/widgets/unit.d.ts

@@ -58,6 +58,7 @@ declare const _default: Readonly<{
     name: string;
     displayName: string;
     getWidget?: (() => typeof OldUnitInput) | undefined;
+    widget: typeof OldUnitInput;
     accessible?: boolean | ((props: any) => boolean) | undefined;
     hidden?: boolean | undefined;
     version?: import("../types").Version | undefined;
@@ -72,6 +73,5 @@ declare const _default: Readonly<{
     propUpgrades?: {
         [key: string]: (arg1: any) => any;
     } | undefined;
-    widget: typeof OldUnitInput;
 }>;
 export default _default;

package/dist/widgets/video.d.ts

@@ -29,6 +29,7 @@ declare const _default: Readonly<{
     name: string;
     displayName: string;
     getWidget?: (() => typeof Video) | undefined;
+    widget: typeof Video;
     accessible?: boolean | ((props: any) => boolean) | undefined;
     hidden?: boolean | undefined;
     version?: import("../types").Version | undefined;
@@ -43,6 +44,5 @@ declare const _default: Readonly<{
     propUpgrades?: {
         [key: string]: (arg1: any) => any;
     } | undefined;
-    widget: typeof Video;
 }>;
 export default _default;

package/package.json

@@ -3,7 +3,7 @@
     "description": "Core Perseus API (includes renderers and widgets)",
     "author": "Khan Academy",
     "license": "MIT",
-    "version": "19.1.2",
+    "version": "19.1.4",
     "publishConfig": {
         "access": "public"
     },
@@ -24,7 +24,7 @@
     "dependencies": {
         "@khanacademy/kas": "^0.3.7",
         "@khanacademy/kmath": "^0.1.10",
-        "@khanacademy/math-input": "^17.0.1",
+        "@khanacademy/math-input": "^17.0.3",
         "@khanacademy/perseus-core": "1.4.1",
         "@khanacademy/perseus-linter": "^0.3.10",
         "@khanacademy/pure-markdown": "^0.2.13",

package/src/__tests__/init.test.ts

@@ -0,0 +1,10 @@
+import init from "../init";
+import {getWidget} from "../widgets";
+
+describe("init", () => {
+    it("should correctly replace the transformer widget", async () => {
+        await init({skipMathJax: true});
+
+        expect(getWidget("transformer")).not.toBeNull();
+    });
+});

package/src/init.ts

@@ -21,10 +21,7 @@ const init = function (options: PerseusOptions): Promise<undefined> {
     Widgets.registerWidgets(basicWidgets);
     Widgets.registerWidgets(extraWidgets);
 
-    // This section replaces widgets
-    // When it's time to replace the transformer widget
-    // uncomment this line
-    // Widgets.replaceWidget("transformer", "deprecated-standin");
+    Widgets.replaceWidget("transformer", "deprecated-standin");
 
     // Pass skipMathJax: true if MathJax is already loaded and configured.
     const skipMathJax = options.skipMathJax;

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

@@ -4,10 +4,11 @@
 
 import _ from "underscore";
 
+import {Graphie} from "../../util/graphie";
 import Movable from "../movable";
 
 const createMock = function (): any {
-    const movable = new Movable(null, {
+    const movable = new Movable(new Graphie(document.createElement("div")), {
         mouseTarget: null,
     });
     movable.modify = function (options: any) {

package/src/interactive2/__tests__/movable.test.ts

@@ -0,0 +1,157 @@
+/* eslint-disable testing-library/prefer-user-event */
+import {fireEvent} from "@testing-library/react";
+
+import {Graphie} from "../../util/graphie";
+import Movable from "../movable";
+
+// Yay for side-effect imports!
+// eslint-disable-next-line import/no-unassigned-import
+import "../../util/interactive";
+
+describe("Movable", () => {
+    it("should be constructable", () => {
+        const movable = new Movable(
+            new Graphie(document.createElement("div")),
+            {},
+        );
+
+        expect(movable).toBeDefined();
+    });
+
+    it("should have accessor properties", () => {
+        const movable = new Movable(
+            new Graphie(document.createElement("div")),
+            {},
+        );
+
+        expect(typeof movable.isHovering).toBe("function");
+        expect(typeof movable.cursor).toBe("function");
+        expect(typeof movable.added).toBe("function");
+        expect(typeof movable.isHovering).toBe("function");
+        expect(typeof movable.isMouseOver).toBe("function");
+        expect(typeof movable.isDragging).toBe("function");
+        expect(typeof movable.mouseTarget).toBe("function");
+    });
+
+    test("cloneState()", () => {
+        const movable = new Movable(
+            new Graphie(document.createElement("div")),
+            {},
+        );
+
+        expect(movable.cloneState()).toEqual(
+            expect.objectContaining({
+                id: expect.any(String),
+                add: [],
+                added: true,
+                cursor: null,
+                draw: [],
+                isDragging: false,
+                isHovering: false,
+                isMouseOver: false,
+                modify: [],
+                mouseTarget: null,
+                onClick: [],
+                onMove: [],
+                onMoveEnd: [],
+                onMoveStart: [],
+                remove: [],
+            }),
+        );
+    });
+
+    test("cloneState() should copy state", () => {
+        const movable = new Movable(
+            new Graphie(document.createElement("div")),
+            {},
+        );
+
+        expect(movable.cloneState()).not.toBe(movable.state);
+    });
+
+    test("modify() resets movable to initial state when no params given", () => {
+        const movable = new Movable(
+            new Graphie(document.createElement("div")),
+            {},
+        );
+
+        const state = movable.cloneState();
+        movable.state.added = false;
+
+        // It seems that all usages of this function in our production code
+        // pass the original state + mutations to modify(). However, it _does_
+        // work to pass no arguments so we'll keep this Characterization test
+        // here for now.
+        movable.modify();
+
+        expect(movable.cloneState()).toEqual(state);
+    });
+
+    test("modify() retains original ID", () => {
+        const movable = new Movable(
+            new Graphie(document.createElement("div")),
+            {},
+        );
+        const id = movable.state.id;
+
+        movable.modify({added: true});
+
+        expect(movable.state.id).toBe(id);
+    });
+
+    test("grab() fires onMoveStart", () => {
+        const graphie = new Graphie(document.createElement("div"));
+        graphie.init({
+            range: [
+                [-10, 10],
+                [-10, 10],
+            ],
+        });
+        const onMoveStart = jest.fn();
+        const movable = new Movable(graphie, {onMoveStart});
+
+        movable.grab([0, 0]);
+
+        expect(onMoveStart).toHaveBeenCalledWith([0, 0], [0, 0]);
+    });
+
+    test("grab() fires onMove when mouse moves", () => {
+        const graphie = new Graphie(document.createElement("div"));
+        graphie.init({
+            range: [
+                [-10, 10],
+                [-10, 10],
+            ],
+            scale: [10, 10],
+        });
+        const onMove = jest.fn();
+        const movable = new Movable(graphie, {onMove});
+
+        movable.grab([0, 0]);
+        fireEvent.mouseMove(document, {clientX: 120, clientY: 80});
+
+        expect(onMove).toHaveBeenCalledWith([2, 2], [0, 0]);
+    });
+
+    test("grab() fires onMoveEnd when mouse up", () => {
+        const dummyGraphie: any = {};
+        const onMoveEnd = jest.fn();
+        const movable = new Movable(dummyGraphie, {onMoveEnd});
+
+        movable.grab([0, 0]);
+        fireEvent.mouseUp(document);
+
+        expect(onMoveEnd).toHaveBeenCalledWith([0, 0], [0, 0]);
+    });
+
+    test("grab() fires onClick if still hovering when mouse up", () => {
+        const dummyGraphie: any = {};
+        const onClick = jest.fn();
+        const movable = new Movable(dummyGraphie, {onClick});
+
+        movable.grab([0, 0]);
+        fireEvent.mouseUp(document);
+
+        expect(onClick).toHaveBeenCalledWith([0, 0], [0, 0]);
+    });
+});

package/src/interactive2/interactive-util.test.ts

@@ -0,0 +1,93 @@
+import InteractiveUtil from "./interactive-util";
+
+describe("normalizeOptions", () => {
+    it("wraps single functions in arrays", () => {
+        const options = {
+            add: () => {},
+            modify: () => {},
+            draw: () => {},
+            remove: () => {},
+            constraints: () => {},
+            onMoveStart: () => {},
+            onMove: () => {},
+            onMoveEnd: () => {},
+            onClick: () => {},
+        };
+        expect(InteractiveUtil.normalizeOptions(options)).toEqual({
+            add: [options.add],
+            modify: [options.modify],
+            draw: [options.draw],
+            remove: [options.remove],
+            constraints: [options.constraints],
+            onMoveStart: [options.onMoveStart],
+            onMove: [options.onMove],
+            onMoveEnd: [options.onMoveEnd],
+            onClick: [options.onClick],
+        });
+    });
+
+    it("tolerates missing properties", () => {
+        const options = {
+            add: () => {},
+        };
+        expect(InteractiveUtil.normalizeOptions(options)).toEqual({
+            add: [options.add],
+        });
+    });
+
+    it("ignores extra properties", () => {
+        const options = {
+            foo: () => {},
+        };
+        expect(InteractiveUtil.normalizeOptions(options)).toEqual({
+            foo: options.foo,
+        });
+    });
+
+    it("does not modify its argument", () => {
+        const options = {
+            add: () => {},
+        };
+        const optionsCopy = {...options};
+        InteractiveUtil.normalizeOptions(options);
+        expect(options).toEqual(optionsCopy);
+    });
+
+    it("leaves existing arrays of functions alone", () => {
+        const options = {
+            add: [() => {}],
+            modify: [() => {}],
+            draw: [() => {}],
+            remove: [() => {}],
+            onMoveStart: [() => {}],
+            onMove: [() => {}],
+            onMoveEnd: [() => {}],
+            onClick: [() => {}],
+        };
+        expect(InteractiveUtil.normalizeOptions(options)).toEqual(options);
+    });
+
+    it("flattens arrays", () => {
+        const dummyFunction = () => {};
+        const options = {
+            add: [[dummyFunction]],
+            modify: [[dummyFunction]],
+            draw: [[dummyFunction]],
+            remove: [[dummyFunction]],
+            onMoveStart: [[dummyFunction]],
+            onMove: [[dummyFunction]],
+            onMoveEnd: [[dummyFunction]],
+            onClick: [[dummyFunction]],
+        };
+        expect(InteractiveUtil.normalizeOptions(options)).toEqual({
+            add: [dummyFunction],
+            modify: [dummyFunction],
+            draw: [dummyFunction],
+            remove: [dummyFunction],
+            onMoveStart: [dummyFunction],
+            onMove: [dummyFunction],
+            onMoveEnd: [dummyFunction],
+            onClick: [dummyFunction],
+        });
+    });
+});

package/src/interactive2/interactive-util.ts

@@ -52,6 +52,18 @@ function computeCanUse3dTransform(): boolean {
     return !!el.style[prefix];
 }
 
+const FUNCTION_ARRAY_OPTIONS = [
+    "add",
+    "modify",
+    "draw",
+    "remove",
+    "constraints",
+    "onMoveStart",
+    "onMove",
+    "onMoveEnd",
+    "onClick",
+];
+
 const InteractiveUtil = {
     assert: function (isTrue: boolean, message?: string) {
         if (!isTrue) {
@@ -106,24 +118,16 @@ const InteractiveUtil = {
     /**
      * Convert all function-or-array arguments to arrays of functions
      */
-    normalizeOptions: function (
-        arrayOptionNames: ReadonlyArray<string>,
-        options: Record<any, any>,
-    ): Record<any, any> {
-        // 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];
+    normalizeOptions: function (options: Record<any, any>): Record<any, any> {
+        const result = {...options};
+        FUNCTION_ARRAY_OPTIONS.forEach(function (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;
+            if (options[eventName] !== undefined) {
+                result[eventName] = InteractiveUtil.arrayify(
+                    options[eventName],
+                );
             }
         });
         return result;

package/src/interactive2/movable-helper-methods.ts

@@ -27,8 +27,13 @@ const MovableHelperMethods: any = {
     /**
      * Fire an onSomething type event to all functions in listeners
      */
-    _fireEvent: function (listeners, currentValue, previousValue) {
-        _.invoke(listeners, "call", this, currentValue, previousValue);
+    _fireEvent: function <F extends (...args: any[]) => any>(
+        listeners: F[],
+        ...args: Parameters<F>
+    ) {
+        for (const listener of listeners) {
+            listener.call(this, ...args);
+        }
     },
 
     /**

package/src/interactive2/movable-line.ts

@@ -14,16 +14,6 @@ import WrappedLine from "./wrapped-line";
 const assert = InteractiveUtil.assert;
 const normalizeOptions = InteractiveUtil.normalizeOptions;
 
-const FUNCTION_ARRAY_OPTIONS = [
-    "add",
-    "draw",
-    "remove",
-    "onMoveStart",
-    "constraints",
-    "onMove",
-    "onMoveEnd",
-];
-
 // Default "props" and "state". Both are added to this.state and
 // receive magic getter methods (this.cursor() etc).
 // However, properties in DEFAULT_PROPS are updated on `modify()`,
@@ -87,7 +77,6 @@ _.extend(MovableLine.prototype, {
                 id: this.state.id,
             },
             normalizeOptions(
-                FUNCTION_ARRAY_OPTIONS,
                 // Defaults are copied from MovableLineOptions.*.standard
                 // These defaults are set here instead of DEFAULT_PROPS/STATE
                 // because they:
@@ -121,7 +110,7 @@ _.extend(MovableLine.prototype, {
         const graphie = this.graphie;
         const state = (self.state = _.extend(
             self.state,
-            normalizeOptions(FUNCTION_ARRAY_OPTIONS, options),
+            normalizeOptions(options),
         ));
 
         // Default things inside the state.normalStyle object, because

package/src/interactive2/movable-point.tsx

@@ -69,10 +69,6 @@ const normalizeOptions = InteractiveUtil.normalizeOptions;
 
 const {processMath} = Tex;
 
-// State parameters that should be converted into an array of
-// functions
-const FUNCTION_ARRAY_OPTIONS = _.keys(MovablePointOptions);
-
 // Default "props" and "state". Both are added to this.state and
 // receive magic getter methods (this.coord() etc).
 // However, properties in DEFAULT_PROPS are updated on `modify()`,
@@ -134,7 +130,6 @@ _.extend(MovablePoint.prototype, {
                 id: this.state.id,
             },
             normalizeOptions(
-                FUNCTION_ARRAY_OPTIONS,
                 // Defaults are copied from MovablePointOptions.*.standard
                 // These defaults are set here instead of DEFAULT_PROPS/STATE
                 // because they:
@@ -216,10 +211,7 @@ _.extend(MovablePoint.prototype, {
     update: function (options) {
         const self = this;
         const graphie = self.graphie;
-        const state = _.extend(
-            self.state,
-            normalizeOptions(FUNCTION_ARRAY_OPTIONS, options),
-        );
+        const state = _.extend(self.state, normalizeOptions(options));
 
         assert(kpoint.is(state.coord));
 

package/src/interactive2/movable-polygon.ts

@@ -15,10 +15,6 @@ import objective_ from "./objective_";
 const assert = InteractiveUtil.assert;
 const normalizeOptions = InteractiveUtil.normalizeOptions;
 
-// State parameters that should be converted into an array of
-// functions
-const FUNCTION_ARRAY_OPTIONS = _.keys(MovablePolygonOptions);
-
 // Default "props" and "state". Both are added to this.state and
 // receive magic getter methods (this.points() etc).
 // However, properties in DEFAULT_PROPS are updated on `modify()`,
@@ -89,7 +85,6 @@ _.extend(MovablePolygon.prototype, {
                 id: this.state.id,
             },
             normalizeOptions(
-                FUNCTION_ARRAY_OPTIONS,
                 // Defaults are copied from MovablePolygonOptions.*.standard
                 // These defaults are set here instead of DEFAULT_PROPS/STATE
                 // because they:
@@ -124,10 +119,7 @@ _.extend(MovablePolygon.prototype, {
     update: function (options) {
         const self = this;
         const graphie = self.graphie;
-        const state = _.extend(
-            self.state,
-            normalizeOptions(FUNCTION_ARRAY_OPTIONS, options),
-        );
+        const state = _.extend(self.state, normalizeOptions(options));
 
         // Default things inside the state.normalStyle object, because
         // _.extend is not deep.

package/src/interactive2/movable.ts

@@ -15,23 +15,13 @@ import _ from "underscore";
 
 import InteractiveUtil from "./interactive-util";
 
+import type {Coord} from "./types";
+import type {Graphie} from "../util/graphie";
+
 const normalizeOptions = InteractiveUtil.normalizeOptions;
 
 const assert = InteractiveUtil.assert;
 
-// state parameters that should be converted into an array of
-// functions
-const FUNCTION_ARRAY_OPTIONS = [
-    "add",
-    "modify",
-    "draw",
-    "remove",
-    "onMoveStart",
-    "onMove",
-    "onMoveEnd",
-    "onClick",
-];
-
 // Default "props" and "state". Both are added to this.state and
 // receive magic getter methods (this.isHovering() etc).
 // However, properties in DEFAULT_PROPS are updated on `modify()`,
@@ -49,10 +39,30 @@ const DEFAULT_STATE = {
     mouseTarget: null,
 } as const;
 
-const Movable = function (graphie: any, options: any): void {
+export interface State {
+    added?: boolean;
+    isHovering?: boolean;
+    isMouseOver?: boolean;
+    isDragging?: boolean;
+    // TODO(benchristel): improve types
+    mouseTarget?: unknown | null;
+    // TODO(benchristel): improve types
+    cursor: unknown | null;
+    id: string;
+    add: (() => void)[];
+    modify: (() => void)[];
+    draw: (() => void)[];
+    remove: (() => void)[];
+    onMoveStart: ((position: Coord) => void)[];
+    onMove: ((end: Coord, start: Coord) => void)[];
+    onMoveEnd: ((end: Coord, start: Coord) => void)[];
+    onClick: ((position: Coord, start: Coord) => void)[];
+}
+
+const Movable = function (graphie: Graphie, options: any): void {
     // @ts-expect-error - TS2683 - 'this' implicitly has type 'any' because it does not have a type annotation.
     _.extend(this, {
-        graphie: graphie,
+        graphie,
         state: {
             // Set here because this must be unique for each instance
             id: _.uniqueId("movable"),
@@ -71,28 +81,26 @@ InteractiveUtil.createGettersFor(
 InteractiveUtil.addMovableHelperMethodsTo(Movable);
 
 _.extend(Movable.prototype, {
-    cloneState: function () {
-        return _.clone(this.state);
+    cloneState: function (): State {
+        return {...this.state};
     },
 
-    _createDefaultState: function () {
-        return _.extend(
-            {
-                id: this.state.id,
-                add: [],
-                modify: [],
-                draw: [],
-                remove: [],
-                onMoveStart: [],
-                onMove: [],
-                onMoveEnd: [],
-                onClick: [],
-
-                // We only update props here, because we want things on state to
-                // be persistent, and updated appropriately in modify()
-            },
-            DEFAULT_PROPS,
-        );
+    _createDefaultState: function (): State {
+        return {
+            id: this.state.id,
+            add: [],
+            modify: [],
+            draw: [],
+            remove: [],
+            onMoveStart: [],
+            onMove: [],
+            onMoveEnd: [],
+            onClick: [],
+
+            // We only update props here, because we want things on state to
+            // be persistent, and updated appropriately in modify()
+            ...DEFAULT_PROPS,
+        };
     },
 
     /**
@@ -101,18 +109,18 @@ _.extend(Movable.prototype, {
      *
      * Analogous to React.js's replaceProps
      */
-    modify: function (options) {
-        this.update(_.extend({}, this._createDefaultState(), options));
+    modify: function (options: Partial<State>) {
+        this.update({...this._createDefaultState(), ...options});
     },
 
     /**
      * Simulates a mouse grab event on the movable object.
      */
-    grab: function (coord) {
+    grab: function (coord: Coord) {
         assert(kpoint.is(coord));
         const self = this;
         const graphie = self.graphie;
-        const state = self.state;
+        const state: State = self.state;
 
         state.isHovering = true;
         state.isDragging = true;
@@ -154,15 +162,12 @@ _.extend(Movable.prototype, {
      *
      * Analogous to React.js's setProps
      */
-    update: function (options) {
+    update: function (options: State) {
         const self = this;
         const graphie = self.graphie;
 
         const prevState = self.cloneState();
-        const state = _.extend(
-            self.state,
-            normalizeOptions(FUNCTION_ARRAY_OPTIONS, options),
-        );
+        const state = _.extend(self.state, normalizeOptions(options));
 
         // the invisible shape in front of the point that gets mouse events
         if (state.mouseTarget && !prevState.mouseTarget) {

package/src/types.ts

@@ -411,9 +411,13 @@ export type WidgetExports<
 > = Readonly<{
     name: string;
     displayName: string;
+
+    // Widgets should provide _one_ of these two properties only!
     // TODO: figure out how to ensure that the component returned supports
     // the `validate` method.
     getWidget?: () => T;
+    widget: T;
+
     accessible?: boolean | ((props: any) => boolean);
     /** Supresses widget from showing up in the dropdown in the content editor */
     hidden?: boolean;
@@ -449,8 +453,6 @@ export type WidgetExports<
     propUpgrades?: {
         [key: string]: (arg1: any) => any;
     }; // OldProps => NewProps,
-
-    widget: T;
 }>;
 
 export type PerseusWidgetMap = {