Add doc comments for widget *PromptJSON types

packages/perseus/src/index.ts

@@ -174,3 +174,7 @@ export type {
     RendererPromptJSON,
     WidgetPromptJSON,
 } from "./widget-ai-utils/prompt-types";
+export type {CategorizerPromptJSON} from "./widget-ai-utils/categorizer/categorizer-ai-utils";
+export type {DefinitionPromptJSON} from "./widget-ai-utils/definition/definition-ai-utils";
+export type {DropdownPromptJSON} from "./widget-ai-utils/dropdown/dropdown-ai-utils";
+export type {UnsupportedWidgetPromptJSON} from "./widget-ai-utils/unsupported-widget";

packages/perseus/src/widget-ai-utils/categorizer/categorizer-ai-utils.ts

@@ -1,13 +1,44 @@
 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 category 2, the second item has not been
+         * assigned to a category, and the third item is in category 0.
+         */
         itemToCategoryMapping: ReadonlyArray<number | null | undefined>;
     };
 };

packages/perseus/src/widget-ai-utils/definition/definition-ai-utils.ts

@@ -1,9 +1,17 @@
 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;
 };
 

packages/perseus/src/widget-ai-utils/dropdown/dropdown-ai-utils.ts

@@ -1,11 +1,25 @@
 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;
     };

packages/perseus/src/widget-ai-utils/explanation/explanation-ai-utils.ts

@@ -1,9 +1,21 @@
 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;
 };
 

packages/perseus/src/widget-ai-utils/expression/expression-ai-utils.ts

@@ -1,9 +1,22 @@
 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;
     };
 };

packages/perseus/src/widget-ai-utils/graded-group-set/graded-group-set-ai-utils.ts

@@ -2,10 +2,22 @@ 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;
     };
 };

packages/perseus/src/widget-ai-utils/graded-group/graded-group-ai-utils.ts

@@ -1,10 +1,24 @@
 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 const getPromptJSON = (
     title: string,

packages/perseus/src/widget-ai-utils/grapher/grapher-ai-utils.ts

@@ -2,17 +2,60 @@ 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;
 };
 

packages/perseus/src/widget-ai-utils/group/group-ai-utils.ts

@@ -1,5 +1,11 @@
 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";
 };

packages/perseus/src/widget-ai-utils/image/image-ai-utils.ts

@@ -1,12 +1,32 @@
 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;
     };
 };

packages/perseus/src/widget-ai-utils/input-number/input-number-ai-utils.ts

@@ -1,13 +1,40 @@
 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.
+         */
+        // TODO(LEMS-4033): render an intelligible string for simplify; the
+        //  current values ("optional", "required", "enforced") aren't
+        //  self-explanatory.
         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;
     };
 };