Categorizer: Extract validation out of scoring

.changeset/green-ghosts-burn.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/perseus": minor
+---
+
+Split out validation function for the `categorizer` widget. This can be used to check if the user selected an answer for every row, confirming the question is ready to be scored.

packages/perseus/src/validation.types.ts

@@ -20,15 +20,21 @@ import type {Relationship} from "./widgets/number-line/number-line";
 
 export type UserInputStatus = "correct" | "incorrect" | "incomplete";
 
-export type PerseusCategorizerRubric = {
+export type PerseusCategorizerScoringData = {
     // The correct answers where index relates to the items and value relates
     // to the category.  e.g. [0, 1, 0, 1, 2]
     values: ReadonlyArray<number>;
-};
+} & PerseusCategorizerValidationData;
 
 export type PerseusCategorizerUserInput = {
-    values: PerseusCategorizerRubric["values"];
+    values: PerseusCategorizerScoringData["values"];
+};
+
+export type PerseusCategorizerValidationData = {
+    // Translatable text; a list of items to categorize. e.g. ["banana", "yellow", "apple", "purple", "shirt"]
+    items: ReadonlyArray<string>;
 };
+
 // TODO(LEMS-2440): Can possibly be removed during 2440?
 // This is not used for grading at all. The only place it is used is to define
 // Props type in cs-program.tsx, but RenderProps already contains WidgetOptions
@@ -187,7 +193,7 @@ export type PerseusTableRubric = {
 export type PerseusTableUserInput = ReadonlyArray<ReadonlyArray<string>>;
 
 export type Rubric =
-    | PerseusCategorizerRubric
+    | PerseusCategorizerScoringData
     | PerseusCSProgramRubric
     | PerseusDropdownRubric
     | PerseusExpressionRubric

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

@@ -21,12 +21,12 @@ import scoreCategorizer from "./score-categorizer";
 import type {PerseusCategorizerWidgetOptions} from "../../perseus-types";
 import type {Widget, WidgetExports, WidgetProps} from "../../types";
 import type {
-    PerseusCategorizerRubric,
+    PerseusCategorizerScoringData,
     PerseusCategorizerUserInput,
 } from "../../validation.types";
 import type {CategorizerPromptJSON} from "../../widget-ai-utils/categorizer/prompt-utils";
 
-type Props = WidgetProps<RenderProps, PerseusCategorizerRubric> & {
+type Props = WidgetProps<RenderProps, PerseusCategorizerScoringData> & {
     values: ReadonlyArray<string>;
 };
 

packages/perseus/src/widgets/categorizer/score-categorizer.test.ts

@@ -2,47 +2,34 @@ import {mockStrings} from "../../strings";
 
 import scoreCategorizer from "./score-categorizer";
 
-import type {PerseusCategorizerRubric} from "../../validation.types";
+import type {PerseusCategorizerScoringData} from "../../validation.types";
 
 describe("scoreCategorizer", () => {
     it("gives points when the answer is correct", () => {
-        const rubric: PerseusCategorizerRubric = {
+        const scoringData: PerseusCategorizerScoringData = {
             values: [1, 3],
+            items: ["apples", "oranges"],
         };
 
         const userInput = {
             values: [1, 3],
         } as const;
-        const score = scoreCategorizer(userInput, rubric, mockStrings);
+        const score = scoreCategorizer(userInput, scoringData, mockStrings);
 
         expect(score).toHaveBeenAnsweredCorrectly();
     });
 
     it("does not give points when incorrectly answered", () => {
-        const rubric: PerseusCategorizerRubric = {
+        const scoringData: PerseusCategorizerScoringData = {
             values: [1, 3],
+            items: ["apples", "oranges"],
         };
 
         const userInput = {
             values: [2, 3],
         } as const;
-        const score = scoreCategorizer(userInput, rubric, mockStrings);
+        const score = scoreCategorizer(userInput, scoringData, mockStrings);
 
         expect(score).toHaveBeenAnsweredIncorrectly();
     });
-
-    it("tells the learner its not complete if not selected", () => {
-        const rubric: PerseusCategorizerRubric = {
-            values: [1, 3],
-        };
-
-        const userInput = {
-            values: [2],
-        } as const;
-        const score = scoreCategorizer(userInput, rubric, mockStrings);
-
-        expect(score).toHaveInvalidInput(
-            "Make sure you select something for every row.",
-        );
-    });
 });

packages/perseus/src/widgets/categorizer/score-categorizer.ts

@@ -1,31 +1,32 @@
+import validateCategorizer from "./validate-categorizer";
+
 import type {PerseusStrings} from "../../strings";
 import type {PerseusScore} from "../../types";
 import type {
-    PerseusCategorizerRubric,
+    PerseusCategorizerScoringData,
     PerseusCategorizerUserInput,
 } from "../../validation.types";
 
 function scoreCategorizer(
     userInput: PerseusCategorizerUserInput,
-    rubric: PerseusCategorizerRubric,
+    scoringData: PerseusCategorizerScoringData,
     strings: PerseusStrings,
 ): PerseusScore {
-    let completed = true;
+    const validationError = validateCategorizer(
+        userInput,
+        scoringData,
+        strings,
+    );
+    if (validationError) {
+        return validationError;
+    }
+
     let allCorrect = true;
-    rubric.values.forEach((value, i) => {
-        if (userInput.values[i] == null) {
-            completed = false;
-        }
+    scoringData.values.forEach((value, i) => {
         if (userInput.values[i] !== value) {
             allCorrect = false;
         }
     });
-    if (!completed) {
-        return {
-            type: "invalid",
-            message: strings.invalidSelection,
-        };
-    }
     return {
         type: "points",
         earned: allCorrect ? 1 : 0,

packages/perseus/src/widgets/categorizer/validate-categorizer.test.ts

@@ -0,0 +1,43 @@
+import {mockStrings} from "../../strings";
+
+import validateCategorizer from "./validate-categorizer";
+
+import type {PerseusCategorizerValidationData} from "../../validation.types";
+
+describe("validateCategorizer", () => {
+    it("tells the learner its not complete if not selected", () => {
+        const validationData: PerseusCategorizerValidationData = {
+            items: ["apples", "oranges"],
+        };
+
+        const userInput = {
+            values: [2],
+        } as const;
+        const score = validateCategorizer(
+            userInput,
+            validationData,
+            mockStrings,
+        );
+
+        expect(score).toHaveInvalidInput(
+            "Make sure you select something for every row.",
+        );
+    });
+
+    it("returns null if the userInput is valid", () => {
+        const validationData: PerseusCategorizerValidationData = {
+            items: ["apples", "oranges"],
+        };
+
+        const userInput = {
+            values: [2, 4],
+        } as const;
+        const score = validateCategorizer(
+            userInput,
+            validationData,
+            mockStrings,
+        );
+
+        expect(score).toBeNull();
+    });
+});

packages/perseus/src/widgets/categorizer/validate-categorizer.ts

@@ -0,0 +1,34 @@
+import type {PerseusStrings} from "../../strings";
+import type {PerseusScore} from "../../types";
+import type {
+    PerseusCategorizerUserInput,
+    PerseusCategorizerValidationData,
+} from "../../validation.types";
+
+/**
+ * Checks userInput from the categorizer widget to see if the user has selected
+ * a category for each item.
+ * @param userInput - The user's input corresponding to an array of indices that
+ * represent the selected category for each row/item.
+ * @param validationData - An array of strings corresponding to each row/item
+ * @param strings - Used to provide a validation message
+ */
+function validateCategorizer(
+    userInput: PerseusCategorizerUserInput,
+    validationData: PerseusCategorizerValidationData,
+    strings: PerseusStrings,
+): Extract<PerseusScore, {type: "invalid"}> | null {
+    const incomplete = validationData.items.some(
+        (_, i) => userInput.values[i] == null,
+    );
+
+    if (incomplete) {
+        return {
+            type: "invalid",
+            message: strings.invalidSelection,
+        };
+    }
+    return null;
+}
+
+export default validateCategorizer;