@pie-lib/math-input-mathlive 1.0.7 → 1.0.8

package/src/__tests__/static-prompts.test.jsx

@@ -0,0 +1,251 @@
+import Static from '../mf/static';
+
+/**
+ * The answer-block contract: `\MathQuillMathField[id]{}` in stored latex becomes
+ * a MathLive prompt, and sub-field values/focus are surfaced through the same
+ * callbacks @pie-lib/math-input exposed (`onSubFieldChange`, `onSubFieldFocus`,
+ * `getFieldName`, `setInput`).
+ *
+ * Driven against a stub mathfield: a real <math-field> needs a browser, and what
+ * matters here is the mapping, not MathLive's rendering.
+ */
+const stubField = (values = {}, selection = null) => ({
+  values: { ...values },
+  getPrompts() {
+    return Object.keys(this.values);
+  },
+  getPromptValue(id) {
+    return this.values[id];
+  },
+  setPromptValue(id, v) {
+    this.values[id] = v;
+  },
+  getPromptRange(id) {
+    const i = Object.keys(this.values).indexOf(id);
+
+    return [i * 10, i * 10 + 5];
+  },
+  selection,
+  addEventListener() {},
+  removeEventListener() {},
+  focus() {
+    this.focused = true;
+  },
+  blur() {
+    this.blurred = true;
+  },
+  remove() {},
+});
+
+const make = (props = {}) => new Static({ latex: 'x=\\MathQuillMathField[r1]{}', getFieldName: () => {}, ...props });
+
+describe('Static: answer blocks / prompts', () => {
+  describe('isInteractive', () => {
+    it('is interactive when the latex has answer blocks', () => {
+      expect(make({ latex: 'x=\\MathQuillMathField[r1]{}' }).isInteractive()).toBe(true);
+      expect(make({ latex: 'x=\\placeholder[r1]{}' }).isInteractive()).toBe(true);
+    });
+
+    it('is display-only for plain latex', () => {
+      expect(make({ latex: '\\frac{1}{2}' }).isInteractive()).toBe(false);
+      expect(make({ latex: '' }).isInteractive()).toBe(false);
+    });
+  });
+
+  describe('values', () => {
+    it('returns {} before the field exists', () => {
+      expect(make().values()).toEqual({});
+    });
+
+    it('maps each prompt id to its stored-form latex', () => {
+      const s = make();
+
+      s.mathField = stubField({ r1: '7', r2: '\\placeholder{}' });
+
+      // \placeholder must not leak into stored values
+      expect(s.values()).toEqual({ r1: '7', r2: '' });
+    });
+  });
+
+  describe('promptHandle / innerFields', () => {
+    it('exposes a MathQuill-field-like handle with get/set latex', () => {
+      const s = make();
+
+      s.mathField = stubField({ r1: '7' });
+
+      const h = s.promptHandle('r1');
+
+      expect(h.id).toEqual('r1');
+      expect(h.latex()).toEqual('7');
+
+      h.latex('9');
+      expect(s.mathField.values.r1).toEqual('9');
+    });
+
+    it('handle latex() is safe with no field', () => {
+      expect(make().promptHandle('r1').latex()).toEqual('');
+    });
+
+    it('innerFields returns one handle per prompt', () => {
+      const s = make();
+
+      s.mathField = stubField({ r1: '1', r2: '2' });
+
+      expect(s.innerFields.map((f) => f.id)).toEqual(['r1', 'r2']);
+      expect(make().innerFields).toEqual([]);
+    });
+  });
+
+  describe('onSubFieldChange', () => {
+    it('fires only for prompts whose value changed', () => {
+      const onSubFieldChange = jest.fn();
+      const s = make({ onSubFieldChange });
+
+      s.mathField = stubField({ r1: '1', r2: '2' });
+      s.promptValues = { r1: '1', r2: '2' };
+
+      s.mathField.values.r2 = '5';
+      s.onPromptInput();
+
+      expect(onSubFieldChange).toHaveBeenCalledTimes(1);
+      expect(onSubFieldChange).toHaveBeenCalledWith('r2', '5');
+    });
+
+    it('uses getFieldName when it returns a name', () => {
+      const onSubFieldChange = jest.fn();
+      const s = make({ onSubFieldChange, getFieldName: (handle) => 'named-' + handle.id });
+
+      s.mathField = stubField({ r1: '1' });
+      s.promptValues = {};
+
+      s.onPromptInput();
+
+      expect(onSubFieldChange).toHaveBeenCalledWith('named-r1', '1');
+    });
+
+    it('still tracks values when no callback is supplied', () => {
+      const s = make();
+
+      s.mathField = stubField({ r1: '3' });
+      s.onPromptInput();
+
+      expect(s.promptValues).toEqual({ r1: '3' });
+    });
+  });
+
+  describe('onSubFieldFocus', () => {
+    it('reports the prompt containing the selection, plus setInput', () => {
+      const onSubFieldFocus = jest.fn();
+      const setInput = jest.fn();
+      const s = make({ onSubFieldFocus, setInput });
+
+      // r2 occupies offsets 10..15
+      s.mathField = stubField({ r1: '', r2: '' }, { ranges: [[11, 11]] });
+      s.onPromptFocus();
+
+      expect(onSubFieldFocus).toHaveBeenCalledTimes(1);
+      expect(onSubFieldFocus.mock.calls[0][0]).toEqual('r2');
+      expect(onSubFieldFocus.mock.calls[0][1].id).toEqual('r2');
+      expect(setInput).toHaveBeenCalled();
+    });
+
+    it('does nothing without a selection', () => {
+      const onSubFieldFocus = jest.fn();
+      const s = make({ onSubFieldFocus });
+
+      s.mathField = stubField({ r1: '' }, null);
+      s.onPromptFocus();
+
+      expect(onSubFieldFocus).not.toHaveBeenCalled();
+    });
+
+    it('does not throw when the field is missing', () => {
+      const s = make({ onSubFieldFocus: jest.fn() });
+
+      expect(() => s.onPromptFocus()).not.toThrow();
+    });
+  });
+
+  describe('accessibility announcements', () => {
+    afterEach(() => {
+      document.body.innerHTML = '';
+    });
+
+    it('creates a polite off-screen live region', () => {
+      const s = make();
+
+      s.createLiveRegion();
+
+      expect(s.liveRegion.getAttribute('aria-live')).toEqual('polite');
+      expect(s.liveRegion.getAttribute('aria-atomic')).toEqual('true');
+      expect(document.body.contains(s.liveRegion)).toBe(true);
+
+      s.removeLiveRegion();
+      expect(s.liveRegion).toBeUndefined();
+    });
+
+    it('does not create a second region', () => {
+      const s = make();
+
+      s.createLiveRegion();
+      const first = s.liveRegion;
+
+      s.createLiveRegion();
+      expect(s.liveRegion).toBe(first);
+      s.removeLiveRegion();
+    });
+
+    it('announces when typed input expands into a command', () => {
+      const s = make();
+
+      s.createLiveRegion();
+      s.promptValues = { r1: 'x' };
+      // grew by more than one char AND gained a backslash => a conversion
+      s.announceConversion({ r1: 'x\\frac{}{}' });
+
+      expect(s.liveRegion.textContent).toEqual('Converted to math symbol');
+      s.removeLiveRegion();
+    });
+
+    it('does not announce ordinary typing', () => {
+      const s = make();
+
+      s.createLiveRegion();
+      s.promptValues = { r1: 'x' };
+      s.announceConversion({ r1: 'xy' });
+
+      expect(s.liveRegion.textContent).toEqual('');
+      s.removeLiveRegion();
+    });
+
+    it('does not announce a deletion', () => {
+      const s = make();
+
+      s.createLiveRegion();
+      s.promptValues = { r1: 'x\\frac{}{}' };
+      s.onKeyDown({ key: 'Backspace' });
+      s.announceConversion({ r1: 'x' });
+
+      expect(s.liveRegion.textContent).toEqual('');
+      s.removeLiveRegion();
+    });
+  });
+
+  describe('focus / blur', () => {
+    it('delegates to the field and is safe without one', () => {
+      const s = make();
+
+      expect(() => {
+        s.focus();
+        s.blur();
+      }).not.toThrow();
+
+      s.mathField = stubField();
+      s.focus();
+      s.blur();
+
+      expect(s.mathField.focused).toBe(true);
+      expect(s.mathField.blurred).toBe(true);
+    });
+  });
+});

package/src/mathlive-instance.js

@@ -66,6 +66,18 @@ export const configureFonts = (dir) => {
   }
 };
 
+/**
+ * What the spacebar inserts in math mode.
+ *
+ * MathLive's `mathModeSpace` defaults to an empty string, which makes the
+ * spacebar a no-op - users cannot type a space at all. `\\ ` (a LaTeX control
+ * space) is what MathQuill serialised spaces as, so existing content and the
+ * MathJax renderer in @pie-lib/math-rendering both already understand it.
+ *
+ * A literal " " is not usable: LaTeX skips raw whitespace.
+ */
+export const MATH_MODE_SPACE = '\\ ';
+
 /**
  * Custom macros for the pie-specific commands that the MathQuill fork
  * understood but stock LaTeX does not.

package/src/mf/input.jsx

@@ -2,7 +2,7 @@ import React from 'react';
 import PropTypes from 'prop-types';
 import { styled } from '@mui/material/styles';
 import debug from 'debug';
-import { loadMathLive, getMacros } from '../mathlive-instance';
+import { loadMathLive, getMacros, MATH_MODE_SPACE } from '../mathlive-instance';
 import { toMathLive, fromMathLive, keyToAction, KEYSTROKES } from '../latex-bridge';
 
 const log = debug('pie-lib:math-input-mathlive:input');
@@ -49,9 +49,16 @@ export class Input extends React.Component {
   }
 
   async componentDidMount() {
+    // MathLive loads asynchronously, so this method resumes after an await and
+    // has to know whether it is still the current mount. React StrictMode calls
+    // mount -> unmount -> mount on the SAME instance in dev, so a boolean
+    // "unmounted" flag would latch and block the remount from ever creating a
+    // field. A generation counter identifies the live mount instead: only the
+    // newest one proceeds, and a real unmount invalidates all pending ones.
+    const generation = (this.mountGeneration = (this.mountGeneration || 0) + 1);
     const ml = await loadMathLive();
 
-    if (!ml || !this.holderRef.current) {
+    if (generation !== this.mountGeneration || !ml || !this.holderRef.current || this.mathField) {
       return;
     }
 
@@ -64,15 +71,18 @@ export class Input extends React.Component {
 
     // pie drives input through its own keypad, so suppress MathLive's.
     this.mathField.mathVirtualKeyboardPolicy = 'manual';
+    // Without this the spacebar does nothing: MathLive's mathModeSpace
+    // defaults to an empty string.
+    this.mathField.mathModeSpace = MATH_MODE_SPACE;
 
     this.mathField.addEventListener('input', this.onInputEdit);
-    this.holderRef.current.appendChild(this.mathField);
+
+    // Belt and braces: drop anything a previous mount may have left behind.
+    this.holderRef.current.replaceChildren(this.mathField);
 
     if (this.props.innerRef) {
       this.props.innerRef(this);
     }
-
-    this.setState?.({});
   }
 
   componentDidUpdate(prevProps) {
@@ -99,6 +109,10 @@ export class Input extends React.Component {
   }
 
   componentWillUnmount() {
+    // Invalidate any mount still awaiting the MathLive load, so it does not
+    // append a field into a holder that is going away.
+    this.mountGeneration = (this.mountGeneration || 0) + 1;
+
     if (this.mathField) {
       this.mathField.removeEventListener('input', this.onInputEdit);
       this.mathField.remove();

package/src/mf/static.jsx

@@ -2,7 +2,7 @@ import React from 'react';
 import PropTypes from 'prop-types';
 import { styled } from '@mui/material/styles';
 import debug from 'debug';
-import { loadMathLive, getMacros, latexToMarkup } from '../mathlive-instance';
+import { loadMathLive, getMacros, latexToMarkup, MATH_MODE_SPACE } from '../mathlive-instance';
 import { toMathLive, fromMathLive, fieldIds } from '../latex-bridge';
 import { placeholderStyles } from './common-styles';
 
@@ -64,28 +64,41 @@ export default class Static extends React.Component {
   }
 
   async componentDidMount() {
+    // See the note in mf/input.jsx: a generation counter, not a boolean, so a
+    // StrictMode mount -> unmount -> mount on the same instance still ends up
+    // with exactly one field.
+    const generation = (this.mountGeneration = (this.mountGeneration || 0) + 1);
+
     if (!this.isInteractive()) {
       await loadMathLive();
-      this.renderMarkup();
+
+      if (generation === this.mountGeneration) {
+        this.renderMarkup();
+      }
+
       return;
     }
 
     const ml = await loadMathLive();
 
-    if (!ml || !this.holderRef.current) {
+    if (generation !== this.mountGeneration || !ml || !this.holderRef.current || this.mathField) {
       return;
     }
 
     this.mathField = new ml.MathfieldElement({ macros: getMacros() });
     this.mathField.readOnly = true;
     this.mathField.mathVirtualKeyboardPolicy = 'manual';
+    // Without this the spacebar does nothing: MathLive's mathModeSpace
+    // defaults to an empty string.
+    this.mathField.mathModeSpace = MATH_MODE_SPACE;
     this.mathField.value = toMathLive(this.props.latex);
 
     this.mathField.addEventListener('input', this.onPromptInput);
     this.mathField.addEventListener('focusin', this.onPromptFocus);
     this.mathField.addEventListener('keydown', this.onKeyDown);
 
-    this.holderRef.current.appendChild(this.mathField);
+    // Belt and braces: drop anything a previous mount may have left behind.
+    this.holderRef.current.replaceChildren(this.mathField);
 
     this.createLiveRegion();
   }
@@ -103,6 +116,9 @@ export default class Static extends React.Component {
   }
 
   componentWillUnmount() {
+    // Invalidate any mount still awaiting the MathLive load.
+    this.mountGeneration = (this.mountGeneration || 0) + 1;
+
     if (this.mathField) {
       this.mathField.removeEventListener('input', this.onPromptInput);
       this.mathField.removeEventListener('focusin', this.onPromptFocus);