@khanacademy/perseus 18.0.1 → 19.1.0

package/src/__testdata__/renderer.testdata.ts

@@ -4,6 +4,7 @@ import type {
     InputNumberWidget,
     PerseusRenderer,
 } from "../perseus-types";
+import type {RenderProps} from "../widgets/radio/widget";
 
 export const dropdownWidget: DropdownWidget = {
     type: "dropdown",
@@ -120,3 +121,154 @@ export const mockedItem: PerseusRenderer = {
         },
     },
 } as PerseusRenderer;
+
+// Note that if this item is used, you _must_ first register the MockWidget
+export const mockedRandomItem: PerseusRenderer = {
+    content: "Mock widgets ==> [[\u2603 radio 1]] [[\u2603 radio 2]]",
+    images: {},
+    widgets: {
+        "radio 1": {
+            graded: true,
+            version: {major: 0, minor: 0},
+            static: false,
+            numCorrect: 1,
+            hasNoneOfTheAbove: false,
+            multipleSelect: false,
+            countChoices: false,
+            deselectEnabled: false,
+            type: "radio",
+            options: {
+                static: false,
+                countChoices: false,
+                deselectEnabled: false,
+                displayCount: null,
+                hasNoneOfTheAbove: false,
+                multipleSelect: false,
+                randomize: true,
+                choices: [
+                    {
+                        content: "Content 1",
+                        correct: true,
+                    },
+                    {
+                        content: "Content 2",
+                        correct: false,
+                    },
+                    {
+                        content: "Content 3",
+                        correct: false,
+                    },
+                    {
+                        content: "Content 4",
+                        correct: false,
+                    },
+                ],
+            },
+            alignment: "default",
+        },
+        "radio 2": {
+            graded: true,
+            version: {major: 0, minor: 0},
+            static: false,
+            numCorrect: 1,
+            hasNoneOfTheAbove: false,
+            multipleSelect: false,
+            countChoices: false,
+            deselectEnabled: false,
+            type: "radio",
+            options: {
+                static: false,
+                countChoices: false,
+                deselectEnabled: false,
+                displayCount: null,
+                hasNoneOfTheAbove: false,
+                multipleSelect: false,
+                randomize: true,
+                choices: [
+                    {
+                        content: "Content 1",
+                        correct: true,
+                    },
+                    {
+                        content: "Content 2",
+                        correct: false,
+                    },
+                    {
+                        content: "Content 3",
+                        correct: false,
+                    },
+                    {
+                        content: "Content 4",
+                        correct: false,
+                    },
+                ],
+            },
+            alignment: "default",
+        },
+    },
+} as PerseusRenderer;
+
+export const mockedShuffledRadioProps: {[key in string]: RenderProps} = {
+    "radio 1": {
+        numCorrect: 1,
+        countChoices: false,
+        deselectEnabled: false,
+        hasNoneOfTheAbove: false,
+        multipleSelect: false,
+        choices: [
+            {
+                content: "Content 4",
+                correct: false,
+                originalIndex: 3,
+            },
+            {
+                content: "Content 2",
+                correct: false,
+                originalIndex: 1,
+            },
+            {
+                content: "Content 1",
+                correct: true,
+                originalIndex: 0,
+            },
+
+            {
+                content: "Content 3",
+                correct: false,
+                originalIndex: 2,
+            },
+        ],
+        selectedChoices: [false, false, true, false],
+    },
+    "radio 2": {
+        numCorrect: 1,
+        countChoices: false,
+        deselectEnabled: false,
+        hasNoneOfTheAbove: false,
+        multipleSelect: false,
+        choices: [
+            {
+                content: "Content 4",
+                correct: false,
+                originalIndex: 3,
+            },
+            {
+                content: "Content 2",
+                correct: false,
+                originalIndex: 1,
+            },
+            {
+                content: "Content 1",
+                correct: true,
+                originalIndex: 0,
+            },
+
+            {
+                content: "Content 3",
+                correct: false,
+                originalIndex: 2,
+            },
+        ],
+        selectedChoices: [false, false, true, false],
+    },
+};

package/src/__tests__/renderer.test.tsx

@@ -14,6 +14,8 @@ import {
     question1,
     question2,
     mockedItem,
+    mockedRandomItem,
+    mockedShuffledRadioProps,
 } from "../__testdata__/renderer.testdata";
 import * as Dependencies from "../dependencies";
 import {Errors} from "../logging/log";
@@ -29,6 +31,7 @@ import type {
     PerseusImageWidgetOptions,
     PerseusInputNumberWidgetOptions,
 } from "../perseus-types";
+import type {APIOptions} from "../types";
 
 // NOTE(jeremy): We can't use an automatic mock for the translation linter,
 // because one of it's "instance" methods is created using `debounce` and Jest
@@ -287,6 +290,20 @@ describe("renderer", () => {
                 /^less than or equal to$/,
             );
         });
+
+        it("should call the onWidgetStartProps callback if provided in apiOptions", () => {
+            // Arrange
+            const onWidgetStartProps = jest.fn();
+            const apiOptions: APIOptions = {onWidgetStartProps};
+
+            // Act
+            renderQuestion(mockedRandomItem, apiOptions);
+
+            // Assert
+            expect(onWidgetStartProps).toHaveBeenCalledWith(
+                mockedShuffledRadioProps,
+            );
+        });
     });
 
     describe("rendering", () => {

package/src/__tests__/widgets.test.ts

@@ -40,7 +40,6 @@ describe("Widget API support", () => {
         "simulator",
         "sorter",
         "table",
-        "transformer",
         "unit-input",
         "video",
     ])("%s widget should provide static validate function", (widgetType) => {

package/src/components/math-input.tsx

@@ -157,7 +157,7 @@ class MathInput extends React.Component<Props, State> {
                 (baseConfig) => ({
                     ...baseConfig,
                     handlers: {
-                        edit: (mathField) => {
+                        edit: (mathField: MathFieldInterface) => {
                             // This handler is guaranteed to be called on change, but
                             // unlike React it sometimes generates false positives.
                             // One of these is on initialization (with an empty string
@@ -184,11 +184,9 @@ class MathInput extends React.Component<Props, State> {
                                 // directly, instead of waiting for `.latex()` to be
                                 // called in `componentDidUpdate()`.
                                 const left =
-                                    mathField.__controller.cursor[
-                                        mathQuillInstance.L
-                                    ];
+                                    mathField.cursor()[mathQuillInstance.L];
                                 if (left && left.ctrlSeq === "\\cdot ") {
-                                    mathField.__controller.backspace();
+                                    mathField.controller().backspace();
                                     mathField.cmd("\\times");
                                 }
                             } else {
@@ -214,7 +212,7 @@ class MathInput extends React.Component<Props, State> {
                                 $(this.__mathFieldWrapperRef).submit();
                             }
                         },
-                        upOutOf: (mathField) => {
+                        upOutOf: (mathField: MathFieldInterface) => {
                             // This handler is called when the user presses the up
                             // arrow key, but there is nowhere in the expression to go
                             // up to (no numerator or exponent). For ease of use,

package/src/extra-widgets.ts

@@ -33,7 +33,6 @@ import Sequence from "./widgets/sequence";
 import Simulator from "./widgets/simulator";
 import Sorter from "./widgets/sorter";
 import Table from "./widgets/table";
-import Transformer from "./widgets/transformer";
 import Unit from "./widgets/unit";
 import Video from "./widgets/video";
 
@@ -70,7 +69,6 @@ export default [
     Simulator,
     Sorter,
     Table,
-    Transformer,
     Unit,
     Video,
     DeprecatedStandin,

package/src/index.ts

@@ -31,7 +31,6 @@ export {default as Radio} from "./widgets/radio";
 export {default as BaseRadio} from "./widgets/radio/base-radio";
 export {default as Categorizer} from "./widgets/categorizer";
 export {default as InteractiveGraphWidget} from "./widgets/interactive-graph";
-export {default as TransformerWidget} from "./widgets/transformer";
 export {default as MatrixWidget} from "./widgets/matrix";
 export {default as TableWidget} from "./widgets/table";
 export {default as PlotterWidget} from "./widgets/plotter";
@@ -84,7 +83,7 @@ export {
     getAnswersFromWidgets,
     injectWidgets,
 } from "./util/extract-perseus-data";
-export {default as parsePerseusJSON} from "./util/parse-perseus-json";
+export {parsePerseusItem} from "./util/parse-perseus-json";
 
 /**
  * Mixins
@@ -124,11 +123,16 @@ export type {
 } from "./types";
 export type {ParsedValue} from "./util";
 export type {
-    InputNumberWidget,
-    MathFormat,
     PerseusAnswerArea,
     PerseusExpressionWidgetOptions,
+    // Utility types
+    Range,
+    Size,
+    MathFormat,
+    InputNumberWidget, // TODO(jeremy): remove?
+    // Widget configuration types
     PerseusImageBackground,
+    PerseusInputNumberWidgetOptions,
     PerseusInteractiveGraphWidgetOptions,
     PerseusItem,
     PerseusPlotterWidgetOptions,

package/src/mixins/changeable.ts

@@ -127,7 +127,7 @@ export type ChangeableProps = {
         values: {
             [key: string]: any;
         },
-        callback?: () => unknown | null | undefined,
+        callback?: (() => unknown) | null | undefined,
         silent?: boolean,
     ) => unknown;
 };

package/src/perseus-types.ts

@@ -90,7 +90,7 @@ type Widget<Type extends string, Options> = {
     // Whether this widget is displayed with the values and is immutable.  For display only
     // NOTE: perseus_data.go says this is required even though it isn't necessary.
     static?: boolean;
-    // Whether a widget is scored.  Usually true except for IFrame widgets (deprecated) and Transformer widgets
+    // Whether a widget is scored.  Usually true except for IFrame widgets (deprecated)
     // Default: true
     graded?: boolean;
     // The HTML alignment of the widget.  "default" or "block"
@@ -164,9 +164,6 @@ export type SimulatorWidget = Widget<'simulator', PerseusSimulatorWidgetOptions>
 export type SorterWidget = Widget<'sorter', PerseusSorterWidgetOptions>;
 // prettier-ignore
 export type TableWidget = Widget<'table', PerseusTableWidgetOptions>;
-// prettier-ignore
-export type TransformerWidget = Widget<'transformer', PerseusTransformerWidgetOptions>;
-
 // prettier-ignore
 export type ExampleGraphieWidget = Widget<'example-graphie-widget', PerseusExampleGraphieWidgetOptions>;
 // prettier-ignore
@@ -228,7 +225,6 @@ export type PerseusWidget =
     | SimulatorWidget
     | SorterWidget
     | TableWidget
-    | TransformerWidget
     | UnitInputWidget
     | VideoWidget
     | AutoCorrectWidget;
@@ -456,7 +452,6 @@ export type PerseusGrapherWidgetOptions = {
               // Two points on the same slope in the tangent wave line.
               coords: [Coord, Coord];
           };
-    // TODO(jeremy): Unify with PerseusTransformerWidgetOptions's .graph
     graph: {
         backgroundImage: {
             bottom?: number;
@@ -990,115 +985,6 @@ export type PerseusTableWidgetOptions = {
     answers: ReadonlyArray<ReadonlyArray<string>>;
 };
 
-export type PerseusTransformerWidgetOptions = {
-    correct: {
-        shape: {
-            type: ReadonlyArray<
-                | "polygon-5"
-                | "polygon-3"
-                | "polygon-4"
-                | "lineSegment"
-                | "polygon-6"
-                | "angle"
-                | "line"
-                | "circle"
-            >;
-            coords: ReadonlyArray<Coord>;
-            options?: ReadonlyArray<{
-                reflex?: boolean;
-            }>;
-        };
-        transformations: ReadonlyArray<PerseusTransformerTransformation>;
-    };
-    drawSolutionShape: boolean;
-    gradeEmpty: boolean;
-    // TODO(jeremy): Unify with PerseusGrapherWidgetOptions's .graph
-    graph: {
-        backgroundImage: {
-            bottom?: number;
-            height?: number;
-            left?: number;
-            scale?: number;
-            url?: string;
-            width?: number;
-        };
-        gridStep?: [number, number];
-        labels?: ["x", "y"];
-        markings: "none" | "graph" | "grid";
-        range: [[number, number], [number, number]];
-        rulerLabel?: string;
-        rulerTicks?: number;
-        showProtractor: boolean;
-        showRuler?: boolean;
-        snapStep?: [number, number];
-        step: [number, number];
-    };
-    graphMode: "dynamic" | "interactive" | "static";
-    listMode: "interactive" | "dynamic" | "static";
-    starting: {
-        shape:
-            | {
-                  type: ReadonlyArray<
-                      | "polygon-5"
-                      | "polygon-3"
-                      | "polygon-4"
-                      | "lineSegment"
-                      | "polygon-6"
-                  >;
-                  coords: ReadonlyArray<Coord>;
-                  options?: ReadonlyArray<Empty>;
-              }
-            | {
-                  type: "polygon-3";
-                  coords: [Coord, Coord, Coord];
-              }
-            | {
-                  type: [
-                      | "polygon-3"
-                      | "lineSegment"
-                      | "polygon-4"
-                      | "polygon-5"
-                      | "polygon-6"
-                      | "line"
-                      | "circle",
-                  ];
-                  coords: ReadonlyArray<Coord>;
-                  options: [Empty];
-              }
-            | {
-                  type: ["polygon-3"];
-                  coords: [Coord, Coord, Coord];
-                  options?: [Empty];
-              }
-            | {
-                  type: ["angle"];
-                  coords: [Coord, Coord, Coord];
-                  options: [
-                      {
-                          reflex: boolean;
-                      },
-                  ];
-              }
-            | {
-                  type: ["line" | "lineSegment"];
-                  coords: [Coord, Coord];
-                  options?: [Empty];
-              }
-            | {
-                  type: "polygon";
-                  coords: ReadonlyArray<Coord>;
-              };
-        transformations: ReadonlyArray<PerseusTransformerTransformation>;
-    };
-    tools: {
-        dilation: DilationTool;
-        reflection: ReflectionTool;
-        rotation: RotationTool;
-        translation: TranslationTool;
-    };
-    version: number;
-};
-
 export type DilationTransformation = {
     type: "dilation";
     center: Coord;
@@ -1131,44 +1017,6 @@ export type TranslationTransformation = {
     contraints: Empty;
 };
 
-export type PerseusTransformerTransformation =
-    | DilationTransformation
-    | ReflectionTransformation
-    | RotationTransformation
-    | TranslationTransformation;
-
-type DilationTool = {
-    constraints: PerseusTransformerToolConstraints;
-    coord: Coord;
-    enabled: boolean;
-    required?: boolean;
-};
-
-type ReflectionTool = {
-    constraints: PerseusTransformerToolConstraints;
-    coords: [Coord, Coord];
-    enabled: boolean;
-    required?: boolean;
-};
-
-type RotationTool = {
-    constraints: PerseusTransformerToolConstraints;
-    coord: Coord;
-    enabled: boolean;
-    required?: boolean;
-};
-
-type TranslationTool = {
-    constraints: Empty;
-    enabled: boolean;
-    required?: boolean;
-};
-
-export type PerseusTransformerToolConstraints = {
-    // Whether we should prevent the student from repositioning the tool
-    fixed: boolean;
-};
-
 export type PerseusInteractionWidgetOptions = {
     // The definition of the graph
     graph: PerseusInteractionGraph;
@@ -1514,6 +1362,5 @@ export type PerseusWidgetOptions =
     | PerseusSimulatorWidgetOptions
     | PerseusSorterWidgetOptions
     | PerseusTableWidgetOptions
-    | PerseusTransformerWidgetOptions
     | PerseusUnitInputWidgetOptions
     | PerseusVideoWidgetOptions;

package/src/renderer.tsx

@@ -1,6 +1,7 @@
 /* eslint-disable @khanacademy/ts-no-error-suppressions */
 /* eslint-disable react/no-unsafe */
 import * as PerseusLinter from "@khanacademy/perseus-linter";
+import {entries} from "@khanacademy/wonder-stuff-core";
 import classNames from "classnames";
 import $ from "jquery";
 import * as React from "react";
@@ -41,6 +42,7 @@ import type {
     FilterCriterion,
     FocusPath,
     PerseusScore,
+    PerseusWidgetMap,
     WidgetProps,
 } from "./types";
 import type {LinterContextProps} from "@khanacademy/perseus-linter";
@@ -485,18 +487,22 @@ class Renderer extends React.Component<Props, State> {
     };
 
     _getAllWidgetsStartProps: (
-        allWidgetInfo: {
-            [key: string]: PerseusWidget;
-        },
+        allWidgetInfo: PerseusWidgetMap,
         props: Props,
-    ) => any = (allWidgetInfo, props) => {
-        // @ts-expect-error - TS2345 - Argument of type '{ [key: string]: PerseusWidget; }' is not assignable to parameter of type 'Partial<Record<string, CategorizerWidget>>'.
-        return mapObject(allWidgetInfo, (widgetInfo) => {
-            return Widgets.getRendererPropsForWidgetInfo(
+    ) => PerseusWidgetMap = (allWidgetInfo, props) => {
+        const {apiOptions, problemNum} = props;
+        const widgetsStartProps: PerseusWidgetMap = {};
+        entries(allWidgetInfo).forEach(([key, widgetInfo]) => {
+            widgetsStartProps[key] = Widgets.getRendererPropsForWidgetInfo(
                 widgetInfo,
-                props.problemNum,
+                problemNum,
             );
         });
+
+        // Call the onWidgetStartProps callback if it exists
+        apiOptions?.onWidgetStartProps?.(widgetsStartProps);
+
+        return widgetsStartProps;
     };
 
     // This is only used in _getWidgetInfo as a fallback if widgetId

package/src/styles/perseus-renderer.less

@@ -448,7 +448,6 @@
 @import "./widgets/sequence.less";
 @import "./widgets/sortable.less";
 @import "./widgets/table.less";
-@import "./widgets/transformer.less";
 @import "./widgets/unit.less";
 
 .perseus-widget-container {

package/src/types.ts

@@ -1,4 +1,3 @@
-import type {SerializedHighlightSet} from "./components/highlighting/types";
 import type {ILogger} from "./logging/log";
 import type {Item} from "./multi-items/item-types";
 import type {
@@ -92,10 +91,6 @@ export type ChangeHandler = (
         currentValue?: string;
         // perseus-all-package/widgets/dropdown.jsx
         selected?: number;
-        // perseus-all-package/widgets/transformer.jsx
-        tools?: ReadonlyArray<any>;
-        transformations?: ReadonlyArray<any>;
-        highlights?: SerializedHighlightSet;
         // perseus-all-package/widgets/grapher.jsx
         plot?: any;
     },
@@ -228,6 +223,11 @@ export type APIOptions = Readonly<{
     // keystroke caused text typed in the text area to appear in it
     // only after a good few seconds.
     editorChangeDelay?: number;
+    // This is a callback function that returns all of the Widget props
+    // after they have been transformed by the widget's transform function.
+    // This is useful for when we need to know how a widget has shuffled its
+    // the available choices.
+    onWidgetStartProps?: (widgets: PerseusWidgetMap) => PerseusWidgetMap;
 }>;
 
 type TeXProps = {
@@ -453,6 +453,10 @@ export type WidgetExports<
     widget: T;
 }>;
 
+export type PerseusWidgetMap = {
+    [key: string]: PerseusWidget;
+};
+
 export type FilterCriterion =
     | string
     | ((

package/src/util/geometry.test.ts

@@ -0,0 +1,75 @@
+import {clockwise, reverseVector} from "./geometry";
+
+describe("reverseVector", () => {
+    it("flips the sign of zero", () => {
+        // This is a characterization test for legacy behavior. It might not
+        // actually be desired behavior.
+        expect(reverseVector([0, 0])).toEqual([-0, -0]);
+    });
+
+    it("flips the sign of each component", () => {
+        expect(reverseVector([1, -5])).toEqual([-1, 5]);
+    });
+});
+
+describe("clockwise", () => {
+    it("returns false given no points", () => {
+        expect(clockwise([])).toBe(false);
+    });
+
+    it("returns false given a single point at the origin", () => {
+        expect(clockwise([[0, 0]])).toBe(false);
+    });
+
+    it("returns false given a single point not at the origin", () => {
+        expect(clockwise([[7, 7]])).toBe(false);
+    });
+
+    it("returns false given two identical points", () => {
+        expect(
+            clockwise([
+                [7, 7],
+                [7, 7],
+            ]),
+        ).toBe(false);
+    });
+
+    it("returns false given two different points", () => {
+        expect(
+            clockwise([
+                [8, 8],
+                [7, 7],
+            ]),
+        ).toBe(false);
+    });
+
+    it("returns true given a clockwise triangle in the first quadrant", () => {
+        expect(
+            clockwise([
+                [0, 1],
+                [1, 0],
+                [0, 0],
+            ]),
+        ).toBe(true);
+    });
+
+    it("returns false given a counter-clockwise triangle in the first quadrant", () => {
+        expect(
+            clockwise([
+                [1, 0],
+                [0, 1],
+                [0, 0],
+            ]),
+        ).toBe(false);
+    });
+
+    it("returns true given a clockwise triangle in the second quadrant", () => {
+        expect(
+            clockwise([
+                [0, 1],
+                [0, 0],
+                [-1, 0],
+            ]),
+        ).toBe(true);
+    });
+});