@khanacademy/perseus 77.1.0 → 77.2.1

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,61 +4,78 @@ 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 = {
+    type: "logarithm";
     startCoords?: {
         coords: readonly [Coord, Coord];
         asymptote: number;
     };
 };
 type NoneGraphOptions = Record<string, never>;
-type GraphOptions = AbsoluteValueGraphOptions | AngleGraphOptions | CircleGraphOptions | ExponentialGraphOptions | LinearGraphOptions | LinearSystemGraphOptions | NoneGraphOptions | PointGraphOptions | PolygonGraphOptions | QuadraticGraphOptions | RayGraphOptions | SegmentGraphOptions | SinusoidGraphOptions | TangentGraphOptions;
+type GraphOptions = AbsoluteValueGraphOptions | AngleGraphOptions | CircleGraphOptions | ExponentialGraphOptions | LinearGraphOptions | LinearSystemGraphOptions | NoneGraphOptions | PointGraphOptions | PolygonGraphOptions | QuadraticGraphOptions | RayGraphOptions | SegmentGraphOptions | SinusoidGraphOptions | TangentGraphOptions | LogarithmGraphOptions;
 type AngleUserInput = {
     coords?: readonly [Coord, Coord, Coord];
     angleOffsetDegrees?: number;
@@ -98,17 +115,39 @@ type ExponentialUserInput = {
     coords?: readonly Coord[] | null;
     asymptote?: number | null;
 };
+type LogarithmUserInput = {
+    coords?: readonly Coord[] | null;
+    asymptote?: number | null;
+};
 type TangentUserInput = {
     coords?: readonly Coord[] | null;
 };
-type UserInput = AbsoluteValueUserInput | AngleUserInput | CircleUserInput | ExponentialUserInput | LinearUserInput | LinearSystemInput | PointUserInput | PolygonUserInput | QuadraticUserInput | RayUserInput | SegmentUserInput | SinusoidUserInput | TangentUserInput;
+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>>;
     };
 };

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

@@ -1,14 +1,66 @@
 import type numberLine from "../../widgets/number-line/number-line";
 import type React from "react";
+/**
+ * JSON describing a number-line widget. Intended for consumption by AI tools.
+ * A number-line widget displays a horizontal number line with a draggable
+ * point. The learner positions the point to answer a question, optionally
+ * selecting an inequality relationship (e.g. ≤, ≥) when the widget is in
+ * inequality mode.
+ */
 export type NumberLinePromptJSON = {
     type: "number-line";
+    /**
+     * The configuration of the widget, set by the content creator.
+     */
     options: {
+        /**
+         * The numeric values of the left and right endpoints of the number
+         * line, e.g. `[-5, 5]`. These bounds also constrain where the learner
+         * can place the point.
+         */
         range: ReadonlyArray<number>;
+        /**
+         * The number of sub-intervals between adjacent tick marks into which
+         * the point can snap. Higher values allow finer-grained placement.
+         * For example, a value of `4` means the point snaps to quarter-tick
+         * increments.
+         */
         snapDivisions: number;
     };
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /**
+         * The numeric axis value where the learner has placed the point,
+         * e.g. `3.5` on a `[-5, 5]` number line. Clamped to `options.range`
+         * and snapped to the nearest tick increment.
+         */
         numLinePosition: number;
+        /**
+         * The number of tick-mark divisions currently shown on the number
+         * line. When the widget's `isTickCtrl` option is enabled, the learner
+         * can adjust this value; otherwise it is set by the content author.
+         */
         numDivisions: number;
+        /**
+         * The number line widget can represent a set of real numbers that is
+         * greater than, greater than or equal to, less than, or less than or
+         * equal to some number. Visually, the portion of the number line
+         * included in this set is shaded. The `rel` property describes the
+         * inequality relation the learner has selected.
+         *
+         * Possible values:
+         * - `"eq"` – equals (standard point, no inequality shading)
+         * - `"lt"` – less than
+         * - `"gt"` – greater than
+         * - `"le"` – less than or equal to
+         * - `"ge"` – greater than or equal to
+         *
+         * Only meaningful when the widget is configured for inequality mode;
+         * otherwise always `"eq"`.
+         */
         rel: string;
     };
 };

package/dist/widget-ai-utils/numeric-input/prompt-utils.d.ts

@@ -1,9 +1,26 @@
 import type numericInput from "../../widgets/numeric-input/numeric-input.class";
 import type React from "react";
+/**
+ * JSON describing a numeric-input widget. Intended for consumption by AI tools.
+ * A numeric-input widget displays a single text field where the learner types
+ * a numeric answer (integer, decimal, fraction, etc.).
+ */
 export type NumericInputPromptJSON = {
     type: "numeric-input";
+    /**
+     * Accessible label for the input field, set by the content creator.
+     * Shown to learners using screen readers to describe what value should
+     * be entered.
+     */
     label: string;
+    /**
+     * The current state of the widget user interface. Usually represents a
+     * learner's attempt to answer a question.
+     */
     userInput: {
+        /**
+         * The text currently entered in the input field by the learner.
+         */
         value: string;
     };
 };