@pie-lib/math-input-mathlive 1.1.5-beta.1 → 1.1.5-beta.10

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

@@ -0,0 +1,364 @@
+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,
+  // Caret bookkeeping: MathLive exposes the caret offset as `position`, and any
+  // executeCommand triggers the render that reveals the caret.
+  position: undefined,
+  commands: [],
+  executeCommand(name) {
+    this.commands.push(name);
+  },
+  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);
+    });
+  });
+
+  /**
+   * MathLive shows the caret only while the field carries `ML__focused`, which
+   * it adds during a render gated on `isSelectionEditable && hasFocus()`. In a
+   * read-only field only prompt interiors are editable, so after a bare
+   * `focus()` - whose selection sits outside every prompt - the answer block
+   * looked focused but had no blinking cursor. Verified in Chromium: the caret
+   * span goes from visibility:hidden to visible once the selection is inside a
+   * prompt AND a render has run.
+   */
+  describe('caret placement', () => {
+    it('puts a collapsed caret in the first prompt on focus', () => {
+      const s = make();
+
+      s.mathField = stubField({ r1: '', r2: '' });
+      s.focus();
+
+      // stub ranges are [0,5] for r1, [10,15] for r2
+      expect(s.mathField.selection).toEqual({ ranges: [[0, 0]] });
+    });
+
+    it('forces the render that makes the caret visible', () => {
+      const s = make();
+
+      s.mathField = stubField({ r1: '' });
+      s.focus();
+
+      // assigning `selection` alone updates the model without re-rendering, so
+      // ML__focused would never be added
+      expect(s.mathField.commands).toEqual(['scrollIntoView']);
+    });
+
+    it('does not move a caret that is already inside a prompt', () => {
+      const s = make();
+
+      s.mathField = stubField({ r1: '', r2: '' });
+      s.mathField.position = 12; // inside r2
+      s.focus();
+
+      expect(s.mathField.selection).toBe(null);
+      expect(s.mathField.commands).toEqual([]);
+    });
+
+    it('targets a specific prompt', () => {
+      const s = make();
+
+      s.mathField = stubField({ r1: '', r2: '' });
+      s.focusPrompt('r2');
+
+      expect(s.mathField.selection).toEqual({ ranges: [[10, 10]] });
+    });
+
+    it('falls back to the first prompt for an unknown id', () => {
+      const s = make();
+
+      s.mathField = stubField({ r1: '', r2: '' });
+      s.focusPrompt('nope');
+
+      expect(s.mathField.selection).toEqual({ ranges: [[0, 0]] });
+    });
+
+    it('is a no-op when there are no prompts', () => {
+      const s = make();
+
+      s.mathField = stubField({});
+
+      expect(() => s.focusPrompt()).not.toThrow();
+      expect(s.mathField.selection).toBe(null);
+    });
+
+    it('is safe without a field', () => {
+      expect(() => make().focusPrompt('r1')).not.toThrow();
+    });
+
+    describe('promptContaining', () => {
+      it('finds the prompt whose range holds the offset, inclusive', () => {
+        const s = make();
+
+        s.mathField = stubField({ r1: '', r2: '' });
+
+        expect(s.promptContaining(0)).toEqual('r1');
+        expect(s.promptContaining(5)).toEqual('r1');
+        expect(s.promptContaining(10)).toEqual('r2');
+        expect(s.promptContaining(7)).toBeUndefined();
+      });
+
+      it('treats a missing position as outside', () => {
+        const s = make();
+
+        s.mathField = stubField({ r1: '' });
+
+        expect(s.promptContaining(undefined)).toBeUndefined();
+      });
+    });
+
+    // MathQuill's inner fields could be focused directly.
+    it('promptHandle exposes focus() for its own prompt', () => {
+      const s = make();
+
+      s.mathField = stubField({ r1: '', r2: '' });
+      s.promptHandle('r2').focus();
+
+      expect(s.mathField.focused).toBe(true);
+      expect(s.mathField.selection).toEqual({ ranges: [[10, 10]] });
+    });
+  });
+});

package/src/keypad/index.jsx

@@ -22,10 +22,25 @@ const log = debug('pie-lib:math-input-mathlive:keypad');
  * `convertLatexToMarkup`, so a 40-key keypad no longer creates 40 live math
  * instances.
  */
+// Labels that the legacy keypad drew slanted. MathQuill styled `\parallel` as
+// italic, which slants the two bars; MathLive draws it upright. A skew is used
+// rather than `font-style: italic` so the slant does not depend on the font
+// having an italic face for this glyph.
+const SLANTED_LABELS = ['\\parallel'];
+const SLANT = 'skewX(-15deg)';
+// MathLive's `∥` has hairline bars next to the radical sign and the other keys, so
+// they are thickened with a text stroke and stretched a little taller.
+const SLANTED_STROKE = '0.03em currentColor';
+const SLANTED_SCALE_Y = 1.25;
+
 // The `color.*()` helpers must be called lazily, inside the styled callback.
 // Evaluating them in a plain object literal runs them at module load, which
 // breaks any consumer that mocks a subset of @pie-lib/render-ui.
-const LabelHolder = styled('span')(() => ({
+const LabelHolder = styled('span', { shouldForwardProp: (prop) => prop !== 'slanted' })(({ slanted }) => ({
+  ...(slanted && {
+    transform: `${SLANT} scaleY(${SLANTED_SCALE_Y})`,
+    '& *': { WebkitTextStroke: SLANTED_STROKE },
+  }),
   pointerEvents: 'none',
   textTransform: 'none',
   color: color.text(),
@@ -112,9 +127,9 @@ export class LatexLabel extends React.Component {
     // Fall back to the raw latex so a button is never blank.
     return markup ? (
       // eslint-disable-next-line react/no-danger
-      <LabelHolder dangerouslySetInnerHTML={{ __html: markup }} />
+      <LabelHolder slanted={SLANTED_LABELS.includes(this.props.latex)} dangerouslySetInnerHTML={{ __html: markup }} />
     ) : (
-      <LabelHolder>{this.props.latex}</LabelHolder>
+      <LabelHolder slanted={SLANTED_LABELS.includes(this.props.latex)}>{this.props.latex}</LabelHolder>
     );
   }
 }

package/src/latex-bridge.js

@@ -69,6 +69,35 @@ export const DEFAULT_FIELD_ID = 'r1';
  */
 const EMPTY_SLOT = '\\htmlData{pie-empty=1}{\\rule{0.55em}{0.55em}}';
 const EMPTY_GROUP_REGEX = /\{\s*\}/g;
+// The segment key (`\overline{}`). The keypad centres every label in its cell, and
+// a thin bar is a much shorter label than the ray and line keys' stretchy arrows,
+// so by default both its bar and its box sit off from theirs: the bar is lower
+// than the arrows' shafts, and the box higher than theirs. Two zero-width struts
+// fix that, found by rendering the three keys at 14-28px and measuring:
+//  - inside the bar, above the box: pushes the bar up to the height of the
+//    arrows' shafts (the bar-to-box distance then matches theirs);
+//  - before the bar, from the baseline: raises the label's top, which moves the
+//    whole label down so the box lands where theirs does.
+const EMPTY_OVERLINE_REGEX = /\\overline\{\s*\}/g;
+const EMPTY_OVERLINE_BAR_STRUT = '\\rule{0em}{0.87em}';
+const EMPTY_OVERLINE_LABEL_STRUT = '\\rule{0em}{1.3em}';
+// Empty delimiter pairs: `\abs{}` is converted to `\left|\right|`, and the
+// parenthesis / bracket keys are `\left(\right)` / `\left[\right]`. None has a
+// `{}` group for the rule above to catch, so they would render as bare fences.
+const EMPTY_FENCE_REGEX = /\\left([([|])\s*\\right([)\]|])/g;
+// The same muted fill as the other slots (`pie-empty`), but a tall rectangle
+// rather than a square. It also sets the fences' height: `\left...\right` stretch
+// to their content, so a taller slot gives taller parentheses.
+//
+// A `\rule` stands on the baseline, but the fences are centred on the math axis
+// (0.25em above it), so an un-lifted box sat high between them. `[-0.25em]`
+// lowers it by (axis - height / 2) = 0.25 - 1 / 2, centring it on the axis.
+//
+// Lowering it alone also shrinks the fences, which size themselves to their
+// content (MathLive switches to short bars). The zero-width `\rule{0em}{1em}`
+// strut keeps the content as tall as before, so the bars keep their height and
+// only the box moves.
+const EMPTY_FENCE_SLOT = '\\rule{0em}{1em}\\htmlData{pie-empty=1}{\\rule[-0.25em]{0.55em}{1em}}';
 
 /**
  * Make empty argument slots visible, for static rendering.
@@ -79,7 +108,11 @@ const EMPTY_GROUP_REGEX = /\{\s*\}/g;
  * @param {string} latex
  * @returns {string}
  */
-export const withVisibleEmptySlots = (latex) => (latex || '').replace(EMPTY_GROUP_REGEX, `{${EMPTY_SLOT}}`);
+export const withVisibleEmptySlots = (latex) =>
+  (latex || '')
+    .replace(EMPTY_OVERLINE_REGEX, `${EMPTY_OVERLINE_LABEL_STRUT}\\overline{${EMPTY_OVERLINE_BAR_STRUT}${EMPTY_SLOT}}`)
+    .replace(EMPTY_GROUP_REGEX, `{${EMPTY_SLOT}}`)
+    .replace(EMPTY_FENCE_REGEX, (_m, open, close) => `\\left${open}${EMPTY_FENCE_SLOT}\\right${close}`);
 
 /**
  * Pie commands that take an argument, and their native MathLive equivalents.
@@ -236,6 +269,138 @@ export const toMathLive = (latex) => {
   return out;
 };
 
+/**
+ * Keypad command names that MathQuill treated as ALIASES of a different command.
+ *
+ * MathQuill registered `\\divide` as another name for `\\div` (and
+ * `\\perpendicular` for `\\perp`), so pressing the key stored the real command.
+ * MathLive only knows these names through `PIE_MACROS`, and serialises a macro
+ * under its own name - so `\\divide` reached storage verbatim, where MathJax
+ * (@pie-lib/math-rendering) has no such command and renders it as red text.
+ *
+ * Every other keypad command already matches what MathQuill stored (`\\degree`,
+ * `\\nsim`, `\\ncong`, `\\nparallel`, `\\square`, `\\napprox`,
+ * `\\parallelogram`), and MathJax understands those.
+ */
+const MATHQUILL_ALIASES = {
+  '\\divide': '\\div',
+  '\\perpendicular': '\\perp',
+};
+
+// Whole command names only: `\\divideontimes` is a real AMS symbol.
+const MATHQUILL_ALIAS_REGEX = /\\(divide|perpendicular)(?![a-zA-Z])/g;
+
+/**
+ * Primes. MathLive turns a prime that follows a base into a superscript atom and
+ * serialises it as `^{\\prime}`, or `^{\\doubleprime}` for the keypad's double
+ * prime key (`5''` comes back out as `5^{\\doubleprime}`). MathJax has no
+ * `\\doubleprime`, and two adjacent `^{\\prime}` groups - what typing `'` twice
+ * produces - are a "double exponent" error. MathQuill stored plain apostrophes,
+ * which both MathJax and MathLive read as primes, so store those.
+ *
+ * Only a superscript made of primes alone is rewritten: `x^{\\prime 2}` keeps
+ * its group, since it holds more than primes.
+ */
+const PRIME_SUPERSCRIPT_REGEX = /\^\{((?:\s*\\(?:prime|doubleprime)(?![a-zA-Z]))+)\s*\}/g;
+const BARE_DOUBLEPRIME_REGEX = /\\doubleprime(?![a-zA-Z])/g;
+
+const primesToApostrophes = (primes) =>
+  // eslint-disable-next-line quotes
+  "'".repeat(
+    (primes.match(/\\prime(?![a-zA-Z])/g) || []).length + 2 * (primes.match(BARE_DOUBLEPRIME_REGEX) || []).length,
+  );
+
+const BARE_PRIME_COMMAND_REGEX = /^\\(doubleprime|prime)(?![a-zA-Z])/;
+
+/**
+ * Primes that are *not* in a superscript.
+ *
+ * MathLive emits bare `\prime` / `\doubleprime` for a `′` or `″` typed or pasted
+ * as a character (`5′6″` serialises as `5\prime6\doubleprime`). A bare `\prime`
+ * is a full-size glyph in MathJax, while `''` is a superscript, so storing
+ * `5\prime6''` drew the single prime visibly larger than each stroke of the
+ * double prime. Both become apostrophes, the superscript primes MathQuill
+ * stored, so they always match.
+ *
+ * Inside a script (`x^{\prime 2}`, `x^\prime`) a prime is already a
+ * superscript, and an apostrophe there would mean something else, so
+ * `\prime` is kept and `\doubleprime` (unknown to MathJax) becomes
+ * `\prime\prime`.
+ *
+ * @param {string} latex
+ * @returns {string}
+ */
+const barePrimesToApostrophes = (latex) => {
+  if (latex.indexOf('prime') === -1) {
+    return latex;
+  }
+
+  // One entry per open brace: is that group a super/subscript?
+  const groups = [];
+  let out = '';
+  let i = 0;
+
+  while (i < latex.length) {
+    const ch = latex[i];
+
+    if (ch === '\\') {
+      const match = latex.slice(i).match(BARE_PRIME_COMMAND_REGEX);
+
+      if (match) {
+        const isDouble = match[1] === 'doubleprime';
+        // `x^\prime`: the command is itself the script.
+        const isScriptArgument = /[\^_]\s*$/.test(out);
+        const inScript = isScriptArgument || groups.indexOf(true) !== -1;
+
+        if (inScript) {
+          out += isDouble ? '\\prime\\prime' : '\\prime';
+        } else {
+          // eslint-disable-next-line quotes
+          out += isDouble ? "''" : "'";
+        }
+
+        i += match[0].length;
+        continue;
+      }
+
+      // Copy any other command, or an escaped character such as `\{`, whole.
+      const command = latex.slice(i).match(/^\\(?:[a-zA-Z]+|.)/);
+      const text = command ? command[0] : ch;
+
+      out += text;
+      i += text.length;
+      continue;
+    }
+
+    if (ch === '{') {
+      groups.push(/[\^_]\s*$/.test(out));
+    } else if (ch === '}') {
+      groups.pop();
+    }
+
+    out += ch;
+    i += 1;
+  }
+
+  return out;
+};
+
+/**
+ * Rewrite what MathLive serialises into the form MathQuill stored: alias
+ * command names, and primes.
+ *
+ * @param {string} latex
+ * @returns {string}
+ */
+export const toCanonicalCommands = (latex) =>
+  typeof latex === 'string'
+    ? barePrimesToApostrophes(
+        latex
+          .replace(MATHQUILL_ALIAS_REGEX, (m) => MATHQUILL_ALIASES[m])
+          .replace(PRIME_SUPERSCRIPT_REGEX, (_m, primes) => primesToApostrophes(primes)),
+      )
+    : latex;
+
 /**
  * Convert latex out of MathLive back into the stored form, so items authored
  * with the MathLive editor remain readable by @pie-lib/math-rendering and by
@@ -273,7 +438,9 @@ export const fromMathLive = (latex) => {
   out = out.replace(BARE_PLACEHOLDER_REGEX, (_m, content) => content);
   out = out.replace(BARE_PLACEHOLDER_NO_ARG_REGEX, '');
 
-  return out;
+  // Store the command MathQuill stored, not the alias - also heals latex that was
+  // saved with `\\divide` before the keypad resolved it.
+  return toCanonicalCommands(out);
 };
 
 /**
@@ -347,7 +514,7 @@ export const keyToAction = (key) => {
     // applied them in sequence; MathLive inserts one latex string, so expand
     // each part and concatenate.
     const parts = Array.isArray(key.command) ? key.command : [key.command];
-    const value = parts.map((c) => COMMANDS_WITH_ARGS[c] || c).join('');
+    const value = parts.map((c) => COMMANDS_WITH_ARGS[c] || MATHQUILL_ALIASES[c] || c).join('');
 
     return { type: 'insert', value };
   }
@@ -361,4 +528,4 @@ export const keyToAction = (key) => {
   return undefined;
 };
 
-export { COMMANDS_WITH_ARGS, KEYSTROKES };
+export { COMMANDS_WITH_ARGS, KEYSTROKES, MATHQUILL_ALIASES };