Create helper to build public widget options for Matcher

.changeset/tricky-hairs-grin.md

@@ -0,0 +1,6 @@
+---
+"@khanacademy/perseus": minor
+"@khanacademy/perseus-core": minor
+---
+
+Implement a widget export function to filter out rubric data from widget options for the Matcher widget

package.json

@@ -153,5 +153,6 @@
     "nyc": {
         "report-dir": "coverage/cypress/"
     },
-    "dependencies": {}
+    "dependencies": {},
+    "packageManager": "[email protected]+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

packages/perseus-core/src/index.ts

@@ -138,3 +138,6 @@ export {default as getTablePublicWidgetOptions} from "./widgets/table/table-util
 export {default as getIFramePublicWidgetOptions} from "./widgets/iframe/iframe-util";
 export {default as getMatrixPublicWidgetOptions} from "./widgets/matrix/matrix-util";
 export {default as getPlotterPublicWidgetOptions} from "./widgets/plotter/plotter-util";
+export {default as getMatcherPublicWidgetOptions} from "./widgets/matcher/matcher-util";
+export {shuffleMatcher} from "./widgets/matcher/matcher-util";
+export {default as CoreUtil} from "./utils/random_utils";

packages/perseus-core/src/utils/random_utils.ts

@@ -0,0 +1,77 @@
+/* Note(tamara): Brought over from the perseus package packages/perseus/src/util.ts file.
+    May be useful to bring other perseus package utilities here. Contains utility functions
+    and types used across multiple widgets for randomization and shuffling. */
+
+import _ from "underscore";
+
+type RNG = () => number;
+
+const seededRNG: (seed: number) => RNG = function (seed: number): RNG {
+    let randomSeed = seed;
+
+    return function () {
+        // Robert Jenkins' 32 bit integer hash function.
+        let seed = randomSeed;
+        seed = (seed + 0x7ed55d16 + (seed << 12)) & 0xffffffff;
+        seed = (seed ^ 0xc761c23c ^ (seed >>> 19)) & 0xffffffff;
+        seed = (seed + 0x165667b1 + (seed << 5)) & 0xffffffff;
+        seed = ((seed + 0xd3a2646c) ^ (seed << 9)) & 0xffffffff;
+        seed = (seed + 0xfd7046c5 + (seed << 3)) & 0xffffffff;
+        seed = (seed ^ 0xb55a4f09 ^ (seed >>> 16)) & 0xffffffff;
+        return (randomSeed = seed & 0xfffffff) / 0x10000000;
+    };
+};
+
+// Shuffle an array using a given random seed or function.
+// If `ensurePermuted` is true, the input and output are guaranteed to be
+// distinct permutations.
+function shuffle<T>(
+    array: ReadonlyArray<T>,
+    randomSeed: number | RNG,
+    ensurePermuted = false,
+): ReadonlyArray<T> {
+    // Always return a copy of the input array
+    const shuffled = _.clone(array);
+
+    // Handle edge cases (input array is empty or uniform)
+    if (
+        !shuffled.length ||
+        _.all(shuffled, function (value) {
+            return _.isEqual(value, shuffled[0]);
+        })
+    ) {
+        return shuffled;
+    }
+
+    let random;
+    if (typeof randomSeed === "function") {
+        random = randomSeed;
+    } else {
+        random = seededRNG(randomSeed);
+    }
+
+    do {
+        // Fischer-Yates shuffle
+        for (let top = shuffled.length; top > 0; top--) {
+            const newEnd = Math.floor(random() * top);
+            const temp = shuffled[newEnd];
+
+            // @ts-expect-error - TS2542 - Index signature in type 'readonly T[]' only permits reading.
+            shuffled[newEnd] = shuffled[top - 1];
+            // @ts-expect-error - TS2542 - Index signature in type 'readonly T[]' only permits reading.
+            shuffled[top - 1] = temp;
+        }
+    } while (ensurePermuted && _.isEqual(array, shuffled));
+
+    return shuffled;
+}
+
+const random: RNG = seededRNG(new Date().getTime() & 0xffffffff);
+
+export const CoreUtil = {
+    seededRNG,
+    shuffle,
+    random,
+} as const;
+
+export default CoreUtil;

packages/perseus-core/src/widgets/matcher/matcher-util.test.ts

@@ -0,0 +1,41 @@
+import getMatcherPublicWidgetOptions from "./matcher-util";
+
+import type {PerseusMatcherWidgetOptions} from "../../data-schema";
+
+describe("getMatcherPublicWidgetOptions", () => {
+    it("should return a shuffled right array when order doesn't matter to remove the correct order information", () => {
+        // Arrange
+        const options: PerseusMatcherWidgetOptions = {
+            labels: ["**Claims**", "**Evidence**"],
+            padding: true,
+            orderMatters: false,
+            left: ["Fuel", "Plate", "Hydrogen", "Average", "Billion"],
+            right: ["Stars", "Earth", "Life", "Rapid", "Milky Way"],
+        };
+
+        // Act
+        const publicWidgetOptions = getMatcherPublicWidgetOptions(options);
+
+        // Assert
+        expect(publicWidgetOptions.left).toEqual(options.left);
+        expect(publicWidgetOptions.right).not.toEqual(options.right);
+    });
+
+    it("should return shuffled left and right arrays when order matters to remove the correct order information", () => {
+        // Arrange
+        const options: PerseusMatcherWidgetOptions = {
+            labels: ["**Claims**", "**Evidence**"],
+            padding: true,
+            orderMatters: true,
+            left: ["Fuel", "Plate", "Hydrogen", "Average", "Billion"],
+            right: ["Stars", "Earth", "Life", "Rapid", "Milky Way"],
+        };
+
+        // Act
+        const publicWidgetOptions = getMatcherPublicWidgetOptions(options);
+
+        // Assert
+        expect(publicWidgetOptions.left).not.toEqual(options.left);
+        expect(publicWidgetOptions.right).not.toEqual(options.right);
+    });
+});

packages/perseus-core/src/widgets/matcher/matcher-util.ts

@@ -0,0 +1,94 @@
+import {CoreUtil} from "@khanacademy/perseus-core";
+
+import type {PerseusMatcherWidgetOptions} from "@khanacademy/perseus-core";
+
+// TODO(LEMS-2841): Should be able to remove once getPublicWidgetOptions is hooked up
+type MatcherInfo = {
+    left: ReadonlyArray<string>;
+    right: ReadonlyArray<string>;
+    orderMatters: boolean;
+    problemNum: number | null | undefined;
+};
+
+type MatcherShuffleInfo = {
+    left: ReadonlyArray<string>;
+    right: ReadonlyArray<string>;
+    orderMatters: boolean;
+};
+
+// TODO(LEMS-2841): Should be able to remove once getPublicWidgetOptions is hooked up
+export const shuffleMatcher = (
+    props: MatcherInfo,
+): {left: ReadonlyArray<string>; right: ReadonlyArray<string>} => {
+    // Use the same random() function to shuffle both columns sequentially
+    const rng = CoreUtil.seededRNG(props.problemNum as number);
+
+    let left;
+    if (!props.orderMatters) {
+        // If the order doesn't matter, don't shuffle the left column
+        left = props.left;
+    } else {
+        left = CoreUtil.shuffle(props.left, rng, /* ensurePermuted */ true);
+    }
+
+    const right = CoreUtil.shuffle(props.right, rng, /* ensurePermuted */ true);
+
+    return {left, right};
+};
+
+// TODO(LEMS-2841): Can shorten to shuffleMatcher after above function removed
+function shuffleMatcherWithRandom(data: MatcherShuffleInfo): {
+    left: ReadonlyArray<string>;
+    right: ReadonlyArray<string>;
+} {
+    // Use the same random() function to shuffle both columns sequentially
+    let left;
+    if (!data.orderMatters) {
+        // If the order doesn't matter, don't shuffle the left column
+        left = data.left;
+    } else {
+        left = CoreUtil.shuffle(
+            data.left,
+            Math.random() * 100,
+            /* ensurePermuted */ true,
+        );
+    }
+
+    const right = CoreUtil.shuffle(
+        data.right,
+        Math.random() * 100,
+        /* ensurePermuted */ true,
+    );
+
+    return {left, right};
+}
+
+/**
+ * For details on the individual options, see the
+ * PerseusMatcherWidgetOptions type
+ */
+type MatcherPublicWidgetOptions = {
+    labels: PerseusMatcherWidgetOptions["labels"];
+    left: PerseusMatcherWidgetOptions["left"];
+    right: PerseusMatcherWidgetOptions["right"];
+    orderMatters: PerseusMatcherWidgetOptions["orderMatters"];
+    padding: PerseusMatcherWidgetOptions["padding"];
+};
+
+/**
+ * Given a PerseusMatcherWidgetOptions object, return a new object with only
+ * the public options that should be exposed to the client.
+ */
+function getMatcherPublicWidgetOptions(
+    options: PerseusMatcherWidgetOptions,
+): MatcherPublicWidgetOptions {
+    const {left, right} = shuffleMatcherWithRandom(options);
+
+    return {
+        ...options,
+        left: left,
+        right: right,
+    };
+}
+
+export default getMatcherPublicWidgetOptions;

packages/perseus/src/types.ts

@@ -36,6 +36,7 @@ import type {
     getIFramePublicWidgetOptions,
     getMatrixPublicWidgetOptions,
     getPlotterPublicWidgetOptions,
+    getMatcherPublicWidgetOptions,
 } from "@khanacademy/perseus-core";
 import type {LinterContextProps} from "@khanacademy/perseus-linter";
 import type {
@@ -496,6 +497,7 @@ export type PublicWidgetOptionsFunction =
     | typeof getPlotterPublicWidgetOptions
     | typeof getIFramePublicWidgetOptions
     | typeof getRadioPublicWidgetOptions
+    | typeof getMatcherPublicWidgetOptions
     | typeof getNumericInputPublicWidgetOptions
     | typeof getDropdownPublicWidgetOptions
     | typeof getCategorizerPublicWidgetOptions

packages/perseus/src/util.ts

@@ -17,8 +17,6 @@ type WordAndPosition = {
     pos: WordPosition;
 };
 
-type RNG = () => number;
-
 export type ParsedValue = {
     value: number;
     exact: boolean;
@@ -92,66 +90,6 @@ const rTypeFromWidgetId = /^([a-z-]+) ([0-9]+)$/;
 const rWidgetParts = new RegExp(rWidgetRule.source + "$");
 const snowman = "\u2603";
 
-const seededRNG: (seed: number) => RNG = function (seed: number): RNG {
-    let randomSeed = seed;
-
-    return function () {
-        // Robert Jenkins' 32 bit integer hash function.
-        let seed = randomSeed;
-        seed = (seed + 0x7ed55d16 + (seed << 12)) & 0xffffffff;
-        seed = (seed ^ 0xc761c23c ^ (seed >>> 19)) & 0xffffffff;
-        seed = (seed + 0x165667b1 + (seed << 5)) & 0xffffffff;
-        seed = ((seed + 0xd3a2646c) ^ (seed << 9)) & 0xffffffff;
-        seed = (seed + 0xfd7046c5 + (seed << 3)) & 0xffffffff;
-        seed = (seed ^ 0xb55a4f09 ^ (seed >>> 16)) & 0xffffffff;
-        return (randomSeed = seed & 0xfffffff) / 0x10000000;
-    };
-};
-
-// Shuffle an array using a given random seed or function.
-// If `ensurePermuted` is true, the input and ouput are guaranteed to be
-// distinct permutations.
-function shuffle<T>(
-    array: ReadonlyArray<T>,
-    randomSeed: number | RNG,
-    ensurePermuted = false,
-): ReadonlyArray<T> {
-    // Always return a copy of the input array
-    const shuffled = _.clone(array);
-
-    // Handle edge cases (input array is empty or uniform)
-    if (
-        !shuffled.length ||
-        _.all(shuffled, function (value) {
-            return _.isEqual(value, shuffled[0]);
-        })
-    ) {
-        return shuffled;
-    }
-
-    let random;
-    if (typeof randomSeed === "function") {
-        random = randomSeed;
-    } else {
-        random = seededRNG(randomSeed);
-    }
-
-    do {
-        // Fischer-Yates shuffle
-        for (let top = shuffled.length; top > 0; top--) {
-            const newEnd = Math.floor(random() * top);
-            const temp = shuffled[newEnd];
-
-            // @ts-expect-error - TS2542 - Index signature in type 'readonly T[]' only permits reading.
-            shuffled[newEnd] = shuffled[top - 1];
-            // @ts-expect-error - TS2542 - Index signature in type 'readonly T[]' only permits reading.
-            shuffled[top - 1] = temp;
-        }
-    } while (ensurePermuted && _.isEqual(array, shuffled));
-
-    return shuffled;
-}
-
 /**
  * TODO(somewhatabstract, FEI-3463):
  * Drop this custom split thing.
@@ -648,17 +586,13 @@ const textarea = {
 const unescapeMathMode: (label: string) => string = (label) =>
     label.startsWith("$") && label.endsWith("$") ? label.slice(1, -1) : label;
 
-const random: RNG = seededRNG(new Date().getTime() & 0xffffffff);
-
 const Util = {
     inputPathsEqual,
     nestedMap,
     rWidgetRule,
     rTypeFromWidgetId,
     rWidgetParts,
     snowman,
-    seededRNG,
-    shuffle,
     split,
     firstNumericalParse,
     stringArrayOfSize,
@@ -687,7 +621,6 @@ const Util = {
     getDataUrl: GraphieUtil.getDataUrl,
     textarea,
     unescapeMathMode,
-    random,
 } as const;
 
 export default Util;

packages/perseus/src/widgets/categorizer/categorizer.tsx

@@ -2,6 +2,7 @@
 import {
     type PerseusCategorizerWidgetOptions,
     getCategorizerPublicWidgetOptions,
+    CoreUtil,
 } from "@khanacademy/perseus-core";
 import {linterContextDefault} from "@khanacademy/perseus-linter";
 import {StyleSheet, css} from "aphrodite";
@@ -16,7 +17,6 @@ import * as Changeable from "../../mixins/changeable";
 import Renderer from "../../renderer";
 import mediaQueries from "../../styles/media-queries";
 import sharedStyles from "../../styles/shared";
-import Util from "../../util";
 import {getPromptJSON as _getPromptJSON} from "../../widget-ai-utils/categorizer/categorizer-ai-utils";
 
 import type {Widget, WidgetExports, WidgetProps} from "../../types";
@@ -92,8 +92,11 @@ export class Categorizer
         const isMobile = this.props.apiOptions.isMobile;
         let indexedItems = this.props.items.map((item, n) => [item, n]);
         if (this.props.randomizeItems) {
-            // @ts-expect-error - TS4104 - The type 'readonly (string | number)[][]' is 'readonly' and cannot be assigned to the mutable type '(string | number)[][]'. | TS2345 - Argument of type 'number | null | undefined' is not assignable to parameter of type 'number | RNG'.
-            indexedItems = Util.shuffle(indexedItems, this.props.problemNum);
+            // @ts-expect-error - TS4104 - The type 'readonly (string | number)[][]' is 'readonly' and cannot be assigned to the mutable type '(string | number)[][]'.
+            indexedItems = CoreUtil.shuffle(
+                indexedItems,
+                this.props.problemNum as any,
+            );
         }
 
         const table = (