@mathscan/math-exercise-engine 1.2.0 → 1.2.2

package/dist/index.mjs

@@ -392,13 +392,9 @@ const MATCHER = createToken({
   name: "MATCHER",
   pattern: /MATCHER/
 });
-const TOP_ROW = createToken({
-  name: "TOP_ROW",
-  pattern: /TOP_ROW/
-});
-const BOTTOM_ROW = createToken({
-  name: "BOTTOM_ROW",
-  pattern: /BOTTOM_ROW/
+const GROUP = createToken({
+  name: "GROUP",
+  pattern: /GROUP/
 });
 const ITEM = createToken({
   name: "ITEM",
@@ -554,8 +550,7 @@ const allTokens = [
   ARROW,
   TABLE,
   ROW,
-  TOP_ROW,
-  BOTTOM_ROW,
+  GROUP,
   CELL,
   COUNTER,
   CLOCK,
@@ -1063,39 +1058,19 @@ class MathExerciseParser extends CstParser {
       this.MANY3(() => {
         this.OR3([{ ALT: () => this.CONSUME3(Space) }, { ALT: () => this.CONSUME3(Newline) }]);
       });
-      this.SUBRULE(this.pairMatcherTopSection);
-      this.SUBRULE(this.pairMatcherBottomSection);
+      this.SUBRULE(this.pairMatcherGroupSection);
+      this.SUBRULE2(this.pairMatcherGroupSection);
       this.SUBRULE(this.matcherAnswers);
       this.CONSUME(RBrace);
       this.MANY4(() => {
         this.OR4([{ ALT: () => this.CONSUME4(Newline) }, { ALT: () => this.CONSUME4(Space) }]);
       });
     });
-    this.pairMatcherTopSection = this.RULE("pairMatcherTopSection", () => {
-      this.MANY(() => {
-        this.OR([{ ALT: () => this.CONSUME(Space) }, { ALT: () => this.CONSUME(Newline) }]);
-      });
-      this.CONSUME(TOP_ROW);
-      this.MANY2(() => {
-        this.OR2([{ ALT: () => this.CONSUME2(Space) }, { ALT: () => this.CONSUME2(Newline) }]);
-      });
-      this.CONSUME(LBrace);
-      this.MANY3(() => {
-        this.OR3([{ ALT: () => this.CONSUME3(Space) }, { ALT: () => this.CONSUME3(Newline) }]);
-      });
-      this.AT_LEAST_ONE(() => {
-        this.SUBRULE(this.matcherItem);
-      });
-      this.CONSUME(RBrace);
-      this.MANY4(() => {
-        this.OR4([{ ALT: () => this.CONSUME4(Space) }, { ALT: () => this.CONSUME4(Newline) }]);
-      });
-    });
-    this.pairMatcherBottomSection = this.RULE("pairMatcherBottomSection", () => {
+    this.pairMatcherGroupSection = this.RULE("pairMatcherGroupSection", () => {
       this.MANY(() => {
         this.OR([{ ALT: () => this.CONSUME(Space) }, { ALT: () => this.CONSUME(Newline) }]);
       });
-      this.CONSUME(BOTTOM_ROW);
+      this.CONSUME(GROUP);
       this.MANY2(() => {
         this.OR2([{ ALT: () => this.CONSUME2(Space) }, { ALT: () => this.CONSUME2(Newline) }]);
       });
@@ -2588,20 +2563,24 @@ function isMatcherBlock(value) {
 const PairMatcherBlockSchema = z.object({
   type: z.literal(AST_TYPES.PAIR_MATCHER_BLOCK),
   name: z.string().min(1),
-  /** Items in the top row — at least one required */
-  topItems: z.array(MatcherItemSchema).min(1),
-  /** Items in the bottom row — at least one required */
-  bottomItems: z.array(MatcherItemSchema).min(1),
+  /** Row layout (top/bottom, default) or column layout (left/right). */
+  layout: z.enum(["rows", "columns"]).optional(),
+  /** Exactly two groups, in declaration order — neither more nor fewer. */
+  groups: z.tuple([
+    z.array(MatcherItemSchema).min(1),
+    z.array(MatcherItemSchema).min(1)
+  ]),
   /**
-   * Each answer pair is [topId, bottomId].
+   * Each answer pair is [groups[0] id, groups[1] id].
    * At least one pair is required.
    */
   answers: z.array(z.tuple([z.string().min(1), z.string().min(1)])).min(1)
 }).superRefine((data, ctx) => {
+  const [groupAItems, groupBItems] = data.groups;
   const idRegistry = /* @__PURE__ */ new Map();
   const sections = [
-    { key: "topItems", items: data.topItems },
-    { key: "bottomItems", items: data.bottomItems }
+    { key: 0, items: groupAItems },
+    { key: 1, items: groupBItems }
   ];
   for (const { key: key2, items } of sections) {
     for (let i = 0; i < items.length; i++) {
@@ -2611,59 +2590,59 @@ const PairMatcherBlockSchema = z.object({
         const isCrossSection = existing.section !== key2;
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
-          message: isCrossSection ? `itemId "${itemId}" appears in both TOP and BOTTOM — ids must be globally unique` : `Duplicate itemId "${itemId}" in ${key2 === "topItems" ? "TOP" : "BOTTOM"} section`,
-          path: [key2, i, "itemId"]
+          message: isCrossSection ? `itemId "${itemId}" appears in both groups — ids must be globally unique` : `Duplicate itemId "${itemId}" in group ${key2}`,
+          path: ["groups", key2, i, "itemId"]
         });
       } else {
         idRegistry.set(itemId, { section: key2, index: i });
       }
     }
   }
-  const topIds = new Set(data.topItems.map((it) => it.itemId));
-  const bottomIds = new Set(data.bottomItems.map((it) => it.itemId));
-  const usedTopIds = /* @__PURE__ */ new Set();
-  const usedBottomIds = /* @__PURE__ */ new Set();
-  data.answers.forEach(([topId, bottomId], i) => {
-    if (!topIds.has(topId)) {
+  const groupAIds = new Set(groupAItems.map((it) => it.itemId));
+  const groupBIds = new Set(groupBItems.map((it) => it.itemId));
+  const usedGroupAIds = /* @__PURE__ */ new Set();
+  const usedGroupBIds = /* @__PURE__ */ new Set();
+  data.answers.forEach(([aId, bId], i) => {
+    if (!groupAIds.has(aId)) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `Answer pair [${topId}, ${bottomId}]: "${topId}" is not declared in TOP section`,
+        message: `Answer pair [${aId}, ${bId}]: "${aId}" is not declared in groups[0]`,
         path: ["answers", i, 0]
       });
     }
-    if (!bottomIds.has(bottomId)) {
+    if (!groupBIds.has(bId)) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `Answer pair [${topId}, ${bottomId}]: "${bottomId}" is not declared in BOTTOM section`,
+        message: `Answer pair [${aId}, ${bId}]: "${bId}" is not declared in groups[1]`,
         path: ["answers", i, 1]
       });
     }
-    if (usedTopIds.has(topId)) {
+    if (usedGroupAIds.has(aId)) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `topId "${topId}" appears in more than one answer pair`,
+        message: `id "${aId}" appears in more than one answer pair`,
         path: ["answers", i, 0]
       });
     } else {
-      usedTopIds.add(topId);
+      usedGroupAIds.add(aId);
     }
-    if (usedBottomIds.has(bottomId)) {
+    if (usedGroupBIds.has(bId)) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `bottomId "${bottomId}" appears in more than one answer pair`,
+        message: `id "${bId}" appears in more than one answer pair`,
         path: ["answers", i, 1]
       });
     } else {
-      usedBottomIds.add(bottomId);
+      usedGroupBIds.add(bId);
     }
   });
 });
-function createPairMatcherBlock(name, topItems, bottomItems, answers) {
+function createPairMatcherBlock(name, groups, answers, layout) {
   return PairMatcherBlockSchema.parse({
     type: AST_TYPES.PAIR_MATCHER_BLOCK,
     name,
-    topItems,
-    bottomItems,
+    layout,
+    groups,
     answers
   });
 }
@@ -2850,7 +2829,7 @@ const ExerciseDocumentSchema = z.object({
     } else if (block.type === AST_TYPES.PAIR_MATCHER_BLOCK) {
       const pm = block;
       record(pm.name, ["lines", bi, "name"]);
-      [...pm.topItems, ...pm.bottomItems].forEach((item, ii) => {
+      pm.groups.flat().forEach((item, ii) => {
         visitInlines(item.inlines, ["lines", bi, "items", ii, "inlines"]);
       });
     } else if (block.type === AST_TYPES.RADIO_OPTIONS) {
@@ -3063,24 +3042,14 @@ class NaturalDSLVisitor extends BaseCstVisitor {
   pairMatcher(ctx) {
     const params = this.visit(ctx.parameterList);
     const name = params.name;
-    const topItems = this.visit(ctx.pairMatcherTopSection);
-    const bottomItems = this.visit(ctx.pairMatcherBottomSection);
+    const layout = params.layout;
+    const [firstGroup, secondGroup] = ctx.pairMatcherGroupSection;
+    const groupAItems = this.visit(firstGroup);
+    const groupBItems = this.visit(secondGroup);
     const rawAnswers = this.visit(ctx.matcherAnswers);
-    return createPairMatcherBlock(name, topItems, bottomItems, rawAnswers);
-  }
-  pairMatcherTopSection(ctx) {
-    return this.visitMatcherItemList(ctx);
+    return createPairMatcherBlock(name, [groupAItems, groupBItems], rawAnswers, layout);
   }
-  pairMatcherBottomSection(ctx) {
-    return this.visitMatcherItemList(ctx);
-  }
-  /**
-   * Maps `ctx.matcherItem` CST nodes to MatcherItem AST nodes.
-   * Shared by pairMatcherTopSection and pairMatcherBottomSection because their
-   * grammar rules are structurally identical — both are `matcherItem+` lists
-   * wrapped in a labelled section keyword.
-   */
-  visitMatcherItemList(ctx) {
+  pairMatcherGroupSection(ctx) {
     return ctx.matcherItem ? ctx.matcherItem.map((i) => this.visit(i)) : [];
   }
   // ═══════════════════════════════════════════════════════════════════════════
@@ -3872,8 +3841,12 @@ const MatcherWidgetJSONSchema = z.object({
 });
 const PairMatcherWidgetJSONSchema = z.object({
   type: z.literal(JSON_TYPES.PAIR_MATCHER),
-  topItems: z.array(MatcherItemContentSchema).min(1),
-  bottomItems: z.array(MatcherItemContentSchema).min(1)
+  /** Row layout (top/bottom, default) or column layout (left/right). */
+  layout: z.enum(["rows", "columns"]).optional(),
+  groups: z.tuple([
+    z.array(MatcherItemContentSchema).min(1),
+    z.array(MatcherItemContentSchema).min(1)
+  ])
 });
 const VisualFractionJSONSchema = z.object({
   type: z.literal(JSON_TYPES.VISUAL_FRACTION),
@@ -9833,7 +9806,7 @@ function collectAllInlines(blocks) {
       }
     } else if (block.type === AST_TYPES.PAIR_MATCHER_BLOCK) {
       const pm = block;
-      for (const item of [...pm.topItems, ...pm.bottomItems]) {
+      for (const item of pm.groups.flat()) {
         result.push(...item.inlines);
       }
     }
@@ -9940,10 +9913,14 @@ function buildMatcherWidget(matcher, idGenerator, inlineDragIds) {
   return result;
 }
 function buildPairMatcherWidget(pm, idGenerator, inlineDragIds) {
+  const [groupAItems, groupBItems] = pm.groups;
   return {
     type: JSON_TYPES.PAIR_MATCHER,
-    topItems: mapMatcherItemList(pm.topItems, idGenerator, inlineDragIds),
-    bottomItems: mapMatcherItemList(pm.bottomItems, idGenerator, inlineDragIds)
+    ...pm.layout !== void 0 && { layout: pm.layout },
+    groups: [
+      mapMatcherItemList(groupAItems, idGenerator, inlineDragIds),
+      mapMatcherItemList(groupBItems, idGenerator, inlineDragIds)
+    ]
   };
 }
 function transformVerticalOperation(vop, idGenerator) {
@@ -16738,7 +16715,9 @@ const PairMatcherWidget = ({
   widgets,
   shuffleItems = true
 }) => {
-  const { topItems, bottomItems } = widget;
+  const { groups, layout } = widget;
+  const [topItems, bottomItems] = groups;
+  const isColumns = layout === "columns";
   const exerciseLocked = useExerciseLocked();
   const [shuffledTop] = useState(
     () => shuffleItems ? lodashExports.shuffle([...topItems]) : [...topItems]
@@ -16915,8 +16894,8 @@ const PairMatcherWidget = ({
     pairStatusByTopId
   });
   const cols = useMemo(
-    () => Math.max(topItems.length, bottomItems.length, 1),
-    [topItems.length, bottomItems.length]
+    () => isColumns ? null : Math.max(topItems.length, bottomItems.length, 1),
+    [isColumns, topItems.length, bottomItems.length]
   );
   const renderCard = (item, isTop) => {
     const isRtl = shouldItemsUseRTL(item.content);
@@ -16962,8 +16941,8 @@ const PairMatcherWidget = ({
   return /* @__PURE__ */ jsxs(
     "div",
     {
-      className: `pair-matcher-widget${validationStatus ? ` pair-matcher-widget--${validationStatus}` : ""}`,
-      style: { "--pm-cols": cols },
+      className: `pair-matcher-widget${isColumns ? " pair-matcher-widget--columns" : ""}${validationStatus ? ` pair-matcher-widget--${validationStatus}` : ""}`,
+      style: cols === null ? {} : { "--pm-cols": cols },
       ref: containerRef,
       role: "group",
       "aria-label": "Pair matcher exercise",
@@ -19397,16 +19376,14 @@ const ExerciseRenderer = forwardRef(({
       setResetKey((k) => k + 1);
     },
     focusFirstInput: () => {
-      const container = rootRef.current;
+      const container = rootRef.current ?? document.querySelector(".math-exercise-renderer");
       if (!container) return;
-      const candidates = container.querySelectorAll(
-        'input[type="text"], input[type="number"], textarea, select'
+      const candidates = Array.from(
+        container.querySelectorAll('input[type="text"], input[type="number"], textarea, select')
       );
-      for (const el of Array.from(candidates)) {
-        if (el.readOnly || el.disabled) continue;
-        el.focus();
-        return;
-      }
+      const canTakeInput = (el) => !el.readOnly && !el.disabled;
+      const target = candidates.find(canTakeInput) ?? (locked ? void 0 : candidates[0]);
+      target?.focus();
     }
   }), [json, values, onSubmit, playSound, locked]);
   const handleChange = (widgetId, value, fromDrop = false, sourceOptionId) => {