@mathscan/math-exercise-engine 1.1.17 → 1.2.1

package/README.md

@@ -94,18 +94,49 @@ import type { ExerciseRendererRef } from '@mathscan/math-exercise-engine';
 const exerciseRef = useRef<ExerciseRendererRef>(null);
 
 // Available methods:
-const result = exerciseRef.current?.submit();    // Returns ValidationResult
+const result = exerciseRef.current?.submit();    // Returns ValidationResult — LOCKS the exercise
 exerciseRef.current?.getValues();        // Get current input values
-exerciseRef.current?.reset();            // Clear all inputs
-exerciseRef.current?.focusFirstInput();  // Focus first input field
+exerciseRef.current?.getCompletion();    // How many answerable inputs are filled
+exerciseRef.current?.revealAnswers();    // Fill in the correct answers — also LOCKS
+exerciseRef.current?.reset();            // Clear all inputs and unlock
+exerciseRef.current?.focusFirstInput();  // Focus first editable input field
 ```
 
 ### Method Details
 
-- **`submit()`**: Performs validation and returns `ValidationResult` (also triggers `onSubmit` callback)
-- **`getValues()`**: Returns `Record<string, string>` of all current input values
-- **`reset()`**: Clears all input fields to empty state
-- **`focusFirstInput()`**: Automatically focuses the first input element
+- **`submit()`**: Performs validation, returns `ValidationResult`, triggers `onSubmit`, and **locks the exercise** (see below). Calling it again while locked is a no-op that replays the same `ValidationResult` — no sound, no `onSubmit`
+- **`getValues()`**: Returns `Record<string, UserAnswerValue>` of all current input values
+- **`getCompletion()`**: Returns `{ total, filled, missing, filledIds, isComplete, isAnyFilled }` — use it to decide when to enable your submit button
+- **`revealAnswers()`**: Fills every widget with its correct answer and **locks the exercise**. No-op for display-only exercises
+- **`reset()`**: Clears all input fields and **unlocks** the exercise
+- **`focusFirstInput()`**: Focuses the first editable input of *this* renderer. Skips read-only/disabled fields, so it does nothing while the exercise is locked
+
+## 🔒 Locking After a Check
+
+Once the answer is checked, the exercise becomes read-only until it is reset. This is the default and cannot be turned off.
+
+**What locks it:** `submit()`, the built-in `showSubmitButton` button, and `revealAnswers()`.
+**What unlocks it:** `reset()` — nothing else.
+
+While locked, every widget refuses input: text inputs go `readOnly`, option/card widgets get `aria-disabled`, keypad and counter buttons get `disabled`, the built-in Check Answer button is `disabled`, drag-and-drop is disabled, and clock hands / number-line cursors stop responding. The root element gets a `.locked` class so you can style the state:
+
+```css
+.math-exercise-renderer.locked { /* your read-only styling */ }
+```
+
+Floating geometry tools (ruler, protractor, set square) stay draggable — they are instruments, not answers.
+
+If your app shows an exercise in review mode (correction, teacher preview) and wants it read-only from the start, wrap it in your own provider:
+
+```tsx
+import { ExerciseLockProvider } from '@mathscan/math-exercise-engine';
+
+<ExerciseLockProvider locked>
+  <ExerciseRenderer json={json} />
+</ExerciseLockProvider>
+```
+
+The renderer ORs your value with its own state, so an outer lock is never overridden by an un-submitted exercise. Custom widgets of your own can read the same state with the `useExerciseLocked()` hook.
 
 ## 📝 DSL Syntax
 
@@ -228,10 +259,12 @@ import type {
 
 // ExerciseRendererRef interface:
 interface ExerciseRendererRef {
-  submit: () => ValidationResult;        // Perform validation & return result
-  getValues: () => Record<string, string>; // Get current values
-  reset: () => void;                     // Clear all inputs
-  focusFirstInput: () => void;           // Focus first input
+  submit: () => ValidationResult;        // Validate, return result, lock the exercise
+  getValues: () => Record<string, UserAnswerValue>; // Get current values
+  getCompletion: () => InputCompletion;  // Fill status of the answerable inputs
+  revealAnswers: () => void;             // Fill in correct answers, lock the exercise
+  reset: () => void;                     // Clear all inputs and unlock
+  focusFirstInput: () => void;           // Focus first editable input
 }
 ```