@khanacademy/perseus 8.0.0 → 10.0.0

package/src/multi-items/multi-renderer.tsx

@@ -41,6 +41,7 @@ import {StyleSheet, css} from "aphrodite"; // eslint-disable-line import/no-extr
 import lens from "hubble"; // eslint-disable-line import/no-extraneous-dependencies
 import * as React from "react";
 
+import {DependenciesContext} from "../dependencies";
 import HintsRenderer from "../hints-renderer";
 import {Errors, Log} from "../logging/log";
 import Renderer from "../renderer";
@@ -50,21 +51,23 @@ import {itemToTree} from "./items";
 import {buildMapper} from "./trees";
 
 import type {Widget} from "../renderer";
-import type {APIOptions, FilterCriterion, PerseusScore} from "../types";
+import type {
+    APIOptions,
+    FilterCriterion,
+    PerseusDependenciesV2,
+    PerseusScore,
+} from "../types";
 import type {Item, ContentNode, HintNode, TagsNode} from "./item-types";
 import type {Shape, ArrayShape} from "./shape-types";
 import type {Tree} from "./tree-types";
 import type {TreeMapper, ContentMapper, HintMapper, Path} from "./trees";
+import type {PropsFor} from "@khanacademy/wonder-blocks-core";
 
 type Hint = any; // TODO(mdr)
 type Score = any; // TODO(mdr)
 type SerializedState = any; // TODO(mdr)
 
-type RendererProps = JSX.LibraryManagedAttributes<
-    typeof Renderer,
-    // @ts-expect-error - TS2344 - Type 'typeof Renderer' does not satisfy the constraint 'keyof IntrinsicElements | JSXElementConstructor<any>'.
-    React.ComponentProps<typeof Renderer>
->;
+type RendererProps = PropsFor<typeof Renderer>;
 
 type ContentRendererElement = React.ReactElement<any>;
 type HintRendererElement = React.ReactElement<any>;
@@ -109,6 +112,8 @@ type Props = {
     onInteractWithWidget?: (id: string) => void;
     apiOptions?: APIOptions;
     reviewMode?: boolean | null | undefined;
+
+    dependencies: PerseusDependenciesV2;
 };
 type State = {
     // We cache functions to generate renderers and refs in `rendererDataTree`,
@@ -306,7 +311,6 @@ class MultiRenderer extends React.Component<Props, State> {
             makeRenderer: () => (
                 <HintsRenderer
                     {...this._getRendererProps()}
-                    // @ts-expect-error - TS2769 - No overload matches this call.
                     findExternalWidgets={findExternalWidgets}
                     hints={[hint]}
                 />
@@ -506,7 +510,6 @@ class MultiRenderer extends React.Component<Props, State> {
             (renderers as any).firstN = (n: any) => (
                 <HintsRenderer
                     {...this._getRendererProps()}
-                    // @ts-expect-error - TS2769 - No overload matches this call.
                     findExternalWidgets={
                         hintRendererDatas[0]
                             ? hintRendererDatas[0].findExternalWidgets
@@ -547,9 +550,13 @@ class MultiRenderer extends React.Component<Props, State> {
 
         // Pass the renderer tree to the `children` function, which will
         // determine the actual content of this component.
-        return this.props.children({
-            renderers: this._getRenderers(),
-        });
+        return (
+            <DependenciesContext.Provider value={this.props.dependencies}>
+                {this.props.children({
+                    renderers: this._getRenderers(),
+                })}
+            </DependenciesContext.Provider>
+        );
     }
 }
 

package/src/renderer.tsx

@@ -35,11 +35,11 @@ import type {
     APIOptionsWithDefaults,
     FilterCriterion,
     FocusPath,
-    LinterContextProps,
     PerseusScore,
     WidgetInfo,
     WidgetProps,
 } from "./types";
+import type {LinterContextProps} from "@khanacademy/perseus-linter";
 
 import "./styles/perseus-renderer.less";
 
@@ -213,7 +213,7 @@ class Renderer extends React.Component<Props, State> {
     _foundTextNodes: boolean;
     // @ts-expect-error - TS2564 - Property '_interactionTrackers' has no initializer and is not definitely assigned in the constructor.
     _interactionTrackers: {
-        [id: string]: InteractionTracker;
+        [id: string]: InteractionTracker<any>;
     };
     // @ts-expect-error - TS2564 - Property '_isMounted' has no initializer and is not definitely assigned in the constructor.
     _isMounted: boolean;
@@ -250,8 +250,8 @@ class Renderer extends React.Component<Props, State> {
         linterContext: PerseusLinter.linterContextDefault,
     };
 
-    constructor(props: Props, context: Context) {
-        super(props, context);
+    constructor(props: Props) {
+        super(props);
         this._translationLinter = new TranslationLinter();
 
         this.state = {

package/src/server-item-renderer.tsx

@@ -12,6 +12,7 @@ import * as React from "react";
 import _ from "underscore";
 
 import AssetContext from "./asset-context";
+import {DependenciesContext} from "./dependencies";
 import HintsRenderer from "./hints-renderer";
 import Objective from "./interactive2/objective_";
 import LoadingContext from "./loading-context";
@@ -20,7 +21,7 @@ import Renderer from "./renderer";
 import Util from "./util";
 
 import type {KeypadProps} from "./mixins/provide-keypad";
-import type {APIOptions, FocusPath} from "./types";
+import type {APIOptions, FocusPath, PerseusDependenciesV2} from "./types";
 import type {RendererInterface, KEScore} from "@khanacademy/perseus-core";
 
 const {mapObject} = Objective;
@@ -37,6 +38,8 @@ type OwnProps = // These props are used by the ProvideKeypad mixin.
         reviewMode?: boolean;
         // from KeypadContext
         keypadElement?: any | null | undefined;
+
+        dependencies: PerseusDependenciesV2;
     };
 
 type HOCProps = {
@@ -418,29 +421,30 @@ export class ServerItemRenderer
             <HintsRenderer
                 hints={this.props.item.hints}
                 hintsVisible={this.props.hintsVisible}
-                // @ts-expect-error - TS2769 - No overload matches this call.
                 apiOptions={apiOptions}
                 ref={(elem) => (this.hintsRenderer = elem)}
             />
         );
 
         return (
-            <div>
-                <div>{questionRenderer}</div>
-                <div
-                    className={
-                        // Avoid adding any horizontal padding when applying the
-                        // mobile hint styles, which are flush to the left.
-                        // NOTE(charlie): We may still want to apply this
-                        // padding for desktop exercises.
-                        apiOptions.isMobile
-                            ? undefined
-                            : css(styles.hintsContainer)
-                    }
-                >
-                    {hintsRenderer}
+            <DependenciesContext.Provider value={this.props.dependencies}>
+                <div>
+                    <div>{questionRenderer}</div>
+                    <div
+                        className={
+                            // Avoid adding any horizontal padding when applying the
+                            // mobile hint styles, which are flush to the left.
+                            // NOTE(charlie): We may still want to apply this
+                            // padding for desktop exercises.
+                            apiOptions.isMobile
+                                ? undefined
+                                : css(styles.hintsContainer)
+                        }
+                    >
+                        {hintsRenderer}
+                    </div>
                 </div>
-            </div>
+            </DependenciesContext.Provider>
         );
     }
 }

package/src/types.ts

@@ -4,12 +4,16 @@ import type {Item} from "./multi-items/item-types";
 import type {PerseusWidget} from "./perseus-types";
 import type {SizeClass} from "./util/sizing-utils";
 import type {KeypadAPI} from "@khanacademy/math-input";
-import type {SendEventFn} from "@khanacademy/perseus-core";
+import type {AnalyticsEventHandlerFn} from "@khanacademy/perseus-core";
+import type {LinterContextProps} from "@khanacademy/perseus-linter";
 import type {Result} from "@khanacademy/wonder-blocks-data";
 import type * as React from "react";
 
 export type FocusPath = ReadonlyArray<string> | null | undefined;
 
+// TODO(FEI-5054): Figure out how to get global .d.ts files working with monorepos
+type Empty = Record<never, never>;
+
 export type Dimensions = {
     width?: number;
     height?: number;
@@ -109,6 +113,20 @@ export type Path = ReadonlyArray<string>;
 
 type StubTagEditorType = any; // from "./components/stub-tag-editor";
 
+type TrackInteractionArgs = {
+    // The widget type that this interaction originates from
+    type: string;
+    // The widget id that this interaction originates from
+    id: string;
+
+    correct?: boolean;
+
+    // Tracking args are all optional here because we don't know which
+    // widgets originated the call, and thus can't know what extra
+    // arguments will be included!
+} & Partial<TrackingGradedGroupExtraArguments> &
+    Partial<TrackingSequenceExtraArguments>;
+
 // APIOptions provides different ways to customize the behaviour of Perseus.
 export type APIOptions = Readonly<{
     isArticle?: boolean;
@@ -162,15 +180,7 @@ export type APIOptions = Readonly<{
     // A function that is called when the user has interacted with a widget. It
     // also includes any extra parameters that the originating widget provided.
     // This is used for keeping track of widget interactions.
-    trackInteraction?: (
-        args: {
-            // The widget type that this interaction originates from
-            type: string;
-            // The widget id that this interaction originates from
-            id: string;
-            correct?: boolean;
-        } & Record<string, unknown>,
-    ) => void;
+    trackInteraction?: (args: TrackInteractionArgs) => void;
     // A boolean that indicates whether or not a custom keypad is
     // being used.  For mobile web this will be the ProvidedKeypad
     // component.  In this situation we use the MathInput component
@@ -310,7 +320,6 @@ export type PerseusDependencies = {
     //misc
     staticUrl: StaticUrlFn;
     InitialRequestUrl: InitialRequestUrlInterface;
-    analytics: SendEventFn;
 
     // video widget
     // This is used as a hook to fetch data about a video which is used to
@@ -332,6 +341,18 @@ export type PerseusDependencies = {
     isMobile: boolean;
 };
 
+/**
+ * The modern iteration of Perseus Depedndencies. These dependencies are
+ * provided to Perseus through its entrypoints (for example:
+ * ServerItemRenderer) and then attached to the DependenciesContext so they are
+ * available anywhere down the React render tree.
+ *
+ * Prefer using this type over `PerseusDependencies` when possible.
+ */
+export type PerseusDependenciesV2 = {
+    analytics: {onAnalyticsEvent: AnalyticsEventHandlerFn};
+};
+
 export type APIOptionsWithDefaults = Readonly<
     APIOptions & {
         GroupMetadataEditor: NonNullable<APIOptions["GroupMetadataEditor"]>;
@@ -355,20 +376,22 @@ export type APIOptionsWithDefaults = Readonly<
     }
 >;
 
-export type LinterContextProps = {
-    contentType: string;
-    highlightLint: boolean;
-    paths: ReadonlyArray<string>;
-    stack: ReadonlyArray<string>;
-    // additional properties can be added to the context by widgets
-};
-
 export type Tracking =
     // Track interactions once
     | ""
     // Track all interactions
     | "all";
 
+// See graded-group widget
+export type TrackingGradedGroupExtraArguments = {
+    status: "correct" | "incorrect" | "invalid";
+};
+
+// See sequence widget
+export type TrackingSequenceExtraArguments = {
+    visible: number;
+};
+
 export type Alignment =
     | "default"
     | "block"
@@ -443,7 +466,13 @@ export type FilterCriterion =
       ) => boolean);
 
 // NOTE: Rubric should always be the corresponding widget options type for the component.
-export type WidgetProps<RenderProps, Rubric> = RenderProps & {
+export type WidgetProps<
+    RenderProps,
+    Rubric,
+    // Defines the arguments that can be passed to the `trackInteraction`
+    // function from APIOptions for this widget.
+    TrackingExtraArgs = Empty,
+> = RenderProps & {
     // provided by renderer.jsx#getWidgetProps()
     widgetId: string;
     alignment: string | null | undefined;
@@ -463,7 +492,7 @@ export type WidgetProps<RenderProps, Rubric> = RenderProps & {
     // APIOptions. This provides the widget an easy way to notify the renderer
     // of an interaction. The Renderer then enriches the data provided with the
     // widget's id and type before calling APIOptions.trackInteraction.
-    trackInteraction: (extraData?: any) => void;
+    trackInteraction: (extraData?: TrackingExtraArgs) => void;
     isLastUsedWidget: boolean;
     // provided by widget-container.jsx#render()
     linterContext: LinterContextProps;

package/src/widget-container.tsx

@@ -9,7 +9,8 @@ import {containerSizeClass, getClassFromWidth} from "./util/sizing-utils";
 import * as Widgets from "./widgets";
 
 import type {PerseusWidgetOptions} from "./perseus-types";
-import type {LinterContextProps, WidgetProps} from "./types";
+import type {WidgetProps} from "./types";
+import type {LinterContextProps} from "@khanacademy/perseus-linter";
 
 type Props = {
     shouldHighlight: boolean;

package/src/widgets/__stories__/definition.stories.tsx

@@ -1,6 +1,7 @@
 import * as React from "react";
 
 import {RendererWithDebugUI} from "../../../../../testing/renderer-with-debug-ui";
+import {storybookDependenciesV2} from "../../../../../testing/test-dependencies";
 import ArticleRenderer from "../../article-renderer";
 
 export default {
@@ -103,5 +104,11 @@ export const MultipleDefinitions = (args: StoryArgs): React.ReactElement => {
 };
 
 export const ArticleDefintion = (args: StoryArgs): React.ReactElement => {
-    return <ArticleRenderer json={article} useNewStyles />;
+    return (
+        <ArticleRenderer
+            json={article}
+            useNewStyles
+            dependencies={storybookDependenciesV2}
+        />
+    );
 };

package/src/widgets/__stories__/expression.stories.tsx

@@ -1,4 +1,4 @@
-import {KeypadContext} from "@khanacademy/math-input";
+import {KeypadContext, KeypadType} from "@khanacademy/math-input";
 import * as React from "react";
 
 import {ItemRendererWithDebugUI} from "../../../../../testing/item-renderer-with-debug-ui";
@@ -62,7 +62,7 @@ export const DesktopKitchenSink = (args: StoryArgs): React.ReactElement => {
     };
 
     const keypadConfiguration = {
-        keypadType: "EXPRESSION",
+        keypadType: KeypadType.EXPRESSION,
         extraKeys: ["x", "y", "z"],
     };
 

package/src/widgets/__tests__/{expression.test.ts → expression.test.tsx}

@@ -3,7 +3,10 @@ import {screen, fireEvent} from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import "@testing-library/jest-dom";
 
-import {testDependencies} from "../../../../../testing/test-dependencies";
+import {
+    testDependencies,
+    testDependenciesV2,
+} from "../../../../../testing/test-dependencies";
 import * as Dependencies from "../../dependencies";
 import {
     expressionItem2,
@@ -15,8 +18,13 @@ import {Expression} from "../expression";
 import {renderQuestion} from "./renderQuestion";
 
 import type {PerseusItem} from "../../perseus-types";
+import type {APIOptions} from "../../types";
 
-const assertComplete = (itemData: PerseusItem, input, isCorrect: boolean) => {
+const assertComplete = (
+    itemData: PerseusItem,
+    input: string,
+    isCorrect: boolean,
+) => {
     const {renderer} = renderQuestion(itemData.question);
     userEvent.type(screen.getByRole("textbox"), input);
     const [_, score] = renderer.guessAndScore();
@@ -27,13 +35,14 @@ const assertComplete = (itemData: PerseusItem, input, isCorrect: boolean) => {
     });
 };
 
-const assertCorrect = (itemData: PerseusItem, input) => {
+const assertCorrect = (itemData: PerseusItem, input: string) => {
     assertComplete(itemData, input, true);
 
-    expect(testDependencies.analytics).toHaveBeenCalledWith({
+    expect(testDependenciesV2.analytics.onAnalyticsEvent).toHaveBeenCalledWith({
         type: "perseus:expression-evaluated",
         payload: {
             result: "correct",
+            virtualKeypadVersion: "PERSEUS_MATH_INPUT",
         },
     });
 };
@@ -41,16 +50,21 @@ const assertCorrect = (itemData: PerseusItem, input) => {
 const assertIncorrect = (itemData: PerseusItem, input: string) => {
     assertComplete(itemData, input, false);
 
-    expect(testDependencies.analytics).toHaveBeenCalledWith({
+    expect(testDependenciesV2.analytics.onAnalyticsEvent).toHaveBeenCalledWith({
         type: "perseus:expression-evaluated",
         payload: {
             result: "incorrect",
+            virtualKeypadVersion: "PERSEUS_MATH_INPUT",
         },
     });
 };
 
 // TODO: actually Assert that message is being set on the score object.
-const assertInvalid = (itemData: PerseusItem, input, message?: string) => {
+const assertInvalid = (
+    itemData: PerseusItem,
+    input: string,
+    message?: string,
+) => {
     const {renderer} = renderQuestion(itemData.question);
     if (input.length) {
         userEvent.type(screen.getByRole("textbox"), input);
@@ -58,17 +72,18 @@ const assertInvalid = (itemData: PerseusItem, input, message?: string) => {
     const [_, score] = renderer.guessAndScore();
     expect(score).toMatchObject({type: "invalid"});
 
-    expect(testDependencies.analytics).toHaveBeenCalledWith({
+    expect(testDependenciesV2.analytics.onAnalyticsEvent).toHaveBeenCalledWith({
         type: "perseus:expression-evaluated",
         payload: {
             result: "invalid",
+            virtualKeypadVersion: "PERSEUS_MATH_INPUT",
         },
     });
 };
 
 describe("Expression Widget", function () {
     beforeEach(() => {
-        jest.spyOn(testDependencies, "analytics");
+        jest.spyOn(testDependenciesV2.analytics, "onAnalyticsEvent");
         jest.spyOn(Dependencies, "getDependencies").mockReturnValue(
             testDependencies,
         );
@@ -171,6 +186,56 @@ describe("Expression Widget", function () {
             expect(err).toStrictEqual({message: null, type: "invalid"});
         });
     });
+
+    describe("analytics", () => {
+        const assertKeypadVersion = (
+            apiOptions: APIOptions,
+            virtualKeypadVersion: string,
+        ) => {
+            const {renderer} = renderQuestion(
+                expressionItem2.question,
+                apiOptions,
+            );
+
+            renderer.guessAndScore();
+
+            expect(
+                testDependenciesV2.analytics.onAnalyticsEvent,
+            ).toHaveBeenCalledWith({
+                type: "perseus:expression-evaluated",
+                payload: {
+                    // We're not interested in validating that the expression
+                    // widget did anything useful or that the keypad worked. We
+                    // just want to make sure the code that derives which
+                    // keypad version it detected is correct.
+                    result: "invalid",
+                    virtualKeypadVersion,
+                },
+            });
+        };
+
+        it("should set the virtual keypad version to REACT_NATIVE_KEYPAD when nativeKeypadProxy is provided", () => {
+            assertKeypadVersion(
+                {nativeKeypadProxy: jest.fn()},
+                "REACT_NATIVE_KEYPAD",
+            );
+        });
+
+        it("should set the virtual keypad version to MATH_INPUT_KEYPAD_V1 when customKeypad is set and useV2Keypad is unset", () => {
+            assertKeypadVersion({customKeypad: true}, "MATH_INPUT_KEYPAD_V1");
+        });
+
+        it("should set the virtual keypad version to MATH_INPUT_KEYPAD_V2 when customKeypad is set and useV2Keypad is true", () => {
+            assertKeypadVersion(
+                {customKeypad: true, useV2Keypad: true},
+                "MATH_INPUT_KEYPAD_V2",
+            );
+        });
+
+        it("should default the virtual keypad version to PERSEUS_MATH_INPUT", () => {
+            assertKeypadVersion(Object.freeze({}), "PERSEUS_MATH_INPUT");
+        });
+    });
 });
 
 describe("getOneCorrectAnswerFromRubric", () => {

package/src/widgets/__tests__/renderQuestion.tsx

@@ -2,48 +2,47 @@ import {RenderStateRoot} from "@khanacademy/wonder-blocks-core";
 import {render} from "@testing-library/react";
 import * as React from "react";
 
+// eslint-disable-next-line import/no-relative-packages
+import {testDependenciesV2} from "../../../../../testing/test-dependencies";
+import {DependenciesContext} from "../../dependencies";
 import * as Perseus from "../../index";
 import {registerAllWidgetsForTesting} from "../../util/register-all-widgets-for-testing";
 
 import type {PerseusRenderer} from "../../perseus-types";
 import type {APIOptions} from "../../types";
+import type {PropsFor} from "@khanacademy/wonder-blocks-core";
 
 type RenderResult = ReturnType<typeof render>;
 
 export const renderQuestion = (
     question: PerseusRenderer,
     apiOptions: APIOptions = Object.freeze({}),
-    extraProps?: JSX.LibraryManagedAttributes<
-        typeof Perseus.Renderer,
-        // @ts-expect-error - TS2344 - Type 'typeof Renderer' does not satisfy the constraint 'keyof IntrinsicElements | JSXElementConstructor<any>'.
-        React.ComponentProps<typeof Perseus.Renderer>
-    >,
+    extraProps?: PropsFor<typeof Perseus.Renderer>,
 ): {
     container: HTMLElement;
     renderer: Perseus.Renderer;
     rerender: (
         question: PerseusRenderer,
-        extraProps?: JSX.LibraryManagedAttributes<
-            typeof Perseus.Renderer,
-            // @ts-expect-error - TS2344 - Type 'typeof Renderer' does not satisfy the constraint 'keyof IntrinsicElements | JSXElementConstructor<any>'.
-            React.ComponentProps<typeof Perseus.Renderer>
-        >,
+        extraProps?: PropsFor<typeof Perseus.Renderer>,
     ) => void;
     unmount: RenderResult["unmount"];
 } => {
     registerAllWidgetsForTesting();
+
     let renderer: Perseus.Renderer | null = null;
     const {container, rerender, unmount} = render(
         <RenderStateRoot>
-            <Perseus.Renderer
-                ref={(node) => (renderer = node)}
-                content={question.content}
-                images={question.images}
-                widgets={question.widgets}
-                problemNum={0}
-                apiOptions={apiOptions}
-                {...extraProps}
-            />
+            <DependenciesContext.Provider value={testDependenciesV2}>
+                <Perseus.Renderer
+                    ref={(node) => (renderer = node)}
+                    content={question.content}
+                    images={question.images}
+                    widgets={question.widgets}
+                    problemNum={0}
+                    apiOptions={apiOptions}
+                    {...extraProps}
+                />
+            </DependenciesContext.Provider>
         </RenderStateRoot>,
     );
     if (!renderer) {
@@ -51,20 +50,21 @@ export const renderQuestion = (
     }
     const renderAgain = (
         question: PerseusRenderer,
-        // @ts-expect-error - TS2344 - Type 'typeof Renderer' does not satisfy the constraint 'keyof IntrinsicElements | JSXElementConstructor<any>'.
         extraProps: undefined | React.ComponentProps<typeof Perseus.Renderer>,
     ) => {
         rerender(
             <RenderStateRoot>
-                <Perseus.Renderer
-                    ref={(node) => (renderer = node)}
-                    content={question.content}
-                    images={question.images}
-                    widgets={question.widgets}
-                    problemNum={0}
-                    apiOptions={apiOptions}
-                    {...extraProps}
-                />
+                <DependenciesContext.Provider value={testDependenciesV2}>
+                    <Perseus.Renderer
+                        ref={(node) => (renderer = node)}
+                        content={question.content}
+                        images={question.images}
+                        widgets={question.widgets}
+                        problemNum={0}
+                        apiOptions={apiOptions}
+                        {...extraProps}
+                    />
+                </DependenciesContext.Provider>
             </RenderStateRoot>,
         );
         if (!renderer) {