@pie-lib/math-input-mathlive 1.1.4 → 1.1.5-beta.2

package/src/latex-bridge.js

@@ -55,11 +55,19 @@ export const DEFAULT_FIELD_ID = 'r1';
  *
  * `\placeholder{}` is not usable here: in static markup it renders as a
  * non-breaking space, because its editable box only exists inside a live
- * mathfield. So an actual glyph is required.
+ * mathfield. So something with real width is required.
+ *
+ * It must be a `\rule`, not a unicode glyph. A glyph's width comes from font
+ * metrics, and U+25AB is not in the KaTeX fonts - the browser substitutes a
+ * wider fallback while MathLive still sizes surrounding accents from its own
+ * metrics. That left stretchy accents (`\overarc`, `\overleftrightarrow`)
+ * visibly narrower than the box they were meant to span. A rule carries an
+ * explicit em width, so accents size correctly - and a filled box is closer to
+ * MathQuill's `.mq-empty` anyway.
  *
  * Live mathfields need none of this - MathLive manages empty slots itself.
  */
-const EMPTY_SLOT = '\\htmlData{pie-empty=1}{\\unicode{"25AB}}';
+const EMPTY_SLOT = '\\htmlData{pie-empty=1}{\\rule{0.55em}{0.55em}}';
 const EMPTY_GROUP_REGEX = /\{\s*\}/g;
 
 /**
@@ -106,6 +114,40 @@ export const toNativeCommands = (latex) => {
   out = replaceAbs(out);
   out = out.replace(/\\longdiv\{/g, '\\enclose{longdiv}{');
   out = out.replace(/\\overarc\{/g, '\\overparen{');
+  out = escapeBareComments(out);
+
+  return out;
+};
+
+/**
+ * Escape an unescaped `%`.
+ *
+ * In real LaTeX `%` starts a comment, so MathLive discards it *and everything
+ * after it*: `50%` renders as `50`, and `x%y` as just `x`. MathQuill had no
+ * such notion - it treated `%` as a symbol - so latex from anywhere outside the
+ * keypad may still carry a bare one.
+ *
+ * Only a `%` preceded by an even number of backslashes is bare: `\%` is already
+ * escaped, while the `%` in `\\%` (a line break, then a comment) is not.
+ *
+ * @param {string} latex
+ * @returns {string}
+ */
+const escapeBareComments = (latex) => {
+  if (latex.indexOf('%') === -1) {
+    return latex;
+  }
+
+  let out = '';
+  // Consecutive backslashes immediately before the current character.
+  let backslashes = 0;
+
+  for (let i = 0; i < latex.length; i++) {
+    const ch = latex[i];
+
+    out += ch === '%' && backslashes % 2 === 0 ? '\\%' : ch;
+    backslashes = ch === '\\' ? backslashes + 1 : 0;
+  }
 
   return out;
 };
@@ -240,8 +282,15 @@ export const fromMathLive = (latex) => {
  * placeholders in the inserted latex.
  */
 const COMMANDS_WITH_ARGS = {
+  // An explicit "blank over blank" key: both slots start empty.
   '\\frac': '\\frac{#?}{#?}',
-  '/': '\\frac{#?}{#?}',
+  // Division, which must behave like MathQuill's `/`: whatever precedes the
+  // cursor becomes the numerator and the caret lands in the denominator. `#@`
+  // is MathLive's token for "the selection, or the item before the cursor" -
+  // this is exactly the template MathLive binds to the `/` key itself. Using
+  // `#?` here instead produced an empty fraction and left the typed number
+  // stranded outside it.
+  '/': '\\frac{#@}{#?}',
   '\\sqrt': '\\sqrt{#?}',
   '\\nthroot': '\\sqrt[#?]{#?}',
   '\\overline': '\\overline{#?}',

package/src/mathlive-instance.js

@@ -1,5 +1,6 @@
 import debug from 'debug';
 import { NEWLINE_EMBED, toMathLive, withVisibleEmptySlots } from './latex-bridge';
+import { ROOT_INDEX_CSS } from './mf/common-styles';
 
 const log = debug('pie-lib:math-input-mathlive:instance');
 
@@ -46,26 +47,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,21 +164,162 @@ 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();
 };
 
+/**
+ * CSS that has to live *inside* a mathfield's shadow root.
+ *
+ * A live `<math-field>` renders in shadow DOM (`attachShadow({mode:'open'})`),
+ * so nothing in the host page's stylesheets reaches it. The stretchy-accent
+ * problem therefore needs fixing twice: once for static markup (see
+ * `placeholderStyles`) and once here for the editor.
+ *
+ * MathLive centres an accent with `margin-left: <half the content width>` as an
+ * inline style. For a stretchy accent that also shrinks its containing block
+ * (`.ML__center` is position:relative), so the arc ends up half-width and offset
+ * - visibly failing to span the text underneath.
+ *
+ * `:has(.ML__stretchy)` keeps the fix to stretchy accents; single-glyph accents
+ * (`\hat{x}`, `\vec{x}`) still need their centring offset.
+ */
+/**
+ * Marker put on the host `<math-field>` while a `\placeholder{}` is selected,
+ * so the caret rules below apply to a placeholder and nothing else.
+ */
+export const PLACEHOLDER_CARET_CLASS = 'pie-caret-in-placeholder';
+
+/** What MathLive serialises a `#?` slot as. */
+const PLACEHOLDER_LATEX = '\\placeholder{}';
+
+/**
+ * A blinking caret inside a selected placeholder box.
+ *
+ * A keypad key such as `\frac` inserts `\frac{#?}{#?}`. MathLive turns each
+ * `#?` into a `\placeholder{}` atom and *selects* the first one. That atom is a
+ * leaf - the offsets around it are "before" and "after", there is no position
+ * inside it - so MathLive renders **no caret element at all** and shows only
+ * the selection highlight. The box therefore looked focused (blue) but dead,
+ * where MathQuill used to blink a cursor inside its empty box.
+ *
+ * So the caret is drawn here. `:not(:has(.ML__selected))` picks the innermost
+ * selected element (MathLive puts the class on a wrapper *and* the glyph span,
+ * which would otherwise give two carets), and the `ML__caret-blink` keyframes
+ * plus `--_caret-color` are MathLive's own, already in this shadow root.
+ *
+ * Typing still replaces the whole placeholder, which for an empty box is
+ * indistinguishable from inserting at the caret.
+ */
+const PLACEHOLDER_CARET_CSS = [
+  `:host(.${PLACEHOLDER_CARET_CLASS}) .ML__selected:not(:has(.ML__selected)){position:relative}`,
+  `:host(.${PLACEHOLDER_CARET_CLASS}) .ML__selected:not(:has(.ML__selected))::after{`,
+  'content:"";position:absolute;left:50%;top:12%;height:76%;',
+  'border-right:2px solid var(--_caret-color, currentColor);',
+  'animation:ML__caret-blink 1.05s step-end forwards infinite}',
+].join('');
+
+// A live mathfield needs the readable radical index too: `rootIndexStyles` is
+// written for static markup in the host page, which cannot cross the shadow
+// boundary.
+const SHADOW_CSS =
+  '.ML__latex .ML__center:has(.ML__stretchy){margin-left:0 !important}' + ROOT_INDEX_CSS + PLACEHOLDER_CARET_CSS;
+
+/**
+ * Keep {@link PLACEHOLDER_CARET_CLASS} in step with the selection.
+ *
+ * Gating on the class is what keeps the caret specific to placeholders: an
+ * ordinary selection (`x+1`) must not sprout one. MathLive fires
+ * `selection-change` for every caret move, including the one that lands on the
+ * placeholder straight after an insert.
+ *
+ * @param {HTMLElement} mathField
+ * @returns {function|undefined} teardown, to call on unmount
+ */
+export const trackPlaceholderCaret = (mathField) => {
+  if (!mathField || typeof mathField.addEventListener !== 'function') {
+    return undefined;
+  }
+
+  const update = () => {
+    let selected = '';
+
+    try {
+      // A collapsed selection already has a real MathLive caret.
+      if (!mathField.selectionIsCollapsed && mathField.selection) {
+        selected = mathField.getValue(mathField.selection, 'latex');
+      }
+    } catch (e) {
+      log('could not read the selection: %s', e && e.message);
+    }
+
+    if (mathField.classList) {
+      mathField.classList.toggle(PLACEHOLDER_CARET_CLASS, selected === PLACEHOLDER_LATEX);
+    }
+  };
+
+  mathField.addEventListener('selection-change', update);
+  update();
+
+  return () => mathField.removeEventListener('selection-change', update);
+};
+
+/**
+ * Apply {@link SHADOW_CSS} inside a mathfield's shadow root.
+ *
+ * Uses `adoptedStyleSheets` when available (which is how MathLive loads its own
+ * stylesheets) and falls back to appending a <style> node.
+ *
+ * @param {HTMLElement} mathField
+ */
+export const applyShadowStyles = (mathField) => {
+  const root = mathField && mathField.shadowRoot;
+
+  if (!root) {
+    return;
+  }
+
+  try {
+    if ('adoptedStyleSheets' in root && typeof CSSStyleSheet !== 'undefined') {
+      // Do not re-add on a re-render.
+      if (root.__pieAccentSheet) {
+        return;
+      }
+
+      const sheet = new CSSStyleSheet();
+
+      sheet.replaceSync(SHADOW_CSS);
+      root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
+      root.__pieAccentSheet = sheet;
+
+      return;
+    }
+
+    if (!root.querySelector('style[data-pie-accent]')) {
+      const style = document.createElement('style');
+
+      style.setAttribute('data-pie-accent', '');
+      style.textContent = SHADOW_CSS;
+      root.appendChild(style);
+    }
+  } catch (e) {
+    log('could not apply shadow styles to the mathfield: %s', e && e.message);
+  }
+};
+
 /**
  * Ensure MathLive's "core" stylesheet is in the document.
  *

package/src/mf/common-styles.js

@@ -13,7 +13,9 @@
  * Most are intentionally near-empty: MathLive sizes scripts, radicals and
  * fences correctly on its own, so the MathQuill-era corrections are not needed.
  * They stay as documented extension points rather than being deleted, so the
- * destructuring above keeps working.
+ * destructuring above keeps working. The exception is the radical index, which
+ * MathLive sizes to TeX metrics that read too small here - see
+ * `rootIndexStyles`.
  */
 
 /**
@@ -40,10 +42,47 @@ export const longdivStyles = {
 };
 
 /**
- * Superscript/subscript sizing. MathLive follows TeX metrics, so no overrides
- * are required.
+ * How the index of a radical is sized.
+ *
+ * MathLive follows TeX and sets the index of `\sqrt[n]{x}` in scriptscriptstyle,
+ * which it emits as an inline `font-size: 50%` on the span wrapping the index's
+ * glyphs. At authoring sizes that leaves the index - on the nth-root key, and in
+ * any radical the author types - too small to read next to the radicand, so it is
+ * scaled up to 80% - 1.6x what MathLive asks for.
+ *
+ * Only that innermost span is resized. `.ML__sqrt-index` itself keeps its font
+ * size on purpose: the vlist inside it tucks the index into the radical's crook
+ * with em-based `top`/`height` offsets, and scaling those lifts the index clear
+ * of the radical instead of just enlarging it.
+ *
+ * The child chain is spelled out so that nothing nested deeper inside the index
+ * (a fraction's numerator, another radical) is caught by the same rule, and
+ * `!important` is required because the 50% is an INLINE style.
  */
-export const supsubStyles = {};
+const ROOT_INDEX_SELECTOR = '.ML__sqrt-index > .ML__vlist-t > .ML__vlist-r > .ML__vlist > span > [style*="font-size"]';
+const ROOT_INDEX_FONT_SIZE = '80%';
+
+export const rootIndexStyles = {
+  [`& ${ROOT_INDEX_SELECTOR}`]: {
+    fontSize: `${ROOT_INDEX_FONT_SIZE} !important`,
+  },
+};
+
+/**
+ * The same rule as a CSS string, for a live mathfield's shadow root - see
+ * `SHADOW_CSS` in mathlive-instance.js. Static markup is styled by
+ * {@link rootIndexStyles}.
+ */
+export const ROOT_INDEX_CSS = `${ROOT_INDEX_SELECTOR}{font-size:${ROOT_INDEX_FONT_SIZE} !important}`;
+
+/**
+ * Superscript/subscript sizing. MathLive follows TeX metrics for scripts, so the
+ * MathQuill-era corrections are gone; the radical index is the one place where a
+ * TeX-correct size reads too small in the authoring UI.
+ */
+export const supsubStyles = {
+  ...rootIndexStyles,
+};
 
 /** Empty placeholder boxes (answer blocks / open slots). */
 export const placeholderStyles = {
@@ -57,13 +96,42 @@ export const placeholderStyles = {
   '& [data-pie-empty]': {
     opacity: 0.5,
   },
-  // Stretchy accents render an <svg>; mathlive-static.css positions it
-  // absolutely at width:100%. Repeated here so static math cannot blow out its
-  // container if that stylesheet is missing.
-  '& svg': {
+  // Stretchy accents (\overarc, \overleftrightarrow, \overrightarrow) render an
+  // <svg width="100%" preserveAspectRatio="none"> inside a `.ML__stretchy`. That
+  // span is absolutely positioned, so its immediate wrapper computes to 0px and
+  // the width has to resolve against a *positioned* ancestor. Pin that to
+  // `.ML__base`, whose width already equals the accent's content (measured:
+  // 9.85px for a 0.56em slot), so the arc spans exactly its content.
+  //
+  // Do NOT write a bare `& svg` rule instead: MathLive's own rule is
+  // descendant-scoped (`.ML__latex .ML__stretchy svg`), and a global one
+  // re-parents every svg in the subtree.
+  '& .ML__base': {
+    position: 'relative',
+  },
+  '& .ML__stretchy': {
     position: 'absolute',
+    left: 0,
     width: '100%',
   },
+  // MathLive centres an accent by shifting it right half the content width -
+  // `margin-left: 0.28em` for a 0.56em slot - which assumes a glyph with its own
+  // side bearings. Over a synthetic empty slot it just pushes the arc right.
+  //
+  // `!important` is required: MathLive writes this as an INLINE style
+  // (`style="top:-3.4em;margin-left:0.28em"`), which a class cannot override.
+  //
+  // It also fixes the width. `.ML__center` is the stretchy's containing block
+  // (MathLive gives `.ML__vlist > span` position:relative), and its width is the
+  // base minus that margin - measured 9.85px - 4.93px = 4.93px, exactly half,
+  // which is why the arc came out half-width AND offset right.
+  //
+  // Scoped with `:has(.ML__stretchy)`: only stretchy accents are affected.
+  // A single-glyph accent (`\hat{x}`, `\vec{x}`) genuinely needs its centring
+  // offset, and must keep it.
+  '& .ML__center:has(.ML__stretchy)': {
+    marginLeft: '0 !important',
+  },
 };
 
 /**
@@ -73,6 +141,7 @@ export const placeholderStyles = {
 export const commonMqKeyboardStyles = {
   ...commonMqFontStyles,
   ...longdivStyles,
+  ...rootIndexStyles,
   ...placeholderStyles,
   touchAction: 'manipulation',
   '& math-field': {
@@ -114,6 +183,7 @@ export const commonKeyboardStyles = commonMqKeyboardStyles;
 export default {
   commonMqFontStyles,
   longdivStyles,
+  rootIndexStyles,
   supsubStyles,
   commonMqKeyboardStyles,
   placeholderStyles,

package/src/mf/index.js

@@ -6,6 +6,7 @@ import CommonMqStyles, {
   commonMqFontStyles,
   commonMqKeyboardStyles,
   longdivStyles,
+  rootIndexStyles,
   supsubStyles,
   placeholderStyles,
 } from './common-styles';
@@ -21,6 +22,7 @@ export {
   commonMqFontStyles,
   commonMqKeyboardStyles,
   longdivStyles,
+  rootIndexStyles,
   supsubStyles,
   placeholderStyles,
 };

package/src/mf/input.jsx

@@ -2,7 +2,13 @@ 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,
+  applyShadowStyles,
+  trackPlaceholderCaret,
+} from '../mathlive-instance';
 import { toMathLive, fromMathLive, keyToAction, KEYSTROKES } from '../latex-bridge';
 
 const log = debug('pie-lib:math-input-mathlive:input');
@@ -49,9 +55,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 +77,25 @@ 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;
+
+    // The mathfield renders in shadow DOM, so page CSS cannot reach it - the
+    // stretchy-accent fix has to be injected there directly.
+    applyShadowStyles(this.mathField);
+
+    // A selected `\placeholder{}` gets no MathLive caret; draw one.
+    this.untrackCaret = trackPlaceholderCaret(this.mathField);
 
     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 +122,15 @@ 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.untrackCaret) {
+      this.untrackCaret();
+      this.untrackCaret = undefined;
+    }
+
     if (this.mathField) {
       this.mathField.removeEventListener('input', this.onInputEdit);
       this.mathField.remove();