mathlive - npm Package Versions

0.57.0 2020-10-09

Major New Feature

This release introduce two major new features which will require code changes. For now, the older API remains supported but it will be dropped in an upcoming release.

#665: Web Component

Support for MathfieldElement custom element/web component and <math-field> tag.

The makeMathField() function is still supported, but it will be removed in an upcoming version. You should transition to using <math-field> or MathfieldElement instead.

This transition require the following changes:

1. Create mathfields using MathfieldElement or declaratively

// Before
let mf = MathLive.makeMathField(document.createElement('div'), {
  virtualKeyboardMode: 'manual',
});
mf.$latex('f(x) = \\sin x');
document.body.appendChild(mf.$el());

// After
let mfe = new MathfieldElement({
  virtualKeyboardMode: 'manual',
});
mfe.value = 'f(x) = \\sin x';
document.body.appendChild(mfe);

or:

<math-field virtual-keyboard-mode="manual">f(x) = \sin x</math-field>

1. Use events instead of callbacks

    // Before
    mf.setConfig({ onContentDidChange: (mf) => {
        console.log(mf.$latex())
    });

    // After
    mfe.addEventListener('input', (ev) => {
        console.log(mfe.value);
    });

#667 Modernized Public API

Support for web component is an opportunity to revisit the MathLive public API and modernize it.

The goals are:

• clarity. For example, the $latex() can be used to read or change the content of the mathfield.
• expressiveness. For example, $selectedText() can return the value of the selection, but there is no way to inspect (or save/restore) the selection.
• consistency with web platform APIs when applicable, otherwise following the monaco (VSCode editor) or CodeMirror conventions primarily. As part of this proposal, the APIs of TinyMCE, CKEditor and QuillJS were also considered. For example, the method equivalent to getConfig() is called getOptions() in most Javascript text editor libraries.

Mathfield methods

The following Mathfield methods have been renamed as indicated:

| Before | After | | :--------------------------- | :------------------------------------- | | $setConfig() | setOptions() | | getConfig() | getOptions() and getOption() | | $text() | getValue() | | $latex() | value, getValue() and setValue() | | $insert() | insert() | | $hasFocus() | hasFocus() | | $focus() | focus() | | $blur() | blur() | | $selectedText() | mf.getValue(mf.selection) | | $selectionIsCollapsed() | mf.selection[0].collapsed | | $selectionDepth() | mf.selection[0].depth | | $selectionAtStart() | mf.position === 0 | | $selectionAtEnd() | mf.position === mf.lastPosition | | $select() | select() | | $clearSelection() | executeCommand('delete-backward') | | $keystroke() | executeCommand() | | $typedText() | executeCommand('typed-text') | | $perform() | executeCommand() | | $revertToOriginalContent() | n/a | | $el() | n/a | | n/a | selection | | n/a | position |

The methods indicated with "n/a" in the After column have been dropped.

Only the new methods are available on MathfieldElement (i.e. when using web components). The Mathfield class retains both the old methods and the new ones to facilitate the transition, but the old ones will be dropped in an upcoming version.

There is also a new selection property on Mathfield and MathfieldElement which can be used to inspect and change the selection and a position property to inspect and change the insertion point (caret).

The getValue() method also now take an (optional) Range, which is the type of the selection property, to extract a fragment of the expression.

Default Exports

While default exports have the benefits of expediency, particularly when converting an existing code base to ES Modules, they are problematic for effective tree shaking. Therefore the default export will be eliminated.

This means that instead of:

import MathLive from 'mathlive';
MathLive.renderMathInDocument();

you will need to use:

import { renderMathInDocument } from 'mathlive';
renderMathInDocument();

The following functions have been renamed:

| Before | After | | :-------------------------------- | :------------------------------ | | MathLive.latexToAST() | Use MathJSON | | MathLive.latexToMarkup() | convertLatexToMarkup() | | MathLive.latexToMathML() | convertLatexToMathMl() | | MathLive.latexToSpeakableText() | convertLatexToSpeakableText() |

New Features

• #101: added getCaretPosition() and setCaretPosition()

Improvements

• The Typescript types for Selector has been improved
• The Typescript type for getOptions() (getConfig()) are more accurate
• The "sqrt" inline shortcut now inserts an argument
• Don't throw an error if the first argument of \enclose is empty
• #591: add upward and downward hooks when navigating out of the mathfield (now also sent as a focus-out event)
• Improved layout of the virtual keyboard on narrow mobile devices (fill the available width).

Issues Resolved

• #198: typing backspace while typing inline shortcuts would prevent the shortcuts from being recognized
• #573: brackets were not properly styled (i.e. color applied to them)
• #543: spurious focus/blur events were dispatched if tabIndex was set to 0 on the mathfield and some area of the mathfield were clicked on. The issue was that with tabIndex="0" the mathfield frame would be focusable and when that happened the focus would correctly switch to the invisible <textarea> element which is normally focused to receive keyboard events, but this generated an incorrect blur event (for the container losing focus) and an incorrect focus event (for the <textarea> gaining focus)
• #599: some characters, for example "ü", would not be correctly parsed or displayed. Note that technically, those characters are ignored by TeX, but it's a reasonable behavior nowadays to accept them as input.
• #628: typing "e" repeatedly inside a matrix would corrupt the emitted
• #637: in Chrome, thin lines, such as fraction bars or square root lines would not display at some zoom levels
• The locale was not properly taking into account when it was set manually
• The config.strings property did not reflect the state of the localization strings
• When configs was updated (e.g. new macros added), the content of the mathfield was not properly re-parsed and rendered
• When making the virtual keyboard visible, the mathfield would not be focused
• The virtual keyboard would not display correctly when the mathfield was inside a shadow DOM

Special Thanks

• Thanks to @stefnotch for contributing several of the improvements in this release

0.56.0 2020-08-22

New Features

• Added support for \phantom, \vphantom, \hphantom and \smash[]
• #182 Added support for the mhchem package, with the commands \ce and \pu, to display chemical equations

0.55.0 2020-08-17

New Features

• WebPack issues workaround and font loading configuration

  Follow up to #508. The fonts can now be loaded either statically or dynamically.

  • dynamic loading by default, the fonts will get loaded programmatically when they are needed and the rendering will be deferred until the fonts are available to avoid unnecessary redrawing. Use this technique if you have a simple build/bundle workflow. You can still customize the relative path to the fonts folder using the fontsDirectory configuration option.

  • static loading include the mathlive-fonts.css stylesheet in your page. The loading of this file will trigget the font to be loaded asynchronously by the browser. Use this technique if you are using WebPack or have a build/bundle workflow that renames the font files or in general require the bundler to know about the required assets.

• New packaging options. The distribution files have been split between minified and non-minified version. In the more common cases, the minified version (mathlive.min.js and mathlive.min.mjs should be used). The non-minified version (mathlive.js and mathlive.mjs can be used to help in debugging issues or to apply patches).

Issues Resolved

• The fonts failed to load when loading MathLive using a <script> tag and a CDN. The fonts folder is now resolved correctly with the following configurations:

  - `<script>` tag and CDN
  - `<script>` tag and local file
  - `import` and CDN
  - `import` and local file
  

0.54.0 2020-06-24

Issues Resolved

• #490 Firefox does not load fonts There is a bug in Firefox (https://bugzilla.mozilla.org/show_bug.cgi?id=1252821) where the status of fonts is reported incorrectly.

  Implemented a workaround by always loading fonts in Firefox.

• #506 Chrome was outputing a harmless warning about passive event listeners. The warning has been silenced.

• #505 Chrome was outputing a harmless warning about passive event listeners. The warning has been silenced with extreme prejudice.

• #503 Dynamic styles were not applied inside of shadow DOM

0.53.3 2020-06-24

Issues Resolved

• #504 "Spacing is inconsistent after editing"

  The spacing of operators should be adjusted depending on what's around them: there is less space after a "-" sign when used as an infix operator than there is around a "-" sign used as a prefix operator (i.e. "-4" vs "3-4").

  The code that was handling this was accounting for it by modifying the type of the element. This worked well enough for static rendering, but for dynamic rendering (i.e. editing), once modified the previous type of the element was lost and could not be restored (i.e. after deleting the atom in front of a "-" sign, the "-" was no longer a binary operator but a regular symbol).

  This is now handled during layout without modifying the type of the element.

• Workaround for a Safari bug where in some cases the caret would not blink.

• #505 More consistent spacing between elements. Previously some Unicode math spacing characters were used. However, these characters are not rendered consistently. Switched to using CSS margins instead.

• The LaTeX generated for a \left command with another command as a fence was lacking a space, e.g. \left\lbracka\right\rbrack instead of \left\lbrack a\right\rbrack

• Smart fence for square brackets was not working correctly.

• Fixed smartmode to avoid converting a decimal point to text when entering, e.g. "314.1576"

• The alt/option+V shortcut now correctly inserts a placeholder in the square root

• The "\arcos" function was incorrectly spelled "\arccos".

New Feature

• #508 In order to better support some deployment configurations, added a 'mathlive-fonts.css' file to the distribution package.

  This is intended to be used by build/bundle environments that have an asset pipeline that can move/rename assets, including the font-files

  Note that this method is not recommended. It will result in some cases where the layout is incorrect until the page is reloaded (especially for formulas using large symbols such as integrals or large parentheses).

  To use it, add the following to the web pages using MathLive:

<link rel="stylesheet" href="dist/mathlive-fonts.css" />

0.53.2 2020-06-10

Issues Resolved

• Adjusted height of square root (there was some extra blank space above)
• Ensure that the 'dt' inline shortcut does not trigger when writing "width" (it should only apply in the math mode)
• #492 Typing "/" to insert as fraction when some items were selected would result in an erroneous output.

0.53.1 2020-06-01

Issues Resolved

• In the virtual keyboard, use \scriptstyle to display small symbols
• Better vertical alignment of extensible arrows
• Don't display a double caret after a \leftright

0.53.0 2020-05-31

Breaking Change / New Feature

• #158 The CSS files mathlive.css and mathlive.core.css have been deprecated and removed from the distribution.

  The necessary CSS is now injected dynamically into the page. This simplifies the use of the library, but also reduces the amount of CSS in the page, potentially improving performance. That's particularly the case when the virtual keyboard is not used, as the CSS stylesheet for the virtual keyboard is substantial, and it is now injected only when the keyboard is used.

  To transition, you should remove from your code any instance of:

  <link rel="stylesheet" href="mathlive.core.css" type="text/css" />
  <link rel="stylesheet" href="mathlive.css" type="text/css" />
  

  (the path to your CSS file may be different).

  You may need to specify the location of the 'fonts' directory. By default, the 'fonts' directory is expected to be next to the 'mathlive.js', 'mathlive.mjs' file. If you need to copy the 'fonts' directory to a different location, specify it using the Config.fontsDirectory option. It should be either a relative path or a full URL pointing to the directory that contains the fonts. (Fix for #425)

  You no longer need to manually specify the stylesheets when using renderMathInElement() or renderMathInDocument() either. The necessary stylesheet will get injected in the document as needed. Note that this stylesheet for these functions is smaller than the stylesheet used when the editor is in use. These two functions also gain a property to specify the location of the 'fonts' directory, if necessary (by default, the 'fonts' directory is expected to be next to the 'mathlive.js', 'mathlive.mjs' file.)

  In some rare cases, you may have used the CSS stylesheet without the MathLive library, for example, after you may have saved the output of latexToMarkup() to a database and use it to render later in a page. In that case, you would need to use the CSS stylesheet dist/mathlive-static.css, which is suitable for this use case. Note that it does reference a 'fonts' folder that may need to be adjusted. By default, the fonts folder should be placed next to the stylesheet. If you need a different location when using the static stylesheet, you will need to modify it.

• #425 Added CSS variable --ML_keyboard-zindex to control the zindex of the virtual keyboard.

• Add support for ^^ and ^^^^ constructs in LaTeX. See TexBook p. 56:

  There’s also a special convention in which ^^ is followed by two
  “lowercase hexadecimal digits,” 0–9 or a–f. With this convention, all 256 characters are
  obtainable in a uniform way, from ^^00 to ^^ff. Character 127 is ^^7f.
  

  XeTeX extends this convention with ^^^^ for four-digit Unicode characters.

• Added support for more TeX primitives, including \string, \csname, \endcsname, \obeyspaces

• Improved the handling of parameters (e.g. #1) to more accurately match the TeX behavior (previously parameters could only substitute for an entire argument, i.e. {#1}). They are now handled by replacing their value with their corresponding tokens.

• Added support for \laplace and \Laplace symbols

Issues Resolved

• #469 The keyboard layout on Linux was not detected correctly, resulting in some keys (such as arrows and backspace) not working correctly.

• Integers in a LaTeX stream would not always be parsed correctly. As per the TeXBook, an integer can be preceded by an arbitrary number of "+", "-" or whitespace characters, so \char -+ +- "4A is valid and equivalent to \char"4A

• Integers in a latex stream specified with a backtick ("alphabetic constant") would not be parsed correctly. Now \char`A gives the expected result (A).

• Consecutive whitespace where not always coalesced.

• The bounding box of the initial selection (before the 'first' atom was inserted) was incorrect.

• The sizing commands (\huge, \small, \tiny, etc...) should not apply in 'math' mode.