@khanacademy/perseus 8.0.0 → 9.0.0

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 = {
@@ -425,22 +428,24 @@ export class ServerItemRenderer
         );
 
         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,15 @@ 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 {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 +112,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 +179,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 +319,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 +340,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"]>;
@@ -369,6 +389,16 @@ export type Tracking =
     // 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 +473,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 +499,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/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,6 +2,9 @@ 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";
 
@@ -32,18 +35,21 @@ export const renderQuestion = (
     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) {
@@ -56,15 +62,17 @@ export const renderQuestion = (
     ) => {
         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) {

package/src/widgets/expression.tsx

@@ -12,7 +12,7 @@ import Tooltip, {
     HorizontalDirection,
     VerticalDirection,
 } from "../components/tooltip";
-import {getDependencies} from "../dependencies";
+import {useDependencies} from "../dependencies";
 import {iconExclamationSign} from "../icon-paths";
 import {Errors as PerseusErrors, Log} from "../logging/log";
 import * as Changeable from "../mixins/changeable";
@@ -23,20 +23,14 @@ import type {
     PerseusExpressionWidgetOptions,
     PerseusExpressionAnswerForm,
 } from "../perseus-types";
-import type {PerseusScore, WidgetExports, WidgetProps} from "../types";
+import type {
+    APIOptions,
+    PerseusScore,
+    WidgetExports,
+    WidgetProps,
+} from "../types";
 import type {Keys as Key} from "@khanacademy/math-input";
 
-const sendExpressionEvaluatedEvent = (
-    result: "correct" | "incorrect" | "invalid",
-) => {
-    getDependencies().analytics({
-        type: "perseus:expression-evaluated",
-        payload: {
-            result,
-        },
-    });
-};
-
 type InputPath = ReadonlyArray<string>;
 
 const ERROR_MESSAGE = i18n._("Sorry, I don't understand that!");
@@ -63,20 +57,43 @@ const insertBraces = (value) => {
     return value.replace(/([_^])([^{])/g, "$1{$2}");
 };
 
+const deriveKeypadVersion = (apiOptions: APIOptions) => {
+    // We can derive which version of the keypad is in use. This is
+    // a bit tricky, but this code will be relatively short-lived
+    // as we coalesce onto the new, v2 Keypad, at which point we
+    // can remove this `virtualKeypadVersion` field entirely.
+    return apiOptions.nativeKeypadProxy != null
+        ? "REACT_NATIVE_KEYPAD"
+        : apiOptions.customKeypad === true
+        ? apiOptions.useV2Keypad === true
+            ? "MATH_INPUT_KEYPAD_V2"
+            : "MATH_INPUT_KEYPAD_V1"
+        : "PERSEUS_MATH_INPUT";
+};
+
 type Rubric = PerseusExpressionWidgetOptions;
 
+type RenderProps = {
+    buttonSets: PerseusExpressionWidgetOptions["buttonSets"];
+    buttonsVisible?: PerseusExpressionWidgetOptions["buttonsVisible"];
+    functions: PerseusExpressionWidgetOptions["functions"];
+    times: PerseusExpressionWidgetOptions["times"];
+    keypadConfiguration: ReturnType<typeof keypadConfigurationForProps>;
+};
+
 type ExternalProps = WidgetProps<RenderProps, Rubric>;
 
-export type Props = ExternalProps & {
-    apiOptions: NonNullable<ExternalProps["apiOptions"]>;
-    buttonSets: NonNullable<ExternalProps["buttonSets"]>;
-    functions: NonNullable<ExternalProps["functions"]>;
-    linterContext: NonNullable<ExternalProps["linterContext"]>;
-    onBlur: NonNullable<ExternalProps["onBlur"]>;
-    onFocus: NonNullable<ExternalProps["onFocus"]>;
-    times: NonNullable<ExternalProps["times"]>;
-    value: string;
-};
+export type Props = ExternalProps &
+    ReturnType<typeof useDependencies> & {
+        apiOptions: NonNullable<ExternalProps["apiOptions"]>;
+        buttonSets: NonNullable<ExternalProps["buttonSets"]>;
+        functions: NonNullable<ExternalProps["functions"]>;
+        linterContext: NonNullable<ExternalProps["linterContext"]>;
+        onBlur: NonNullable<ExternalProps["onBlur"]>;
+        onFocus: NonNullable<ExternalProps["onFocus"]>;
+        times: NonNullable<ExternalProps["times"]>;
+        value: string;
+    };
 
 export type ExpressionState = {
     showErrorTooltip: boolean;
@@ -211,8 +228,6 @@ export class Expression extends React.Component<Props, ExpressionState> {
         // we did, whether it's considered correct, incorrect, or ungraded
         if (!matchingAnswerForm) {
             if (firstUngradedResult) {
-                sendExpressionEvaluatedEvent("invalid");
-
                 // While we didn't directly match with any answer form, we
                 // did at some point get an "ungraded" validation result,
                 // which might indicate e.g. a mismatch in variable casing.
@@ -227,8 +242,6 @@ export class Expression extends React.Component<Props, ExpressionState> {
                 };
             }
             if (allEmpty) {
-                sendExpressionEvaluatedEvent("invalid");
-
                 // If everything graded as empty, it's invalid.
                 return {
                     type: "invalid",
@@ -237,7 +250,6 @@ export class Expression extends React.Component<Props, ExpressionState> {
             }
             // We fell through all the possibilities and we're not empty,
             // so the answer is considered incorrect.
-            sendExpressionEvaluatedEvent("incorrect");
             return {
                 type: "points",
                 earned: 0,
@@ -252,7 +264,6 @@ export class Expression extends React.Component<Props, ExpressionState> {
                 userInput,
                 matchMessage,
             );
-            sendExpressionEvaluatedEvent("invalid");
             return {
                 type: "invalid",
                 message: apiResult === false ? null : matchMessage,
@@ -264,12 +275,6 @@ export class Expression extends React.Component<Props, ExpressionState> {
         // TODO(eater): Seems silly to translate result to this
         // invalid/points thing and immediately translate it back in
         // ItemRenderer.scoreInput()
-        sendExpressionEvaluatedEvent(
-            matchingAnswerForm.considered === "correct"
-                ? "correct"
-                : "incorrect",
-        );
-
         return {
             type: "points",
             earned: matchingAnswerForm.considered === "correct" ? 1 : 0,
@@ -369,7 +374,21 @@ export class Expression extends React.Component<Props, ExpressionState> {
         onInputError: OnInputErrorFunctionType,
     ) => PerseusScore = (rubric, onInputError) => {
         onInputError = onInputError || function () {};
-        return Expression.validate(this.getUserInput(), rubric, onInputError);
+        const result = Expression.validate(
+            this.getUserInput(),
+            rubric,
+            onInputError,
+        );
+
+        this.sendExpressionEvaluatedEvent(
+            result.type === "invalid"
+                ? "invalid"
+                : result.earned === result.total
+                ? "correct"
+                : "incorrect",
+        );
+
+        return result;
     };
 
     getUserInput: () => string = () => {
@@ -471,6 +490,18 @@ export class Expression extends React.Component<Props, ExpressionState> {
         );
     };
 
+    sendExpressionEvaluatedEvent(result: "correct" | "incorrect" | "invalid") {
+        this.props.analytics.onAnalyticsEvent({
+            type: "perseus:expression-evaluated",
+            payload: {
+                result,
+                virtualKeypadVersion: deriveKeypadVersion(
+                    this.props.apiOptions,
+                ),
+            },
+        });
+    }
+
     render():
         | React.ReactNode
         | React.ReactElement<React.ComponentProps<"div">> {
@@ -640,22 +671,25 @@ const propUpgrades = {
     }),
 } as const;
 
-type RenderProps = {
-    buttonSets: any;
-    buttonsVisible?: "always" | "focused" | "never";
-    functions: ReadonlyArray<string>;
-    keypadConfiguration: {
-        extraKeys: ReadonlyArray<any | string>;
-        keypadType: any;
-    };
-    times: boolean;
-};
+const ExpressionWithDependencies = React.forwardRef<
+    Expression,
+    Omit<
+        JSX.LibraryManagedAttributes<
+            typeof Expression,
+            React.ComponentProps<typeof Expression>
+        >,
+        keyof ReturnType<typeof useDependencies>
+    >
+>((props, ref) => {
+    const deps = useDependencies();
+    return <Expression ref={ref} analytics={deps.analytics} {...props} />;
+});
 
 export default {
     name: "expression",
     displayName: "Expression / Equation",
     defaultAlignment: "inline-block",
-    widget: Expression,
+    widget: ExpressionWithDependencies,
     transform: (widgetOptions: PerseusExpressionWidgetOptions): RenderProps => {
         const {times, functions, buttonSets, buttonsVisible} = widgetOptions;
         return {
@@ -671,4 +705,4 @@ export default {
 
     // For use by the editor
     isLintable: true,
-} as WidgetExports<typeof Expression>;
+} as WidgetExports<typeof ExpressionWithDependencies>;