@khanacademy/perseus-core 3.2.0 → 3.4.0

package/dist/data-schema.d.ts

@@ -33,6 +33,49 @@ export type Range = Interval;
 export type Size = [width: number, height: number];
 export type CollinearTuple = [Vector2, Vector2];
 export type ShowSolutions = "all" | "selected" | "none";
+/**
+ * A utility type that constructs a widget map from a "registry interface".
+ * The keys of the registry should be the widget type (aka, "categorizer" or
+ * "radio", etc) and the value should be the option type stored in the value
+ * of the map.
+ *
+ * You can think of this as a type that generates another type. We use
+ * "registry interfaces" as a way to keep a set of widget types to their data
+ * type in several places in Perseus. This type then allows us to generate a
+ * map type that maps a widget id to its data type and keep strong typing by
+ * widget id.
+ *
+ * For example, given a fictitious registry such as this:
+ *
+ * ```
+ * interface DummyRegistry {
+ *     categorizer: { categories: ReadonlyArray<string> };
+ *     dropdown: { choices: ReadonlyArray<string> }:
+ * }
+ * ```
+ *
+ * If we create a DummyMap using this helper:
+ *
+ * ```
+ * type DummyMap = MakeWidgetMap<DummyRegistry>;
+ * ```
+ *
+ * We'll get a map that looks like this:
+ *
+ * ```
+ * type DummyMap = {
+ *     `categorizer ${number}`: { categories: ReadonlyArray<string> };
+ *     `dropdown ${number}`: { choices: ReadonlyArray<string> };
+ * }
+ * ```
+ *
+ * We use interfaces for the registries so that they can be extended in cases
+ * where the consuming app brings along their own widgets. Interfaces in
+ * TypeScript are always open (ie. you can extend them) whereas types aren't.
+ */
+export type MakeWidgetMap<TRegistry> = {
+    [Property in keyof TRegistry as `${Property & string} ${number}`]: TRegistry[Property];
+};
 /**
  * Our core set of Perseus widgets.
  *
@@ -54,7 +97,7 @@ export type ShowSolutions = "all" | "selected" | "none";
  * `PerseusWidgets` with the one defined below.
  *
  * ```typescript
- * declare module "@khanacademy/perseus" {
+ * declare module "@khanacademy/perseus-core" {
  *     interface PerseusWidgetTypes {
  *         // A new widget
  *         "new-awesomeness": MyAwesomeNewWidget;
@@ -96,7 +139,6 @@ export interface PerseusWidgetTypes {
     matcher: MatcherWidget;
     matrix: MatrixWidget;
     measurer: MeasurerWidget;
-    "mock-widget": MockWidget;
     "molecule-renderer": MoleculeRendererWidget;
     "number-line": NumberLineWidget;
     "numeric-input": NumericInputWidget;
@@ -128,9 +170,18 @@ export interface PerseusWidgetTypes {
  * @see {@link PerseusWidgetTypes} additional widgets can be added to this map type
  * by augmenting the PerseusWidgetTypes with new widget types!
  */
-export type PerseusWidgetsMap = {
-    [Property in keyof PerseusWidgetTypes as `${Property} ${number}`]: PerseusWidgetTypes[Property];
-};
+export type PerseusWidgetsMap = MakeWidgetMap<PerseusWidgetTypes>;
+/**
+ * PerseusWidget is a union of all the different types of widget options that
+ * Perseus knows about.
+ *
+ * Thanks to it being based on PerseusWidgetTypes interface, this union is
+ * automatically extended to include widgets used in tests without those widget
+ * option types seeping into our production types.
+ *
+ * @see MockWidget for an example
+ */
+export type PerseusWidget = PerseusWidgetTypes[keyof PerseusWidgetTypes];
 /**
  * A "PerseusItem" is a classic Perseus item. It is rendered by the
  * `ServerItemRenderer` and the layout is pre-set.
@@ -228,7 +279,6 @@ export type LabelImageWidget = WidgetOptions<'label-image', PerseusLabelImageWid
 export type MatcherWidget = WidgetOptions<'matcher', PerseusMatcherWidgetOptions>;
 export type MatrixWidget = WidgetOptions<'matrix', PerseusMatrixWidgetOptions>;
 export type MeasurerWidget = WidgetOptions<'measurer', PerseusMeasurerWidgetOptions>;
-export type MockWidget = WidgetOptions<'mock-widget', MockWidgetOptions>;
 export type NumberLineWidget = WidgetOptions<'number-line', PerseusNumberLineWidgetOptions>;
 export type NumericInputWidget = WidgetOptions<'numeric-input', PerseusNumericInputWidgetOptions>;
 export type OrdererWidget = WidgetOptions<'orderer', PerseusOrdererWidgetOptions>;
@@ -245,7 +295,6 @@ export type MoleculeRendererWidget = WidgetOptions<'molecule-renderer', PerseusM
 export type RefTargetWidget = WidgetOptions<'passage-ref-target', PerseusPassageRefTargetWidgetOptions>;
 export type VideoWidget = WidgetOptions<'video', PerseusVideoWidgetOptions>;
 export type DeprecatedStandinWidget = 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 | MockWidget | MoleculeRendererWidget | NumberLineWidget | NumericInputWidget | OrdererWidget | PassageRefWidget | PassageWidget | PhetSimulationWidget | PlotterWidget | PythonProgramWidget | RadioWidget | RefTargetWidget | SorterWidget | TableWidget | VideoWidget | DeprecatedStandinWidget;
 /**
  * A background image applied to various widgets.
  */
@@ -723,7 +772,7 @@ export type PerseusNumberLineWidgetOptions = {
     correctRel: string | null | undefined;
     correctX: number | null;
     initialX: number | null | undefined;
-    showTooltip?: boolean;
+    showTooltips?: boolean;
     static: boolean;
 };
 export type PerseusOrdererWidgetOptions = {
@@ -955,10 +1004,6 @@ export type PerseusVideoWidgetOptions = {
     location: string;
     static?: boolean;
 };
-export type MockWidgetOptions = {
-    static?: boolean;
-    value: string;
-};
 export type PerseusInputNumberWidgetOptions = {
     answerType?: "number" | "decimal" | "integer" | "rational" | "improper" | "mixed" | "percent" | "pi";
     inexact?: boolean;