@mathscan/math-exercise-engine 1.2.8 → 1.2.10

package/README.md

@@ -22,6 +22,19 @@ pnpm add @mathscan/math-exercise-engine
 yarn add @mathscan/math-exercise-engine
 ```
 
+### Upgrading to 2.0
+
+- **React 19.2+** is required for the renderer (peer dependency was `^18 || ^19`).
+- **`konva` and `react-konva`** are new optional peers, needed only to render GEOMETRY widgets.
+  npm 7+ and pnpm install them automatically; with Yarn 1 add them yourself.
+- **Node** `^20.19.0 || >=22.12.0`.
+- **Geometry engine on the main entry.** `validate()` grades GEOMETRY widgets, so importing the
+  package now loads `@mathscan/geometry-engine` (and its `jsxgraph` kernel) even for exercises
+  without geometry. It runs headless — no DOM, no React — but adds to install and import cost.
+  The geometry canvas UI stays lazy and loads only when a GEOMETRY widget renders.
+- **`ValidationResult.scoreContribution`** (new, optional) carries raw `{ correct, earned, possible }`
+  scoring units. `validate()` always sets it; its return type is `ScoredValidationResult`.
+
 ## 🚀 Quick Start
 
 ```typescript
@@ -301,6 +314,30 @@ All layout items include unique `id` fields for React/JSX rendering:
 }
 ```
 
+### Migrating to grouped-bar charts
+
+`ChartItem` (the `chart` layout item) is now a discriminated union on `chartType`, and each variant carries only its own fields:
+
+| `chartType` | Fields |
+|-------------|--------|
+| `bar` | `bars` |
+| `pictograph` | `pictos` |
+| `grouped-bar` | `series`, `groups`, `legend` |
+
+Older stored JSON still parses: an empty `pictos: []` on a bar chart or `bars: []` on a pictograph is accepted and dropped. Compiled output changes too: it now contains only the fields of its variant, so a bar chart no longer emits `pictos: []` and a pictograph no longer emits `bars: []`. Code that read `item.bars` or `item.pictos` on any chart must narrow first:
+
+```ts
+if (item.chartType === 'bar') {
+  item.bars.forEach(/* … */);
+}
+```
+
+Other chart changes in the same release:
+
+- Compiled interactive bars now also carry `answer`, next to the existing `interactive: true` and `widgetId`. Bar JSON with only `answer` is accepted too.
+- **Hosts must not strip `answer` from chart items.** On a `PICTO` and a grouped-bar `SERIES_BAR`, `answer` is what makes the item draggable: remove it and the item renders as display-only. A `BAR` stays draggable through `interactive: true` + `widgetId`, but keep its `answer` too for consistency. The answers are also in `validation.answers`, so hiding them from students takes more than stripping one of the two.
+- Interactive chart item ids (`BAR`, `PICTO`, `SERIES_BAR` with an `answer`) share the widget namespace. They must not clash with any input name, including `VISUAL_FRACTION` and interactive `CLOCK` names. A clash is now a compile error ("Duplicate name") instead of silently overwriting the widget or answer.
+
 ## ✅ Testing
 
 ```bash

package/dist/GeometryWidget-DgPfqyQv.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const jsxRuntime = require("react/jsx-runtime");
+const React = require("react");
+const react = require("@mathscan/geometry-engine/react");
+const validation = require("@mathscan/geometry-engine/validation");
+const index = require("./index-tEgJE6m2.js");
+const GeometryWidget = ({
+  widgetId,
+  widget,
+  value,
+  validationDetail,
+  onChange
+}) => {
+  const exerciseLocked = index.useExerciseLocked();
+  const { attempt, issues } = React.useMemo(() => index.readGeometryAttempt(value), [value]);
+  React.useEffect(() => {
+    if (issues) index.logRejectedGeometryAttempt(widgetId, issues);
+  }, [issues, widgetId]);
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "geometry-widget", "data-widget-id": widgetId, children: /* @__PURE__ */ jsxRuntime.jsx(
+    react.StudentGeometryExercise,
+    {
+      showCompanion: false,
+      exercise: widget.json,
+      value: attempt,
+      readOnly: exerciseLocked,
+      validationFeedback: validationDetail?.geometryFeedback ?? null,
+      controls: {
+        toolbar: false,
+        history: false,
+        delete: false,
+        reset: false,
+        instruments: false
+      },
+      onChange: (next) => onChange(widgetId, validation.serializeGeometryState(next)),
+      onError: (issues2) => {
+        console.error(
+          `Geometry exercise rejected (widget "${widgetId}"):`,
+          issues2.map(({ source, path, message }) => ({
+            source,
+            path: path.join("."),
+            message
+          }))
+        );
+      }
+    }
+  ) });
+};
+exports.GeometryWidget = GeometryWidget;
+//# sourceMappingURL=GeometryWidget-DgPfqyQv.js.map

package/dist/GeometryWidget-DgPfqyQv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GeometryWidget-DgPfqyQv.js","sources":["../src/renderer/widgets/geometry/GeometryWidget.tsx"],"sourcesContent":["import React, { useEffect, useMemo } from 'react';\nimport { StudentGeometryExercise } from '@mathscan/geometry-engine/react';\nimport { serializeGeometryState } from '@mathscan/geometry-engine/validation';\nimport type { GeometryJSON } from '../../../transformers/zod-schemas';\nimport type { WidgetValidation } from '../../../validators';\nimport { logRejectedGeometryAttempt, readGeometryAttempt } from '../../../validators';\nimport { useExerciseLocked } from '../../lock';\n\nexport interface GeometryWidgetProps {\n  widgetId: string;\n  widget: GeometryJSON;\n  /** Serialized `GeometryState` — the value this package stores and validates. */\n  value?: string;\n  validationDetail?: WidgetValidation;\n  onChange: (widgetId: string, value: string) => void;\n}\n\n/**\n * Adapter between this package's widget contract and the geometry engine's\n * student component. It owns no geometry logic: the attempt is passed through as\n * data, the engine's verdict is passed back untouched, and the canvas itself\n * decides what to draw and when a result has gone stale.\n */\nexport const GeometryWidget: React.FC<GeometryWidgetProps> = ({\n  widgetId,\n  widget,\n  value,\n  validationDetail,\n  onChange,\n}) => {\n  const exerciseLocked = useExerciseLocked();\n  // Parsed per value change: the component is controlled, and handing it the\n  // same attempt as a fresh object on every render would look like a new value.\n  const { attempt, issues } = useMemo(() => readGeometryAttempt(value), [value]);\n\n  // A stored value the engine refuses is shown as an empty canvas, so the\n  // student's saved work silently vanishes unless this says so — once per value.\n  useEffect(() => {\n    if (issues) logRejectedGeometryAttempt(widgetId, issues);\n  }, [issues, widgetId]);\n\n  return (\n    <div className=\"geometry-widget\" data-widget-id={widgetId}>\n      <StudentGeometryExercise\n        showCompanion={false}\n        exercise={widget.json}\n        value={attempt}\n        readOnly={exerciseLocked}\n        validationFeedback={validationDetail?.geometryFeedback ?? null}\n        // Reset belongs to the exercise, which clears every widget at once.\n        controls={{\n          toolbar: false,\n          history: false,\n          delete: false,\n          reset: false,\n          instruments: false,\n        }}\n        onChange={(next) => onChange(widgetId, serializeGeometryState(next))}\n        // The engine renders its own error box for a rejected exercise or\n        // value; this is the only place the reasons surface for an author.\n        onError={(issues) => {\n          console.error(\n            `Geometry exercise rejected (widget \"${widgetId}\"):`,\n            issues.map(({ source, path, message }) => ({\n              source,\n              path: path.join('.'),\n              message,\n            }))\n          );\n        }}\n      />\n    </div>\n  );\n};\n"],"names":["useExerciseLocked","useMemo","readGeometryAttempt","useEffect","logRejectedGeometryAttempt","jsx","StudentGeometryExercise","serializeGeometryState","issues"],"mappings":";;;;;;;AAuBO,MAAM,iBAAgD,CAAC;AAAA,EAC5D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,MAAM;AACJ,QAAM,iBAAiBA,MAAAA,kBAAA;AAGvB,QAAM,EAAE,SAAS,OAAA,IAAWC,MAAAA,QAAQ,MAAMC,MAAAA,oBAAoB,KAAK,GAAG,CAAC,KAAK,CAAC;AAI7EC,QAAAA,UAAU,MAAM;AACd,QAAI,OAAQC,OAAAA,2BAA2B,UAAU,MAAM;AAAA,EACzD,GAAG,CAAC,QAAQ,QAAQ,CAAC;AAErB,SACEC,2BAAAA,IAAC,OAAA,EAAI,WAAU,mBAAkB,kBAAgB,UAC/C,UAAAA,2BAAAA;AAAAA,IAACC,MAAAA;AAAAA,IAAA;AAAA,MACC,eAAe;AAAA,MACf,UAAU,OAAO;AAAA,MACjB,OAAO;AAAA,MACP,UAAU;AAAA,MACV,oBAAoB,kBAAkB,oBAAoB;AAAA,MAE1D,UAAU;AAAA,QACR,SAAS;AAAA,QACT,SAAS;AAAA,QACT,QAAQ;AAAA,QACR,OAAO;AAAA,QACP,aAAa;AAAA,MAAA;AAAA,MAEf,UAAU,CAAC,SAAS,SAAS,UAAUC,WAAAA,uBAAuB,IAAI,CAAC;AAAA,MAGnE,SAAS,CAACC,YAAW;AACnB,gBAAQ;AAAA,UACN,uCAAuC,QAAQ;AAAA,UAC/CA,QAAO,IAAI,CAAC,EAAE,QAAQ,MAAM,eAAe;AAAA,YACzC;AAAA,YACA,MAAM,KAAK,KAAK,GAAG;AAAA,YACnB;AAAA,UAAA,EACA;AAAA,QAAA;AAAA,MAEN;AAAA,IAAA;AAAA,EAAA,GAEJ;AAEJ;;"}

package/dist/GeometryWidget-gtAP_-_S.mjs

@@ -0,0 +1,50 @@
+import { jsx } from "react/jsx-runtime";
+import { useMemo, useEffect } from "react";
+import { StudentGeometryExercise } from "@mathscan/geometry-engine/react";
+import { serializeGeometryState } from "@mathscan/geometry-engine/validation";
+import { u as useExerciseLocked, r as readGeometryAttempt, l as logRejectedGeometryAttempt } from "./index-DBteHZkS.mjs";
+const GeometryWidget = ({
+  widgetId,
+  widget,
+  value,
+  validationDetail,
+  onChange
+}) => {
+  const exerciseLocked = useExerciseLocked();
+  const { attempt, issues } = useMemo(() => readGeometryAttempt(value), [value]);
+  useEffect(() => {
+    if (issues) logRejectedGeometryAttempt(widgetId, issues);
+  }, [issues, widgetId]);
+  return /* @__PURE__ */ jsx("div", { className: "geometry-widget", "data-widget-id": widgetId, children: /* @__PURE__ */ jsx(
+    StudentGeometryExercise,
+    {
+      showCompanion: false,
+      exercise: widget.json,
+      value: attempt,
+      readOnly: exerciseLocked,
+      validationFeedback: validationDetail?.geometryFeedback ?? null,
+      controls: {
+        toolbar: false,
+        history: false,
+        delete: false,
+        reset: false,
+        instruments: false
+      },
+      onChange: (next) => onChange(widgetId, serializeGeometryState(next)),
+      onError: (issues2) => {
+        console.error(
+          `Geometry exercise rejected (widget "${widgetId}"):`,
+          issues2.map(({ source, path, message }) => ({
+            source,
+            path: path.join("."),
+            message
+          }))
+        );
+      }
+    }
+  ) });
+};
+export {
+  GeometryWidget
+};
+//# sourceMappingURL=GeometryWidget-gtAP_-_S.mjs.map

package/dist/GeometryWidget-gtAP_-_S.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"GeometryWidget-gtAP_-_S.mjs","sources":["../src/renderer/widgets/geometry/GeometryWidget.tsx"],"sourcesContent":["import React, { useEffect, useMemo } from 'react';\nimport { StudentGeometryExercise } from '@mathscan/geometry-engine/react';\nimport { serializeGeometryState } from '@mathscan/geometry-engine/validation';\nimport type { GeometryJSON } from '../../../transformers/zod-schemas';\nimport type { WidgetValidation } from '../../../validators';\nimport { logRejectedGeometryAttempt, readGeometryAttempt } from '../../../validators';\nimport { useExerciseLocked } from '../../lock';\n\nexport interface GeometryWidgetProps {\n  widgetId: string;\n  widget: GeometryJSON;\n  /** Serialized `GeometryState` — the value this package stores and validates. */\n  value?: string;\n  validationDetail?: WidgetValidation;\n  onChange: (widgetId: string, value: string) => void;\n}\n\n/**\n * Adapter between this package's widget contract and the geometry engine's\n * student component. It owns no geometry logic: the attempt is passed through as\n * data, the engine's verdict is passed back untouched, and the canvas itself\n * decides what to draw and when a result has gone stale.\n */\nexport const GeometryWidget: React.FC<GeometryWidgetProps> = ({\n  widgetId,\n  widget,\n  value,\n  validationDetail,\n  onChange,\n}) => {\n  const exerciseLocked = useExerciseLocked();\n  // Parsed per value change: the component is controlled, and handing it the\n  // same attempt as a fresh object on every render would look like a new value.\n  const { attempt, issues } = useMemo(() => readGeometryAttempt(value), [value]);\n\n  // A stored value the engine refuses is shown as an empty canvas, so the\n  // student's saved work silently vanishes unless this says so — once per value.\n  useEffect(() => {\n    if (issues) logRejectedGeometryAttempt(widgetId, issues);\n  }, [issues, widgetId]);\n\n  return (\n    <div className=\"geometry-widget\" data-widget-id={widgetId}>\n      <StudentGeometryExercise\n        showCompanion={false}\n        exercise={widget.json}\n        value={attempt}\n        readOnly={exerciseLocked}\n        validationFeedback={validationDetail?.geometryFeedback ?? null}\n        // Reset belongs to the exercise, which clears every widget at once.\n        controls={{\n          toolbar: false,\n          history: false,\n          delete: false,\n          reset: false,\n          instruments: false,\n        }}\n        onChange={(next) => onChange(widgetId, serializeGeometryState(next))}\n        // The engine renders its own error box for a rejected exercise or\n        // value; this is the only place the reasons surface for an author.\n        onError={(issues) => {\n          console.error(\n            `Geometry exercise rejected (widget \"${widgetId}\"):`,\n            issues.map(({ source, path, message }) => ({\n              source,\n              path: path.join('.'),\n              message,\n            }))\n          );\n        }}\n      />\n    </div>\n  );\n};\n"],"names":["issues"],"mappings":";;;;;AAuBO,MAAM,iBAAgD,CAAC;AAAA,EAC5D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,MAAM;AACJ,QAAM,iBAAiB,kBAAA;AAGvB,QAAM,EAAE,SAAS,OAAA,IAAW,QAAQ,MAAM,oBAAoB,KAAK,GAAG,CAAC,KAAK,CAAC;AAI7E,YAAU,MAAM;AACd,QAAI,OAAQ,4BAA2B,UAAU,MAAM;AAAA,EACzD,GAAG,CAAC,QAAQ,QAAQ,CAAC;AAErB,SACE,oBAAC,OAAA,EAAI,WAAU,mBAAkB,kBAAgB,UAC/C,UAAA;AAAA,IAAC;AAAA,IAAA;AAAA,MACC,eAAe;AAAA,MACf,UAAU,OAAO;AAAA,MACjB,OAAO;AAAA,MACP,UAAU;AAAA,MACV,oBAAoB,kBAAkB,oBAAoB;AAAA,MAE1D,UAAU;AAAA,QACR,SAAS;AAAA,QACT,SAAS;AAAA,QACT,QAAQ;AAAA,QACR,OAAO;AAAA,QACP,aAAa;AAAA,MAAA;AAAA,MAEf,UAAU,CAAC,SAAS,SAAS,UAAU,uBAAuB,IAAI,CAAC;AAAA,MAGnE,SAAS,CAACA,YAAW;AACnB,gBAAQ;AAAA,UACN,uCAAuC,QAAQ;AAAA,UAC/CA,QAAO,IAAI,CAAC,EAAE,QAAQ,MAAM,eAAe;AAAA,YACzC;AAAA,YACA,MAAM,KAAK,KAAK,GAAG;AAAA,YACnB;AAAA,UAAA,EACA;AAAA,QAAA;AAAA,MAEN;AAAA,IAAA;AAAA,EAAA,GAEJ;AAEJ;"}