@khanacademy/perseus 77.2.0 → 77.2.2

package/dist/renderer.d.ts

@@ -5,7 +5,7 @@ import TranslationLinter from "./translation-linter";
 import WidgetContainer from "./widget-container";
 import type { DependenciesContext } from "./dependencies";
 import type { PerseusStrings } from "./strings";
-import type { APIOptions, APIOptionsWithDefaults, FilterCriterion, FocusPath, Widget, WidgetProps } from "./types";
+import type { APIOptions, APIOptionsWithDefaults, FilterCriterion, FindWidgetsFunction, FocusPath, Widget, WidgetProps } from "./types";
 import type { HandleUserInputCallback, InitializeUserInputCallback } from "./user-input-manager";
 import type { GetPromptJSONInterface, RendererPromptJSON } from "./widget-ai-utils/prompt-types";
 import type { KeypadAPI } from "@khanacademy/math-input";
@@ -29,7 +29,7 @@ type Props = Partial<React.ContextType<typeof DependenciesContext>> & {
     handleUserInput?: HandleUserInputCallback;
     initializeUserInput?: InitializeUserInputCallback;
     alwaysUpdate?: boolean;
-    findExternalWidgets: (criterion: FilterCriterion) => any;
+    findExternalWidgets: FindWidgetsFunction;
     keypadElement?: KeypadAPI | null;
     onRender: (node?: any) => void;
     problemNum?: number;
@@ -147,7 +147,7 @@ declare class Renderer extends React.Component<Props, State> implements GetPromp
      * Includes both widgets internal to this Renderer, and external widgets
      * exposed by the `findExternalWidgets` prop.
      *
-     * See `findInteralWidgets` for more information.
+     * See `findInternalWidgets` for more information.
      */
     findWidgets: (filterCriterion: FilterCriterion) => any;
     getWidgetInstance: (id: string) => Widget | null | undefined;

package/dist/testing/test-dependencies.d.ts

@@ -1,7 +1,6 @@
 import type { PerseusDependencies, PerseusDependenciesV2 } from "../types";
 export declare const testDependencies: PerseusDependencies;
 export declare const testDependenciesV2: PerseusDependenciesV2;
-export declare const storybookTestDependencies: PerseusDependencies;
 export declare const storybookDependenciesV2: PerseusDependenciesV2;
 export declare const cypressTestDependencies: PerseusDependencies;
 export declare const cypressDependenciesV2: PerseusDependenciesV2;

package/dist/types.d.ts

@@ -368,6 +368,7 @@ export type WidgetExports<T extends React.ComponentType<any> & Widget = React.Co
     getCorrectUserInput?: (widgetOptions: WidgetOptions) => TUserInput;
     getStartUserInput?: (widgetOptions: WidgetOptions, problemNum: number) => TUserInput;
 }>;
+export type FindWidgetsFunction = (filterFunc: FilterCriterion) => ReadonlyArray<Widget | null | undefined>;
 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
@@ -389,7 +390,7 @@ type UniversalWidgetProps<TUserInput = Empty, TrackingExtraArgs = Empty> = {
     keypadElement?: any;
     onFocus: (blurPath: FocusPath) => void;
     onBlur: (blurPath: FocusPath) => void;
-    findWidgets: (criterion: FilterCriterion) => ReadonlyArray<Widget>;
+    findWidgets: FindWidgetsFunction;
     reviewMode: boolean;
     showSolutions?: ShowSolutions;
     handleUserInput: (newUserInput: TUserInput, cb?: () => void, silent?: boolean) => void;

package/dist/widget-ai-utils/categorizer/categorizer-ai-utils.d.ts

@@ -1,12 +1,41 @@
 import type categorizer from "../../widgets/categorizer/categorizer";
 import type React from "react";
+/**
+ * JSON describing a categorizer widget. Intended for consumption by AI tools.
+ * A categorizer displays a table where each row represents an item to be
+ * categorized, and each column represents a category. Each table cell contains
+ * a bubble that the learner can fill to indicate that that item belongs in
+ * that category. Only one bubble in each row can be filled. Learners fill
+ * bubbles by clicking on them.
+ */
 export type CategorizerPromptJSON = {
     type: "categorizer";
+    /**
+     * The configuration of the widget, set by the content creator.
+     */
     options: {
+        /**
+         * The items for the learner to categorize.
+         */
         items: ReadonlyArray<string>;
+        /**
+         * Categories to which items can be assigned.
+         */
         categories: ReadonlyArray<string>;
     };
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /**
+         * The category indices for each item. Elements in this array
+         * correspond to elements of `options.items`, and refer to indices of
+         * the `categories` array. For example, a value of `[2, null, 0]` means
+         * that the first item is in the category at index 2, the second item
+         * has not been assigned to a category, and the third item is in the
+         * category at index 0.
+         */
         itemToCategoryMapping: ReadonlyArray<number | null | undefined>;
     };
 };

package/dist/widget-ai-utils/definition/definition-ai-utils.d.ts

@@ -1,8 +1,16 @@
 import type definition from "../../widgets/definition/definition";
 import type React from "react";
+/**
+ * JSON describing a definition widget. Intended for consumption by AI tools.
+ * The definition widget usually appears inline in a paragraph of text. It
+ * renders a term and displays its definition in a popover when clicked.
+ * Learners' interactions with this widget are not graded.
+ */
 export type DefinitionPromptJSON = {
     type: "definition";
+    /** The definition of the term. */
     definition: string;
+    /** The term being defined. */
     togglePrompt: string;
 };
 export declare const getPromptJSON: (widgetData: React.ComponentProps<typeof definition.widget>) => DefinitionPromptJSON;

package/dist/widget-ai-utils/dropdown/dropdown-ai-utils.d.ts

@@ -1,10 +1,22 @@
 import type dropdown from "../../widgets/dropdown/dropdown";
 import type React from "react";
+/**
+ * JSON describing a dropdown widget. Intended for consumption by AI tools.
+ * The dropdown widget displays a menu of options.
+ */
 export type DropdownPromptJSON = {
     type: "dropdown";
+    /**
+     * The configuration of the widget, set by the content creator.
+     */
     options: {
+        /** The choices present in the dropdown */
         items: ReadonlyArray<string>;
     };
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
         selectedIndex: number;
     };

package/dist/widget-ai-utils/explanation/explanation-ai-utils.d.ts

@@ -1,8 +1,20 @@
 import type explanation from "../../widgets/explanation/explanation";
 import type React from "react";
+/**
+ * JSON describing an explanation widget. Intended for consumption by AI tools.
+ * The explanation widget displays a disclosure element that the user can
+ * click to see more details about a topic. Learners' interactions with this
+ * widget are not graded.
+ */
 export type ExplanationPromptJSON = {
     type: "explanation";
+    /**
+     * The clickable text shown when the disclosure is closed.
+     */
     showPrompt: string;
+    /**
+     * The text shown when the disclosure is open.
+     */
     explanation: string;
 };
 export declare const getPromptJSON: (widgetData: React.ComponentProps<typeof explanation.widget>) => ExplanationPromptJSON;

package/dist/widget-ai-utils/expression/expression-ai-utils.d.ts

@@ -1,8 +1,19 @@
 import type { PerseusExpressionUserInput } from "@khanacademy/perseus-core";
+/**
+ * JSON describing an expression widget. Intended for consumption by AI tools.
+ * The expression widget shows an input field that allows a user to input a
+ * math expression or equation.
+ */
 export type ExpressionPromptJSON = {
     type: "expression";
+    /** The label shown on the input field */
     label?: string;
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /** The expression or equation input by the user. Uses TeX syntax. */
         value: string;
     };
 };

package/dist/widget-ai-utils/graded-group/graded-group-ai-utils.d.ts

@@ -1,7 +1,19 @@
 import type { RendererPromptJSON } from "../prompt-types";
-export type GradedGroupPromptJSON = RendererPromptJSON & {
+/**
+ * JSON describing a graded group widget. Intended for consumption by AI tools.
+ * The graded group widget displays a self-contained question with its own
+ * "check answer" button. The learner's score on this question is not recorded.
+ * Graded groups are provided for learners to check their own understanding of
+ * a concept.
+ */
+export interface GradedGroupPromptJSON extends RendererPromptJSON {
     type: "graded-group";
+    /** Displayed above the graded group. */
     title: string;
-    hint: RendererPromptJSON | string;
-};
+    /**
+     * Explanation of the question, which the learner can show or hide by
+     * clicking a button. There is no penalty for looking at this hint.
+     */
+    hint: RendererPromptJSON;
+}
 export declare const getPromptJSON: (title: string, rendererJSON: RendererPromptJSON | undefined, hintRendererJSON: RendererPromptJSON) => GradedGroupPromptJSON;

package/dist/widget-ai-utils/graded-group-set/graded-group-set-ai-utils.d.ts

@@ -1,10 +1,20 @@
 import type gradedGroupSet from "../../widgets/graded-group-set";
 import type { GradedGroupPromptJSON } from "../graded-group/graded-group-ai-utils";
 import type React from "react";
+/**
+ * JSON describing a graded group set widget. Intended for consumption by AI tools.
+ * A graded group set displays several review questions (GradedGroups) in a
+ * carousel-like UI. The learner's score on a graded group set is not recorded.
+ * Graded group sets are provided for learners to check their own understanding
+ * of a concept.
+ */
 export type GradedGroupSetPromptJSON = {
     type: "graded-group-set";
+    /** The configuration of the widget, set by the content creator. */
     options: {
+        /** The number of questions (`GradedGroup`s) in this widget */
         groupCount: number;
+        /** The currently-displayed question */
         currentGroup: GradedGroupPromptJSON;
     };
 };

package/dist/widget-ai-utils/grapher/grapher-ai-utils.d.ts

@@ -1,17 +1,52 @@
 import type grapher from "../../widgets/grapher/grapher";
 import type { GrapherAnswerTypes } from "@khanacademy/perseus-core";
 import type React from "react";
+/**
+ * JSON describing a grapher widget. Intended for consumption by AI tools.
+ * The grapher widget displays a Cartesian plane where the learner can plot an
+ * equation by clicking and dragging control points.
+ */
 export type GrapherPromptJSON = {
     type: "grapher";
+    /** The configuration of the widget, set by the content creator. */
     options: {
+        /**
+         * The types of equations the learner can plot. If there is more than
+         * one entry in this array, the widget displays a set of buttons for
+         * selecting the graph type.
+         */
         availableTypes: ReadonlyArray<string>;
+        /**
+         * The bounds of the graph, in the format
+         * `[[xMin, xMax], [yMin, yMax]]`.
+         */
         range: [x: [min: number, max: number], y: [min: number, max: number]];
+        /**
+         * Labels for the x and y axes of the graph, in the format `[x, y]`.
+         */
         labels: ReadonlyArray<string>;
+        /**
+         * The spacing between tick markings on the graph axes, measured in
+         * units on the Cartesian plane. Format: `[xTickStep, yTickStep]`.
+         */
         tickStep: [number, number];
+        /**
+         * The spacing between grid lines, measured in units on the Cartesian
+         * plane. Format: `[xGridStep, yGridStep]`.
+         */
         gridStep?: [number, number];
+        /**
+         * Control points snap to coordinates that are multiples of the snap
+         * step. Format: `[xSnapStep, ySnapStep]`.
+         */
         snapStep?: [number, number];
+        /** An image displayed behind the graph */
         backgroundImageUrl?: string | null;
     };
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: GrapherAnswerTypes;
 };
 export declare const getPromptJSON: (widgetData: React.ComponentProps<typeof grapher.widget>) => GrapherPromptJSON;

package/dist/widget-ai-utils/group/group-ai-utils.d.ts

@@ -1,4 +1,10 @@
 import type { RendererPromptJSON } from "../prompt-types";
+/**
+ * JSON describing a group widget. Intended for consumption by AI tools.
+ * A group widget is simply an embedded Markdown document that can contain
+ * other widgets. To the user, the group widget looks like part of the
+ * surrounding document.
+ */
 export type GroupPromptJSON = RendererPromptJSON & {
     type: "group";
 };

package/dist/widget-ai-utils/image/image-ai-utils.d.ts

@@ -1,10 +1,26 @@
 import type image from "../../widgets/image/image.class";
 import type React from "react";
+/**
+ * JSON describing an image widget. Intended for consumption by AI tools.
+ */
 export type ImagePromptJSON = {
     type: "image";
+    /** Configuration set by the content creator. */
     options: {
+        /**
+         * Text displayed to screenreaders and browsers without graphical
+         * capabilities
+         */
         altText: string;
+        /**
+         * Displayed above the image. May contain Markdown formatting, and TeX
+         * delimited by dollar signs, e.g. `$\dfrac{1}{2}$`.
+         */
         title: string;
+        /**
+         * Displayed below the image. May contain Markdown formatting, and TeX
+         * delimited by dollar signs, e.g. `$\dfrac{1}{2}$`.
+         */
         caption: string;
         imageUrl: string | null | undefined;
     };

package/dist/widget-ai-utils/input-number/input-number-ai-utils.d.ts

@@ -1,12 +1,34 @@
 import type inputNumber from "../../widgets/input-number/input-number";
 import type React from "react";
+/**
+ * JSON describing an InputNumber widget. Intended for consumption by AI tools.
+ * An InputNumber displays a text field where users can enter numbers in a
+ * variety of formats: decimals, integers, fractions, mixed numbers,
+ * percentages, and multiples of pi. The allowed formats are configurable by
+ * the content creator.
+ */
 export type InputNumberPromptJSON = {
     type: "input-number";
+    /** The configuration of the widget, set by the content creator. */
     options: {
+        /**
+         * Indicates how answers in unsimplified form are scored.
+         *
+         * - "optional" means the answer can be unsimplified.
+         * - "required" means an unsimplified answer is considered invalid,
+         *   and the learner can try again without penalty.
+         * - "enforced" means unsimplified answers are counted as incorrect.
+         */
         simplify: string;
+        /** The expected numeric form, e.g. "rational", "decimal" */
         answerType: string;
     };
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /** The text input by the user */
         value: string;
     };
 };

package/dist/widget-ai-utils/interactive-graph/interactive-graph-ai-utils.d.ts

@@ -4,60 +4,71 @@ import type { PerseusGraphType } from "@khanacademy/perseus-core";
 import type React from "react";
 type Coord = [x: number, y: number];
 type CollinearTuple = readonly [Coord, Coord];
-type BaseGraphOptions = {
-    type: string;
-};
-type AngleGraphOptions = BaseGraphOptions & {
-    angleOffsetDegrees: number;
+type AngleGraphOptions = {
+    type: "angle";
+    angleOffsetDegrees: number | undefined;
     startCoords?: readonly [Coord, Coord, Coord];
 };
-type CircleGraphOptions = BaseGraphOptions & {
+type CircleGraphOptions = {
+    type: "circle";
     startParams: {
         center?: Coord;
         radius?: number;
     };
 };
-type LinearGraphOptions = BaseGraphOptions & {
+type LinearGraphOptions = {
+    type: "linear";
     startCoords?: CollinearTuple;
 };
-type LinearSystemGraphOptions = BaseGraphOptions & {
+type LinearSystemGraphOptions = {
+    type: "linear-system";
     startCoords?: readonly CollinearTuple[];
 };
-type PointGraphOptions = BaseGraphOptions & {
+type PointGraphOptions = {
+    type: "point";
     numPoints?: number | "unlimited";
     startCoords?: readonly Coord[];
 };
-type PolygonGraphOptions = BaseGraphOptions & {
+type PolygonGraphOptions = {
+    type: "polygon";
     match?: string;
     numSides?: number | "unlimited";
     startCoords?: readonly Coord[];
 };
-type QuadraticGraphOptions = BaseGraphOptions & {
+type QuadraticGraphOptions = {
+    type: "quadratic";
     startCoords?: readonly [Coord, Coord, Coord];
 };
-type RayGraphOptions = BaseGraphOptions & {
+type RayGraphOptions = {
+    type: "ray";
     startCoords?: CollinearTuple;
 };
-type SegmentGraphOptions = BaseGraphOptions & {
+type SegmentGraphOptions = {
+    type: "segment";
     numSegments?: number;
-    startCoords?: CollinearTuple;
+    startCoords?: CollinearTuple[];
 };
-type SinusoidGraphOptions = BaseGraphOptions & {
+type SinusoidGraphOptions = {
+    type: "sinusoid";
     startCoords?: readonly Coord[];
 };
-type AbsoluteValueGraphOptions = BaseGraphOptions & {
+type AbsoluteValueGraphOptions = {
+    type: "absolute-value";
     startCoords?: readonly [Coord, Coord];
 };
-type TangentGraphOptions = BaseGraphOptions & {
+type TangentGraphOptions = {
+    type: "tangent";
     startCoords?: readonly Coord[];
 };
-type ExponentialGraphOptions = BaseGraphOptions & {
+type ExponentialGraphOptions = {
+    type: "exponential";
     startCoords?: {
         coords: readonly [Coord, Coord];
         asymptote: number;
     };
 };
-type LogarithmGraphOptions = BaseGraphOptions & {
+type LogarithmGraphOptions = {
+    type: "logarithm";
     startCoords?: {
         coords: readonly [Coord, Coord];
         asymptote: number;
@@ -112,13 +123,31 @@ type TangentUserInput = {
     coords?: readonly Coord[] | null;
 };
 type UserInput = AbsoluteValueUserInput | AngleUserInput | CircleUserInput | ExponentialUserInput | LinearUserInput | LinearSystemInput | PointUserInput | PolygonUserInput | QuadraticUserInput | RayUserInput | SegmentUserInput | SinusoidUserInput | TangentUserInput | LogarithmUserInput;
+/**
+ * JSON describing an interactive graph widget. Intended for consumption by AI tools.
+ * An interactive graph plots equations and draws geometric figures on a
+ * Cartesian plane. The user can move and reshape these elements by dragging
+ * control points.
+ */
 export type InteractiveGraphPromptJSON = {
     type: "interactive-graph";
+    /**
+     * The configuration of the widget, set by the content creator.
+     */
     options: {
+        /**
+         * Configuration of the plotted equation or geometric figure.
+         */
         graph: GraphOptions;
+        /**
+         * The bounds of the graph. Format: `[[xMin, xMax], [yMin, yMax]]`
+         */
+        range: [x: [min: number, max: number], y: [min: number, max: number]];
+        /**
+         * Labels on the graph axes. Format: `[xLabel, yLabel]`.
+         */
+        labels: string[];
         backgroundImageUrl: string | null | undefined;
-        range: [min: number, max: number][];
-        labels: ReadonlyArray<string>;
     };
     userInput: UserInput;
 };

package/dist/widget-ai-utils/label-image/label-image-ai-utils.d.ts

@@ -1,22 +1,85 @@
 import type labelImage from "../../widgets/label-image/label-image";
 import type React from "react";
+/**
+ * A marker placed on the image, representing a location the learner must
+ * label. Used in the `options` section to describe the marker's identity and
+ * correct answers.
+ */
 type BaseMarker = {
+    /**
+     * The text label identifying this marker's position on the image. Not
+     * shown directly to the learner; used to correlate options markers with
+     * user input markers.
+     */
     label: string;
 };
+/**
+ * A marker as it appears in the user input section. Extends the base marker
+ * with optional correct answers (when present) and the learner's current
+ * selections.
+ */
 type UserInputMarker = {
+    /**
+     * The text label identifying this marker's position on the image.
+     * Corresponds to the matching marker in `options.markers`.
+     */
     label: string;
+    /**
+     * The set of correct answer labels for this marker, as defined by the
+     * content creator. Only present when the marker has designated correct
+     * answers. A marker without answers is used purely for labeling purposes
+     * and is not scored.
+     */
     answers?: string[];
+    /**
+     * The answer labels the learner has selected for this marker. Each entry
+     * is one of the strings from `options.choices`. May be absent or empty if
+     * the learner has not yet made a selection for this marker.
+     */
     selected?: ReadonlyArray<string>;
 };
+/**
+ * JSON describing a label-image widget. Intended for consumption by AI tools.
+ * A label-image widget displays an image with interactive markers placed at
+ * specific locations. The learner selects one or more answer labels from a
+ * shared list of choices for each marker.
+ */
 export type LabelImagePromptJSON = {
     type: "label-image";
+    /**
+     * The configuration of the widget, set by the content creator.
+     */
     options: {
+        /**
+         * The list of answer choices available to the learner. Each marker's
+         * selection must come from this list.
+         */
         choices: ReadonlyArray<string>;
+        /**
+         * The URL of the image on which markers are placed.
+         */
         imageUrl: string;
+        /**
+         * Accessible alternative text for the image, used in the `alt`
+         * attribute.
+         */
         imageAlt: string;
+        /**
+         * The markers placed on the image by the content creator, each
+         * identifying a location the learner must label.
+         */
         markers: BaseMarker[];
     };
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /**
+         * The learner's selections for each marker, parallel to
+         * `options.markers`. Each element corresponds to the marker at the
+         * same index.
+         */
         markers: UserInputMarker[];
     };
 };

package/dist/widget-ai-utils/matcher/matcher-ai-utils.d.ts

@@ -1,15 +1,55 @@
 import type matcher from "../../widgets/matcher/matcher";
 import type React from "react";
+/**
+ * JSON describing a matcher widget. Intended for consumption by AI tools.
+ * A matcher displays two columns of items that the learner must match by
+ * dragging cards in the right column to align with their corresponding items
+ * in the left column.
+ */
 export type MatcherPromptJSON = {
     type: "matcher";
+    /**
+     * The configuration of the widget, set by the content creator.
+     */
     options: {
+        /**
+         * Labels for the column headings. Contains exactly 2 values:
+         * the left column label and the right column label.
+         * e.g. `["Concepts", "Things"]`
+         */
         labels: ReadonlyArray<string>;
+        /**
+         * The items shown in the left column that the learner must match
+         * against. e.g. `["Fruit", "Color", "Clothes"]`
+         */
         left: ReadonlyArray<string>;
+        /**
+         * The draggable cards in the right column that the learner arranges
+         * to match the left column items. e.g. `["Red", "Shirt", "Banana"]`
+         */
         right: ReadonlyArray<string>;
+        /**
+         * When true, the items in the left column are draggable and the
+         * learner must put them into the correct order. When false, the left
+         * column is static.
+         */
         orderMatters: boolean;
     };
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /**
+         * The current order of items in the left column. When `orderMatters`
+         * is false, the left column is fixed and only right can be reordered.
+         */
         left: ReadonlyArray<string>;
+        /**
+         * The current order of cards in the right column, as arranged by the
+         * learner. Each element corresponds to the left column item at the
+         * same index.
+         */
         right: ReadonlyArray<string>;
     };
 };

package/dist/widget-ai-utils/matrix/matrix-ai-utils.d.ts

@@ -1,12 +1,35 @@
 import type matrix from "../../widgets/matrix/matrix";
 import type React from "react";
+/**
+ * JSON describing a matrix widget. Intended for consumption by AI tools.
+ * A matrix widget displays a grid of numeric cells that the learner fills in.
+ */
 export type MatrixPromptJSON = {
     type: "matrix";
+    /**
+     * The configuration of the widget, set by the content creator.
+     */
     options: {
+        /**
+         * The number of rows in the matrix grid.
+         */
         height: number;
+        /**
+         * The number of columns in the matrix grid.
+         */
         width: number;
     };
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /**
+         * The current values entered by the learner. Each element of the outer
+         * array represents a row; each element of the inner arrays represents a
+         * cell value within that row. Cells that have not been filled in are
+         * represented as empty strings.
+         */
         answerRows: ReadonlyArray<ReadonlyArray<string>>;
     };
 };