@khanacademy/perseus 19.1.4 → 19.1.5

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

@@ -14,7 +14,7 @@ declare const InteractiveUtil: {
     /**
      * Turn a function or an array of functions into an array of functions
      */
-    readonly arrayify: (funcOrArray: readonly unknown[] | ((...args: ReadonlyArray<unknown>) => unknown)) => ReadonlyArray<unknown>;
+    readonly arrayify: (funcOrArray: ((...args: ReadonlyArray<unknown>) => unknown) | readonly unknown[]) => ReadonlyArray<unknown>;
     /**
      * Convert all function-or-array arguments to arrays of functions
      */

package/dist/interactive2/movable-point-options.d.ts

@@ -1,4 +1,5 @@
-import type { Coord } from "./types";
+import type { Constraint, Coord } from "./types";
+import type { Interval } from "../util/interval";
 declare const _default: {
     add: {
         readonly constrain: () => void;
@@ -17,9 +18,9 @@ declare const _default: {
         standard: null;
     };
     constraints: {
-        readonly fixed: () => () => boolean;
-        readonly snap: (snap: any) => (arg1: Coord) => unknown;
-        readonly bound: (range: any, snap: any, paddingPx: number) => (arg1: Coord, arg2: Coord, arg3: any) => Coord;
+        readonly fixed: () => Constraint;
+        readonly snap: (snap?: number | null | undefined) => Constraint;
+        readonly bound: (range?: [Interval, Interval] | undefined, snap?: number | Coord | undefined, optionalPaddingPx?: number | undefined) => Constraint;
     };
     onMove: {
         standard: null;

package/dist/interactive2/movable.d.ts

@@ -1,21 +1,98 @@
-import type { Coord } from "./types";
+import type { Constraint, ConstraintCallbacks, 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;
+    mouseTarget?: {
+        toFront(): void;
+        toBack(): void;
+        remove(): void;
+        getMouseTarget(): Element;
+    } | null;
+    cursor?: 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)[];
+    add?: (() => void)[];
+    modify?: ((state: State, prevState?: State) => void)[];
+    draw?: ((state: State, prevState?: State) => void)[];
+    remove?: (() => void)[];
+    onMoveStart?: ((position: Coord, positionAgain: Coord) => void)[];
+    onMove?: ((end: Coord, start: Coord) => void)[];
+    onMoveEnd?: ((end: Coord, start: Coord) => void)[];
+    onClick?: ((position: Coord, start: Coord) => void)[];
+    constraints?: Constraint[];
+}
+export declare class Movable<Options extends Record<string, any>> {
+    graphie: Graphie;
+    state: State;
+    prevState: State | undefined;
+    _listenerMap: Record<string, number>;
+    constructor(graphie: Graphie, options: Options);
+    modify(options: Options): void;
+    _createDefaultState(): {
+        cursor: null;
+        id: string;
+        add: never[];
+        modify: never[];
+        draw: never[];
+        remove: never[];
+        onMoveStart: never[];
+        onMove: never[];
+        onMoveEnd: never[];
+        onClick: never[];
+    };
+    update(options: Options): void;
+    cloneState(): State;
+    /**
+     * Fire an onSomething type event to all functions in listeners
+     */
+    _fireEvent<F extends (...args: any[]) => any>(listeners: F[] | undefined, ...args: Parameters<F>): void;
+    /**
+     * Call all draw functions, and update our prevState for the next
+     * draw function
+     */
+    draw(): void;
+    /**
+     * Simulates a mouse grab event on the movable object.
+     */
+    grab(coord: Coord): void;
+    _applyConstraints(current: Coord, previous: Coord, extraOptions?: ConstraintCallbacks): any;
+    toBack(): void;
+    toFront(): void;
+    /**
+     * Add a listener to any event: startMove, constraints, onMove, onMoveEnd,
+     * etc. If a listener is already bound to the given eventName and id, then
+     * it is overwritten by func.
+     *
+     * eventName: the string name of the event to listen to. one of:
+     *   "onMoveStart", "onMove", "onMoveEnd", "draw", "remove"
+     *
+     * id: a string id that can be used to remove this event at a later time
+     *   note: adding multiple listeners with the same id is undefined behavior
+     *
+     * func: the function to call when the event happens, which is called
+     *   with the event's standard parameters [usually (coord, prevCoord) or
+     *   (state, prevState)]
+     */
+    listen(eventName: string, id: string, func: () => unknown): void;
+    /**
+     * Remove a previously added listener, by the id specified in the
+     * corresponding listen() call
+     *
+     * If the given id has not been registered already, this is a no-op
+     */
+    unlisten(eventName: string, id: string): void;
+    remove(): void;
+    cursor(): null | undefined;
+    added(): boolean | undefined;
+    isHovering(): boolean | undefined;
+    isMouseOver(): boolean | undefined;
+    isDragging(): boolean | undefined;
+    mouseTarget(): {
+        toFront(): void;
+        toBack(): void;
+        remove(): void;
+        getMouseTarget(): Element;
+    } | null | undefined;
 }
-declare const Movable: (graphie: Graphie, options: any) => void;
-export default Movable;

package/dist/interactive2/types.d.ts

@@ -1,2 +1,8 @@
+import type { Movable } from "./movable";
 export type Coord = [number, number];
 export type Line = [Coord, Coord];
+export type Constraint = (this: Movable<any>, current: Coord | boolean, previous: Coord, options: ConstraintCallbacks) => Coord | boolean | undefined;
+export type ConstraintCallbacks = {
+    onSkipRemaining(): void;
+    onOutOfBounds?: () => void;
+};

package/dist/util/graphie.d.ts

@@ -40,6 +40,7 @@ export declare class Graphie {
     dimensions?: Coord;
     xpixels?: number;
     ypixels?: number;
+    isDragging?: boolean;
     constructor(el: Element);
     init(options: {
         range: [Interval, Interval];
@@ -102,6 +103,10 @@ export declare class Graphie {
     unscalePoint: (point: Coord) => any;
     unscaleVector: (point: Coord) => any;
     private processAttributes;
+    getMouseCoord(event: Readonly<{
+        pageX?: number;
+        pageY?: number;
+    }>): Coord;
 }
 type RangeSpecifier = [Interval, Interval] | Coord | number;
 export declare function normalizeRange(range: RangeSpecifier): [Interval, Interval];

package/dist/widgets/expression.d.ts

@@ -212,10 +212,10 @@ declare const _default: Readonly<{
         onFocus: (blurPath: import("../types").FocusPath) => void;
         times: boolean;
         value: string;
-    }, "trackInteraction" | "onChange" | "static" | "analytics" | "problemNum" | "questionCompleted" | "keypadElement" | "alignment" | "buttonsVisible" | "containerSizeClass" | "widgetId" | "findWidgets" | "keypadConfiguration" | "reviewModeRubric" | "isLastUsedWidget"> & {
-        value?: string | undefined;
+    }, "onChange" | "trackInteraction" | "static" | "analytics" | "problemNum" | "questionCompleted" | "keypadElement" | "alignment" | "buttonsVisible" | "containerSizeClass" | "widgetId" | "findWidgets" | "keypadConfiguration" | "reviewModeRubric" | "isLastUsedWidget"> & {
         onFocus?: ((blurPath: import("../types").FocusPath) => void) | undefined;
         onBlur?: ((blurPath: import("../types").FocusPath) => void) | undefined;
+        value?: string | undefined;
         linterContext?: import("@khanacademy/perseus-linter").LinterContextProps | undefined;
         apiOptions?: Readonly<Readonly<{
             isArticle?: boolean | undefined;
@@ -401,10 +401,10 @@ declare const _default: Readonly<{
         onFocus: (blurPath: import("../types").FocusPath) => void;
         times: boolean;
         value: string;
-    }, "trackInteraction" | "onChange" | "static" | "analytics" | "problemNum" | "questionCompleted" | "keypadElement" | "alignment" | "buttonsVisible" | "containerSizeClass" | "widgetId" | "findWidgets" | "keypadConfiguration" | "reviewModeRubric" | "isLastUsedWidget"> & {
-        value?: string | undefined;
+    }, "onChange" | "trackInteraction" | "static" | "analytics" | "problemNum" | "questionCompleted" | "keypadElement" | "alignment" | "buttonsVisible" | "containerSizeClass" | "widgetId" | "findWidgets" | "keypadConfiguration" | "reviewModeRubric" | "isLastUsedWidget"> & {
         onFocus?: ((blurPath: import("../types").FocusPath) => void) | undefined;
         onBlur?: ((blurPath: import("../types").FocusPath) => void) | undefined;
+        value?: string | undefined;
         linterContext?: import("@khanacademy/perseus-linter").LinterContextProps | undefined;
         apiOptions?: Readonly<Readonly<{
             isArticle?: boolean | undefined;

package/package.json

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

package/src/components/graphie.tsx

@@ -62,6 +62,9 @@ type DefaultProps = {
 
 interface Movable {
     remove(): void;
+    props: unknown;
+    modify(graphie: GraphieDrawingContext): "reordered" | undefined;
+    toFront(): void;
 }
 
 class Graphie extends React.Component<Props> {
@@ -231,7 +234,12 @@ class Graphie extends React.Component<Props> {
     // @ts-expect-error - TS2322 - Type '(children: readonly any[], options: any) => ReactElement<any, string | JSXElementConstructor<any>> | readonly ReactElement<any, string | JSXElementConstructor<any>>[]' is not assignable to type '(children: readonly any[], arg2: any) => ReactElement<any, string | JSXElementConstructor<any>>'.
     _renderMovables: (
         children: ReadonlyArray<any>,
-        arg2: any,
+        arg2: {
+            nextKey: number;
+            graphie: GraphieDrawingContext;
+            oldMovables: Record<string, Movable>;
+            newMovables: Record<string, Movable>;
+        },
     ) => React.ReactElement = (children, options) => {
         // Each leaf of `children` is a movable descriptor created by a call to
         // some `GraphieMovable`, such as `MovablePoint`.

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

@@ -5,39 +5,51 @@
 import _ from "underscore";
 
 import {Graphie} from "../../util/graphie";
-import Movable from "../movable";
+import {Movable} from "../movable";
+
+import type {Coord} from "@khanacademy/perseus";
 
 const createMock = function (): any {
-    const movable = new Movable(new Graphie(document.createElement("div")), {
-        mouseTarget: null,
-    });
-    movable.modify = function (options: any) {
-        Movable.prototype.modify.call(movable, _.omit(options, "mouseTarget"));
-    };
-    _.each(
-        ["onMoveStart", "onMove", "onMoveEnd", "onClick"],
-        function (eventName) {
-            movable[eventName] = function (coord: any, prevCoord) {
-                this._fireEvent(this.state[eventName], coord, prevCoord);
-            };
-        },
-    );
-    movable.move = function (...args) {
-        const startPoint = _.first(args);
+    return new MovableMock(new Graphie(document.createElement("div")), {});
+};
+
+class MovableMock extends Movable<Record<string, never>> {
+    modify(options: any) {
+        // TODO(benchristel): what is mouseTarget? It seems to be unused.
+        super.modify(_.omit(options, "mouseTarget"));
+    }
+
+    move(...args) {
+        const [startPoint, ...rest] = 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]);
+        this.state.isMouseOver = true;
+        this.state.isHovering = true;
+        this.onMoveStart(startPoint, startPoint);
+        rest.forEach((point, i) => {
+            this.state.isDragging = true;
+            this.onMove(point, args[i]);
         });
-        movable.onMoveEnd(_.last(args), startPoint);
-        movable.state.dragging = false;
-        movable.state.isMouseOver = false;
-        movable.state.isHovering = false;
-    };
-    return movable;
-};
+        this.onMoveEnd(_.last(args), startPoint);
+        this.state.isDragging = false;
+        this.state.isMouseOver = false;
+        this.state.isHovering = false;
+    }
+
+    onMoveStart(coord: Coord, prevCoord: Coord) {
+        this._fireEvent(this.state.onMoveStart, coord, prevCoord);
+    }
+
+    onMove(coord: Coord, prevCoord: Coord) {
+        this._fireEvent(this.state.onMove, coord, prevCoord);
+    }
+
+    onMoveEnd(coord: Coord, prevCoord: Coord) {
+        this._fireEvent(this.state.onMoveEnd, coord, prevCoord);
+    }
+
+    onClick(coord: Coord, prevCoord: Coord) {
+        this._fireEvent(this.state.onClick, coord, prevCoord);
+    }
+}
 
 export default createMock;

package/src/interactive2/movable-point-options.ts

@@ -7,7 +7,8 @@ import _ from "underscore";
 
 import WrappedEllipse from "./wrapped-ellipse";
 
-import type {Coord} from "./types";
+import type {Constraint, ConstraintCallbacks, Coord} from "./types";
+import type {Interval} from "../util/interval";
 
 const add = {
     constrain: function () {
@@ -119,51 +120,62 @@ const remove = {
 remove.standard = remove.basic;
 
 const constraints = {
-    fixed: function (): () => boolean {
+    fixed: function (): Constraint {
         return function () {
             return false;
         };
     },
 
-    snap: function (snap: any): (arg1: Coord) => unknown {
-        return function (coord: Coord): unknown {
+    snap: function (snap?: number | null): Constraint {
+        return function (coord: Coord) {
             if (snap === null) {
-                // NOTE(kevinb): this should probably return the original point
+                // TODO(benchristel), NOTE(kevinb): this should probably return
+                // the original point
                 return true;
             }
-            // @ts-expect-error - TS2683 - 'this' implicitly has type 'any' because it does not have a type annotation.
-            snap = snap || this.graphie.snap;
-            return kpoint.roundTo(coord, snap);
+            // @ts-expect-error - TS2339: Property 'snap' does not exist on type 'Graphie'.
+            return kpoint.roundTo(coord, snap || this.graphie.snap);
         };
     },
 
     bound: function (
-        range: any,
-        snap: any,
-        paddingPx: number,
-    ): (arg1: Coord, arg2: Coord, arg3: any) => Coord {
-        if (paddingPx === undefined) {
-            if (range === undefined) {
-                paddingPx = 10;
+        range?: [Interval, Interval],
+        snap?: Coord | number,
+        optionalPaddingPx?: number,
+    ): Constraint {
+        const paddingPx = (() => {
+            if (optionalPaddingPx === undefined) {
+                if (range === undefined) {
+                    return 10;
+                } else {
+                    return 0;
+                }
             } else {
-                paddingPx = 0;
+                return optionalPaddingPx;
             }
-        }
-        return function (coord: Coord, prev, options: any) {
-            // @ts-expect-error - TS2683 - 'this' implicitly has type 'any' because it does not have a type annotation.
+        })();
+
+        return function (
+            coord: Coord,
+            prev: Coord,
+            options: ConstraintCallbacks,
+        ) {
             const graphie = this.graphie;
             range = range || graphie.range;
 
             if (snap === undefined) {
+                // @ts-expect-error - Property 'snap' does not exist on type 'Graphie'.
                 snap = graphie.snap;
             }
 
             let lower = graphie.unscalePoint([
                 paddingPx,
+                // @ts-expect-error - 'graphie.ypixels' is possibly 'undefined'.
                 graphie.ypixels - paddingPx,
             ]);
 
             let upper = graphie.unscalePoint([
+                // @ts-expect-error - 'graphie.ypixels' is possibly 'undefined'.
                 graphie.xpixels - paddingPx,
                 paddingPx,
             ]);

package/src/interactive2/movable.test.ts

@@ -0,0 +1,249 @@
+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", () => {
+    const properties = [
+        "graphie",
+        "state",
+        "prevState",
+        "cursor",
+        "added",
+        "isHovering",
+        "isMouseOver",
+        "isDragging",
+        "mouseTarget",
+        "_fireEvent",
+        "_applyConstraints",
+        "draw",
+        "listen",
+        "unlisten",
+        "cloneState",
+        "_createDefaultState",
+        "modify",
+        "grab",
+        "update",
+        "remove",
+        "toBack",
+        "toFront",
+    ];
+
+    it.each(properties)("has a %s property", (property) => {
+        const dummyGraphie: any = {};
+        const movable = new Movable(dummyGraphie, {});
+        expect(movable[property]).toBeDefined();
+    });
+
+    const getters = [
+        "cursor",
+        "added",
+        "isHovering",
+        "isMouseOver",
+        "isDragging",
+        "mouseTarget",
+    ];
+
+    it.each(getters)(
+        "returns the corresponding state property from %s()",
+        (getter) => {
+            const dummyGraphie: any = {};
+            const movable = new Movable(dummyGraphie, {});
+            expect(movable[getter]()).toBe(movable.state[getter]);
+        },
+    );
+
+    it("sets default state when constructed", () => {
+        const dummyGraphie: any = {};
+        const movable = new Movable(dummyGraphie, {});
+        expect(movable.state).toEqual({
+            id: expect.any(String),
+            add: [],
+            added: true,
+            cursor: null,
+            draw: [],
+            isDragging: false,
+            isHovering: false,
+            isMouseOver: false,
+            modify: [],
+            mouseTarget: null,
+            onClick: [],
+            onMove: [],
+            onMoveEnd: [],
+            onMoveStart: [],
+            remove: [],
+        });
+    });
+
+    it("calls the modify listener when constructed", () => {
+        const dummyGraphie: any = {};
+        const modifySpy = jest.fn().mockName("modify");
+
+        const _ = new Movable(dummyGraphie, {modify: modifySpy});
+
+        const baseExpectedState = {
+            add: [],
+            added: false,
+            cursor: null,
+            draw: [],
+            id: expect.any(String),
+            isDragging: false,
+            isHovering: false,
+            isMouseOver: false,
+            modify: [modifySpy],
+            mouseTarget: null,
+            onClick: [],
+            onMove: [],
+            onMoveEnd: [],
+            onMoveStart: [],
+            remove: [],
+        };
+        expect(modifySpy.mock.calls).toEqual([
+            [baseExpectedState, {}],
+            [
+                {...baseExpectedState, added: true},
+                {...baseExpectedState, added: true},
+            ],
+        ]);
+    });
+
+    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() makes a copy", () => {
+        const movable = new Movable(
+            new Graphie(document.createElement("div")),
+            {},
+        );
+
+        expect(movable.cloneState()).not.toBe(movable.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]);
+        // eslint-disable-next-line testing-library/prefer-user-event
+        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]);
+        // eslint-disable-next-line testing-library/prefer-user-event
+        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]);
+        // eslint-disable-next-line testing-library/prefer-user-event
+        fireEvent.mouseUp(document);
+
+        expect(onClick).toHaveBeenCalledWith([0, 0], [0, 0]);
+    });
+
+    test("draw() fires a draw event", () => {
+        const dummyGraphie: any = {};
+        const drawSpy = jest.fn();
+        const movable = new Movable(dummyGraphie, {draw: drawSpy});
+
+        movable.draw();
+
+        const expectedState = {
+            add: [],
+            added: true,
+            cursor: null,
+            draw: [drawSpy],
+            id: expect.any(String),
+            isDragging: false,
+            isHovering: false,
+            isMouseOver: false,
+            modify: [],
+            mouseTarget: null,
+            onClick: [],
+            onMove: [],
+            onMoveEnd: [],
+            onMoveStart: [],
+            remove: [],
+        };
+
+        expect(drawSpy).toHaveBeenCalledWith(expectedState, expectedState);
+    });
+});