@khanacademy/perseus-core 0.0.0-PR973-20240207193807 → 0.0.0-PR973-20240207194831

package/.babelrc.js

@@ -0,0 +1,8 @@
+/**
+ * HACK(kevinb): Due to https://github.com/facebook/jest/issues/11741,
+ * we need to have this file, or updating inline snapshots can fail rather
+ * cryptically.
+ *
+ * We should remove this when jest is fixed.
+ */
+module.exports = require("../../config/build/babel.config");

package/.eslintrc.js

@@ -0,0 +1,12 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+/* eslint-disable import/no-commonjs */
+const path = require("path");
+
+module.exports = {
+    rules: {
+        "import/no-extraneous-dependencies": [
+            "error",
+            {packageDir: [__dirname, path.join(__dirname, "../../")]},
+        ],
+    },
+};

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# @khanacademy/perseus-core
+
+## 0.0.0-PR973-20240207194831
+
+### Patch Changes
+
+-   [#973](https://github.com/Khan/perseus/pull/973) [`2ffc6971`](https://github.com/Khan/perseus/commit/2ffc6971e7003cbc64a8a3988337c6ca6019c9db) Thanks [@jeremywiebe](https://github.com/jeremywiebe)! - Include 'types' key in package.json and move types to 'types' package subdirectory
+
+## 1.4.2
+
+### Patch Changes
+
+-   [#971](https://github.com/Khan/perseus/pull/971) [`90ff7a48`](https://github.com/Khan/perseus/commit/90ff7a483b01552a556c7852427e98153cc20417) Thanks [@benchristel](https://github.com/benchristel)! - Remove source files from the distributed NPM package
+
+## 1.4.1
+
+### Patch Changes
+
+-   [#860](https://github.com/Khan/perseus/pull/860) [`1f4e17ba`](https://github.com/Khan/perseus/commit/1f4e17ba77e1491523813655af18a70285a25989) Thanks [@nixterrimus](https://github.com/nixterrimus)! - Add hover states in label-image widget
+
+*   [#848](https://github.com/Khan/perseus/pull/848) [`8857950b`](https://github.com/Khan/perseus/commit/8857950bdeeb6e13bc3766b1c6545289b21cbe2a) Thanks [@nixterrimus](https://github.com/nixterrimus)! - Add analytics for label image
+
+## 1.4.0
+
+### Minor Changes
+
+-   [#794](https://github.com/Khan/perseus/pull/794) [`a91c84fe`](https://github.com/Khan/perseus/commit/a91c84fe53827ff4333220777a9918882b7fe9f0) Thanks [@SonicScrewdriver](https://github.com/SonicScrewdriver)! - Removing the useV2Keypad apiOption as the V1 keypad is no longer in use.
+
+### Patch Changes
+
+-   [#814](https://github.com/Khan/perseus/pull/814) [`105d2060`](https://github.com/Khan/perseus/commit/105d20603d935d35cff237b17f0bfb57ca751e4c) Thanks [@jeremywiebe](https://github.com/jeremywiebe)! - Minor build change to how we provide Typescript type definitions (should be no change to build output).
+
+## 1.3.0
+
+### Minor Changes
+
+-   [#783](https://github.com/Khan/perseus/pull/783) [`79403e06`](https://github.com/Khan/perseus/commit/79403e06eedb597d7818d6c858bbba6f51ff3fe1) Thanks [@jeremywiebe](https://github.com/jeremywiebe)! - Adds 'widgetId' to the 'perseus:widget-rendering-error' analytics event.
+
+## 1.2.0
+
+### Minor Changes
+
+-   [#780](https://github.com/Khan/perseus/pull/780) [`376eb0e4`](https://github.com/Khan/perseus/commit/376eb0e4aaaa4c7a90fd6107a84bb74d382b077c) Thanks [@jeremywiebe](https://github.com/jeremywiebe)! - Added 'perseus:widget-rendering-error' analytics event.
+
+## 1.1.2
+
+### Patch Changes
+
+-   22a9c408: Fix bug caused by package version diagnostics
+
+## 1.1.1
+
+### Patch Changes
+
+-   55d4cd00: Print package name and version when loaded in the page
+
+## 1.1.0
+
+### Minor Changes
+
+-   4f4fe4f9: Added new analytics event "perseus:expression-focused"
+
+## 1.0.0
+
+### Major Changes
+
+-   2af4f9fa: Switch from using ProvideKeypad in ArticleRenderer to passing the keypad element down instead
+
+## 0.2.0
+
+### Minor Changes
+
+-   dd800c22: Rename analytics prop from onEvent to onAnalyticsEvent
+
+## 0.1.1
+
+### Patch Changes
+
+-   57f75510: Commented RendererInterface
+
+## 0.1.0
+
+### Minor Changes
+
+-   b4c06409: Add perseus-core to changeset
+
+## 0.0.2
+
+### Patch Changes
+
+-   71c631ea: Add keypad opened and closed analytics events
+
+## 0.0.1
+
+### Patch Changes
+
+-   1f3fdc6c: Introducing `perseus-core` for types and functionality shared across the Perseus ecosystem

package/package.json

@@ -3,7 +3,7 @@
     "description": "Shared Perseus infrastructure",
     "author": "Khan Academy",
     "license": "MIT",
-    "version": "0.0.0-PR973-20240207193807",
+    "version": "0.0.0-PR973-20240207194831",
     "publishConfig": {
         "access": "public"
     },
@@ -19,9 +19,6 @@
     "main": "dist/index.js",
     "source": "src/index.ts",
     "types": "dist/types/index.d.ts",
-    "files": [
-        "dist"
-    ],
     "scripts": {
         "test": "bash -c 'yarn --silent --cwd \"../..\" test ${@:0} $($([[ ${@: -1} = -* ]] || [[ ${@: -1} = bash ]]) && echo $PWD)'"
     },

package/src/analytics.ts

@@ -0,0 +1,64 @@
+export type VirtualKeypadVersion =
+    | "MATH_INPUT_KEYPAD_V2"
+    | "REACT_NATIVE_KEYPAD";
+
+/**
+ * A type union of all the events that any package in the Perseus ecosystem can
+ * send.
+ */
+export type PerseusAnalyticsEvent =
+    | {
+          type: "perseus:expression-evaluated";
+          payload: {
+              virtualKeypadVersion: VirtualKeypadVersion;
+              result: "correct" | "incorrect" | "invalid";
+          };
+      }
+    | {
+          type: "perseus:expression-focused";
+          payload: null;
+      }
+    | {
+          type: "perseus:widget-rendering-error";
+          payload: {
+              widgetType: string;
+              widgetId: string;
+          };
+      }
+    | {
+          type: "perseus:label-image:toggle-answers-hidden";
+          payload: null;
+      }
+    | {
+          type: "perseus:label-image:marker-interacted-with";
+          payload: null;
+      }
+    | {
+          type: "perseus:label-image:choiced-interacted-with";
+          payload: null;
+      }
+    | {
+          type: "math-input:keypad-closed";
+          payload: {
+              virtualKeypadVersion: VirtualKeypadVersion;
+          };
+      }
+    | {
+          type: "math-input:keypad-opened";
+          payload: {
+              virtualKeypadVersion: VirtualKeypadVersion;
+          };
+      };
+
+// Add more events here as needed. Note that each event should have a `type`
+// key and a payload that varies by type.
+// | {type: "b"; payload: {name: string}};
+//
+// Event types should be formatted as "package-name:event-name" (where the
+// package name is the name of the package that emits the event without the
+// `@khanacademy/` prefix and then the name of the event.)
+
+/** A function that is called when Perseus emits an analytics event. */
+export type AnalyticsEventHandlerFn = (
+    event: PerseusAnalyticsEvent,
+) => Promise<void>;

package/src/index.ts

@@ -0,0 +1,11 @@
+export type {PerseusAnalyticsEvent, AnalyticsEventHandlerFn} from "./analytics";
+export type {
+    KEScore,
+    KeypadContextRendererInterface,
+    RendererInterface,
+} from "./types";
+
+// Careful, `version.ts` uses this function so it _must_ be imported above it
+export {addLibraryVersionToPerseusDebug} from "./utils/add-library-version-to-perseus-debug";
+
+export {libVersion} from "./version";

package/src/types.ts

@@ -0,0 +1,30 @@
+// Types that can be shared between Perseus packages
+// ideally without causing circular dependencies
+
+// Used by KeypadContext to pass around a renderer reference
+export interface KeypadContextRendererInterface {
+    blur(): void;
+}
+
+// TODO: this should be typed
+type State = any;
+
+// Interfact currently only implemented by
+// ServerItemRenderer
+export interface RendererInterface {
+    getSerializedState(): State;
+    restoreSerializedState(state: State, callback?: () => void): void;
+    scoreInput(): KEScore;
+    blur(): void;
+    focus(): boolean | null | undefined;
+    props: any;
+}
+
+export type KEScore = {
+    empty: boolean;
+    correct: boolean;
+    message?: string | null | undefined;
+    suppressAlmostThere?: boolean | null | undefined;
+    guess: any;
+    state: any;
+};

package/src/utils/add-library-version-to-perseus-debug.test.ts

@@ -0,0 +1,109 @@
+import {addLibraryVersionToPerseusDebug} from "./add-library-version-to-perseus-debug";
+
+describe("add-library-version-to-perseus-debug", () => {
+    beforeEach(() => {
+        delete globalThis.__perseus_debug__;
+    });
+
+    it("should add the given library to __perseus_debug__", () => {
+        // Array
+
+        // Act
+        addLibraryVersionToPerseusDebug("test-lib", "1.0.0");
+
+        // Assert
+        expect(globalThis.__perseus_debug__).toMatchInlineSnapshot(`
+            {
+              "test-lib": "v1.0.0",
+            }
+        `);
+    });
+
+    it("should extend __perseus_debug__ when multiple libraries registered", () => {
+        // Arrange
+
+        // Act
+        addLibraryVersionToPerseusDebug("test-lib", "1.0.0");
+        addLibraryVersionToPerseusDebug("sample-lib", "2.0.0");
+        addLibraryVersionToPerseusDebug("utility-lib", "3.0.0");
+
+        // Assert
+        expect(globalThis.__perseus_debug__).toMatchInlineSnapshot(`
+            {
+              "sample-lib": "v2.0.0",
+              "test-lib": "v1.0.0",
+              "utility-lib": "v3.0.0",
+            }
+        `);
+    });
+
+    it("should convert library entry to array when multiple versions of the same library registered", () => {
+        // Arrange
+        jest.spyOn(console, "warn").mockImplementation();
+
+        // Act
+        addLibraryVersionToPerseusDebug("test-lib", "1.0.1");
+        addLibraryVersionToPerseusDebug("test-lib", "4.1.8");
+        addLibraryVersionToPerseusDebug("test-lib", "1.0.0");
+        addLibraryVersionToPerseusDebug("test-lib", "2.0.0");
+
+        // Assert
+        expect(globalThis.__perseus_debug__).toMatchInlineSnapshot(`
+            {
+              "test-lib": [
+                "v1.0.0",
+                "v1.0.1",
+                "v2.0.0",
+                "v4.1.8",
+              ],
+            }
+        `);
+    });
+
+    it("should warn when multiple versions of the same library registered", () => {
+        // Arrange
+        const warnSpy = jest.spyOn(console, "warn").mockImplementation();
+
+        // Act
+        addLibraryVersionToPerseusDebug("test-lib", "1.0.1");
+        addLibraryVersionToPerseusDebug("test-lib", "4.1.8");
+        addLibraryVersionToPerseusDebug("test-lib", "1.0.0");
+        addLibraryVersionToPerseusDebug("test-lib", "2.0.0");
+
+        // Assert
+        expect(warnSpy).toHaveBeenCalledWith(
+            expect.stringMatching(
+                /Multiple versions of test-lib loaded on this page/,
+            ),
+        );
+    });
+
+    it("should not register duplicates for duplicate calls of the same library and version", () => {
+        // Arrange
+
+        // Act
+        addLibraryVersionToPerseusDebug("test-lib", "1.0.0");
+        addLibraryVersionToPerseusDebug("test-lib", "1.0.0");
+        addLibraryVersionToPerseusDebug("test-lib", "1.0.0");
+
+        // Assert
+        expect(globalThis.__perseus_debug__).toMatchInlineSnapshot(`
+            {
+              "test-lib": "v1.0.0",
+            }
+        `);
+    });
+
+    it("should not warn for duplicate calls for a library of the same library and version", () => {
+        // Arrange
+        const warnSpy = jest.spyOn(console, "warn").mockImplementation();
+
+        // Act
+        addLibraryVersionToPerseusDebug("test-lib", "1.0.0");
+        addLibraryVersionToPerseusDebug("test-lib", "1.0.0");
+        addLibraryVersionToPerseusDebug("test-lib", "1.0.0");
+
+        // Assert
+        expect(warnSpy).not.toHaveBeenCalled();
+    });
+});

package/src/utils/add-library-version-to-perseus-debug.ts

@@ -0,0 +1,52 @@
+/**
+ * Adds the given perseus library version information to the __perseus_debug__
+ * object and ensures that the object is attached to `globalThis` (`window` in
+ * browser environments).
+ *
+ * This allows each library to provide runtime version information to assist in
+ * debugging in production environments.
+ */
+export const addLibraryVersionToPerseusDebug = (
+    libraryName: string,
+    libraryVersion: string,
+) => {
+    // If the library version is the default value, then we don't want to
+    // prefix it with a "v" to indicate that it is a version number.
+    let prefix = "v";
+    if (libraryVersion === "__lib_version__") {
+        prefix = "";
+    }
+    const formattedVersion = `${prefix}${libraryVersion}`;
+
+    if (typeof globalThis !== "undefined") {
+        globalThis.__perseus_debug__ = globalThis.__perseus_debug__ ?? {};
+
+        const existingVersionEntry = globalThis.__perseus_debug__[libraryName];
+        if (existingVersionEntry) {
+            // If we already have an entry and it doesn't match the registered
+            // version, we morph the entry into an array and log a warning.
+            if (existingVersionEntry !== formattedVersion) {
+                // Existing entry might be an array already (oops, at least 2
+                // versions of the library already loaded!).
+                const allVersions = Array.isArray(existingVersionEntry)
+                    ? existingVersionEntry
+                    : [existingVersionEntry];
+                allVersions.push(formattedVersion);
+
+                globalThis.__perseus_debug__[libraryName] = allVersions;
+
+                // eslint-disable-next-line no-console
+                console.warn(
+                    `Multiple versions of ${libraryName} loaded on this page: ${allVersions
+                        .sort()
+                        .join(", ")}`,
+                );
+            }
+        } else {
+            globalThis.__perseus_debug__[libraryName] = formattedVersion;
+        }
+    } else {
+        // eslint-disable-next-line no-console
+        console.warn(`globalThis not found found (${formattedVersion})`);
+    }
+};

package/src/version.ts

@@ -0,0 +1,10 @@
+// This file is processed by a Rollup plugin (replace) to inject the production
+// version number during the release build.
+// In dev, you'll never see the version number.
+
+import {addLibraryVersionToPerseusDebug} from "./utils/add-library-version-to-perseus-debug";
+
+const libName = "@khanacademy/perseus-core";
+export const libVersion = "__lib_version__";
+
+addLibraryVersionToPerseusDebug(libName, libVersion);

package/tsconfig-build.json

@@ -0,0 +1,19 @@
+{
+    "extends": "../tsconfig-shared.json",
+    "compilerOptions": {
+        "outDir": "./dist/types",
+        "rootDir": "src",
+        "paths": {
+            // NOTE(kevinb): We have to repeat this here because TS doesn't do
+            // intelligent merge of tsconfig.json files when using `extends`.
+            "@khanacademy/*": [
+                "../*/src"
+            ]
+        }
+    },
+    "references": [
+        /* Add in-repo pacakge references here, like this:
+           {"path": "../path/to/package/tsconfig-build.json"}
+        */
+    ]
+}