@mathscan/math-exercise-engine 1.0.12 → 1.0.13

package/dist/index.mjs

@@ -21,6 +21,8 @@ const AST_TYPES = {
   BOLD_TEXT: "BoldText",
   /** Inline input widget (string or numeric) */
   INLINE_INPUT: "InlineInput",
+  /** Inline fraction widget (numerator/denominator with optional inputs) */
+  FRACTION: "Fraction",
   // ═══════════════════════════════════════════════════════════════════════════
   // Blocks
   // ═══════════════════════════════════════════════════════════════════════════
@@ -112,7 +114,9 @@ const JSON_TYPES = {
   /** Radio button options widget */
   RADIO_OPTIONS: "radio-options",
   /** Numeric keypad widget */
-  NUMERIC_KEYPAD: "numeric-keypad"
+  NUMERIC_KEYPAD: "numeric-keypad",
+  /** Inline fraction widget */
+  FRACTION: "fraction"
 };
 const DRAG_OPTIONS_WIDGET_ID = "_drag_options";
 const VALIDATION_MODES = {
@@ -134,6 +138,17 @@ const SIDE_PAD = 7;
 const CSS_VAR_SIDE_PAD = "--nl-side-pad";
 const NUMBER_LINE_LABELS = ["all", "extremes", "min-only", "max-only", "none"];
 const NUMBER_LINE_HIGHLIGHT_COLORS = ["blue", "red", "green", "orange", "purple", "yellow"];
+function getFractionKey(widgetId, part) {
+  return `${widgetId}__${part}`;
+}
+function isFractionKey(key2) {
+  return key2.endsWith("__num") || key2.endsWith("__den");
+}
+function parseFractionKey(key2) {
+  const match = key2.match(/^(.+)__(num|den)$/);
+  if (!match) return null;
+  return { widgetId: match[1], part: match[2] };
+}
 const Newline = createToken({
   name: "Newline",
   pattern: /\r?\n/,
@@ -235,6 +250,10 @@ const HIGHLIGHT = createToken({
   name: "HIGHLIGHT",
   pattern: /HIGHLIGHT(?!_TEXT)/
 });
+const FRACTION = createToken({
+  name: "FRACTION",
+  pattern: /FRACTION/
+});
 const NumberLiteral = createToken({
   name: "NumberLiteral",
   pattern: /-?\d+(\.\d+)?/
@@ -344,6 +363,7 @@ const allTokens = [
   CELL,
   COUNTER,
   HIGHLIGHT,
+  FRACTION,
   // Literals
   NumberLiteral,
   StringLiteral,
@@ -678,6 +698,8 @@ class MathExerciseParser extends CstParser {
         { ALT: () => this.SUBRULE(this.colorText) },
         // BOLD_TEXT (for bold text)
         { ALT: () => this.SUBRULE(this.boldText) },
+        // FRACTION (inline fraction widget)
+        { ALT: () => this.SUBRULE(this.fraction) },
         // W_S_I (inline input widget)
         { ALT: () => this.SUBRULE(this.inlineInput) }
       ]);
@@ -703,6 +725,12 @@ class MathExerciseParser extends CstParser {
       this.SUBRULE(this.parameterList);
       this.CONSUME(RBracket);
     });
+    this.fraction = this.RULE("fraction", () => {
+      this.CONSUME(FRACTION);
+      this.CONSUME(LBracket);
+      this.SUBRULE(this.parameterList);
+      this.CONSUME(RBracket);
+    });
     this.inlineInput = this.RULE("inlineInput", () => {
       this.OR([
         { ALT: () => this.CONSUME(W_S_I, { LABEL: "stringInput" }) },
@@ -885,13 +913,22 @@ const InlineInputWidgetSchema = z.discriminatedUnion("inputType", [
     answer: z.union([z.string(), z.number()]).optional()
   })
 ]);
+const FractionInlineSchema = z.object({
+  type: z.literal(AST_TYPES.FRACTION),
+  name: z.string(),
+  numerator: z.number().optional(),
+  denominator: z.number().optional(),
+  answer: z.string().optional(),
+  simplified: z.boolean().default(true)
+});
 const InlineNodeSchema = z.union([
   FreeTextInlineSchema,
   SpaceInlineSchema,
   HighlightedTextInlineSchema,
   ColorTextInlineSchema,
   BoldTextInlineSchema,
-  InlineInputWidgetSchema
+  InlineInputWidgetSchema,
+  FractionInlineSchema
 ]);
 function createFreeText(value) {
   return FreeTextInlineSchema.parse({
@@ -944,6 +981,13 @@ function createNumericInput(name, digits, answer) {
     answer
   });
 }
+function createFraction(name, options = {}) {
+  return FractionInlineSchema.parse({
+    type: AST_TYPES.FRACTION,
+    name,
+    ...options
+  });
+}
 function isFreeText(value) {
   return FreeTextInlineSchema.safeParse(value).success;
 }
@@ -953,6 +997,9 @@ function isSpace(value) {
 function isInlineInput(value) {
   return InlineInputWidgetSchema.safeParse(value).success;
 }
+function isFraction(value) {
+  return FractionInlineSchema.safeParse(value).success;
+}
 function isInlineNode(value) {
   return InlineNodeSchema.safeParse(value).success;
 }
@@ -1445,6 +1492,9 @@ class NaturalDSLVisitor extends BaseCstVisitor {
     if (ctx.boldText) {
       return this.visit(ctx.boldText);
     }
+    if (ctx.fraction) {
+      return this.visit(ctx.fraction);
+    }
     if (ctx.inlineInput) {
       return this.visit(ctx.inlineInput);
     }
@@ -1478,6 +1528,15 @@ class NaturalDSLVisitor extends BaseCstVisitor {
     }
     return createBoldText(value, highlight);
   }
+  fraction(ctx) {
+    const params = this.visit(ctx.parameterList);
+    const name = params.name;
+    const numerator = params.numerator;
+    const denominator = params.denominator;
+    const answer = params.answer;
+    const simplified = params.simplified !== void 0 ? params.simplified : void 0;
+    return createFraction(name, { numerator, denominator, answer, simplified });
+  }
   inlineInput(ctx) {
     const params = this.visit(ctx.parameterList);
     const name = params.name;
@@ -1750,11 +1809,18 @@ const NumericKeypadJSONSchema = z.object({
   includeOperators: z.boolean().optional(),
   includeDecimal: z.boolean().optional()
 });
+const FractionJSONSchema = z.object({
+  type: z.literal(JSON_TYPES.FRACTION),
+  numerator: z.number().nullable(),
+  denominator: z.number().nullable(),
+  simplified: z.boolean()
+});
 const WidgetJSONSchema = z.union([
   InlineInputJSONSchema,
   DragOptionsJSONSchema,
   RadioOptionsJSONSchema,
-  NumericKeypadJSONSchema
+  NumericKeypadJSONSchema,
+  FractionJSONSchema
 ]);
 const ValidationJSONSchema = z.object({
   mode: z.enum([VALIDATION_MODES.SIMPLE, VALIDATION_MODES.EXPRESSION]),
@@ -1839,6 +1905,9 @@ function isRadioOptionsJSON(widget) {
 function isNumericKeypadJSON(widget) {
   return widget.type === JSON_TYPES.NUMERIC_KEYPAD;
 }
+function isFractionJSON(widget) {
+  return widget.type === JSON_TYPES.FRACTION;
+}
 class LayoutIdGenerator {
   constructor() {
     this.counter = 0;
@@ -1903,6 +1972,17 @@ function toJSON(ast) {
         answers[inline.name] = inline.answer;
       }
     }
+    if (inline.type === AST_TYPES.FRACTION) {
+      widgets[inline.name] = {
+        type: JSON_TYPES.FRACTION,
+        numerator: inline.numerator ?? null,
+        denominator: inline.denominator ?? null,
+        simplified: inline.simplified ?? true
+      };
+      if (inline.answer !== void 0) {
+        answers[inline.name] = inline.answer;
+      }
+    }
   }
   for (const block of ast.lines) {
     if (block.type === AST_TYPES.RADIO_OPTIONS) {
@@ -2093,6 +2173,12 @@ function transformInline(inline, idGenerator) {
         type: JSON_TYPES.WIDGET_REF,
         widgetId: inline.name
       };
+    case AST_TYPES.FRACTION:
+      return {
+        id: idGenerator.generate(JSON_TYPES.WIDGET_REF),
+        type: JSON_TYPES.WIDGET_REF,
+        widgetId: inline.name
+      };
     default:
       throw new Error(`Unknown inline type: ${inline.type}`);
   }
@@ -2146,6 +2232,7 @@ function isNLDragCorrect(encoded, expectedLabel, expectedPosition) {
   const position = normalize(payload.slice(atIdx + 1));
   return label === normalize(expectedLabel) && position === normalize(expectedPosition);
 }
+const math$1 = create(all);
 function collectNumberLines(items) {
   const result = [];
   for (const item of items) {
@@ -2185,7 +2272,9 @@ function validateSimple(exercise, userInputs) {
   for (const [widgetId, expected] of Object.entries(answers)) {
     totalCount++;
     const userValue = userInputs[widgetId];
-    const isCorrect = areValuesEqual(userValue, expected, positionMap[widgetId]);
+    const widget = exercise.widgets[widgetId];
+    const isFractionLenient = widget?.type === JSON_TYPES.FRACTION && widget.simplified === false;
+    const isCorrect = isFractionLenient ? areFractionsEquivalent(userValue, expected) : areValuesEqual(userValue, expected, positionMap[widgetId]);
     details[widgetId] = {
       widgetId,
       userValue,
@@ -2221,6 +2310,16 @@ function areValuesEqual(userValue, expected, expectedPosition) {
   }
   return normalize(userValue) === normalize(expected);
 }
+function areFractionsEquivalent(user, expected) {
+  if (user === void 0 || user === null) return false;
+  try {
+    const userFrac = math$1.fraction(String(user));
+    const expectedFrac = math$1.fraction(String(expected));
+    return math$1.equal(userFrac, expectedFrac);
+  } catch {
+    return areValuesEqual(user, expected);
+  }
+}
 const math = create(all);
 const BLOCKED_FUNCTIONS = [
   "import",
@@ -2374,7 +2473,7 @@ function validateExpression(exercise, userInputs) {
       hasInvalidInput = true;
       continue;
     }
-    const numValue = typeof rawValue === "number" ? rawValue : parseFloat(String(rawValue).trim());
+    const numValue = typeof rawValue === "number" ? rawValue : parseFractionOrNumber(String(rawValue).trim());
     if (!Number.isFinite(numValue)) {
       details[varName] = {
         widgetId: varName,
@@ -2469,6 +2568,39 @@ function findValidCombination(expression, ranges) {
   }
   return null;
 }
+function parseFractionOrNumber(s) {
+  const parts = s.split("/");
+  if (parts.length === 2) {
+    const num = parseFloat(parts[0]);
+    const den = parseFloat(parts[1]);
+    if (Number.isFinite(num) && Number.isFinite(den) && den !== 0) {
+      return num / den;
+    }
+    return NaN;
+  }
+  return parseFloat(s);
+}
+function preprocessFractionValues(exercise, userInputs) {
+  const result = { ...userInputs };
+  for (const [widgetId, widget] of Object.entries(exercise.widgets)) {
+    if (widget.type !== JSON_TYPES.FRACTION) continue;
+    const numKey = getFractionKey(widgetId, "num");
+    const denKey = getFractionKey(widgetId, "den");
+    const numEffective = widget.numerator !== null ? String(widget.numerator) : result[numKey] !== void 0 ? String(result[numKey]) : "";
+    const denEffective = widget.denominator !== null ? String(widget.denominator) : result[denKey] !== void 0 ? String(result[denKey]) : "";
+    if (numEffective !== "" && denEffective !== "") {
+      result[widgetId] = `${numEffective}/${denEffective}`;
+    }
+    delete result[numKey];
+    delete result[denKey];
+  }
+  for (const key2 of Object.keys(result)) {
+    if (isFractionKey(key2)) {
+      delete result[key2];
+    }
+  }
+  return result;
+}
 function validate(exercise, userInputs) {
   if (!exercise.validation) {
     return {
@@ -2476,12 +2608,13 @@ function validate(exercise, userInputs) {
       details: {}
     };
   }
+  const processedInputs = preprocessFractionValues(exercise, userInputs);
   const validatedExercise = exercise;
   switch (validatedExercise.validation.mode) {
     case VALIDATION_MODES.SIMPLE:
-      return validateSimple(validatedExercise, userInputs);
+      return validateSimple(validatedExercise, processedInputs);
     case VALIDATION_MODES.EXPRESSION:
-      return validateExpression(validatedExercise, userInputs);
+      return validateExpression(validatedExercise, processedInputs);
     default:
       return {
         isCorrect: false,
@@ -6551,6 +6684,7 @@ const InlineInput = ({
   widgetId,
   value,
   isDropped = false,
+  validationStatus = null,
   inputType,
   length,
   digits,
@@ -6568,6 +6702,7 @@ const InlineInput = ({
   }, [handleChange]);
   const expectedLength = inputType === "numeric" ? digits : length;
   const dynamicWidth = `${(expectedLength || 5) * 0.8 + 1}em`;
+  const statusClass = validationStatus ? ` widget--${validationStatus}` : "";
   return /* @__PURE__ */ jsx(
     Droppable,
     {
@@ -6580,7 +6715,7 @@ const InlineInput = ({
         /* @__PURE__ */ jsx(
           "button",
           {
-            className: "inline-input-chip",
+            className: `inline-input-chip${statusClass}`,
             onClick: () => handleChange("", false),
             title: "Click to remove",
             children: value
@@ -6593,7 +6728,7 @@ const InlineInput = ({
           {
             id: widgetId + "-input",
             type: "text",
-            className: "inline-input",
+            className: `inline-input${statusClass}`,
             value,
             onChange: (e) => handleChange(e.target.value, false),
             onFocus: () => onFocus?.(widgetId),
@@ -6670,18 +6805,83 @@ const NumericKeypad = ({
     includeOperators && /* @__PURE__ */ jsx("button", { className: "keypad-btn keypad-btn-operator", onClick: () => handleDigit("÷"), children: "÷" })
   ] });
 };
+const FractionInput = ({
+  widgetId,
+  numerator,
+  denominator,
+  values,
+  droppedInputs,
+  validationStatus = null,
+  onChange,
+  onFocus
+}) => {
+  const numKey = getFractionKey(widgetId, "num");
+  const denKey = getFractionKey(widgetId, "den");
+  const numValue = values[numKey] ?? "";
+  const denValue = values[denKey] ?? "";
+  const statusClass = validationStatus ? ` widget--${validationStatus}` : "";
+  const handleDrop = useCallback((subKey) => (item) => {
+    if (item.type === "drag-option") {
+      const data = item.data;
+      onChange(subKey, data.value, true, String(item.id));
+    }
+  }, [onChange]);
+  const renderSlot = (subKey, fixedValue, currentValue, label) => {
+    if (fixedValue !== null) {
+      return /* @__PURE__ */ jsx("span", { className: "fraction-fixed", children: fixedValue });
+    }
+    const isDroppedHere = droppedInputs.has(subKey);
+    return /* @__PURE__ */ jsx(
+      Droppable,
+      {
+        id: subKey,
+        accepts: ["drag-option"],
+        onDrop: handleDrop(subKey),
+        className: "fraction-slot-droppable",
+        children: isDroppedHere && currentValue !== "" ? /* @__PURE__ */ jsx(
+          "button",
+          {
+            className: `inline-input-chip fraction-chip${statusClass}`,
+            onClick: () => onChange(subKey, "", false),
+            title: "Click to remove",
+            children: currentValue
+          }
+        ) : /* @__PURE__ */ jsx(
+          "input",
+          {
+            id: `${subKey}-input`,
+            type: "text",
+            className: `inline-input fraction-input${statusClass}`,
+            value: currentValue,
+            onChange: (e) => onChange(subKey, e.target.value, false),
+            onFocus: () => onFocus?.(subKey),
+            maxLength: 4,
+            "aria-label": label
+          }
+        )
+      }
+    );
+  };
+  return /* @__PURE__ */ jsxs("span", { className: "fraction", role: "math", "aria-label": `fraction ${widgetId}`, children: [
+    /* @__PURE__ */ jsx("span", { className: "fraction-numerator", children: renderSlot(numKey, numerator, numValue, "numerator") }),
+    /* @__PURE__ */ jsx("span", { className: "fraction-bar", "aria-hidden": "true" }),
+    /* @__PURE__ */ jsx("span", { className: "fraction-denominator", children: renderSlot(denKey, denominator, denValue, "denominator") })
+  ] });
+};
 const RadioOptions = ({
   name,
   options,
   value,
+  validationStatus = null,
   onChange
 }) => {
   return /* @__PURE__ */ jsx("div", { className: "radio-options", children: options.map((option, idx) => {
     const isSelected = value === option;
+    const statusClass = isSelected && validationStatus ? ` widget--${validationStatus}` : "";
     return /* @__PURE__ */ jsx(
       "button",
       {
-        className: `radio-option${isSelected ? " selected" : ""}`,
+        className: `radio-option${isSelected ? " selected" : ""}${statusClass}`,
         onClick: () => onChange(name, option),
         type: "button",
         children: option
@@ -6702,11 +6902,17 @@ function isRadioOptionsWidget(widget) {
 function isNumericKeypadWidget(widget) {
   return widget.type === "numeric-keypad";
 }
+function isFractionWidget(widget) {
+  return widget.type === "fraction";
+}
 const WidgetRenderer = ({
   widget,
   widgetId,
   value,
+  values = {},
   isDropped = false,
+  validationStatus = null,
+  droppedInputs = /* @__PURE__ */ new Set(),
   onChange,
   onInputFocus,
   onKeypadChange
@@ -6718,6 +6924,7 @@ const WidgetRenderer = ({
         widgetId,
         value,
         isDropped,
+        validationStatus,
         inputType: widget.inputType,
         length: widget.inputType === "string" ? widget.length : void 0,
         digits: widget.inputType === "numeric" ? widget.digits : void 0,
@@ -6743,6 +6950,7 @@ const WidgetRenderer = ({
         name: widgetId,
         options: widget.options,
         value,
+        validationStatus,
         onChange
       }
     );
@@ -6759,6 +6967,21 @@ const WidgetRenderer = ({
       }
     );
   }
+  if (isFractionWidget(widget)) {
+    return /* @__PURE__ */ jsx(
+      FractionInput,
+      {
+        widgetId,
+        numerator: widget.numerator,
+        denominator: widget.denominator,
+        values,
+        droppedInputs,
+        validationStatus,
+        onChange,
+        onFocus: onInputFocus
+      }
+    );
+  }
   return null;
 };
 const EPSILON = 10 ** -INTERNAL_PRECISION;
@@ -7266,6 +7489,7 @@ const NumberLineRenderer = ({
   widgets,
   values,
   droppedInputs,
+  validationDetails,
   onChange,
   onInputFocus
 }) => {
@@ -7333,6 +7557,7 @@ const NumberLineRenderer = ({
                 widgets,
                 values,
                 droppedInputs,
+                validationDetails,
                 onChange,
                 onInputFocus
               },
@@ -7457,6 +7682,7 @@ const LayoutRenderer = ({
   widgets,
   values,
   droppedInputs,
+  validationDetails,
   onChange,
   onInputFocus
 }) => {
@@ -7509,13 +7735,18 @@ const LayoutRenderer = ({
     case JSON_TYPES.WIDGET_REF: {
       const widget = widgets[item.widgetId];
       if (!widget) return null;
+      const isCorrect = validationDetails?.[item.widgetId];
+      const validationStatus = isCorrect === true ? "correct" : isCorrect === false ? "incorrect" : null;
       return /* @__PURE__ */ jsx(
         WidgetRenderer,
         {
           widget,
           widgetId: item.widgetId,
           value: values[item.widgetId] || "",
+          values,
           isDropped: droppedInputs.has(item.widgetId),
+          validationStatus,
+          droppedInputs,
           onChange,
           onInputFocus
         }
@@ -7535,6 +7766,7 @@ const LayoutRenderer = ({
           widgets,
           values,
           droppedInputs,
+          validationDetails,
           onChange,
           onInputFocus
         },
@@ -7553,6 +7785,7 @@ const LayoutRenderer = ({
               widgets,
               values,
               droppedInputs,
+              validationDetails,
               onChange,
               onInputFocus
             },
@@ -7569,6 +7802,7 @@ const LayoutRenderer = ({
           widgets,
           values,
           droppedInputs,
+          validationDetails,
           onChange,
           onInputFocus
         }
@@ -7596,9 +7830,15 @@ const ExerciseRenderer = forwardRef(({
   const [values, setValues] = useState({});
   const [droppedSources, setDroppedSources] = useState(/* @__PURE__ */ new Map());
   const [focusedInputId, setFocusedInputId] = useState(null);
+  const [validationDetails, setValidationDetails] = useState(null);
   useImperativeHandle(ref, () => ({
     submit: () => {
       const result = validate(json, values);
+      const details = {};
+      for (const [id, v] of Object.entries(result.details)) {
+        details[id] = v.isCorrect;
+      }
+      setValidationDetails(details);
       onSubmit?.(values);
       return result;
     },
@@ -7607,6 +7847,7 @@ const ExerciseRenderer = forwardRef(({
       setValues({});
       setDroppedSources(/* @__PURE__ */ new Map());
       setFocusedInputId(null);
+      setValidationDetails(null);
     },
     focusFirstInput: () => {
       const container = document.querySelector(".math-exercise-renderer");
@@ -7720,6 +7961,7 @@ const ExerciseRenderer = forwardRef(({
                   widgets: json.widgets,
                   values,
                   droppedInputs,
+                  validationDetails,
                   onChange: handleChange,
                   onInputFocus: setFocusedInputId
                 },
@@ -7734,6 +7976,7 @@ const ExerciseRenderer = forwardRef(({
                   widgets: json.widgets,
                   values,
                   droppedInputs,
+                  validationDetails,
                   onChange: handleChange,
                   onInputFocus: setFocusedInputId
                 },
@@ -7749,6 +7992,7 @@ const ExerciseRenderer = forwardRef(({
                 widgets: json.widgets,
                 values,
                 droppedInputs,
+                validationDetails,
                 onChange: handleChange,
                 onInputFocus: setFocusedInputId
               },
@@ -7838,6 +8082,8 @@ export {
   ExerciseMetaSchema,
   ExerciseRenderer,
   ExpressionValidationSchema,
+  FractionInlineSchema,
+  FractionJSONSchema,
   FreeTextInlineSchema,
   GroupItemSchema,
   HighlightedTextInlineSchema,
@@ -7885,6 +8131,7 @@ export {
   createDragOptions,
   createExerciseDocument,
   createExpressionValidation,
+  createFraction,
   createFreeText,
   createHighlightedText,
   createLineBlock,
@@ -7897,6 +8144,7 @@ export {
   evaluate,
   extractVariables as extractExpressionVariables,
   findValidCombination,
+  getFractionKey,
   getMissingInputs,
   isBoldText,
   isColorText,
@@ -7904,6 +8152,9 @@ export {
   isDragOptionsJSON,
   isExerciseDocument,
   isExpressionValidation,
+  isFraction,
+  isFractionJSON,
+  isFractionKey,
   isFreeText,
   isGroupItem,
   isHighlightedText,
@@ -7930,6 +8181,7 @@ export {
   isValidationNode,
   isWidgetRef,
   parse,
+  parseFractionKey,
   parseSafe,
   renderExercise,
   toAST,