@khanacademy/perseus 17.8.0 → 18.0.0

package/src/index.ts

@@ -80,6 +80,11 @@ export {default as KhanColors} from "./util/colors";
 export {default as preprocessTex} from "./util/katex-preprocess";
 export {registerAllWidgetsForTesting} from "./util/register-all-widgets-for-testing";
 export * as SizingUtils from "./util/sizing-utils";
+export {
+    getAnswersFromWidgets,
+    injectWidgets,
+} from "./util/extract-perseus-data";
+export {default as parsePerseusJSON} from "./util/parse-perseus-json";
 
 /**
  * Mixins
@@ -116,7 +121,6 @@ export type {
     VideoKind,
     WidgetDict,
     WidgetExports,
-    WidgetInfo,
 } from "./types";
 export type {ParsedValue} from "./util";
 export type {
@@ -130,6 +134,7 @@ export type {
     PerseusPlotterWidgetOptions,
     PerseusRadioWidgetOptions,
     PerseusRenderer,
+    PerseusWidget,
 } from "./perseus-types";
 export type {Coord} from "./interactive2/types";
 export type {MarkerType} from "./widgets/label-image/types";

package/src/init.ts

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

package/src/perseus-types.ts

@@ -97,7 +97,7 @@ type Widget<Type extends string, Options> = {
     // NOTE: perseus_data.go says this is required even though it isn't necessary.
     alignment?: string;
     // Options specific to the type field of the widget.  See Perseus*WidgetOptions for more details
-    options: Options | null | undefined;
+    options: Options;
     // Only used by interactive child widgets (line, point, etc) to identify the components
     // NOTE: perseus_data.go says this is required even though it isn't necessary.
     key?: number;
@@ -704,13 +704,14 @@ export type PerseusMatcherWidgetOptions = {
     padding: boolean;
 };
 
+export type PerseusMatrixWidgetAnswers = ReadonlyArray<ReadonlyArray<number>>;
 export type PerseusMatrixWidgetOptions = {
     // Translatable Text; Shown before the matrix
     prefix: string;
     // Translatable Text; Shown after the matrix
     suffix: string;
     // A data matrix representing the "correct" answers to be entered into the matrix
-    answers: ReadonlyArray<ReadonlyArray<number>>;
+    answers: PerseusMatrixWidgetAnswers;
     // The coordinate location of the cursor position at start. default: [0, 0]
     cursorPosition: ReadonlyArray<number>;
     // The coordinate size of the matrix.  Only supports 2-dimensional matrix.  default: [3, 3]
@@ -821,7 +822,7 @@ export type PerseusNumberLineWidgetOptions = {
     // The correct relative value. default: "eq". options: "eq", "lt", "gt", "le", "ge"
     correctRel: string | null | undefined;
     // This is the correct answer. The answer is validated (as right or wrong) by using only the end position of the point and the relation (=, &lt;, &gt;, ≤, ≥).
-    correctX: number | null | undefined;
+    correctX: number;
     // This controls the initial position of the point along the number line
     initialX: number | null | undefined;
     // Show tooltips

package/src/renderer.tsx

@@ -30,14 +30,17 @@ import WidgetContainer from "./widget-container";
 import * as Widgets from "./widgets";
 
 import type {DependenciesContext} from "./dependencies";
-import type {PerseusRenderer, PerseusWidgetOptions} from "./perseus-types";
+import type {
+    PerseusRenderer,
+    PerseusWidget,
+    PerseusWidgetOptions,
+} from "./perseus-types";
 import type {
     APIOptions,
     APIOptionsWithDefaults,
     FilterCriterion,
     FocusPath,
     PerseusScore,
-    WidgetInfo,
     WidgetProps,
 } from "./types";
 import type {LinterContextProps} from "@khanacademy/perseus-linter";
@@ -179,7 +182,7 @@ type Props = Partial<React.ContextType<typeof DependenciesContext>> & {
 type State = {
     translationLintErrors: ReadonlyArray<string>;
     widgetInfo: Readonly<{
-        [id: string]: WidgetInfo | null | undefined;
+        [id: string]: PerseusWidget | null | undefined;
     }>;
     widgetProps: Readonly<{
         [id: string]: any | null | undefined;
@@ -461,7 +464,7 @@ class Renderer extends React.Component<Props, State> {
 
     // @ts-expect-error - TS2322 - Type '(props: Props) => Partial<Record<string, CategorizerWidget | CSProgramWidget | DefinitionWidget | DropdownWidget | ... 35 more ... | VideoWidget>>' is not assignable to type '(props: Props) => { [key: string]: PerseusWidget; }'.
     _getAllWidgetsInfo: (props: Props) => {
-        [key: string]: WidgetInfo;
+        [key: string]: PerseusWidget;
     } = (props: Props) => {
         // @ts-expect-error - TS2345 - Argument of type '{ [key: string]: PerseusWidget; }' is not assignable to parameter of type 'Partial<Record<string, CategorizerWidget>>'.
         return mapObject(props.widgets, (widgetInfo, widgetId) => {
@@ -483,7 +486,7 @@ class Renderer extends React.Component<Props, State> {
 
     _getAllWidgetsStartProps: (
         allWidgetInfo: {
-            [key: string]: WidgetInfo;
+            [key: string]: PerseusWidget;
         },
         props: Props,
     ) => any = (allWidgetInfo, props) => {
@@ -519,9 +522,9 @@ class Renderer extends React.Component<Props, State> {
         };
     };
 
-    _getWidgetInfo: (widgetId: string) => WidgetInfo = (
+    _getWidgetInfo: (widgetId: string) => PerseusWidget = (
         widgetId: string,
-    ): WidgetInfo => {
+    ): PerseusWidget => {
         return (
             this.state.widgetInfo[widgetId] ||
             this._getDefaultWidgetInfo(widgetId)
@@ -816,14 +819,14 @@ class Renderer extends React.Component<Props, State> {
                 const widgetId = filterCriterion;
                 filterFunc = (
                     id: string,
-                    widgetInfo: WidgetInfo,
+                    widgetInfo: PerseusWidget,
                     widget?: Widget | null,
                 ) => id === widgetId;
             } else {
                 const widgetType = filterCriterion;
                 filterFunc = (
                     id: string,
-                    widgetInfo: WidgetInfo,
+                    widgetInfo: PerseusWidget,
                     widget?: Widget | null,
                 ) => {
                     return widgetInfo.type === widgetType;

package/src/server-item-renderer.tsx

@@ -21,6 +21,7 @@ import {ApiOptions} from "./perseus-api";
 import Renderer from "./renderer";
 import Util from "./util";
 
+import type {PerseusItem} from "./perseus-types";
 import type {APIOptions, FocusPath, PerseusDependenciesV2} from "./types";
 import type {KeypadAPI} from "@khanacademy/math-input";
 import type {
@@ -36,10 +37,7 @@ const {mapObject} = Objective;
 type OwnProps = {
     apiOptions: APIOptions;
     hintsVisible?: number;
-    item: {
-        hints: ReadonlyArray<any>;
-        question: any;
-    };
+    item: PerseusItem;
     linterContext: LinterContextProps;
     problemNum?: number;
     reviewMode?: boolean;

package/src/styles/widgets/image.less

@@ -1,7 +1,4 @@
 .perseus-image-widget {
-    margin-left: auto;
-    margin-right: auto;
-
     .perseus-image-title {
         text-align: center;
     }

package/src/types.ts

@@ -415,12 +415,15 @@ export type WidgetExports<
     // the `validate` method.
     getWidget?: () => T;
     accessible?: boolean | ((props: any) => boolean);
+    /** Supresses widget from showing up in the dropdown in the content editor */
     hidden?: boolean;
-    // The widget version. Any time the _major_ version changes, the widget
-    // should provide a new entry in the propUpgrades map to migrate from the
-    // older version to the current (new) version. Minor version changes must
-    // be backwards compatible with previous minor versions widget options.
-    // This key defaults to `{major: 0, minor: 0}` if not provided.
+    /**
+    The widget version. Any time the _major_ version changes, the widget
+    should provide a new entry in the propUpgrades map to migrate from the
+    older version to the current (new) version. Minor version changes must
+    be backwards compatible with previous minor versions widget options.
+    This key defaults to `{major: 0, minor: 0}` if not provided.
+     */
     version?: Version;
     supportedAlignments?: ReadonlyArray<Alignment>;
     defaultAlignment?: Alignment;
@@ -430,17 +433,19 @@ export type WidgetExports<
 
     traverseChildWidgets?: any; // (Props, traverseRenderer) => NewProps,
 
-    // transforms the widget options to the props used to render the widget
+    /** transforms the widget options to the props used to render the widget */
     transform?: WidgetTransform;
-    // transforms the widget options to the props used to render the widget for
-    // static renders
+    /** transforms the widget options to the props used to render the widget for
+    static renders  */
     staticTransform?: WidgetTransform; // this is a function of some sort,
 
-    // A map of major version numbers (as a string, eg "1") to a function that
-    // migrates from the _previous_ major version.
-    // Example:
-    //   propUpgrades: {'1': (options) => ({...options})}
-    // would migrate from major version 0 to 1.
+    /**
+    A map of major version numbers (as a string, eg "1") to a function that
+    migrates from the _previous_ major version.
+    Example:
+      propUpgrades: {'1': (options) => ({...options})}
+    would migrate from major version 0 to 1.
+    */
     propUpgrades?: {
         [key: string]: (arg1: any) => any;
     }; // OldProps => NewProps,
@@ -448,13 +453,11 @@ export type WidgetExports<
     widget: T;
 }>;
 
-export type WidgetInfo = PerseusWidget;
-
 export type FilterCriterion =
     | string
     | ((
           id: string,
-          widgetInfo: WidgetInfo,
+          widgetInfo: PerseusWidget,
           widget?: Widget | null | undefined,
       ) => boolean);
 

package/src/util/drawing-transform.test.ts

@@ -0,0 +1,67 @@
+import {DrawingTransform} from "./drawing-transform";
+import {GraphBounds} from "./graph-bounds";
+
+import type {Coord} from "../interactive2/types";
+
+describe("DrawingTransform", () => {
+    describe("with bounds of -10 to 10, and 5px per unit", () => {
+        let transform: DrawingTransform;
+        beforeEach(() => {
+            const bounds = new GraphBounds([-10, 10], [-10, 10]);
+            // Each unit in both dimensions is 5 pixels, so the whole graph
+            // is 100px by 100px
+            const scale: [number, number] = [5, 5];
+            transform = new DrawingTransform({setSize() {}}, scale, bounds);
+        });
+
+        const testPoints: [string, Coord, Coord][] = [
+            ["lower left corner", [-10, -10], [0, 100]],
+            ["upper left corner", [-10, 10], [0, 0]],
+            ["lower right corner", [10, -10], [100, 100]],
+            ["upper right corner", [10, 10], [100, 0]],
+            ["origin", [0, 0], [50, 50]],
+        ];
+
+        it.each(testPoints)(
+            "transforms the point at the %s from math coords to canvas coords",
+            (_, cartesian, canvas) => {
+                expect(transform.scalePoint(cartesian)).toEqual(canvas);
+            },
+        );
+
+        it.each(testPoints)(
+            "transforms the point at the %s from canvas coords to math coords",
+            (_, cartesian, canvas) => {
+                expect(transform.unscalePoint(canvas)).toEqual(cartesian);
+            },
+        );
+    });
+
+    it("updates the size of the Raphael canvas when setScale is called with a number", () => {
+        const raphael = {setSize: jest.fn()};
+        const scale: Coord = [40, 40];
+        const bounds = new GraphBounds([-10, 10], [-10, 10]);
+        const transform = new DrawingTransform(raphael, scale, bounds);
+        expect(raphael.setSize).toHaveBeenCalledWith(800, 800);
+
+        // Act
+        transform.setScale(5);
+
+        // Assert
+        expect(raphael.setSize).toHaveBeenCalledWith(100, 100);
+    });
+
+    it("updates the size of the Raphael canvas when setScale is called with dimensions", () => {
+        const raphael = {setSize: jest.fn()};
+        const scale: Coord = [40, 40];
+        const bounds = new GraphBounds([-5, 5], [-5, 5]);
+        const transform = new DrawingTransform(raphael, scale, bounds);
+        expect(raphael.setSize).toHaveBeenCalledWith(400, 400);
+
+        // Act
+        transform.setScale([3, 7]);
+
+        // Assert
+        expect(raphael.setSize).toHaveBeenCalledWith(30, 70);
+    });
+});

package/src/util/drawing-transform.ts

@@ -0,0 +1,102 @@
+import type {GraphBounds} from "./graph-bounds";
+import type {Coord} from "../interactive2/types";
+
+interface Raphael {
+    setSize(width: number, height: number);
+}
+
+// DrawingTransform is responsible for transforming from "math coordinates"
+// (on the Cartesian plane) to "canvas coordinates" in pixels.
+export class DrawingTransform {
+    raphael: Raphael;
+
+    // Scale is measured in pixels per unit on the Cartesian plane.
+    xScale: number;
+    yScale: number;
+    bounds: GraphBounds;
+
+    constructor(
+        raphael: Raphael,
+        initialScale: [number, number],
+        bounds: GraphBounds,
+    ) {
+        this.raphael = raphael;
+        this.bounds = bounds;
+        this.xScale = initialScale[0];
+        this.yScale = initialScale[1];
+        this.setScale(initialScale);
+    }
+
+    // TODO(benchristel): rename these methods to transform* instead of scale*.
+    // They're doing more than scaling! Some of them also translate.
+    scaleVector = (point: number | Coord) => {
+        if (typeof point === "number") {
+            return this.scaleVector([point, point]);
+        }
+
+        const x = point[0];
+        const y = point[1];
+        return [x * this.xScale, y * this.yScale];
+    };
+
+    scalePoint = (point: number | Coord): Coord => {
+        if (typeof point === "number") {
+            return this.scalePoint([point, point]);
+        }
+
+        const x = point[0];
+        const y = point[1];
+        return [
+            (x - this.bounds.xMin) * this.xScale,
+            (this.bounds.yMax - y) * this.yScale,
+        ];
+    };
+
+    unscalePoint = (point: number | Coord) => {
+        if (typeof point === "number") {
+            return this.unscalePoint([point, point]);
+        }
+
+        const x = point[0];
+        const y = point[1];
+        return [
+            x / this.xScale + this.bounds.xMin,
+            this.bounds.yMax - y / this.yScale,
+        ];
+    };
+
+    unscaleVector = (point: number | Coord) => {
+        if (typeof point === "number") {
+            return this.unscaleVector([point, point]);
+        }
+
+        return [point[0] / this.xScale, point[1] / this.yScale];
+    };
+
+    setScale = (scale: number | Coord) => {
+        if (typeof scale === "number") {
+            scale = [scale, scale];
+        }
+
+        this.xScale = scale[0];
+        this.yScale = scale[1];
+
+        // Update the canvas size
+        this.raphael.setSize(...this.canvasDimensions());
+    };
+
+    canvasDimensions = (): Coord => {
+        return [
+            this.bounds.width() * this.xScale,
+            this.bounds.height() * this.yScale,
+        ];
+    };
+
+    pixelsPerUnitX = (): number => {
+        return this.xScale;
+    };
+
+    pixelsPerUnitY = (): number => {
+        return this.yScale;
+    };
+}