@khanacademy/perseus 20.8.1 → 21.0.0

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

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

package/dist/util/snowman-utils.d.ts

@@ -1,43 +1,3 @@
-export declare enum WidgetType {
-    Categorizer = "categorizer",
-    CSProgram = "cs-program",
-    Definition = "definition",
-    Dropdown = "dropdown",
-    Explanation = "explanation",
-    Expression = "expression",
-    GradedGroup = "graded-group",
-    GradedGroupAnswerBar = "graded-group-answer-bar",
-    GradedGroupSet = "graded-group-set",
-    Grapher = "grapher",
-    Group = "group",
-    Iframe = "iframe",
-    Image = "image",
-    InputNumber = "input-number",
-    Interaction = "interaction",
-    InteractiveGraph = "interactive-graph",
-    InteractiveNumberLine = "interactive-number-line",
-    LabelImage = "label-image",
-    Matcher = "matcher",
-    Matrix = "matrix",
-    Measurer = "measurer",
-    Molecule = "molecule",
-    NumberLine = "number-line",
-    NumericInput = "numeric-input",
-    Orderer = "orderer",
-    Passage = "passage",
-    PassageRef = "passage-ref",
-    PassageRefTarget = "passage-ref-target",
-    Plotter = "plotter",
-    Protractor = "protractor",
-    PythonProgram = "python-program",
-    Radio = "radio",
-    Sorter = "sorter",
-    Table = "table",
-    Unit = "unit",
-    Video = "video",
-    VideoTranscriptLink = "video-transcript-link"
-}
-export type WidgetId = `${WidgetType} ${number}`;
 export declare const QUESTION_WIDGETS: ReadonlyArray<string>;
 /**
  * Regex for widget placeholders in a string.
@@ -55,35 +15,3 @@ export declare function getWidgetRegex(): RegExp;
  * @returns {string}
  */
 export declare function addWidget(id: string): string;
-/**
- * Extract all widget IDs, which includes the widget type and instance number.
- * example output: ['radio 1', 'categorizer 1', 'categorizor 2']
- *
- * Content should contain Perseus widget placeholders,
- * which look like: '[[☃ radio 1]]'.
- *
- * @param {string} content
- * @returns {Array<WidgetId>} widgets
- */
-export declare function getAllWidgetIds(content: string): Array<WidgetId>;
-/**
- * Extract all widget types from a Perseus JSON content string.
- * This does not include the instance number and prevents duplicates.
- * example output: ['radio', 'categorizer']
- *
- * @param {string} content
- * @returns {Array<WidgetId>}
- */
-export declare function getAllWidgetTypes(content: string): Array<WidgetId>;
-/**
- * Extract the widget IDs of all widgets considered question widgets. Widget IDs
- * include widget type and instance number.
- * example output: ['radio 1', 'categorizer 1']
- *
- * Content should contain Perseus widget placeholders,
- * which look like: '[[☃ radio 1]]'.
- *
- * @param {string} content
- * @returns Array<WidgetId>
- */
-export declare function getQuestionWidgetIds(content: string): Array<WidgetId>;

package/dist/util/test-utils.d.ts

@@ -1,4 +1,4 @@
-import type { PerseusItem } from "../perseus-types";
+import type { CategorizerWidget, ExpressionWidget, InteractiveGraphWidget, NumericInputWidget, PerseusItem, RadioWidget } from "../perseus-types";
 export declare const genericPerseusItemData: PerseusItem;
 /**
  * Generate a Perseus item object for testing purposes.
@@ -7,6 +7,41 @@ export declare const genericPerseusItemData: PerseusItem;
  * uses a basic Perseus object and updates it with custom values as needed.
  *
  * @param {Partial<PerseusItem>} customFields
- * @returns PerseusItem
+ * @returns {PerseusItem}
  */
 export declare function generateTestPerseusItem(customFields?: Partial<PerseusItem>): PerseusItem;
+/**
+ * Creates an object with the bare amount
+ * of data to be a properly typed RadioWidget
+ *
+ * @returns {RadioWidget} skeleton RadioWidget for testing
+ */
+export declare function generateTestRadioWidget(): RadioWidget;
+/**
+ * Creates an object with the bare amount
+ * of data to be a properly typed InteractiveGraphWidget
+ *
+ * @returns {InteractiveGraphWidget} skeleton InteractiveGraphWidget for testing
+ */
+export declare function generateTestInteractiveGraphWidget(): InteractiveGraphWidget;
+/**
+ * Creates an object with the bare amount
+ * of data to be a properly typed InteractiveGraphWidget
+ *
+ * @returns {InteractiveGraphWidget} skeleton InteractiveGraphWidget for testing
+ */
+export declare function generateTestCategorizerWidget(): CategorizerWidget;
+/**
+ * Creates an object with the bare amount
+ * of data to be a properly typed ExpressionWidget
+ *
+ * @returns {ExpressionWidget} skeleton ExpressionWidget for testing
+ */
+export declare function generateTestExpressionWidget(): ExpressionWidget;
+/**
+ * Creates an object with the bare amount
+ * of data to be a properly typed NumericInputWidget
+ *
+ * @returns {NumericInputWidget} skeleton NumericInputWidget for testing
+ */
+export declare function generateTestNumericInputWidget(): NumericInputWidget;

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

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

package/dist/widget-type-utils.d.ts

@@ -0,0 +1,64 @@
+import type { PerseusItem, PerseusWidget, PerseusWidgetsMap } from "./perseus-types";
+/**
+ * Get a widget type by a widget's ID
+ * (please don't derive type from ID)
+ *
+ * @param {string} widgetId the ID of the widget
+ * @param {PerseusWidgetsMap} widgetMap widget ID to widget map
+ * @returns {string} the widget type (ie "radio")
+ */
+export declare function getWidgetTypeByWidgetId(WidgetId: string, widgetMap: PerseusWidgetsMap): string | null;
+/**
+ * Does the content have a specific type of widget?
+ *
+ * @param {string} type the type of the widget in question (ie "radio")
+ * @param {string} content the string to search through
+ * @param {PerseusWidgetsMap} widgetMap widget ID to widget map
+ * @returns {boolean} if the content includes the widget type
+ */
+export declare function contentHasWidgetType(type: string, content: string, widgetMap: PerseusWidgetsMap): boolean;
+/**
+ * Extract all widget IDs, which includes the widget type and instance number.
+ * example output: ['radio 1', 'categorizer 1', 'categorizor 2']
+ *
+ * Content should contain Perseus widget placeholders,
+ * which look like: '[[☃ radio 1]]'.
+ *
+ * @param {string} content
+ * @returns {ReadonlyArray<string>} widgetIds
+ */
+export declare function getWidgetIdsFromContent(content: string): ReadonlyArray<string>;
+/**
+ * Get a list of widget IDs from content,
+ * but only for specific widget types
+ *
+ * @param {string} type the type of widget (ie "radio")
+ * @param {string} content the string to parse
+ * @param {PerseusWidgetsMap} widgetMap widget ID to widget map
+ * @returns {ReadonlyArray<string>} the widget type (ie "radio")
+ */
+export declare function getWidgetIdsFromContentByType(type: string, content: string, widgetMap: PerseusWidgetsMap): ReadonlyArray<string>;
+/**
+ * Pull the widget map out of ItemData
+ *
+ * @param {PerseusItem} PerseusItem containing a widgetMap
+ * @returns {WidgetMap} the widget map in the PerseusItem
+ */
+export declare function getWidgetsMapFromItemData(itemData: PerseusItem): PerseusWidgetsMap;
+/**
+ * Get the widget information from a WidgetMap
+ *
+ * @param {string} widgetId the ID of the widget
+ * @returns {PerseusWidget | null} the widget data if it exists, otherwise null
+ */
+export declare function getWidgetFromWidgetMap(widgetId: string, widgetMap: PerseusWidgetsMap): PerseusWidget | null;
+/**
+ * Get select widgets from a widget map.
+ * Useful for multi-items that needs to split
+ * one PerseusItem into several
+ *
+ * @param {ReadonlyArray<string>} widgetIds to extract
+ * @param {PerseusWidgetsMap} widgetMap to extract from
+ * @return {PerseusWidgetsMap} a new widget map with requested widgets
+ */
+export declare function getWidgetsFromWidgetMap(widgetIds: ReadonlyArray<string>, widgetMap: PerseusWidgetsMap): PerseusWidgetsMap;

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

@@ -155,7 +155,7 @@ declare class InteractiveGraph extends React.Component<Props, State> {
     static getRayEquationString(props: Props): string;
     static getPolygonEquationString(props: Props): string;
     static getAngleEquationString(props: Props): string;
-    static validate(state: PerseusGraphType, rubric: Rubric, component: any): PerseusScore;
+    static validate(userInput: PerseusGraphType, rubric: Rubric, component: any): PerseusScore;
     static getUserInputFromProps(props: Props): PerseusGraphType;
 }
 declare const _default: Readonly<{

package/dist/widgets/interactive-graphs/graphs/components/angle.d.ts

@@ -1,13 +1,23 @@
 /// <reference types="react" />
 import { vec } from "mafs";
+import type { CollinearTuple } from "../../../../perseus-types";
 import type { Interval } from "mafs";
 interface Props {
     centerPoint: vec.Vector2;
     endPoints: [vec.Vector2, vec.Vector2];
-    polygonPoints: readonly vec.Vector2[];
+    polygonLines: readonly CollinearTuple[];
     active: boolean;
     range: [Interval, Interval];
     showAngles: boolean;
 }
-export declare const Angle: ({ centerPoint, endPoints, range, polygonPoints, showAngles, }: Props) => JSX.Element | null;
+export declare const Angle: ({ centerPoint, endPoints, range, polygonLines, showAngles, }: Props) => JSX.Element | null;
+/**
+ * Determines if an angle is an inside (false) or outside (true) angle.
+ * They way, we know to flip the `largeArc` and `sweepArc` flags.
+ * Uses the priciple that a ray from a point inside a polygon will intersect
+ * with an odd number of lines, while a ray from a point outside the polygon
+ * will intersect with an even number of lines.
+ * https://stackoverflow.com/questions/217578/how-can-i-determine-whether-a-2d-point-is-within-a-polygon
+ */
+export declare const shouldDrawArcOutside: (midpoint: vec.Vector2, vertex: vec.Vector2, range: [Interval, Interval], polygonLines: readonly CollinearTuple[]) => boolean;
 export {};

package/dist/widgets/interactive-graphs/graphs/components/css-transform-wrapper.d.ts

@@ -0,0 +1,7 @@
+import * as React from "react";
+/**
+ * Wrapper with Mafs transform styles for SVG elements.
+ * Scales and translates the SVG element to match the Mafs view.
+ * Use if you do not need/want to use the hook in `use-transform.ts`.
+ */
+export declare const MafsCssTransformWrapper: ({ children, }: React.PropsWithChildren<unknown>) => JSX.Element;

package/dist/widgets/interactive-graphs/graphs/components/text-label.d.ts

@@ -0,0 +1,6 @@
+import type { TextProps } from "mafs";
+import type { PropsWithChildren } from "react";
+type Props = PropsWithChildren<Pick<TextProps, "x" | "y" | "attach" | "attachDistance">>;
+export declare const TextLabel: ({ children, ...rest }: Props) => JSX.Element;
+export declare const SvgDefs: () => JSX.Element;
+export {};

package/dist/widgets/interactive-graphs/graphs/utils.d.ts

@@ -1,3 +1,4 @@
+import type { CollinearTuple } from "../../../perseus-types";
 import type { Interval, vec } from "mafs";
 /**
  * Given two points, find the tips that extends through the points to the edge of the range.
@@ -5,3 +6,4 @@ import type { Interval, vec } from "mafs";
  * @param extendFrom - The point that the line extends from to the edge of the graph.
  */
 export declare const getRayIntersectionCoords: (collinearPoint: vec.Vector2, extendFrom: vec.Vector2, range: [Interval, Interval]) => [number, number];
+export declare const getLines: (points: readonly vec.Vector2[]) => CollinearTuple[];

package/dist/widgets/interactive-graphs/reducer/interactive-graph-state.d.ts

@@ -7,4 +7,4 @@ export declare function initializeGraphState(params: {
     snapStep: vec.Vector2;
     graph: PerseusGraphType;
 }): InteractiveGraphState;
-export declare function getGradableGraph<GraphType extends PerseusGraphType>(state: InteractiveGraphState, initialGraph: GraphType): GraphType;
+export declare function getGradableGraph(state: InteractiveGraphState, initialGraph: PerseusGraphType): PerseusGraphType;

package/package.json

@@ -3,7 +3,7 @@
     "description": "Core Perseus API (includes renderers and widgets)",
     "author": "Khan Academy",
     "license": "MIT",
-    "version": "20.8.1",
+    "version": "21.0.0",
     "publishConfig": {
         "access": "public"
     },