@pie-lib/math-input-mathlive 1.0.9-next.6618 → 1.0.9

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

@@ -46,26 +46,63 @@ const absoluteFontsDirectory = (dir) => {
   }
 };
 
+/**
+ * Version-pinned CDN fallback for the KaTeX fonts.
+ *
+ * Some symbols are composed from Private Use Area glyphs that exist only in
+ * those fonts: `\\neq` is U+E020 (a negation slash) overlapped on `=`, and
+ * `\\nsim` / `\\ncong` work the same way. With no fonts the browser substitutes
+ * an arbitrary glyph for U+E020, so those keys render as garbage rather than
+ * simply falling back to a plainer face.
+ *
+ * The version comes from MathLive itself, so the fonts always match the engine.
+ * Hosts that would rather not depend on a third party should serve the fonts and
+ * call `configureFonts('/their/path')`, or pass `null` to opt out.
+ */
+const FALLBACK_MATHLIVE_VERSION = '0.110.0';
+
+const cdnFontsDirectory = () => {
+  const version = (mathlive && mathlive.version && mathlive.version.mathlive) || FALLBACK_MATHLIVE_VERSION;
+
+  // NOTE: `/fonts`, not `/dist/fonts` - the published package root holds them.
+  return `https://unpkg.com/mathlive@${version}/fonts`;
+};
+
 /**
  * Tell the package where the MathLive fonts are served from.
  *
- * Call before `loadMathLive()`. Accepts an absolute URL, a root-relative path
- * (`/mathlive-fonts`) or a relative one; pass `null` to skip font loading and
- * fall back to system fonts.
+ * Call before `loadMathLive()`.
+ *
+ *  - a path/URL: served by you, no third-party request
+ *  - `null`:     skip font loading; note `\\neq`, `\\nsim` and `\\ncong` then
+ *                render incorrectly, being built from Private Use Area glyphs
+ *  - not called: falls back to a version-pinned CDN
  *
  * The fonts ship inside the `mathlive` package (`node_modules/mathlive/fonts`)
- * and must be copied into whatever the host app serves statically.
+ * ready to copy into whatever the host app serves statically.
  *
- * @param {string|null} dir
+ * @param {string|null} [dir]
  */
 export const configureFonts = (dir) => {
   fontsDirectory = dir;
 
   if (mathlive) {
-    mathlive.MathfieldElement.fontsDirectory = absoluteFontsDirectory(dir);
+    mathlive.MathfieldElement.fontsDirectory = dir === undefined ? cdnFontsDirectory() : absoluteFontsDirectory(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.
@@ -126,17 +163,19 @@ let loadWarned = false;
 /** Apply post-load configuration exactly once. */
 const configureLoaded = () => {
   // Always replace MathLive's relative `'./fonts/'` default: it throws
-  // "Invalid base URL" when bundled. Either point at the host app's copy or
-  // disable font loading, both of which are safe.
+  // "Invalid base URL" when bundled. Use the host's copy if one was configured,
+  // otherwise the version-pinned CDN.
   if (fontsDirectory === undefined) {
     log(
-      'no fontsDirectory configured - MathLive will use fallback fonts. ' +
-        'Call configureFonts("/path/to/fonts") with a copy of node_modules/mathlive/fonts to enable them.',
+      'no fontsDirectory configured - falling back to the CDN (%s). ' +
+        'Serve the fonts yourself and call configureFonts("/path/to/fonts") to avoid the network request, ' +
+        'or configureFonts(null) to opt out.',
+      cdnFontsDirectory(),
     );
   }
 
   mathlive.MathfieldElement.fontsDirectory =
-    fontsDirectory === undefined ? null : absoluteFontsDirectory(fontsDirectory);
+    fontsDirectory === undefined ? cdnFontsDirectory() : absoluteFontsDirectory(fontsDirectory);
 
   injectCoreStylesheet();
 };

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);

package/LICENSE.md

@@ -1,5 +0,0 @@
-Copyright 2019 CoreSpring Inc
-
-Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.