@khanacademy/perseus 19.1.3 → 19.1.4

package/dist/interactive2/interactive-util.d.ts

@@ -18,7 +18,7 @@ declare const InteractiveUtil: {
     /**
      * Convert all function-or-array arguments to arrays of functions
      */
-    readonly normalizeOptions: (arrayOptionNames: ReadonlyArray<string>, options: Record<any, any>) => Record<any, any>;
+    readonly normalizeOptions: (options: Record<any, any>) => Record<any, any>;
     /**
      * Get the correct vendor-prefixed `transform`.
      */

package/dist/interactive2/movable.d.ts

@@ -1,2 +1,21 @@
-declare const Movable: (graphie: any, options: any) => void;
+import type { Coord } from "./types";
+import type { Graphie } from "../util/graphie";
+export interface State {
+    added?: boolean;
+    isHovering?: boolean;
+    isMouseOver?: boolean;
+    isDragging?: boolean;
+    mouseTarget?: unknown | null;
+    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)[];
+}
+declare const Movable: (graphie: Graphie, options: any) => void;
 export default Movable;

package/dist/util/graphie.d.ts

@@ -42,7 +42,7 @@ export declare class Graphie {
     ypixels?: number;
     constructor(el: Element);
     init(options: {
-        range?: [Interval, Interval];
+        range: [Interval, Interval];
         scale?: number | Coord;
         isMobile?: boolean;
     }): this;

package/package.json

@@ -3,7 +3,7 @@
     "description": "Core Perseus API (includes renderers and widgets)",
     "author": "Khan Academy",
     "license": "MIT",
-    "version": "19.1.3",
+    "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.2",
+        "@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/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/util/graphie.ts

@@ -121,13 +121,15 @@ export class Graphie {
     }
 
     init(options: {
-        range?: [Interval, Interval];
+        range: [Interval, Interval];
         scale?: number | Coord;
         isMobile?: boolean;
     }) {
         let scale = options.scale || [40, 40];
         scale = typeof scale === "number" ? [scale, scale] : scale;
 
+        // TODO(jeremy): This can be removed once we're confident that callers
+        // obey the Typescript types.
         if (options.range == null) {
             throw new PerseusError(
                 "range should be specified in graph init",