@khanacademy/perseus 20.4.1 → 20.6.0

package/dist/interactive2/movable.d.ts

@@ -57,7 +57,7 @@ export declare class Movable<Options extends Record<string, any>> {
      * Simulates a mouse grab event on the movable object.
      */
     grab(coord: Coord): void;
-    _applyConstraints(current: Coord, previous: Coord, extraOptions?: ConstraintCallbacks): false | [number, number];
+    _applyConstraints(current: Coord, previous: Coord, extraOptions?: ConstraintCallbacks): false | Coord;
     toBack(): void;
     toFront(): void;
     /**

package/dist/interactive2/objective_.d.ts

@@ -7,7 +7,7 @@
  */
 declare const _default: {
     pluck: (table: any, subKey: string) => any;
-    mapObject: <K extends string, V, U>(obj: Partial<Record<K, V>>, lambda: (arg1: V, arg2: K) => U) => Partial<Record<K, U>>;
-    mapObjectFromArray: <K_1 extends string, V_1>(arr: readonly K_1[], lambda: (arg1: K_1) => V_1) => Partial<Record<K_1, V_1>>;
+    mapObject: <K extends string, V, U>(obj: Record<K, V>, lambda: (arg1: V, arg2: K) => U) => Record<K, U>;
+    mapObjectFromArray: <K_1 extends string, V_1>(arr: readonly K_1[], lambda: (arg1: K_1) => V_1) => Record<K_1, V_1>;
 };
 export default _default;

package/dist/perseus-types.d.ts

@@ -3,7 +3,7 @@ import type { Interval, vec } from "mafs";
 export type Range = Interval;
 export type Size = [number, number];
 export type CollinearTuple = readonly [vec.Vector2, vec.Vector2];
-type StyleParams = {
+export type StyleParams = {
     fill?: string;
     stroke?: string;
 };

package/dist/styles/global-styles.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="../../types/aphrodite.d.ts" />
 import type { StyleDeclaration } from "aphrodite";
 export declare const colors: {
     readonly white: "#FFFFFF";

package/dist/styles/shared.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="../../types/aphrodite.d.ts" />
 import type { StyleDeclaration } from "aphrodite";
 declare const _default: StyleDeclaration;
 export default _default;

package/dist/types.d.ts

@@ -75,6 +75,11 @@ type TrackInteractionArgs = {
     id: string;
     correct?: boolean;
 } & Partial<TrackingGradedGroupExtraArguments> & Partial<TrackingSequenceExtraArguments>;
+/**
+ * APIOptions provides different ways to customize the behaviour of Perseus.
+ *
+ * @see APIOptionsWithDefaults
+ */
 export type APIOptions = Readonly<{
     isArticle?: boolean;
     onInputError?: (widgetId: any, value: string, message?: string | null | undefined) => unknown;
@@ -87,25 +92,117 @@ export type APIOptions = Readonly<{
     interactionCallback?: (widgetData: {
         [widgetId: string]: any;
     }) => void;
+    /**
+     * A function that takes in the relative problem number (starts at
+     * 0 and is incremented for each group widget), and the ID of the
+     * group widget, then returns a react component that will be added
+     * immediately above the renderer in the group widget. If the
+     * function returns null, no annotation will be added.
+     */
     groupAnnotator?: (groupNumber: number, widgetId: string) => React.ReactNode;
+    /**
+     * If imagePlaceholder is set, Perseus will render the placeholder instead
+     * of the image node.
+     */
     imagePlaceholder?: React.ReactNode;
+    /**
+     * If widgetPlaceholder is set, Perseus will render the placeholder instead
+     * of the widget node.
+     */
     widgetPlaceholder?: React.ReactNode;
+    /**
+     * Base React elements that can be used in place of the standard DOM
+     * DOM elements. For example, when provided, <Link /> will be used
+     * in place of <a />. This allows clients to provide pre-styled
+     * components or components with custom behavior.
+     */
     baseElements?: {
+        /**
+         * The <Link /> component provided here must adhere to the same
+         * interface as React's base <a /> component.
+         */
         Link: React.ComponentType<any>;
     };
+    /**
+     * Function that takes dimensions and returns a React component
+     * to display while an image is loading.
+     */
     imagePreloader?: (dimensions: Dimensions) => React.ReactNode;
+    /**
+     * A function that is called when the user has interacted with a widget. It
+     * also includes any extra parameters that the originating widget provided.
+     * This is used for keeping track of widget interactions.
+     */
     trackInteraction?: (args: TrackInteractionArgs) => void;
+    /**
+     * A boolean that indicates whether or not a custom keypad is
+     * being used.  For mobile web this will be the ProvidedKeypad
+     * component.  In this situation we use the MathInput component
+     * from the math-input repo instead of the existing perseus math
+     * input components.
+     */
     customKeypad?: boolean;
+    /**
+     * If this is provided, it is called instead of appending an instance
+     * of `math-input`'s keypad to the body. This is used by the native
+     * apps so they can have the keypad be defined on the native side.
+     * It is called with an function that, when called, blurs the input,
+     * and is expected to return an object of the shape
+     * keypadElementPropType from math-input/src/prop-types.js.
+     */
     nativeKeypadProxy?: (blur: () => void) => KeypadAPI;
+    /** Indicates whether or not to use mobile styling. */
     isMobile?: boolean;
+    /** A function, called with a bool indicating whether use of the
+     * drawing area (scratchpad) should be allowed/disallowed.
+     *
+     * Previously handled by `Khan.scratchpad.enable/disable`
+     */
     setDrawingAreaAvailable?: (arg1: boolean) => unknown;
+    /** Whether to use the Draft.js editor or the legacy textarea */
     useDraftEditor?: boolean;
+    /** The color used for the hint progress indicator (eg. 1 / 3) */
     hintProgressColor?: string;
+    /**
+     * Whether this Renderer is allowed to auto-scroll the rest of the
+     * page. For example, if this is enabled, the most recently used
+     * radio widget will attempt to keep the "selected" answer in view
+     * after entering review mode.
+     *
+     * Defaults to `false`.
+     */
     canScrollPage?: boolean;
+    /** Whether or not we are rendering content inside of a modal. */
     inModal?: boolean;
+    /**
+     * Whether to enable the cross-out feature on multiple-choice radio
+     * widgets. This allows users to note which answers they believe to
+     * be incorrect, to find the answer by process of elimination.
+     *
+     * We plan to roll this out to all call sites eventually, but for
+     * now we have this flag, to add it to Generalized Test Prep first.
+     */
     crossOutEnabled?: boolean;
+    /**
+     * The value in milliseconds by which the local state of content
+     * in a editor is delayed before propagated to a prop. For example,
+     * when text is typed in the text area of an Editor component,
+     * there will be a delay equal to the value of `editorChangeDelay`
+     * before the change is propagated. This is added for better
+     * responsiveness of the editor when used in certain contexts such
+     * as StructuredItem exercises where constant re-rendering for each
+     * keystroke caused text typed in the text area to appear in it
+     * only after a good few seconds.
+     */
     editorChangeDelay?: number;
+    /** Feature flags that can be passed from consuming application. */
     flags?: Record<string, boolean | Record<string, boolean>>;
+    /**
+     * 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: PerseusWidgetsMap) => PerseusWidgetsMap;
 }>;
 type TeXProps = {
@@ -181,6 +278,11 @@ export type PerseusDependenciesV2 = {
         onAnalyticsEvent: AnalyticsEventHandlerFn;
     };
 };
+/**
+ * APIOptionsWithDefaults represents the type that is provided to all widgets.
+ * The Renderer fills in these defaults when providing APIOptions to any
+ * widget.
+ */
 export type APIOptionsWithDefaults = Readonly<APIOptions & {
     GroupMetadataEditor: NonNullable<APIOptions["GroupMetadataEditor"]>;
     baseElements: NonNullable<APIOptions["baseElements"]>;

package/dist/util/a11y.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="../../types/aphrodite.d.ts" />
 import type { StyleDeclaration } from "aphrodite";
 declare const _default: StyleDeclaration;
 export default _default;

package/dist/util/extract-perseus-data.d.ts

@@ -1,4 +1,4 @@
-import type { PerseusRenderer } from "../perseus-types";
+import type { PerseusItem, PerseusRenderer } from "../perseus-types";
 /**
  * This function extracts the answers from the widgets.
  *
@@ -23,4 +23,11 @@ declare function getAnswersFromWidgets(widgets: PerseusRenderer["widgets"]): Rea
  * @returns
  */
 declare function injectWidgets(content: string, widgets: PerseusRenderer["widgets"]): string;
+export declare const getWidgetTypeFromWidgetKey: (widgetKey: string) => string;
+export declare const isWrongAnswerSupported: (widgetKeys: Array<string>) => boolean;
+export declare const shouldHaveIndividualAnswer: (widgetKey: string) => boolean;
+export declare const getAnswerFromUserInput: (widgetType: string, userInput: any) => any;
+export declare const getCorrectAnswerForWidgetKey: (widgetKey: string, itemData: PerseusItem) => string | undefined;
+export declare const isWidgetKeyInContent: (perseusItem: PerseusItem, widgetKey: string) => boolean;
+export declare const getValidWidgetKeys: (perseusItem: PerseusItem) => Array<string>;
 export { getAnswersFromWidgets, injectWidgets };

package/dist/util/widget-enum-utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Some helpers for CEDAR logging. CEDAR convention dictates
+ * that enum values should be upper case. Ex: for the
+ * PerseusWidgetUsedInProblemAttempt CEDAR event, we needed
+ * to: get the type and convert that to an enum value.
+ */
+type WidgetName = "categorizer" | "cs-program" | "definition" | "deprecated-standin" | "dropdown" | "explanation" | "expression" | "graded-group-set" | "graded-group" | "grapher" | "group" | "iframe" | "image" | "input-number" | "interaction" | "interactive-graph" | "label-image" | "lights-puzzle" | "matcher" | "matrix" | "measurer" | "molecule-renderer" | "number-line" | "numeric-input" | "orderer" | "passage" | "passage-ref" | "passage-ref-target" | "plotter" | "python-program" | "reaction-diagram" | "radio" | "sequence" | "simulator" | "sorter" | "table" | "unit-input" | "video";
+type WidgetEnum = "CATEGORIZER" | "CS_PROGRAM" | "DEFINITION" | "DEPRECATED_STANDIN" | "DROPDOWN" | "EXPLANATION" | "EXPRESSION" | "GRADED_GROUP" | "GRADED_GROUP_SET" | "GRAPHER" | "GROUP" | "IFRAME" | "IMAGE" | "INPUT_NUMBER" | "INTERACTIVE" | "INTERACTIVE_GRAPH" | "LABEL_IMAGE" | "LIGHTS_PUZZLE" | "MATCHER" | "MATRIX" | "MEASURER" | "MOLECULE" | "NUMBER_LINE" | "NUMERIC_INPUT" | "ORDERER" | "PASSAGE" | "PASSAGE_REF" | "PASSAGE_REF_TARGET" | "PLOTTER" | "PYTHON_PROGRAM" | "REACTION_DIAGRAM" | "RADIO" | "SEQUENCE" | "SIMULATOR" | "SORTER" | "TABLE" | "UNIT" | "VIDEO";
+export declare function convertWidgetNameToEnum(name: WidgetName): WidgetEnum;
+export declare function getWidgetTypeFromWidgetId(widgetId: string): WidgetName;
+export {};

package/dist/util.d.ts

@@ -190,7 +190,7 @@ declare function getWordBeforeCursor(textarea: HTMLTextAreaElement): WordAndPosi
 declare function moveCursor(textarea: HTMLTextAreaElement, pos: number): void;
 declare const Util: {
     readonly inputPathsEqual: typeof inputPathsEqual;
-    readonly nestedMap: <T, M>(children: T | readonly T[], func: (arg1: T) => M, context: unknown) => M | readonly M[];
+    readonly nestedMap: <T, M>(children: T | ReadonlyArray<T>, func: (arg1: T) => M, context: unknown) => M | ReadonlyArray<M>;
     readonly rWidgetRule: RegExp;
     readonly rTypeFromWidgetId: RegExp;
     readonly rWidgetParts: RegExp;

package/dist/widgets/interactive-graph.d.ts

@@ -21,7 +21,7 @@ type DefaultProps = {
     rulerTicks: Props["rulerTicks"];
     graph: Props["graph"];
 };
-declare class InteractiveGraph extends React.Component<Props, State> {
+declare class LegacyInteractiveGraph extends React.Component<Props, State> {
     angle: any | null | undefined;
     circle: any | null | undefined;
     graphie: any | null | undefined;
@@ -39,7 +39,6 @@ declare class InteractiveGraph extends React.Component<Props, State> {
     trashCan: any | null | undefined;
     vertHairline: any | null | undefined;
     static defaultProps: DefaultProps;
-    mafsRef: React.RefObject<Widget>;
     state: State;
     UNSAFE_componentWillMount(): void;
     componentDidMount(): void;
@@ -99,6 +98,14 @@ declare class InteractiveGraph extends React.Component<Props, State> {
     simpleValidate: (rubric: Rubric) => PerseusScore;
     focus: () => void;
     render(): React.ReactNode;
+}
+declare class InteractiveGraph extends React.Component<Props, State> {
+    legacyGraphRef: React.RefObject<LegacyInteractiveGraph>;
+    mafsRef: React.RefObject<Widget>;
+    static defaultProps: DefaultProps;
+    getUserInput: Widget["getUserInput"];
+    simpleValidate: (rubric: Rubric) => PerseusScore;
+    render(): JSX.Element;
     static getQuadraticCoefficients(coords: ReadonlyArray<Coord>): QuadraticCoefficient;
     static getSinusoidCoefficients(coords: ReadonlyArray<Coord>): SineCoefficient;
     /**

package/dist/widgets/interactive-graphs/mafs-graph.d.ts

@@ -71,7 +71,7 @@ export declare const MafsGraph: React.ForwardRefExoticComponent<import("../..").
     onChange: import("../..").ChangeHandler;
     trackInteraction: (extraData?: {} | undefined) => void;
     isLastUsedWidget: boolean;
-    linterContext: import("../../../../perseus-linter/src").LinterContextProps;
+    linterContext: import("@khanacademy/perseus-linter").LinterContextProps;
     containerSizeClass: import("../../util/sizing-utils").SizeClass;
 } & {
     children?: React.ReactNode;

package/dist/widgets/label-image/answer-pill.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="../../../types/aphrodite.d.ts" />
 /// <reference types="react" />
 import { type CSSProperties } from "aphrodite";
 export declare const AnswerPill: (props: {

package/dist/widgets/label-image/marker.d.ts

@@ -3,6 +3,7 @@
  *
  * The target for labeling question image with answers.
  */
+/// <reference path="../../../types/aphrodite.d.ts" />
 import * as React from "react";
 import type { InteractiveMarkerType } from "./types";
 import type { AnalyticsEventHandlerFn } from "@khanacademy/perseus-core";

package/dist/widgets/radio/choice-icon/shared-styles.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="../../../../types/aphrodite.d.ts" />
 import type { StyleDeclaration } from "aphrodite";
 declare const CHOICE_ICON_SIZE = 24;
 declare const styles: StyleDeclaration;

package/dist/widgets/radio.d.ts

@@ -1,4 +1,4 @@
-import Radio from "./radio/widget";
+import Radio from "./radio/radio";
 declare const _default: Readonly<{
     name: string;
     displayName: string;

package/package.json

@@ -3,7 +3,7 @@
     "description": "Core Perseus API (includes renderers and widgets)",
     "author": "Khan Academy",
     "license": "MIT",
-    "version": "20.4.1",
+    "version": "20.6.0",
     "publishConfig": {
         "access": "public"
     },
@@ -30,8 +30,8 @@
         "@khanacademy/math-input": "^17.3.0",
         "@khanacademy/perseus-core": "1.4.2",
         "@khanacademy/perseus-linter": "^0.3.12",
-        "@khanacademy/pure-markdown": "^0.3.0",
-        "@khanacademy/simple-markdown": "^0.11.3",
+        "@khanacademy/pure-markdown": "^0.3.1",
+        "@khanacademy/simple-markdown": "^0.11.4",
         "@khanacademy/wonder-blocks-banner": "^3.0.33",
         "mafs": "https://github.com/Khan/mafs/releases/download/v0.18.1%2Bbuild-cd8b2467893342ba0b02100073fe21f93f8b1125/mafs-0.18.1.tgz"
     },