@khanacademy/perseus 44.0.0 → 45.1.0

package/dist/interactive2/objective_.d.ts

@@ -5,9 +5,30 @@
  *
  * TODO(aria): Move this out of interactive2
  */
-declare const _default: {
-    pluck: (table: any, subKey: string) => any;
-    mapObject: <K extends string, V, U>(obj: Record<K, V>, lambda: (arg1: V, arg2: K) => U) => Record<K, U>;
-    mapObjectFromArray: <K extends string, V>(arr: ReadonlyArray<K>, lambda: (arg1: K) => V) => Record<K, V>;
-};
-export default _default;
+/**
+ * Does a pluck on keys inside objects in an object
+ *
+ * Ex:
+ * tools = {
+ *     translation: {
+ *         enabled: true
+ *     },
+ *     rotation: {
+ *         enabled: false
+ *     }
+ * };
+ * pluckObject(tools, "enabled") returns {
+ *     translation: true
+ *     rotation: false
+ * }
+ */
+export declare const pluck: (table: any, subKey: string) => any;
+/**
+ * Maps an object to an object
+ *
+ * > mapObject({a: '1', b: '2'}, (value, key) => {
+ *       return value + 1;
+ *   });
+ * {a: 2, b: 3}
+ */
+export declare const mapObject: <K extends string, V, U>(obj: Record<K, V>, lambda: (arg1: V, arg2: K) => U) => Record<K, U>;

package/dist/perseus-types.d.ts

@@ -4,72 +4,99 @@ export type Range = Interval;
 export type Size = [number, number];
 export type CollinearTuple = [vec.Vector2, vec.Vector2];
 export type ShowSolutions = "all" | "selected" | "none";
+/**
+ * Our core set of Perseus widgets.
+ *
+ * This interface is the basis for "registering" all Perseus widget types.
+ * There should be one key/value pair for each supported widget. If you create
+ * a new widget, an entry should be added to this interface. Note that this
+ * only registers the widget options type, you'll also need to register the
+ * widget so that it's available at runtime (@see
+ * {@link file://./widgets.ts#registerWidget}).
+ *
+ * Importantly, the key should be the name that is used in widget IDs. For most
+ * widgets that is the same as the widget option's `type` field. In cases where
+ * a widget has been deprecated and replaced with the deprecated-standin
+ * widget, it should be the original widget type!
+ *
+ * If you define the widget outside of this package, you can still add the new
+ * widget to this interface by writing the following in that package that
+ * contains the widget. TypeScript will merge that definition of the
+ * `PerseusWidgets` with the one defined below.
+ *
+ * ```typescript
+ * declare module "@khanacademy/perseus" {
+ *     interface PerseusWidgetTypes {
+ *         // A new widget
+ *         "new-awesomeness": MyAwesomeNewWidget;
+ *
+ *         // A deprecated widget
+ *         "super-old-widget": AutoCorrectWidget;
+ *     }
+ * }
+ *
+ * // The new widget's options definition
+ * type MyAwesomeNewWidget = WidgetOptions<'new-awesomeness', MyAwesomeNewWidgetOptions>;
+ *
+ * // The deprecated widget's options definition
+ * type SuperOldWidget = WidgetOptions<'super-old-widget', object>;
+ * ```
+ *
+ * This interface can be extended through the magic of TypeScript "Declaration
+ * merging". Specifically, we augment this module and extend this interface.
+ *
+ * @see {@link https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation}
+ */
+export interface PerseusWidgetTypes {
+    categorizer: CategorizerWidget;
+    "cs-program": CSProgramWidget;
+    definition: DefinitionWidget;
+    dropdown: DropdownWidget;
+    explanation: ExplanationWidget;
+    expression: ExpressionWidget;
+    grapher: GrapherWidget;
+    "graded-group-set": GradedGroupSetWidget;
+    "graded-group": GradedGroupWidget;
+    group: GroupWidget;
+    iframe: IFrameWidget;
+    image: ImageWidget;
+    "input-number": InputNumberWidget;
+    interaction: InteractionWidget;
+    "interactive-graph": InteractiveGraphWidget;
+    "label-image": LabelImageWidget;
+    matcher: MatcherWidget;
+    matrix: MatrixWidget;
+    measurer: MeasurerWidget;
+    "molecule-renderer": MoleculeRendererWidget;
+    "number-line": NumberLineWidget;
+    "numeric-input": NumericInputWidget;
+    orderer: OrdererWidget;
+    "passage-ref-target": RefTargetWidget;
+    "passage-ref": PassageRefWidget;
+    passage: PassageWidget;
+    "phet-simulation": PhetSimulationWidget;
+    "python-program": PythonProgramWidget;
+    plotter: PlotterWidget;
+    radio: RadioWidget;
+    sorter: SorterWidget;
+    table: TableWidget;
+    video: VideoWidget;
+    sequence: AutoCorrectWidget;
+}
+/**
+ * A map of widget IDs to widget options. This is most often used as the type
+ * for a set of widgets defined in a `PerseusItem` but can also be useful to
+ * represent a function parameter where only `widgets` from a `PerseusItem` are
+ * needed. Today Widget IDs are made up of the widget type and an incrementing
+ * integer (eg. `interactive-graph 1` or `radio 3`). It is suggested to avoid
+ * reading/parsing the widget id to derive any information from it, except in
+ * the case of this map.
+ *
+ * @see {@link PerseusWidgetTypes} additional widgets can be added to this map type
+ * by augmenting the PerseusWidgetTypes with new widget types!
+ */
 export type PerseusWidgetsMap = {
-    [key in `categorizer ${number}`]: CategorizerWidget;
-} & {
-    [key in `cs-program ${number}`]: CSProgramWidget;
-} & {
-    [key in `definition ${number}`]: DefinitionWidget;
-} & {
-    [key in `dropdown ${number}`]: DropdownWidget;
-} & {
-    [key in `explanation ${number}`]: ExplanationWidget;
-} & {
-    [key in `expression ${number}`]: ExpressionWidget;
-} & {
-    [key in `grapher ${number}`]: GrapherWidget;
-} & {
-    [key in `group ${number}`]: GroupWidget;
-} & {
-    [key in `graded-group ${number}`]: GradedGroupWidget;
-} & {
-    [key in `graded-group-set ${number}`]: GradedGroupSetWidget;
-} & {
-    [key in `iframe ${number}`]: IFrameWidget;
-} & {
-    [key in `image ${number}`]: ImageWidget;
-} & {
-    [key in `input-number ${number}`]: InputNumberWidget;
-} & {
-    [key in `interaction ${number}`]: InteractionWidget;
-} & {
-    [key in `interactive-graph ${number}`]: InteractiveGraphWidget;
-} & {
-    [key in `label-image ${number}`]: LabelImageWidget;
-} & {
-    [key in `matcher ${number}`]: MatcherWidget;
-} & {
-    [key in `matrix ${number}`]: MatrixWidget;
-} & {
-    [key in `measurer ${number}`]: MeasurerWidget;
-} & {
-    [key in `molecule-renderer ${number}`]: MoleculeRendererWidget;
-} & {
-    [key in `number-line ${number}`]: NumberLineWidget;
-} & {
-    [key in `numeric-input ${number}`]: NumericInputWidget;
-} & {
-    [key in `orderer ${number}`]: OrdererWidget;
-} & {
-    [key in `passage ${number}`]: PassageWidget;
-} & {
-    [key in `passage-ref ${number}`]: PassageRefWidget;
-} & {
-    [key in `passage-ref-target ${number}`]: PassageRefWidget;
-} & {
-    [key in `phet-simulation ${number}`]: PhetSimulationWidget;
-} & {
-    [key in `plotter ${number}`]: PlotterWidget;
-} & {
-    [key in `python-program ${number}`]: PythonProgramWidget;
-} & {
-    [key in `radio ${number}`]: RadioWidget;
-} & {
-    [key in `sorter ${number}`]: SorterWidget;
-} & {
-    [key in `table ${number}`]: TableWidget;
-} & {
-    [key in `video ${number}`]: VideoWidget;
+    [Property in keyof PerseusWidgetTypes as `${Property} ${number}`]: PerseusWidgetTypes[Property];
 };
 /**
  * A "PerseusItem" is a classic Perseus item. It is rendered by the
@@ -101,6 +128,9 @@ export type PerseusArticle = PerseusRenderer | ReadonlyArray<PerseusRenderer>;
  * A "MultiItem" is an advanced Perseus item. It is rendered by the
  * `MultiRenderer` and you can control the layout of individual parts of the
  * item.
+ *
+ * @deprecated MultiItem support is slated for removal in a future Perseus
+ * release.
  */
 export type MultiItem = {
     _multi: any;
@@ -110,11 +140,25 @@ export type Version = {
     minor: number;
 };
 export type PerseusRenderer = {
+    /**
+     * Translatable Markdown content to be rendered.  May include references to
+     * widgets (as [[☃ widgetName]]) or images (as ![image text](imageUrl)).
+     * For each image found in this content, there can be an entry in the
+     * `images` dict (below) with the key being the image's url which defines
+     * additional attributes for the image.
+     */
     content: string;
+    /**
+     * A dictionary of {[widgetName]: Widget} to be referenced from the content
+     * field.
+     */
     widgets: PerseusWidgetsMap;
     metadata?: ReadonlyArray<string>;
+    /**
+     * A dictionary of {[imageUrl]: PerseusImageDetail}.
+     */
     images: {
-        [key: string]: PerseusImageDetail;
+        [imageUrl: string]: PerseusImageDetail;
     };
 };
 export type Hint = PerseusRenderer & {
@@ -131,6 +175,10 @@ export type PerseusImageDetail = {
 };
 export declare const ItemExtras: readonly ["calculator", "chi2Table", "financialCalculatorMonthlyPayment", "financialCalculatorTotalAmount", "financialCalculatorTimeToPayOff", "periodicTable", "periodicTableWithKey", "tTable", "zTable"];
 export type PerseusAnswerArea = Record<(typeof ItemExtras)[number], boolean>;
+/**
+ * The type representing the common structure of all widget's options. The
+ * `Options` generic type represents the widget-specific option data.
+ */
 export type WidgetOptions<Type extends string, Options> = {
     type: Type;
     static?: boolean;
@@ -173,8 +221,11 @@ export type InputNumberWidget = WidgetOptions<'input-number', PerseusInputNumber
 export type MoleculeRendererWidget = WidgetOptions<'molecule-renderer', PerseusMoleculeRendererWidgetOptions>;
 export type RefTargetWidget = WidgetOptions<'passage-ref-target', PerseusPassageRefTargetWidgetOptions>;
 export type VideoWidget = WidgetOptions<'video', PerseusVideoWidgetOptions>;
-export type AutoCorrectWidget = WidgetOptions<'deprecated-standin', PerseusWidgetOptions>;
+export type AutoCorrectWidget = WidgetOptions<'deprecated-standin', object>;
 export type PerseusWidget = CategorizerWidget | CSProgramWidget | DefinitionWidget | DropdownWidget | ExplanationWidget | ExpressionWidget | GradedGroupSetWidget | GradedGroupWidget | GrapherWidget | GroupWidget | IFrameWidget | ImageWidget | InputNumberWidget | InteractionWidget | InteractiveGraphWidget | LabelImageWidget | MatcherWidget | MatrixWidget | MeasurerWidget | MoleculeRendererWidget | NumberLineWidget | NumericInputWidget | OrdererWidget | PassageRefWidget | PassageWidget | PhetSimulationWidget | PlotterWidget | PythonProgramWidget | RadioWidget | RefTargetWidget | SorterWidget | TableWidget | VideoWidget | AutoCorrectWidget;
+/**
+ * A background image applied to various widgets.
+ */
 export type PerseusImageBackground = {
     url: string | null | undefined;
     width?: number;
@@ -334,8 +385,8 @@ export type PerseusImageLabel = {
 };
 export type PerseusInteractiveGraphWidgetOptions = {
     step: [number, number];
-    gridStep: [number, number];
-    snapStep: [number, number];
+    gridStep?: [x: number, y: number];
+    snapStep?: [x: number, y: number];
     backgroundImage?: PerseusImageBackground;
     /**
      * The type of markings to display on the graph.
@@ -344,7 +395,7 @@ export type PerseusInteractiveGraphWidgetOptions = {
      * - none: shows no markings
      */
     markings: "graph" | "grid" | "none";
-    labels: ReadonlyArray<string>;
+    labels?: ReadonlyArray<string>;
     showProtractor: boolean;
     /**
      * Whether to show the Ruler tool overlayed on top of the graph.
@@ -621,7 +672,7 @@ export type PerseusNumericInputAnswerForm = {
 };
 export type PerseusNumericInputWidgetOptions = {
     answers: ReadonlyArray<PerseusNumericInputAnswer>;
-    labelText: string;
+    labelText?: string | undefined;
     size: string;
     coefficient: boolean;
     rightAlign?: boolean;
@@ -630,7 +681,7 @@ export type PerseusNumericInputWidgetOptions = {
 };
 export type PerseusNumericInputAnswer = {
     message: string;
-    value: number;
+    value?: number;
     status: string;
     answerForms?: ReadonlyArray<MathFormat>;
     strict: boolean;

package/dist/renderer-util.d.ts

@@ -1,8 +1,10 @@
-import type { PerseusWidgetsMap } from "./perseus-types";
+import type { PerseusRenderer, PerseusWidgetsMap } from "./perseus-types";
 import type { PerseusStrings } from "./strings";
 import type { PerseusScore } from "./types";
 import type { UserInputMap } from "./validation.types";
+export declare function getUpgradedWidgetOptions(oldWidgetOptions: PerseusWidgetsMap): PerseusWidgetsMap;
 export declare function emptyWidgetsFunctional(widgets: PerseusWidgetsMap, widgetIds: Array<string>, userInputMap: UserInputMap, strings: PerseusStrings, locale: string): ReadonlyArray<string>;
-export declare function scoreWidgetsFunctional(widgets: PerseusWidgetsMap, widgetIds: Array<string>, userInputMap: UserInputMap, strings: PerseusStrings, locale: string): {
+export declare function scorePerseusItem(perseusRenderData: PerseusRenderer, userInputMap: UserInputMap, strings: PerseusStrings, locale: string): PerseusScore;
+export declare function scoreWidgetsFunctional(widgets: PerseusWidgetsMap, widgetIds: ReadonlyArray<string>, userInputMap: UserInputMap, strings: PerseusStrings, locale: string): {
     [widgetId: string]: PerseusScore;
 };

package/dist/renderer.d.ts

@@ -103,7 +103,6 @@ declare class Renderer extends React.Component<Props, State> implements GetPromp
         widgetInfo: State["widgetInfo"];
         widgetProps: State["widgetProps"];
     };
-    _getAllWidgetsInfo: (props: Props) => PerseusWidgetsMap;
     _getAllWidgetsStartProps: (allWidgetInfo: PerseusWidgetsMap, props: Props) => PerseusWidgetsMap;
     _getDefaultWidgetInfo: (widgetId: string) => any;
     _getWidgetInfo: (widgetId: string) => PerseusWidget;
@@ -193,9 +192,15 @@ declare class Renderer extends React.Component<Props, State> implements GetPromp
     blurPath: (path: FocusPath) => void;
     blur: () => void;
     serialize: () => Record<any, any>;
+    /**
+     * Returns an array of widget ids that are empty (meaning widgets where the
+     * learner has not interacted with the widget yet or has not filled in all
+     * fields).  For example, the `interactive-graph` widget is considered
+     * empty if the graph is in the starting state.
+     */
     emptyWidgets(): ReadonlyArray<string>;
     _setWidgetProps: SetWidgetPropsFn;
-    setInputValue: (path: FocusPath, newValue: string, focus?: () => unknown) => void;
+    setInputValue: (path: FocusPath, newValue: string, cb?: () => void) => void;
     /**
      * Returns an array of the widget `.getUserInput()` results
      *
@@ -218,18 +223,15 @@ declare class Renderer extends React.Component<Props, State> implements GetPromp
      */
     getPromptJSON(): RendererPromptJSON;
     /**
-     * Returns an object mapping from widget ID to perseus-style score.
-     * The keys of this object are the values of the array returned
-     * from `getWidgetIds`.
+     * Scores the content.
+     *
+     * @deprecated use scorePerseusItem
      */
-    scoreWidgets(): {
-        [widgetId: string]: PerseusScore;
-    };
+    score(): PerseusScore;
     /**
-     * Grades the content.
+     * @deprecated use scorePerseusItem
      */
-    score(): PerseusScore;
-    guessAndScore(): [UserInputArray, PerseusScore];
+    guessAndScore: () => [UserInputArray, PerseusScore];
     examples: () => ReadonlyArray<string> | null | undefined;
     handletranslationLintErrors: (lintErrors: ReadonlyArray<string>) => void;
     render(): React.ReactNode;

package/dist/server-item-renderer.d.ts

@@ -12,12 +12,14 @@ import { PerseusI18nContext } from "./components/i18n-context";
 import Renderer from "./renderer";
 import type { PerseusItem, ShowSolutions } from "./perseus-types";
 import type { FocusPath, PerseusDependenciesV2, SharedRendererProps } from "./types";
+import type { UserInputArray, UserInputMap } from "./validation.types";
 import type { GetPromptJSONInterface, RendererPromptJSON } from "./widget-ai-utils/prompt-types";
 import type { KeypadAPI } from "@khanacademy/math-input";
 import type { KeypadContextRendererInterface, RendererInterface, KEScore } from "@khanacademy/perseus-core";
 type OwnProps = {
     hintsVisible?: number;
     item: PerseusItem;
+    score?: KEScore | null;
     problemNum?: number;
     reviewMode?: boolean;
     keypadElement?: KeypadAPI | null | undefined;
@@ -30,8 +32,23 @@ type HOCProps = {
 type Props = SharedRendererProps & OwnProps & HOCProps;
 type DefaultProps = Required<Pick<Props, "apiOptions" | "onRendered" | "linterContext">>;
 type State = {
+    /**
+     * questionCompleted is used to signal that a learner has attempted
+     * the exercise. This is used when widgets want to show things like
+     * rationale or partial correctness.
+     */
     questionCompleted: boolean;
-    questionHighlightedWidgets: ReadonlyArray<any>;
+    /**
+     * As far as I can tell, this is used to highlight empty widgets
+     * after a learner has clicked the "check" button. I don't think this could
+     * still be used though, because the "check" button is disabled while there
+     * are empty widgets.
+     */
+    questionHighlightedWidgets: ReadonlyArray<string>;
+    /**
+     * Keeps track of whether each asset (SvgImage or TeX) rendered by
+     * the questionRenderer has finished loading or rendering.
+     */
     assetStatuses: {
         [assetKey: string]: boolean;
     };
@@ -76,8 +93,22 @@ export declare class ServerItemRenderer extends React.Component<Props, State> im
     blur(): void;
     getNumHints(): number;
     getPromptJSON(): RendererPromptJSON;
+    /**
+     * Returns an array of the widget `.getUserInput()` results
+     *
+     * TODO: can we remove this? Seems to be just for backwards
+     * compatibility with old Perseus Chrome logging
+     * @deprecated use getUserInput
+     */
+    getUserInputLegacy(): UserInputArray;
+    /**
+     * Returns an object of the widget `.getUserInput()` results
+     */
+    getUserInput(): UserInputMap;
     /**
      * Grades the item.
+     *
+     * @deprecated use scorePerseusItem
      */
     scoreInput(): KEScore;
     /**

package/dist/types.d.ts

@@ -46,6 +46,12 @@ export interface Widget {
     } | boolean;
     getDOMNodeForPath?: (path: FocusPath) => Element | Text | null;
     deselectIncorrectSelectedChoices?: () => void;
+    /**
+     * Returns widget state that can be passed back to `restoreSerializedState`
+     * to put the widget back into exactly the same state. If the widget does
+     * not implement this function, the renderer simply returns all of the
+     * widget's props.
+     */
     getSerializedState?: () => SerializedState;
     restoreSerializedState?: (props: any, callback: () => void) => any;
     blurInputPath?: (path: FocusPath) => void;
@@ -103,7 +109,7 @@ export type ChangeHandler = (arg1: {
     selected?: number;
     plot?: any;
     graph?: PerseusGraphType;
-}, callback?: () => unknown | null | undefined, silent?: boolean) => unknown;
+}, callback?: () => void, silent?: boolean) => unknown;
 export type ImageUploader = (file: File, callback: (url: string) => unknown) => unknown;
 export type Path = ReadonlyArray<string>;
 type StubTagEditorType = any;
@@ -297,6 +303,17 @@ type InitialRequestUrlInterface = {
     protocol: string;
 };
 export type VideoKind = "YOUTUBE_ID" | "READABLE_ID";
+/**
+ * An object for dependency injection, to allow different clients
+ * to provide different methods for logging, translation, network
+ * requests, etc.
+ *
+ * NOTE: You should avoid adding new dependencies here as this type was added
+ * as a quick fix to get around the fact that some of the dependencies Perseus
+ * needs are used in places where neither `APIOptions` nor a React Context
+ * could be used. Aim to shrink the footprint of PerseusDependencies and try to
+ * use alternative methods where possible.
+ */
 export type PerseusDependencies = {
     JIPT: JIPT;
     graphieMovablesJiptLabels: JiptLabelStore;
@@ -353,6 +370,11 @@ type TrackingSequenceExtraArguments = {
 };
 export type Alignment = "default" | "block" | "inline-block" | "inline" | "float-left" | "float-right" | "full-width";
 type WidgetOptions = any;
+/**
+ * A transform that maps the WidgetOptions (sometimes referred to as
+ * EditorProps) to the props used to render the widget. Often this is an
+ * identity transform.
+ */
 export type WidgetTransform = (arg1: WidgetOptions, strings: PerseusStrings, problemNumber?: number) => any;
 export type WidgetScorerFunction = (userInput: UserInput, rubric: Rubric, string?: PerseusStrings, locale?: string) => PerseusScore;
 export type WidgetExports<T extends React.ComponentType<any> & Widget = React.ComponentType<any>> = Readonly<{
@@ -364,11 +386,12 @@ export type WidgetExports<T extends React.ComponentType<any> & Widget = React.Co
     /** 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>;
@@ -377,25 +400,44 @@ export type WidgetExports<T extends React.ComponentType<any> & Widget = React.Co
     isLintable?: boolean;
     tracking?: Tracking;
     traverseChildWidgets?: any;
-    /** 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;
+    /**
+     * A function that scores user input (the guess) for the widget.
+     */
     scorer?: WidgetScorerFunction;
     getOneCorrectAnswerFromRubric?: (rubric: Rubric) => string | null | undefined;
     /**
-    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})}
+     * ```
+     *
+     * This configuration would migrate options from major version 0 to 1.
+     */
     propUpgrades?: {
-        [key: string]: (arg1: any) => any;
+        [targetMajorVersion: string]: (arg1: any) => any;
     };
 }>;
 export type FilterCriterion = string | ((id: string, widgetInfo: PerseusWidget, widget?: Widget | null | undefined) => boolean);
+/**
+ * The full set of props provided to all widgets when they are rendered. The
+ * `RenderProps` generic argument are the widget-specific props that originate
+ * from the stored PerseusItem. Note that they may not match the serialized
+ * widget options exactly as they are the result of running the options through
+ * any `propUpgrades` the widget defines as well as its `transform` or
+ * `staticTransform` functions (depending on the options `static` flag).
+ */
 export type WidgetProps<RenderProps, Rubric = Empty, TrackingExtraArgs = Empty> = RenderProps & {
     widgetId: string;
     alignment: string | null | undefined;
@@ -403,6 +445,11 @@ export type WidgetProps<RenderProps, Rubric = Empty, TrackingExtraArgs = Empty>
     problemNum: number | null | undefined;
     apiOptions: APIOptionsWithDefaults;
     keypadElement?: any;
+    /**
+     * questionCompleted is used to signal that a learner has attempted
+     * the exercise. This is used when widgets want to show things like
+     * rationale or partial correctness.
+     */
     questionCompleted?: boolean;
     onFocus: (blurPath: FocusPath) => void;
     onBlur: (blurPath: FocusPath) => void;

package/dist/util/parse-perseus-json/general-purpose-parsers/string-to-number.d.ts

@@ -0,0 +1,2 @@
+import type { PartialParser } from "../parser-types";
+export declare const stringToNumber: PartialParser<string | number, number>;

package/dist/validation.types.d.ts

@@ -27,7 +27,7 @@
  * } & Perseus<Widget>ValidationData;
  * ```
  */
-import type { GrapherAnswerTypes, PerseusDropdownChoice, PerseusExpressionAnswerForm, PerseusGradedGroupSetWidgetOptions, PerseusGradedGroupWidgetOptions, PerseusGraphType, PerseusGroupWidgetOptions, PerseusMatcherWidgetOptions, PerseusMatrixWidgetAnswers, PerseusNumberLineWidgetOptions, PerseusNumericInputAnswer, PerseusOrdererWidgetOptions, PerseusRadioChoice, PerseusGraphCorrectType } from "./perseus-types";
+import type { GrapherAnswerTypes, PerseusDropdownChoice, PerseusExpressionAnswerForm, PerseusGradedGroupSetWidgetOptions, PerseusGradedGroupWidgetOptions, PerseusGraphType, PerseusGroupWidgetOptions, PerseusMatcherWidgetOptions, PerseusMatrixWidgetAnswers, PerseusNumericInputAnswer, PerseusOrdererWidgetOptions, PerseusRadioChoice, PerseusGraphCorrectType } from "./perseus-types";
 import type { InteractiveMarkerType } from "./widgets/label-image/types";
 import type { Relationship } from "./widgets/number-line/number-line";
 export type UserInputStatus = "correct" | "incorrect" | "incomplete";
@@ -57,6 +57,7 @@ export type PerseusExpressionRubric = {
 };
 export type PerseusExpressionUserInput = string;
 export type PerseusGroupRubric = PerseusGroupWidgetOptions;
+export type PerseusGroupUserInput = UserInputMap;
 export type PerseusGradedGroupRubric = PerseusGradedGroupWidgetOptions;
 export type PerseusGradedGroupSetRubric = PerseusGradedGroupSetWidgetOptions;
 export type PerseusGrapherRubric = {
@@ -99,7 +100,11 @@ export type PerseusMatrixValidationData = Empty;
 export type PerseusMatrixUserInput = {
     answers: PerseusMatrixRubric["answers"];
 };
-export type PerseusNumberLineRubric = PerseusNumberLineWidgetOptions & {
+export type PerseusNumberLineScoringData = {
+    correctRel: string | null | undefined;
+    correctX: number;
+    range: ReadonlyArray<number>;
+    initialX: number | null | undefined;
     isInequality: boolean;
 };
 export type PerseusNumberLineUserInput = {
@@ -144,7 +149,7 @@ export type PerseusTableRubric = {
     answers: ReadonlyArray<ReadonlyArray<string>>;
 };
 export type PerseusTableUserInput = ReadonlyArray<ReadonlyArray<string>>;
-export type Rubric = PerseusCategorizerScoringData | PerseusCSProgramRubric | PerseusDropdownRubric | PerseusExpressionRubric | PerseusGroupRubric | PerseusGradedGroupRubric | PerseusGradedGroupSetRubric | PerseusGrapherRubric | PerseusIFrameRubric | PerseusInputNumberRubric | PerseusInteractiveGraphRubric | PerseusLabelImageRubric | PerseusMatcherRubric | PerseusMatrixRubric | PerseusNumberLineRubric | PerseusNumericInputRubric | PerseusOrdererRubric | PerseusPlotterScoringData | PerseusRadioRubric | PerseusSorterRubric | PerseusTableRubric;
+export type Rubric = PerseusCategorizerScoringData | PerseusCSProgramRubric | PerseusDropdownRubric | PerseusExpressionRubric | PerseusGroupRubric | PerseusGradedGroupRubric | PerseusGradedGroupSetRubric | PerseusGrapherRubric | PerseusIFrameRubric | PerseusInputNumberRubric | PerseusInteractiveGraphRubric | PerseusLabelImageRubric | PerseusMatcherRubric | PerseusMatrixRubric | PerseusNumberLineScoringData | PerseusNumericInputRubric | PerseusOrdererRubric | PerseusPlotterScoringData | PerseusRadioRubric | PerseusSorterRubric | PerseusTableRubric;
 export type UserInput = PerseusCategorizerUserInput | PerseusCSProgramUserInput | PerseusDropdownUserInput | PerseusExpressionUserInput | PerseusGrapherUserInput | PerseusIFrameUserInput | PerseusInputNumberUserInput | PerseusInteractiveGraphUserInput | PerseusLabelImageUserInput | PerseusMatcherUserInput | PerseusMatrixUserInput | PerseusNumberLineUserInput | PerseusNumericInputUserInput | PerseusOrdererUserInput | PerseusPlotterUserInput | PerseusRadioUserInput | PerseusSorterUserInput | PerseusTableUserInput;
 export type UserInputMap = {
     [widgetId: string]: UserInput | UserInputMap;

package/dist/widgets/deprecated-standin/deprecated-standin.d.ts

@@ -1,7 +1,7 @@
 import React from "react";
 import { PerseusI18nContext } from "../../components/i18n-context";
 import type { Widget } from "../../types";
-type Props = any;
+type Props = object;
 declare class DeprecatedStandin extends React.Component<Props> implements Widget {
     static contextType: React.Context<{
         strings: import("../../strings").PerseusStrings;

package/dist/widgets/expression/expression.d.ts

@@ -172,7 +172,7 @@ declare const _default: {
         visibleLabel: PerseusExpressionWidgetOptions["visibleLabel"];
         ariaLabel: PerseusExpressionWidgetOptions["ariaLabel"];
         value: string;
-    }, "ariaLabel" | "static" | "onChange" | "keypadElement" | "containerSizeClass" | "widgetId" | "problemNum" | "questionCompleted" | "findWidgets" | "trackInteraction" | "reviewMode" | keyof import("../..").PerseusDependenciesV2 | "alignment" | "reviewModeRubric" | "isLastUsedWidget" | "visibleLabel" | "buttonsVisible" | "keypadConfiguration"> & {
+    }, "ariaLabel" | "static" | "onChange" | "keypadElement" | "containerSizeClass" | "widgetId" | "problemNum" | "questionCompleted" | "findWidgets" | "trackInteraction" | "alignment" | "reviewMode" | keyof import("../..").PerseusDependenciesV2 | "reviewModeRubric" | "isLastUsedWidget" | "visibleLabel" | "buttonsVisible" | "keypadConfiguration"> & {
         value?: string | undefined;
         onFocus?: ((blurPath: FocusPath) => void) | undefined;
         onBlur?: ((blurPath: FocusPath) => void) | undefined;

package/dist/widgets/group/group.d.ts

@@ -1,6 +1,7 @@
 import * as React from "react";
 import { PerseusI18nContext } from "../../components/i18n-context";
 import Renderer from "../../renderer";
+import scoreGroup from "./score-group";
 import type { PerseusGroupWidgetOptions } from "../../perseus-types";
 import type { ChangeFn, FocusPath, Widget, WidgetProps } from "../../types";
 import type { PerseusGroupRubric, UserInputArray } from "../../validation.types";
@@ -23,7 +24,7 @@ declare class Group extends React.Component<Props> implements Widget {
     static defaultProps: DefaultProps;
     componentDidMount(): void;
     change: ChangeFn;
-    getUserInputMap(): import("../../validation.types").UserInputMap | undefined;
+    getUserInputMap(): import("../..").UserInputMap | undefined;
     /**
      * @deprecated getUserInputMap should be used for Groups
      */
@@ -44,6 +45,7 @@ declare const _default: {
     displayName: string;
     widget: typeof Group;
     traverseChildWidgets: (props: any, traverseRenderer: any) => any;
+    scorer: typeof scoreGroup;
     hidden: true;
     isLintable: true;
 };

package/dist/widgets/group/score-group.d.ts

@@ -0,0 +1,5 @@
+import type { PerseusStrings } from "../../strings";
+import type { PerseusScore } from "../../types";
+import type { PerseusGroupRubric, PerseusGroupUserInput } from "../../validation.types";
+declare function scoreGroup(userInput: PerseusGroupUserInput, options: PerseusGroupRubric, strings: PerseusStrings, locale: string): PerseusScore;
+export default scoreGroup;