@khanacademy/perseus 19.1.3 → 19.1.5

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

@@ -14,11 +14,11 @@ 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
      */
-    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-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,2 +1,98 @@
-declare const Movable: (graphie: any, options: any) => void;
-export default Movable;
+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?: {
+        toFront(): void;
+        toBack(): void;
+        remove(): void;
+        getMouseTarget(): Element;
+    } | null;
+    cursor?: null;
+    id: string;
+    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;
+}

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,9 +40,10 @@ export declare class Graphie {
     dimensions?: Coord;
     xpixels?: number;
     ypixels?: number;
+    isDragging?: boolean;
     constructor(el: Element);
     init(options: {
-        range?: [Interval, Interval];
+        range: [Interval, Interval];
         scale?: number | Coord;
         isMobile?: boolean;
     }): this;
@@ -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.3",
+    "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.2",
+        "@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

@@ -4,39 +4,52 @@
 
 import _ from "underscore";
 
-import Movable from "../movable";
+import {Graphie} from "../../util/graphie";
+import {Movable} from "../movable";
+
+import type {Coord} from "@khanacademy/perseus";
 
 const createMock = function (): any {
-    const movable = new Movable(null, {
-        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/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-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-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));