Number Line: Extract validation out of scoring

.changeset/sweet-ligers-arrive.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/perseus": minor
+---
+
+Introduces a validation function for the number line widget (extracted from the scoring function).

packages/perseus/src/validation.types.ts

@@ -37,7 +37,6 @@ import type {
     PerseusGroupWidgetOptions,
     PerseusMatcherWidgetOptions,
     PerseusMatrixWidgetAnswers,
-    PerseusNumberLineWidgetOptions,
     PerseusNumericInputAnswer,
     PerseusOrdererWidgetOptions,
     PerseusPlotterWidgetOptions,
@@ -156,7 +155,14 @@ export type PerseusMatrixUserInput = {
     answers: PerseusMatrixRubric["answers"];
 };
 
-export type PerseusNumberLineRubric = PerseusNumberLineWidgetOptions & {
+export type PerseusNumberLineScoringData = {
+    correctRel: string | null | undefined;
+    correctX: number;
+} & PerseusNumberLineValidationData;
+
+export type PerseusNumberLineValidationData = {
+    range: ReadonlyArray<number>;
+    initialX: number | null | undefined;
     isInequality: boolean;
 };
 
@@ -230,7 +236,7 @@ export type Rubric =
     | PerseusLabelImageRubric
     | PerseusMatcherRubric
     | PerseusMatrixRubric
-    | PerseusNumberLineRubric
+    | PerseusNumberLineScoringData
     | PerseusNumericInputRubric
     | PerseusOrdererRubric
     | PerseusPlotterRubric

packages/perseus/src/widgets/number-line/score-number-line.test.ts

@@ -1,109 +1,58 @@
 import scoreNumberLine from "./score-number-line";
 
 import type {
-    PerseusNumberLineRubric,
+    PerseusNumberLineScoringData,
     PerseusNumberLineUserInput,
 } from "../../validation.types";
 
-const baseInput: PerseusNumberLineUserInput = {
-    isTickCrtl: true,
-    numLinePosition: 1,
-    rel: "eq",
-    numDivisions: 10,
-    divisionRange: [-10, 10],
-};
-
-const baseRubric: PerseusNumberLineRubric = {
-    correctRel: "eq",
-    correctX: -1.5,
-    divisionRange: [1, 12],
-    initialX: -1,
-    labelRange: [null, null],
-    labelStyle: "decimal",
-    labelTicks: true,
-    numDivisions: null,
-    range: [-1.5, 1.5],
-    snapDivisions: 2,
-    static: false,
-    tickStep: 0.5,
-    isInequality: false,
-};
-
-function generateInput(
-    extend?: Partial<PerseusNumberLineUserInput>,
-): PerseusNumberLineUserInput {
-    return {...baseInput, ...extend};
-}
-
-function generateRubric(
-    extend?: Partial<PerseusNumberLineRubric>,
-): PerseusNumberLineRubric {
-    return {...baseRubric, ...extend};
-}
-
 describe("scoreNumberLine", () => {
-    it("is invalid when outside allowed range", () => {
-        // Arrange
-        const userInput = generateInput({
-            divisionRange: [-1, 1],
-            numLinePosition: 10,
-        });
-
-        const rubric = generateRubric();
-
-        // Act
-        const result = scoreNumberLine(userInput, rubric);
-
-        // Assert
-        expect(result).toHaveInvalidInput(
-            "Number of divisions is outside the allowed range.",
-        );
-    });
-
-    it("is invalid when end state is the same as beginning state", () => {
-        // Arrange
-        const userInput = generateInput({
-            numLinePosition: 0,
-        });
-
-        const rubric = generateRubric({
-            initialX: 0,
-        });
-
-        // Act
-        const result = scoreNumberLine(userInput, rubric);
-
-        // Assert
-        expect(result).toHaveInvalidInput();
-    });
-
     it("can be answered correctly", () => {
         // Arrange
-        const userInput = generateInput({
+        const userInput: PerseusNumberLineUserInput = {
+            isTickCrtl: true,
+            rel: "eq",
+            numDivisions: 10,
+            divisionRange: [-10, 10],
             numLinePosition: -1.5,
-        });
+        };
 
-        const rubric = generateRubric();
+        const scoringData: PerseusNumberLineScoringData = {
+            correctRel: "eq",
+            correctX: -1.5,
+            initialX: -1,
+            range: [-1.5, 1.5],
+            isInequality: false,
+        };
 
         // Act
-        const result = scoreNumberLine(userInput, rubric);
+        const score = scoreNumberLine(userInput, scoringData);
 
         // Assert
-        expect(result).toHaveBeenAnsweredCorrectly();
+        expect(score).toHaveBeenAnsweredCorrectly();
     });
 
     it("can be answered incorrectly", () => {
         // Arrange
-        const userInput = generateInput({
+        const userInput: PerseusNumberLineUserInput = {
+            isTickCrtl: true,
+            rel: "eq",
+            numDivisions: 10,
+            divisionRange: [-10, 10],
             numLinePosition: 1.5,
-        });
+        };
 
-        const rubric = generateRubric();
+        const scoringData: PerseusNumberLineScoringData = {
+            correctRel: "eq",
+            correctX: -1.5,
+            initialX: -1,
+            range: [-1.5, 1.5],
+            isInequality: false,
+        };
 
         // Act
-        const result = scoreNumberLine(userInput, rubric);
+        const score = scoreNumberLine(userInput, scoringData);
 
         // Assert
-        expect(result).toHaveBeenAnsweredIncorrectly();
+        expect(score).toHaveBeenAnsweredIncorrectly();
     });
 });

packages/perseus/src/widgets/number-line/score-number-line.ts

@@ -1,50 +1,36 @@
 import {number as knumber} from "@khanacademy/kmath";
 
+import validateNumberLine from "./validate-number-line";
+
 import type {PerseusScore} from "../../types";
 import type {
-    PerseusNumberLineRubric,
+    PerseusNumberLineScoringData,
     PerseusNumberLineUserInput,
 } from "../../validation.types";
 
 function scoreNumberLine(
-    state: PerseusNumberLineUserInput,
-    rubric: PerseusNumberLineRubric,
+    userInput: PerseusNumberLineUserInput,
+    scoringData: PerseusNumberLineScoringData,
 ): PerseusScore {
-    const range = rubric.range;
-    const divisionRange = state.divisionRange;
-    const start = rubric.initialX != null ? rubric.initialX : range[0];
-    const startRel = rubric.isInequality ? "ge" : "eq";
-    const correctRel = rubric.correctRel || "eq";
+    const validationError = validateNumberLine(userInput, scoringData);
+    if (validationError) {
+        return validationError;
+    }
+
+    const correctRel = scoringData.correctRel || "eq";
     const correctPos = knumber.equal(
-        state.numLinePosition,
-        rubric.correctX || 0,
+        userInput.numLinePosition,
+        scoringData.correctX || 0,
     );
-    const outsideAllowedRange =
-        state.numDivisions > divisionRange[1] ||
-        state.numDivisions < divisionRange[0];
 
-    // TODO: I don't think isTickCrtl is a thing anymore
-    if (state.isTickCrtl && outsideAllowedRange) {
-        return {
-            type: "invalid",
-            message: "Number of divisions is outside the allowed range.",
-        };
-    }
-    if (correctPos && correctRel === state.rel) {
+    if (correctPos && correctRel === userInput.rel) {
         return {
             type: "points",
             earned: 1,
             total: 1,
             message: null,
         };
     }
-    if (state.numLinePosition === start && state.rel === startRel) {
-        // We're where we started.
-        return {
-            type: "invalid",
-            message: null,
-        };
-    }
     return {
         type: "points",
         earned: 0,

packages/perseus/src/widgets/number-line/validate-number-line.test.ts

@@ -0,0 +1,79 @@
+import validateNumberLine from "./validate-number-line";
+
+import type {
+    PerseusNumberLineUserInput,
+    PerseusNumberLineValidationData,
+} from "../../validation.types";
+
+describe("validateNumberLine", () => {
+    it("is invalid when outside allowed range", () => {
+        // Arrange
+        const userInput: PerseusNumberLineUserInput = {
+            isTickCrtl: true,
+            rel: "eq",
+            numDivisions: 10,
+            divisionRange: [-1, 1],
+            numLinePosition: 10,
+        };
+
+        const validationData: PerseusNumberLineValidationData = {
+            range: [-1.5, 1.5],
+            initialX: -1,
+            isInequality: false,
+        };
+
+        // Act
+        const validationError = validateNumberLine(userInput, validationData);
+
+        // Assert
+        expect(validationError).toHaveInvalidInput(
+            "Number of divisions is outside the allowed range.",
+        );
+    });
+
+    it("is invalid when end state is the same as beginning state", () => {
+        // Arrange
+        const userInput: PerseusNumberLineUserInput = {
+            isTickCrtl: true,
+            rel: "eq",
+            numDivisions: 10,
+            divisionRange: [-10, 10],
+            numLinePosition: 0,
+        };
+
+        const validationData: PerseusNumberLineValidationData = {
+            range: [-1.5, 1.5],
+            isInequality: false,
+            initialX: 0,
+        };
+
+        // Act
+        const validationError = validateNumberLine(userInput, validationData);
+
+        // Assert
+        expect(validationError).toHaveInvalidInput();
+    });
+
+    it("returns null when validation passes", () => {
+        // Arrange
+        const userInput: PerseusNumberLineUserInput = {
+            isTickCrtl: true,
+            rel: "eq",
+            numDivisions: 10,
+            divisionRange: [-10, 10],
+            numLinePosition: -1.5,
+        };
+
+        const validationData: PerseusNumberLineValidationData = {
+            initialX: -1,
+            range: [-1.5, 1.5],
+            isInequality: false,
+        };
+
+        // Act
+        const validationError = validateNumberLine(userInput, validationData);
+
+        // Assert
+        expect(validationError).toBeNull();
+    });
+});

packages/perseus/src/widgets/number-line/validate-number-line.ts

@@ -0,0 +1,45 @@
+import type {PerseusScore} from "../../types";
+import type {
+    PerseusNumberLineUserInput,
+    PerseusNumberLineValidationData,
+} from "../../validation.types";
+
+/**
+ * Checks user input is within the allowed range and not the same as the initial
+ * state.
+ * @param userInput
+ * @param validationData
+ * @see 'scoreNumberLine' for the scoring logic.
+ */
+function validateNumberLine(
+    userInput: PerseusNumberLineUserInput,
+    validationData: PerseusNumberLineValidationData,
+): Extract<PerseusScore, {type: "invalid"}> | null {
+    const range = validationData.range;
+    const divisionRange = userInput.divisionRange;
+    const start =
+        validationData.initialX != null ? validationData.initialX : range[0];
+    const startRel = validationData.isInequality ? "ge" : "eq";
+    const outsideAllowedRange =
+        userInput.numDivisions > divisionRange[1] ||
+        userInput.numDivisions < divisionRange[0];
+
+    // TODO: I don't think isTickCrtl is a thing anymore
+    if (userInput.isTickCrtl && outsideAllowedRange) {
+        return {
+            type: "invalid",
+            message: "Number of divisions is outside the allowed range.",
+        };
+    }
+
+    if (userInput.numLinePosition === start && userInput.rel === startRel) {
+        // We're where we started.
+        return {
+            type: "invalid",
+            message: null,
+        };
+    }
+    return null;
+}
+
+export default validateNumberLine;