@pie-lib/math-input-mathlive 1.0.0

package/src/latex-bridge.js

@@ -0,0 +1,190 @@
+/**
+ * LaTeX translation layer between the MathQuill-era content model and MathLive.
+ *
+ * Two independent concerns live here:
+ *
+ *  1. Newlines. MathQuill had no line break, so pie-lib registered a custom
+ *     `newLine` embed that serialises to `\embed{newLine}[]`. MathLive has no
+ *     embed system but supports real multiline environments, so we translate
+ *     `\embed{newLine}[]` <-> `\\` inside `\displaylines{}`.
+ *
+ *     Authored content keeps its `\embed{newLine}[]` on-disk form (that is what
+ *     @pie-lib/math-rendering already normalises for MathJax), so each renderer
+ *     normalises at its own boundary and stored items stay compatible.
+ *
+ *  2. Keypad key -> MathLive action. MathQuill keys carry `write`/`command`/
+ *     `keystroke` built for `mf.write()` / `mf.cmd()` / `mf.keystroke()`.
+ *     MathLive has `insert()` and `executeCommand()` instead.
+ */
+
+export const NEWLINE_EMBED = '\\embed{newLine}[]';
+const NEWLINE_EMBED_REGEX = /\\embed\{newLine\}\[\]/g;
+const DISPLAYLINES_REGEX = /^\\displaylines\{([\s\S]*)\}$/;
+
+/**
+ * MathQuill's editable sub-field syntax, e.g. `\MathQuillMathField[r1]{}`.
+ * These are the answer blocks in templated math items; MathLive expresses the
+ * same idea as `\placeholder[id]{}` and reads them back via the prompts API.
+ */
+const MQ_FIELD_REGEX = /\\MathQuillMathField\[([^\]]*)\]\{([^{}]*)\}/g;
+const PLACEHOLDER_REGEX = /\\placeholder\[([^\]]*)\]\{([^{}]*)\}/g;
+
+/** Default id used when stored latex has an unnamed field. */
+export const DEFAULT_FIELD_ID = 'r1';
+
+/**
+ * Ids of the answer blocks in a piece of stored latex, in document order.
+ *
+ * @param {string} latex
+ * @returns {string[]}
+ */
+export const fieldIds = (latex) => {
+  if (typeof latex !== 'string') {
+    return [];
+  }
+
+  const out = [];
+  let match;
+
+  MQ_FIELD_REGEX.lastIndex = 0;
+
+  while ((match = MQ_FIELD_REGEX.exec(latex)) !== null) {
+    out.push(match[1] || DEFAULT_FIELD_ID);
+  }
+
+  return out;
+};
+
+/**
+ * Convert stored latex (which may contain `\embed{newLine}[]`) into latex that
+ * MathLive can parse and render as multiple lines.
+ *
+ * @param {string} latex
+ * @returns {string}
+ */
+export const toMathLive = (latex) => {
+  if (typeof latex !== 'string' || !latex) {
+    return latex || '';
+  }
+
+  // Answer blocks: \MathQuillMathField[id]{x} -> \placeholder[id]{x}
+  let out = latex.replace(MQ_FIELD_REGEX, (_m, id, content) => `\\placeholder[${id || DEFAULT_FIELD_ID}]{${content}}`);
+
+  // Newlines: \embed{newLine}[] -> a multiline environment
+  if (out.indexOf(NEWLINE_EMBED) !== -1) {
+    out = `\\displaylines{${out.split(NEWLINE_EMBED_REGEX).join(' \\\\ ')}}`;
+  }
+
+  return out;
+};
+
+/**
+ * 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
+ * the existing MathQuill implementation.
+ *
+ * @param {string} latex
+ * @returns {string}
+ */
+export const fromMathLive = (latex) => {
+  if (typeof latex !== 'string' || !latex) {
+    return latex || '';
+  }
+
+  const match = latex.trim().match(DISPLAYLINES_REGEX);
+  let out = match ? match[1] : latex;
+
+  // `\\` is the line separator inside a multiline environment.
+  if (out.indexOf('\\\\') !== -1) {
+    out = out
+      .split(/\s*\\\\\s*/)
+      .map((s) => s.trim())
+      .join(NEWLINE_EMBED);
+  }
+
+  // Answer blocks: \placeholder[id]{x} -> \MathQuillMathField[id]{x}
+  out = out.replace(
+    PLACEHOLDER_REGEX,
+    (_m, id, content) => `\\MathQuillMathField[${id || DEFAULT_FIELD_ID}]{${content}}`,
+  );
+
+  return out;
+};
+
+/**
+ * MathQuill `cmd()` semantics: commands that take arguments should land the
+ * cursor inside the first argument. MathLive expresses that with `#?`
+ * placeholders in the inserted latex.
+ */
+const COMMANDS_WITH_ARGS = {
+  '\\frac': '\\frac{#?}{#?}',
+  '/': '\\frac{#?}{#?}',
+  '\\sqrt': '\\sqrt{#?}',
+  '\\nthroot': '\\sqrt[#?]{#?}',
+  '\\overline': '\\overline{#?}',
+  '\\overrightarrow': '\\overrightarrow{#?}',
+  '\\overleftrightarrow': '\\overleftrightarrow{#?}',
+  '\\overarc': '\\overarc{#?}',
+  '\\longdiv': '\\longdiv{#?}',
+  '^': '^{#?}',
+  _: '_{#?}',
+  '(': '\\left(#?\\right)',
+  '[': '\\left[#?\\right]',
+  '|': '\\left|#?\\right|',
+};
+
+/**
+ * MathQuill keystroke names -> MathLive command selectors.
+ */
+const KEYSTROKES = {
+  Left: 'moveToPreviousChar',
+  Right: 'moveToNextChar',
+  Backspace: 'deleteBackward',
+  Delete: 'deleteForward',
+  Up: 'moveUp',
+  Down: 'moveDown',
+};
+
+/**
+ * Translate a keypad key definition into a MathLive action.
+ *
+ * Mirrors the precedence in @pie-lib/math-input's MathInput.keypadPress:
+ * latex (unless a command is present) -> write -> command -> keystroke.
+ *
+ * @param {object} key
+ * @returns {{type: 'insert'|'command', value: string}|undefined}
+ */
+export const keyToAction = (key) => {
+  if (!key) {
+    return undefined;
+  }
+
+  if (key.latex && !key.command) {
+    return { type: 'insert', value: key.latex };
+  }
+
+  if (key.write) {
+    return { type: 'insert', value: key.write };
+  }
+
+  if (key.command) {
+    // Some keys carry an array of commands (e.g. Measured Angle is
+    // ['m', '\\angle'], log-base-n is ['\\log', '_']). MathQuill's `cmd()`
+    // 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('');
+
+    return { type: 'insert', value };
+  }
+
+  if (key.keystroke) {
+    const selector = KEYSTROKES[key.keystroke];
+
+    return selector ? { type: 'command', value: selector } : undefined;
+  }
+
+  return undefined;
+};
+
+export { COMMANDS_WITH_ARGS, KEYSTROKES };

package/src/math-input.jsx

@@ -0,0 +1,115 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { styled } from '@mui/material/styles';
+import debug from 'debug';
+
+import * as mf from './mf';
+import { baseSet } from './keys';
+import KeyPad from './keypad';
+import { keyToAction } from './latex-bridge';
+
+const log = debug('pie-lib:math-input-mathlive');
+
+const grey = 'rgba(0, 0, 0, 0.23)';
+
+const MathInputContainer = styled('div')(({ theme, focused }) => ({
+  borderRadius: '4px',
+  border: `solid 1px ${focused ? theme.palette.primary.main : grey}`,
+  marginTop: theme.spacing(1),
+  marginBottom: theme.spacing(1),
+  transition: 'border 200ms linear',
+}));
+
+const PadContainer = styled('div')({
+  width: '100%',
+  display: 'flex',
+});
+
+const StyledInput = styled(mf.Input)(({ theme }) => ({
+  width: '100%',
+  transition: 'border 200ms linear',
+  padding: theme.spacing(1),
+  '& math-field:focus-within': {
+    outline: 'none',
+    boxShadow: 'none',
+  },
+}));
+
+/**
+ * MathLive-backed equivalent of @pie-lib/math-input's `MathInput`.
+ * Same props (`keyset`, `latex`, `onChange`, `displayMode`).
+ */
+export class MathInput extends React.Component {
+  static propTypes = {
+    className: PropTypes.string,
+    keyset: PropTypes.array,
+    displayMode: PropTypes.oneOf(['block', 'block-on-focus']),
+    latex: PropTypes.string,
+    onChange: PropTypes.func,
+  };
+
+  static defaultProps = {
+    keyset: [],
+    displayMode: 'block',
+  };
+
+  constructor(props) {
+    super(props);
+    this.state = { focused: false };
+  }
+
+  keypadPress = (key) => {
+    log('[keypadPress] key:', key);
+
+    if (!this.input) {
+      return;
+    }
+
+    const action = keyToAction(key);
+
+    if (!action) {
+      return;
+    }
+
+    if (action.type === 'command') {
+      this.input.keystroke(action.value);
+    } else {
+      this.input.write(action.value);
+    }
+  };
+
+  inputFocus = () => this.setState({ focused: true });
+
+  inputBlur = () => this.setState({ focused: false });
+
+  changeLatex = (l) => {
+    const { onChange } = this.props;
+
+    if (onChange && l !== this.props.latex) {
+      log('[changeLatex]', l, this.props.latex);
+      onChange(l);
+    }
+  };
+
+  render() {
+    const { className, keyset, latex } = this.props;
+    const { focused } = this.state;
+
+    return (
+      <MathInputContainer className={className} focused={focused}>
+        <StyledInput
+          innerRef={(r) => (this.input = r)}
+          onFocus={this.inputFocus}
+          onBlur={this.inputBlur}
+          latex={latex}
+          onChange={this.changeLatex}
+        />
+        <PadContainer>
+          <KeyPad baseSet={baseSet} additionalKeys={keyset} onPress={this.keypadPress} />
+        </PadContainer>
+      </MathInputContainer>
+    );
+  }
+}
+
+export default MathInput;

package/src/mathlive-instance.js

@@ -0,0 +1,286 @@
+import debug from 'debug';
+import { NEWLINE_EMBED, toMathLive } from './latex-bridge';
+
+const log = debug('pie-lib:math-input-mathlive:instance');
+
+/**
+ * MathLive bootstrap + compatibility shims for @pie-lib/math-input's public API.
+ *
+ * MathLive is loaded lazily and only in the browser: the editor bundle is
+ * ~227KB gzip and registers custom elements, so it must never run during SSR.
+ */
+
+let mathlive;
+
+/**
+ * Where the KaTeX woff2 fonts are served from, as configured by the host app.
+ * `undefined` means "not configured"; `null` means "explicitly disabled".
+ */
+let fontsDirectory;
+
+/**
+ * Turn a fonts path into a fully-qualified URL.
+ *
+ * MathLive's default `fontsDirectory` is the relative `'./fonts/'`, which it
+ * resolves against its own script URL. Under a bundler (webpack/Next) that
+ * script URL is empty, so `new URL('./fonts/', '')` throws
+ * "Failed to construct 'URL': Invalid base URL" from `loadFonts`.
+ * Resolving against `document.baseURI` avoids that entirely and honours any
+ * <base href> / asset prefix the host app uses.
+ */
+const absoluteFontsDirectory = (dir) => {
+  if (!dir) {
+    return dir;
+  }
+
+  // Already absolute (http://, https://, //cdn...) - MathLive handles these.
+  if (/^(?:[a-z+]+:)?\/\//i.test(dir)) {
+    return dir;
+  }
+
+  try {
+    return new URL(dir, document.baseURI).href;
+  } catch (e) {
+    log('could not resolve fontsDirectory "%s": %s', dir, e && e.message);
+    return null;
+  }
+};
+
+/**
+ * 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.
+ *
+ * The fonts ship inside the `mathlive` package (`node_modules/mathlive/fonts`)
+ * and must be copied into whatever the host app serves statically.
+ *
+ * @param {string|null} dir
+ */
+export const configureFonts = (dir) => {
+  fontsDirectory = dir;
+
+  if (mathlive) {
+    mathlive.MathfieldElement.fontsDirectory = absoluteFontsDirectory(dir);
+  }
+};
+
+/**
+ * Custom macros for the pie-specific commands that the MathQuill fork
+ * understood but stock LaTeX does not.
+ *
+ * Kept deliberately in sync with the MathJax macros in
+ * @pie-lib/math-rendering (`render-math.js`) so the same latex renders the same
+ * way in the editor and in the static renderer.
+ */
+export const PIE_MACROS = {
+  parallelogram: '\\htmlData{pie-macro=parallelogram}{\\unicode{"25B1}}',
+  overarc: '\\overparen{#1}',
+  napprox: '\\not\\approx',
+  nsim: '\\not\\sim',
+  ncong: '\\not\\cong',
+  nparallel: '\\not\\parallel',
+  perpendicular: '\\perp',
+  divide: '\\div',
+  degree: '^{\\circ}',
+  square: '\\unicode{"25A1}',
+  longdiv: '\\htmlData{pie-macro=longdiv}{#1}',
+  abs: '\\left|#1\\right|',
+};
+
+/**
+ * Registry for `registerEmbed`.
+ *
+ * MathLive has no embed plugin system, so an embed is expressed as a macro that
+ * expands to real LaTeX. `\htmlData{embed=<name>}` tags the rendered output so
+ * consumers can target it with CSS exactly as they targeted the old
+ * `htmlString` markup.
+ *
+ * Known embeds map to native constructs:
+ *  - `newLine`    -> structural, handled by latex-bridge (`\displaylines` + `\\`)
+ *  - `answerBlock`-> `\placeholder{}` (interactive, read via the prompts API)
+ *
+ * @type {Map<string, {factory: Function, latex: string}>}
+ */
+const embeds = new Map();
+
+const KNOWN_EMBED_LATEX = {
+  // newLine is structural: it is translated by latex-bridge before it ever
+  // reaches MathLive, so the macro only needs to be harmless.
+  newLine: '',
+  answerBlock: '\\placeholder{}',
+};
+
+/**
+ * Load MathLive. Resolves to undefined during SSR.
+ * @returns {Promise<object|undefined>}
+ */
+export const loadMathLive = async () => {
+  if (typeof window === 'undefined') {
+    return undefined;
+  }
+
+  if (!mathlive) {
+    try {
+      mathlive = await import('mathlive');
+    } catch (e) {
+      // MathLive is browser-only and ships an ESM-conditional exports map, so
+      // the import can fail in test/SSR-ish runtimes. Fail soft: callers all
+      // handle a missing instance (static rendering falls back to raw latex).
+      log('MathLive could not be loaded: %s', e && e.message);
+      return undefined;
+    }
+
+    // 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.
+    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.',
+      );
+    }
+
+    mathlive.MathfieldElement.fontsDirectory =
+      fontsDirectory === undefined ? null : absoluteFontsDirectory(fontsDirectory);
+  }
+
+  return mathlive;
+};
+
+/**
+ * Synchronous accessor for an already-loaded MathLive.
+ * @returns {object|undefined}
+ */
+export const getMathLive = () => mathlive;
+
+/**
+ * The macro dictionary to hand to a mathfield: pie macros plus anything
+ * registered through `registerEmbed`.
+ *
+ * @returns {object}
+ */
+export const getMacros = () => {
+  const out = { ...PIE_MACROS };
+
+  embeds.forEach(({ latex }, name) => {
+    out[name] = `\\htmlData{embed=${name}}{${latex}}`;
+  });
+
+  return out;
+};
+
+/**
+ * Register an embed. API-compatible with @pie-lib/math-input's `registerEmbed`
+ * so existing callers do not change.
+ *
+ * MathQuill's factory returns `{ htmlString, text, latex }`. Only the
+ * declarative parts survive: `latex` round-trips through a macro and the
+ * styling hook becomes a `data-embed` attribute. Arbitrary DOM injection via
+ * `htmlString` has no MathLive equivalent and is ignored.
+ *
+ * @param {string} name
+ * @param {Function} factory
+ */
+export function registerEmbed(name, factory) {
+  if (!name || typeof factory !== 'function') {
+    return;
+  }
+
+  let definition = {};
+
+  try {
+    definition = factory() || {};
+  } catch (e) {
+    log('embed factory threw for "%s": %s', name, e.message);
+  }
+
+  const latex = Object.prototype.hasOwnProperty.call(KNOWN_EMBED_LATEX, name)
+    ? KNOWN_EMBED_LATEX[name]
+    : definition.mathliveLatex || '\\placeholder{}';
+
+  if (!Object.prototype.hasOwnProperty.call(KNOWN_EMBED_LATEX, name) && !definition.mathliveLatex) {
+    // Unknown third-party embed: degrade instead of throwing. `htmlString`
+    // cannot be reproduced, so it renders as an editable slot.
+    log(
+      'embed "%s" is not natively supported by MathLive; rendering as a placeholder. ' +
+        'Provide `mathliveLatex` in the factory result to control this.',
+      name,
+    );
+  }
+
+  embeds.set(name, { factory, latex });
+}
+
+/**
+ * Embeds registered so far. Exposed for tests/diagnostics.
+ * @returns {string[]}
+ */
+export const registeredEmbeds = () => Array.from(embeds.keys());
+
+/** Reset the embed registry. Test helper. */
+export const __resetEmbeds = () => embeds.clear();
+
+/** Inject a stub MathLive instance. Test helper. */
+export const __setMathLiveForTest = (stub) => {
+  mathlive = stub;
+};
+
+/**
+ * Render static math into an element. API-compatible with
+ * @pie-lib/math-input's `applyStaticMath`.
+ *
+ * @param {HTMLElement} element
+ * @param {string} [latex] assigned to the element before rendering
+ * @param {object} [options] `{ macros }` overrides
+ * @returns {HTMLElement|undefined} the element, for parity with the old return
+ */
+export function applyStaticMath(element, latex, options = {}) {
+  if (!element || typeof window === 'undefined') {
+    return undefined;
+  }
+
+  const ml = getMathLive();
+
+  if (!ml) {
+    log('applyStaticMath called before MathLive loaded - call loadMathLive() first');
+    return undefined;
+  }
+
+  const source = latex === undefined || latex === null ? element.textContent : latex;
+
+  element.innerHTML = ml.convertLatexToMarkup(toMathLive(source), {
+    macros: { ...getMacros(), ...(options.macros || {}) },
+  });
+
+  return element;
+}
+
+/**
+ * Convert latex to markup using the pie macro set. Used for keypad labels and
+ * any read-only rendering that does not need a live mathfield.
+ *
+ * @param {string} latex
+ * @param {object} [options]
+ * @returns {string} HTML markup, or '' if MathLive is not loaded
+ */
+export function latexToMarkup(latex, options = {}) {
+  const ml = getMathLive();
+
+  if (!ml || !latex) {
+    return '';
+  }
+
+  try {
+    return ml.convertLatexToMarkup(toMathLive(latex), {
+      macros: { ...getMacros(), ...(options.macros || {}) },
+      ...options,
+    });
+  } catch (e) {
+    log('convertLatexToMarkup failed for "%s": %s', latex, e.message);
+    return '';
+  }
+}
+
+export { NEWLINE_EMBED };

package/src/mf/common-styles.js

@@ -0,0 +1,108 @@
+/**
+ * Shared MathLive styling.
+ *
+ * Replaces @pie-lib/math-input's `common-mq-styles.js`. That file was built
+ * around MathQuill's `.mq-*` class names, none of which exist in MathLive
+ * output, so the selectors here target MathLive's own structure instead.
+ *
+ * The four named groups are kept because consumers destructure them:
+ *
+ *   const { commonMqFontStyles, commonMqKeyboardStyles, longdivStyles, supsubStyles }
+ *     = mq.CommonMqStyles;   // math-toolbar/src/editor-and-pad.jsx, math-preview.jsx
+ *
+ * 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.
+ */
+
+/**
+ * Font styling. MathQuill needed explicit MathJax font families to match the
+ * static renderer; MathLive ships the KaTeX fonts it renders with, so this only
+ * smooths rendering and lets the host override the family.
+ */
+export const commonMqFontStyles = {
+  '-webkit-font-smoothing': 'antialiased',
+  '& math-field': {
+    fontFamily: 'inherit',
+  },
+};
+
+/**
+ * Long division. The MathQuill fork drew this with nested `.mq-longdiv-*`
+ * elements that needed manual offsets; here it comes from the `\longdiv` macro
+ * (see `PIE_MACROS`), tagged with `data-pie-macro="longdiv"`.
+ */
+export const longdivStyles = {
+  '& [data-pie-macro="longdiv"]': {
+    display: 'inline-flex',
+  },
+};
+
+/**
+ * Superscript/subscript sizing. MathLive follows TeX metrics, so no overrides
+ * are required.
+ */
+export const supsubStyles = {};
+
+/** Empty placeholder boxes (answer blocks / open slots). */
+export const placeholderStyles = {
+  '& .ML__placeholder': {
+    borderBottom: '1px solid currentColor',
+    minWidth: '1em',
+  },
+};
+
+/**
+ * Styling for the on-screen keyboard and any container rendering math labels.
+ * Also hides MathLive's own affordances, since pie supplies its own keypad.
+ */
+export const commonMqKeyboardStyles = {
+  ...commonMqFontStyles,
+  ...longdivStyles,
+  ...placeholderStyles,
+  touchAction: 'manipulation',
+  '& math-field': {
+    fontSize: 'inherit',
+    outline: 'none',
+  },
+  '& math-field::part(virtual-keyboard-toggle)': {
+    display: 'none',
+  },
+  '& math-field::part(menu-toggle)': {
+    display: 'none',
+  },
+};
+
+/** Everything combined - the common case for a container of math. */
+export const commonMathLiveStyles = {
+  ...commonMqFontStyles,
+  ...longdivStyles,
+  ...supsubStyles,
+  ...placeholderStyles,
+  '& math-field': {
+    fontSize: 'inherit',
+    outline: 'none',
+  },
+  '& math-field::part(virtual-keyboard-toggle)': {
+    display: 'none',
+  },
+  '& math-field::part(menu-toggle)': {
+    display: 'none',
+  },
+};
+
+export const commonKeyboardStyles = commonMqKeyboardStyles;
+
+/**
+ * Default export mirrors @pie-lib/math-input's `CommonMqStyles` object so
+ * existing destructuring keeps working.
+ */
+export default {
+  commonMqFontStyles,
+  longdivStyles,
+  supsubStyles,
+  commonMqKeyboardStyles,
+  placeholderStyles,
+  commonMathLiveStyles,
+};