@khanacademy/perseus-core 3.6.0 → 3.7.0

package/dist/index.d.ts

@@ -101,3 +101,5 @@ export { default as getTablePublicWidgetOptions } from "./widgets/table/table-ut
 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, shuffleMatcher, } from "./widgets/matcher/matcher-util";
+export { shuffle, seededRNG, random } from "./utils/random-util";

package/dist/index.js

@@ -2,6 +2,8 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var perseusCore = require('@khanacademy/perseus-core');
+
 /**
  * Adds the given perseus library version information to the __perseus_debug__
  * object and ensures that the object is attached to `globalThis` (`window` in
@@ -821,7 +823,7 @@ function times(n, iteratee, context) {
 }
 
 // Return a random integer between `min` and `max` (inclusive).
-function random(min, max) {
+function random$1(min, max) {
   if (max == null) {
     max = min;
     min = 0;
@@ -1564,14 +1566,14 @@ function toArray(obj) {
 function sample(obj, n, guard) {
   if (n == null || guard) {
     if (!isArrayLike(obj)) obj = values(obj);
-    return obj[random(obj.length - 1)];
+    return obj[random$1(obj.length - 1)];
   }
   var sample = toArray(obj);
   var length = getLength(sample);
   n = Math.max(Math.min(n, length), 0);
   var last = length - 1;
   for (var index = 0; index < n; index++) {
-    var rand = random(index, last);
+    var rand = random$1(index, last);
     var temp = sample[index];
     sample[index] = sample[rand];
     sample[rand] = temp;
@@ -1580,7 +1582,7 @@ function sample(obj, n, guard) {
 }
 
 // Shuffle a collection.
-function shuffle(obj) {
+function shuffle$1(obj) {
   return sample(obj, Infinity);
 }
 
@@ -1966,7 +1968,7 @@ var allExports = /*#__PURE__*/Object.freeze({
     matcher: matcher,
     matches: matcher,
     times: times,
-    random: random,
+    random: random$1,
     now: now,
     escape: escape,
     unescape: unescape,
@@ -2023,7 +2025,7 @@ var allExports = /*#__PURE__*/Object.freeze({
     where: where,
     max: max,
     min: min,
-    shuffle: shuffle,
+    shuffle: shuffle$1,
     sample: sample,
     sortBy: sortBy,
     groupBy: groupBy,
@@ -3075,7 +3077,7 @@ function parseWidget(parseType, parseOptions) {
     graded: optional(boolean),
     alignment: optional(string),
     options: parseOptions,
-    key: optional(number),
+    key: optional(nullable(number)),
     version: optional(object({
       major: number,
       minor: number
@@ -3463,14 +3465,15 @@ const imageDimensionToNumber = pipeParsers(union(number).or(string).parser)
 // string parses to either NaN (using parseInt) or 0 (using unary +) and
 // CSS will treat NaN as invalid and default to 0 instead.
 .then(convert(emptyToZero)).then(stringToNumber).parser;
+const dimensionOrUndefined = defaulted(imageDimensionToNumber, () => undefined);
 const parsePerseusImageBackground = object({
   url: optional(nullable(string)),
-  width: optional(imageDimensionToNumber),
-  height: optional(imageDimensionToNumber),
-  top: optional(imageDimensionToNumber),
-  left: optional(imageDimensionToNumber),
-  bottom: optional(imageDimensionToNumber),
-  scale: optional(imageDimensionToNumber)
+  width: dimensionOrUndefined,
+  height: dimensionOrUndefined,
+  top: dimensionOrUndefined,
+  left: dimensionOrUndefined,
+  bottom: dimensionOrUndefined,
+  scale: dimensionOrUndefined
 });
 
 const pairOfNumbers$2 = pair(number, number);
@@ -4211,7 +4214,7 @@ const parseNumericInputWidget = parseWidget(constant("numeric-input"), object({
     // the data, simplify this.
     value: optional(nullable(number)),
     status: string,
-    answerForms: optional(array(parseMathFormat)),
+    answerForms: defaulted(array(parseMathFormat), () => undefined),
     strict: boolean,
     maxError: optional(nullable(number)),
     // TODO(benchristel): simplify should never be a boolean, but we
@@ -4309,7 +4312,7 @@ const parseRadioWidget = parseWidget(constant("radio"), object({
     // There is an import cycle between radio-widget.ts and
     // widgets-map.ts. The anonymous function below ensures that we
     // don't refer to parseWidgetsMap before it's defined.
-    widgets: optional((rawVal, ctx) => parseWidgetsMap(rawVal, ctx))
+    widgets: defaulted((rawVal, ctx) => parseWidgetsMap(rawVal, ctx), () => undefined)
   })),
   hasNoneOfTheAbove: optional(boolean),
   countChoices: optional(boolean),
@@ -4463,13 +4466,17 @@ const parseDeprecatedWidget = parseWidget(
 (_, ctx) => ctx.success("deprecated-standin"),
 // Allow any widget options
 object({}));
-const parseStringToPositiveInt = (rawValue, ctx) => {
-  if (typeof rawValue !== "string" || !/^[1-9][0-9]*$/.test(rawValue)) {
-    return ctx.failure("a string representing a positive integer", rawValue);
+const parseStringToNonNegativeInt = (rawValue, ctx) => {
+  // The article renderer seems to allow the numeric part of a widget ID to
+  // be 0, at least for image widgets. However, if widget IDs in an exercise
+  // contain 0, the exercise renderer will blow up. We allow 0 here for
+  // compatibility with articles.
+  if (typeof rawValue !== "string" || !/^(0|[1-9][0-9]*)$/.test(rawValue)) {
+    return ctx.failure("a string representing a non-negative integer", rawValue);
   }
   return ctx.success(+rawValue);
 };
-const parseWidgetIdComponents = pair(string, parseStringToPositiveInt);
+const parseWidgetIdComponents = pair(string, parseStringToNonNegativeInt);
 
 const parsePerseusRenderer = defaulted(object({
   // TODO(benchristel): content is also defaulted to empty string in
@@ -4480,8 +4487,9 @@ const parsePerseusRenderer = defaulted(object({
   // The anonymous function below ensures that we don't try to access
   // parseWidgetsMap before it's defined.
   widgets: defaulted((rawVal, ctx) => parseWidgetsMap(rawVal, ctx), () => ({})),
-  metadata: optional(array(string)),
-  images: parseImages
+  images: parseImages,
+  // deprecated
+  metadata: any
 }),
 // Default value
 () => ({
@@ -4496,14 +4504,44 @@ const parseHint = object({
   replace: optional(boolean),
   content: string,
   widgets: defaulted(parseWidgetsMap, () => ({})),
-  metadata: optional(array(string)),
-  images: parseImages
+  images: parseImages,
+  // deprecated
+  metadata: any
 });
 
+const parsePerseusAnswerArea = pipeParsers(defaulted(object({}), () => ({}))).then(convert(toAnswerArea)).parser;
+
+// Some answerAreas have extra, bogus fields, like:
+//
+//   "answerArea": {
+//     "type": "multiple",
+//     "options": {},
+//     "version": null,
+//     "static": false,
+//     "graded": false,
+//     "alignment": "",
+//   }
+//
+// This function filters the fields of an answerArea object, keeping only the
+// known ones, and converts `undefined` and `null` values to `false`.
+function toAnswerArea(raw) {
+  return {
+    zTable: !!raw.zTable,
+    calculator: !!raw.calculator,
+    chi2Table: !!raw.chi2Table,
+    financialCalculatorMonthlyPayment: !!raw.financialCalculatorMonthlyPayment,
+    financialCalculatorTotalAmount: !!raw.financialCalculatorTotalAmount,
+    financialCalculatorTimeToPayOff: !!raw.financialCalculatorTimeToPayOff,
+    periodicTable: !!raw.periodicTable,
+    periodicTableWithKey: !!raw.periodicTableWithKey,
+    tTable: !!raw.tTable
+  };
+}
+
 const parsePerseusItem$1 = object({
   question: parsePerseusRenderer,
   hints: defaulted(array(parseHint), () => []),
-  answerArea: pipeParsers(defaulted(object({}), () => ({}))).then(migrateAnswerArea).then(record(enumeration(...ItemExtras), boolean)).parser,
+  answerArea: parsePerseusAnswerArea,
   itemDataVersion: optional(object({
     major: number,
     minor: number
@@ -4512,28 +4550,6 @@ const parsePerseusItem$1 = object({
   answer: any
 });
 
-// Some answerAreas have extra fields, like:
-//
-//   "answerArea": {
-//     "type": "multiple",
-//     "options": {
-//       "content": "",
-//       "images": {},
-//       "widgets": {}
-//     }
-//   }
-//
-// The "type" and "options" fields don't seem to be used anywhere. This
-// migration function removes them.
-function migrateAnswerArea(rawValue, ctx) {
-  const {
-    type: _,
-    options: __,
-    ...rest
-  } = rawValue;
-  return ctx.success(rest);
-}
-
 /**
  * Helper to parse PerseusItem JSON
  * Why not just use JSON.parse? We want:
@@ -4608,7 +4624,7 @@ function throwErrorIfCheatingDetected() {
 
 // This file is processed by a Rollup plugin (replace) to inject the production
 const libName = "@khanacademy/perseus-core";
-const libVersion = "3.6.0";
+const libVersion = "3.7.0";
 addLibraryVersionToPerseusDebug(libName, libVersion);
 
 /**
@@ -4930,10 +4946,7 @@ const grapherWidgetLogic = {
 const defaultWidgetOptions$m = {
   content: "",
   widgets: {},
-  images: {},
-  // `undefined` instead of `null` so that getDefaultProps works for
-  // `the GroupMetadataEditor`
-  metadata: undefined
+  images: {}
 };
 const groupWidgetLogic = {
   name: "group",
@@ -5079,6 +5092,64 @@ const labelImageWidgetLogic = {
   getPublicWidgetOptions: getLabelImagePublicWidgetOptions
 };
 
+// TODO(LEMS-2841): Should be able to remove once getPublicWidgetOptions is hooked up
+
+// TODO(LEMS-2841): Should be able to remove once getPublicWidgetOptions is hooked up
+const shuffleMatcher = props => {
+  // Use the same random() function to shuffle both columns sequentially
+  const rng = perseusCore.seededRNG(props.problemNum);
+  let left;
+  if (!props.orderMatters) {
+    // If the order doesn't matter, don't shuffle the left column
+    left = props.left;
+  } else {
+    left = perseusCore.shuffle(props.left, rng, /* ensurePermuted */true);
+  }
+  const right = perseusCore.shuffle(props.right, rng, /* ensurePermuted */true);
+  return {
+    left,
+    right
+  };
+};
+
+// TODO(LEMS-2841): Can shorten to shuffleMatcher after above function removed
+function shuffleMatcherWithRandom(data) {
+  // 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 = perseusCore.shuffle(data.left, Math.random, /* ensurePermuted */true);
+  }
+  const right = perseusCore.shuffle(data.right, Math.random, /* ensurePermuted */true);
+  return {
+    left,
+    right
+  };
+}
+
+/**
+ * For details on the individual options, see the
+ * PerseusMatcherWidgetOptions type
+ */
+
+/**
+ * Given a PerseusMatcherWidgetOptions object, return a new object with only
+ * the public options that should be exposed to the client.
+ */
+function getMatcherPublicWidgetOptions(options) {
+  const {
+    left,
+    right
+  } = shuffleMatcherWithRandom(options);
+  return {
+    ...options,
+    left: left,
+    right: right
+  };
+}
+
 const defaultWidgetOptions$f = {
   left: ["$x$", "$y$", "$z$"],
   right: ["$1$", "$2$", "$3$"],
@@ -5088,7 +5159,8 @@ const defaultWidgetOptions$f = {
 };
 const matcherWidgetLogic = {
   name: "matcher",
-  defaultWidgetOptions: defaultWidgetOptions$f
+  defaultWidgetOptions: defaultWidgetOptions$f,
+  getPublicWidgetOptions: getMatcherPublicWidgetOptions
 };
 
 function getMatrixPublicWidgetOptions(options) {
@@ -5430,13 +5502,17 @@ const radioWidgetLogic = {
  * the public options that should be exposed to the client.
  */
 function getSorterPublicWidgetOptions(options) {
+  const shuffledCorrect = perseusCore.shuffle(options.correct, Math.random, /* ensurePermuted */true);
   return {
+    ...options,
     // Note(Tamara): This does not provide correct answer information any longer.
     // To maintain compatibility with the original widget options, we are
     // keeping the key the same. Represents initial state of the cards here.
-    correct: options.correct.slice().sort(),
-    padding: options.padding,
-    layout: options.layout
+    correct: shuffledCorrect,
+    // Note(Tamara): This new key is only added here with "true". There isn't
+    // a place where it is set to false. It indicates that the correct field
+    // has been shuffled and no longer contains correct answer info.
+    isCorrectShuffled: true
   };
 }
 
@@ -5743,6 +5819,60 @@ function splitPerseusItem(originalItem) {
   };
 }
 
+/* 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. */
+const seededRNG = function (seed) {
+  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(array, randomSeed) {
+  let ensurePermuted = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
+  // 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 = seededRNG(new Date().getTime() & 0xffffffff);
+
 exports.CoreWidgetRegistry = coreWidgetRegistry;
 exports.Errors = Errors;
 exports.GrapherUtil = grapherUtil;
@@ -5769,6 +5899,7 @@ exports.getGrapherPublicWidgetOptions = getGrapherPublicWidgetOptions;
 exports.getIFramePublicWidgetOptions = getIFramePublicWidgetOptions;
 exports.getInteractiveGraphPublicWidgetOptions = getInteractiveGraphPublicWidgetOptions;
 exports.getLabelImagePublicWidgetOptions = getLabelImagePublicWidgetOptions;
+exports.getMatcherPublicWidgetOptions = getMatcherPublicWidgetOptions;
 exports.getMatrixPublicWidgetOptions = getMatrixPublicWidgetOptions;
 exports.getMatrixSize = getMatrixSize;
 exports.getNumberLinePublicWidgetOptions = getNumberLinePublicWidgetOptions;
@@ -5816,6 +5947,10 @@ exports.plotterPlotTypes = plotterPlotTypes;
 exports.pluck = pluck;
 exports.pythonProgramLogic = pythonProgramWidgetLogic;
 exports.radioLogic = radioWidgetLogic;
+exports.random = random;
+exports.seededRNG = seededRNG;
+exports.shuffle = shuffle;
+exports.shuffleMatcher = shuffleMatcher;
 exports.sorterLogic = sorterWidgetLogic;
 exports.splitPerseusItem = splitPerseusItem;
 exports.tableLogic = tableWidgetLogic;