@ziloen/micromark-extension-math 3.1.0-patch.0

package/dev/lib/math-text.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @param {Options | null | undefined} [options={}]
+ *   Configuration (default: `{}`).
+ * @returns {Construct}
+ *   Construct.
+ */
+export function mathText(options?: Options | null | undefined): Construct;
+import type { Options } from '@ziloen/micromark-extension-math';
+import type { Construct } from 'micromark-util-types';

package/dev/lib/math-text.js

@@ -0,0 +1,408 @@
+/**
+ * @import {Options} from '@ziloen/micromark-extension-math'
+ * @import {Construct, Previous, Resolver, State, Token, TokenizeContext, Tokenizer} from 'micromark-util-types'
+ */
+
+// To do: next major: clean spaces in HTML compiler.
+// This has to be coordinated together with `mdast-util-math`.
+
+import {ok as assert} from 'devlop'
+import {
+  asciiDigit,
+  markdownLineEnding,
+  markdownSpace
+} from 'micromark-util-character'
+import {codes, types} from 'micromark-util-symbol'
+
+/**
+ * @param {Options | null | undefined} [options={}]
+ *   Configuration (default: `{}`).
+ * @returns {Construct}
+ *   Construct.
+ */
+export function mathText(options) {
+  const options_ = options || {}
+  let single = options_.singleDollarTextMath
+
+  if (single === null || single === undefined) {
+    single = true
+  }
+
+  return {
+    tokenize: tokenizeMathText,
+    resolve: resolveMathText,
+    previous: previousCode,
+    name: 'mathText'
+  }
+
+  /**
+   * @this {TokenizeContext}
+   * @type {Tokenizer}
+   */
+  function tokenizeMathText(effects, ok, nok) {
+    const self = this
+    /** @type {number} */
+    let codeOpen = codes.dollarSign
+    /** @type {number} */
+    let codeClose = codes.dollarSign
+    /** @type {'mathText' | 'mathTextDisplay'} */
+    let type = 'mathText'
+    let sizeOpen = 0
+    /** @type {number} */
+    let size
+    /** @type {number | null | undefined} */
+    let previous
+    /** @type {Token} */
+    let tokenType
+    /** @type {Token} */
+    let token
+    let dataSeen = false
+
+    return start
+
+    /**
+     * Start of math (text).
+     *
+     * ```markdown
+     * > | $a$
+     *     ^
+     * > | \$a$
+     *      ^
+     * ```
+     *
+     * @type {State}
+     */
+    function start(code) {
+      assert(
+        code === codes.dollarSign || code === codes.backslash,
+        'expected `$` or `\\`'
+      )
+      assert(
+        code === codes.backslash || previousCode.call(self, self.previous),
+        'expected correct previous'
+      )
+
+      if (code === codes.backslash) {
+        codeOpen = codes.leftParenthesis
+        codeClose = codes.rightParenthesis
+      }
+
+      tokenType = effects.enter(type)
+      effects.enter('mathTextSequence')
+      effects.consume(code)
+      sizeOpen++
+      return code === codes.backslash ? sequenceOpenBackslash : sequenceOpen
+    }
+
+    /**
+     * In opening sequence.
+     *
+     * ```markdown
+     * > | $a$
+     *     ^
+     * ```
+     *
+     * @type {State}
+     */
+
+    function sequenceOpen(code) {
+      if (code === codes.dollarSign) {
+        effects.consume(code)
+        sizeOpen++
+        return sequenceOpen
+      }
+
+      // Not enough markers in the sequence.
+      if (
+        (sizeOpen < 2 && !single) ||
+        (sizeOpen === 1 && !validSingleDollarOpen(code))
+      ) {
+        return nok(code)
+      }
+
+      effects.exit('mathTextSequence')
+      return between(code)
+    }
+
+    /**
+     * After the backslash in an opening sequence.
+     *
+     * ```markdown
+     * > | \(a\)
+     *      ^
+     * > | \[a\]
+     *      ^
+     * ```
+     *
+     * @type {State}
+     */
+    function sequenceOpenBackslash(code) {
+      if (code !== codes.leftParenthesis && code !== codes.leftSquareBracket) {
+        return nok(code)
+      }
+
+      codeOpen = code
+      codeClose =
+        code === codes.leftParenthesis
+          ? codes.rightParenthesis
+          : codes.rightSquareBracket
+      type = code === codes.leftParenthesis ? 'mathText' : 'mathTextDisplay'
+
+      tokenType.type = type
+      effects.consume(code)
+      effects.exit('mathTextSequence')
+      return between
+    }
+
+    /**
+     * Between something and something else.
+     *
+     * ```markdown
+     * > | $a$
+     *      ^^
+     * ```
+     *
+     * @type {State}
+     */
+    function between(code) {
+      if (code === codes.eof) {
+        return nok(code)
+      }
+
+      if (code === codes.dollarSign && codeOpen === codes.dollarSign) {
+        token = effects.enter('mathTextSequence')
+        size = 0
+        return sequenceClose(code)
+      }
+
+      if (code === codes.backslash && codeOpen !== codes.dollarSign) {
+        token = effects.enter('mathTextSequence')
+        return sequenceCloseBackslash(code)
+      }
+
+      // Tabs don’t work, and virtual spaces don’t make sense.
+      if (code === codes.space) {
+        effects.enter('space')
+        effects.consume(code)
+        effects.exit('space')
+        previous = code
+        return between
+      }
+
+      if (markdownLineEnding(code)) {
+        effects.enter(types.lineEnding)
+        effects.consume(code)
+        effects.exit(types.lineEnding)
+        previous = code
+        return between
+      }
+
+      // Data.
+      effects.enter('mathTextData')
+      return data(code)
+    }
+
+    /**
+     * In data.
+     *
+     * ```markdown
+     * > | $a$
+     *      ^
+     * ```
+     *
+     * @type {State}
+     */
+    function data(code) {
+      if (
+        code === codes.eof ||
+        code === codes.space ||
+        (code === codes.dollarSign && codeOpen === codes.dollarSign) ||
+        (code === codes.backslash && codeOpen !== codes.dollarSign) ||
+        markdownLineEnding(code)
+      ) {
+        effects.exit('mathTextData')
+        return between(code)
+      }
+
+      effects.consume(code)
+      previous = code
+      dataSeen = true
+      return data
+    }
+
+    /**
+     * In closing sequence.
+     *
+     * ```markdown
+     * > | `a`
+     *       ^
+     * ```
+     *
+     * @type {State}
+     */
+
+    function sequenceClose(code) {
+      // More.
+      if (code === codes.dollarSign) {
+        effects.consume(code)
+        size++
+        return sequenceClose
+      }
+
+      // Done!
+      if (
+        size === sizeOpen &&
+        (sizeOpen !== 1 || validSingleDollarClose(previous, code))
+      ) {
+        effects.exit('mathTextSequence')
+        effects.exit(type)
+        return ok(code)
+      }
+
+      // More or less accents: mark as data.
+      token.type = 'mathTextData'
+      return data(code)
+    }
+
+    /**
+     * In a closing backslash sequence.
+     *
+     * ```markdown
+     * > | \(a\)
+     *        ^
+     * ```
+     *
+     * @type {State}
+     */
+    function sequenceCloseBackslash(code) {
+      assert(code === codes.backslash, 'expected `\\`')
+      effects.consume(code)
+      return sequenceCloseBackslashEnd
+    }
+
+    /**
+     * After the backslash in a closing sequence.
+     *
+     * @type {State}
+     */
+    function sequenceCloseBackslashEnd(code) {
+      if (code === codeClose) {
+        if (!dataSeen) {
+          return nok(code)
+        }
+
+        effects.consume(code)
+        effects.exit('mathTextSequence')
+        effects.exit(type)
+        return ok
+      }
+
+      token.type = 'mathTextData'
+      previous = codes.backslash
+      return data(code)
+    }
+  }
+}
+
+/** @type {Resolver} */
+function resolveMathText(events) {
+  let tailExitIndex = events.length - 4
+  let headEnterIndex = 3
+  /** @type {number} */
+  let index
+  /** @type {number | undefined} */
+  let enter
+
+  // If we start and end with an EOL or a space.
+  if (
+    (events[headEnterIndex][1].type === types.lineEnding ||
+      events[headEnterIndex][1].type === 'space') &&
+    (events[tailExitIndex][1].type === types.lineEnding ||
+      events[tailExitIndex][1].type === 'space')
+  ) {
+    index = headEnterIndex
+
+    // And we have data.
+    while (++index < tailExitIndex) {
+      if (events[index][1].type === 'mathTextData') {
+        // Then we have padding.
+        events[tailExitIndex][1].type = 'mathTextPadding'
+        events[headEnterIndex][1].type = 'mathTextPadding'
+        headEnterIndex += 2
+        tailExitIndex -= 2
+        break
+      }
+    }
+  }
+
+  // Merge adjacent spaces and data.
+  index = headEnterIndex - 1
+  tailExitIndex++
+
+  while (++index <= tailExitIndex) {
+    if (enter === undefined) {
+      if (
+        index !== tailExitIndex &&
+        events[index][1].type !== types.lineEnding
+      ) {
+        enter = index
+      }
+    } else if (
+      index === tailExitIndex ||
+      events[index][1].type === types.lineEnding
+    ) {
+      events[enter][1].type = 'mathTextData'
+
+      if (index !== enter + 2) {
+        events[enter][1].end = events[index - 1][1].end
+        events.splice(enter + 2, index - enter - 2)
+        tailExitIndex -= index - enter - 2
+        index = enter + 2
+      }
+
+      enter = undefined
+    }
+  }
+
+  return events
+}
+
+/**
+ * @this {TokenizeContext}
+ * @type {Previous}
+ */
+function previousCode(code) {
+  // If there is a previous code, there will always be a tail.
+  return (
+    code !== codes.dollarSign ||
+    this.events[this.events.length - 1][1].type === types.characterEscape
+  )
+}
+
+/**
+ * @param {number | null} code
+ *   Code.
+ * @returns {boolean}
+ *   Whether `code` can follow an opening single dollar.
+ */
+function validSingleDollarOpen(code) {
+  return code !== codes.eof && !markdownLineEnding(code) && !markdownSpace(code)
+}
+
+/**
+ * @param {number | null | undefined} before
+ *   Code before the closing dollar.
+ * @param {number | null} after
+ *   Code after the closing dollar.
+ * @returns {boolean}
+ *   Whether a single dollar can close.
+ */
+function validSingleDollarClose(before, after) {
+  return (
+    before !== undefined &&
+    before !== codes.eof &&
+    !markdownLineEnding(before) &&
+    !markdownSpace(before) &&
+    !asciiDigit(after)
+  )
+}

package/dev/lib/syntax.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Create an extension for `micromark` to enable math syntax.
+ *
+ * @param {Options | null | undefined} [options={}]
+ *   Configuration (default: `{}`).
+ * @returns {Extension}
+ *   Extension for `micromark` that can be passed in `extensions`, to
+ *   enable math syntax.
+ */
+export function math(options?: Options | null | undefined): Extension;
+import type { Options } from '@ziloen/micromark-extension-math';
+import type { Extension } from 'micromark-util-types';

package/dev/lib/syntax.js

@@ -0,0 +1,26 @@
+/**
+ * @import {Options} from '@ziloen/micromark-extension-math'
+ * @import {Extension} from 'micromark-util-types'
+ */
+
+import {codes} from 'micromark-util-symbol'
+import {mathFlow} from './math-flow.js'
+import {mathText} from './math-text.js'
+
+/**
+ * Create an extension for `micromark` to enable math syntax.
+ *
+ * @param {Options | null | undefined} [options={}]
+ *   Configuration (default: `{}`).
+ * @returns {Extension}
+ *   Extension for `micromark` that can be passed in `extensions`, to
+ *   enable math syntax.
+ */
+export function math(options) {
+  const text = mathText(options)
+
+  return {
+    flow: {[codes.dollarSign]: mathFlow, [codes.backslash]: mathFlow},
+    text: {[codes.dollarSign]: text, [codes.backslash]: text}
+  }
+}

package/index.d.ts

@@ -0,0 +1,62 @@
+import type {KatexOptions} from 'katex'
+
+export {mathHtml} from './lib/html.js'
+export {math} from './lib/syntax.js'
+
+/**
+ * Configuration for HTML output.
+ *
+ * > 👉 **Note**: passed to `katex.renderToString`.
+ * > `displayMode` is overwritten by this plugin, to `false` for math in
+ * > text (inline), and `true` for math in flow (block).
+ */
+export interface HtmlOptions extends KatexOptions {
+  /**
+   * The field `displayMode` cannot be passed to `micromark-extension-math`.
+   * It is overwritten by it,
+   * to `false` for math in text (inline) and `true` for math in flow (block).
+   */
+  displayMode?: never
+}
+
+/**
+ * Configuration.
+ */
+export interface Options {
+  /**
+   * Whether to support math (text) with a single dollar (default: `true`).
+   *
+   * Single dollars work in Pandoc and many other places, but often interfere
+   * with “normal” dollars in text.
+   * If you turn this off, you can use two or more dollars for text math.
+   */
+  singleDollarTextMath?: boolean | null | undefined
+}
+
+/**
+ * Augment types.
+ */
+declare module 'micromark-util-types' {
+  /**
+   * Compile data.
+   */
+  interface CompileData {
+    mathFlowOpen?: boolean
+  }
+
+  /**
+   * Token types.
+   */
+  interface TokenTypeMap {
+    mathFlow: 'mathFlow'
+    mathFlowFence: 'mathFlowFence'
+    mathFlowFenceMeta: 'mathFlowFenceMeta'
+    mathFlowFenceSequence: 'mathFlowFenceSequence'
+    mathFlowValue: 'mathFlowValue'
+    mathText: 'mathText'
+    mathTextData: 'mathTextData'
+    mathTextDisplay: 'mathTextDisplay'
+    mathTextPadding: 'mathTextPadding'
+    mathTextSequence: 'mathTextSequence'
+  }
+}

package/index.js

@@ -0,0 +1,3 @@
+// Note: types exported from `index.d.ts`.
+export { math } from './lib/syntax.js';
+export { mathHtml } from './lib/html.js';

package/lib/html.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Create an extension for `micromark` to support math when serializing to
+ * HTML.
+ *
+ * > 👉 **Note**: this uses KaTeX to render math.
+ *
+ * @param {Options | null | undefined} [options={}]
+ *   Configuration (default: `{}`).
+ * @returns {HtmlExtension}
+ *   Extension for `micromark` that can be passed in `htmlExtensions`, to
+ *   support math when serializing to HTML.
+ */
+export function mathHtml(options?: Options | null | undefined): HtmlExtension;
+import type { HtmlOptions as Options } from '@ziloen/micromark-extension-math';
+import type { HtmlExtension } from 'micromark-util-types';

package/lib/html.js

@@ -0,0 +1,93 @@
+/**
+ * @import {HtmlOptions as Options} from '@ziloen/micromark-extension-math'
+ * @import {HtmlExtension} from 'micromark-util-types'
+ */
+
+import katex from 'katex';
+const renderToString = katex.renderToString;
+
+/**
+ * Create an extension for `micromark` to support math when serializing to
+ * HTML.
+ *
+ * > 👉 **Note**: this uses KaTeX to render math.
+ *
+ * @param {Options | null | undefined} [options={}]
+ *   Configuration (default: `{}`).
+ * @returns {HtmlExtension}
+ *   Extension for `micromark` that can be passed in `htmlExtensions`, to
+ *   support math when serializing to HTML.
+ */
+export function mathHtml(options) {
+  return {
+    enter: {
+      mathFlow() {
+        this.lineEndingIfNeeded();
+        this.tag('<div class="math math-display">');
+      },
+      mathFlowFenceMeta() {
+        this.buffer();
+      },
+      mathText() {
+        // Double?
+        this.tag('<span class="math math-inline">');
+        this.buffer();
+      },
+      mathTextDisplay() {
+        this.tag('<div class="math math-display">');
+        this.buffer();
+      }
+    },
+    exit: {
+      mathFlow() {
+        const value = this.resume();
+        this.tag(math(value.replace(/(?:\r?\n|\r)$/, ''), true));
+        this.tag('</div>');
+        this.setData('mathFlowOpen');
+        this.setData('slurpOneLineEnding');
+      },
+      mathFlowFence() {
+        // After the first fence.
+        if (!this.getData('mathFlowOpen')) {
+          this.setData('mathFlowOpen', true);
+          this.setData('slurpOneLineEnding', true);
+          this.buffer();
+        }
+      },
+      mathFlowFenceMeta() {
+        this.resume();
+      },
+      mathFlowValue(token) {
+        this.raw(this.sliceSerialize(token));
+      },
+      mathText() {
+        const value = this.resume();
+        this.tag(math(value, false));
+        this.tag('</span>');
+      },
+      mathTextDisplay() {
+        const value = this.resume();
+        this.tag(math(value, true));
+        this.tag('</div>');
+      },
+      mathTextData(token) {
+        this.raw(this.sliceSerialize(token));
+      }
+    }
+  };
+
+  /**
+   * @param {string} value
+   *   Math text.
+   * @param {boolean} displayMode
+   *   Whether the math is in display mode.
+   * @returns {string}
+   *   HTML.
+   */
+  function math(value, displayMode) {
+    return renderToString(value, {
+      ...options,
+      displayMode
+    });
+  }
+}

package/lib/math-flow.d.ts

@@ -0,0 +1,3 @@
+/** @type {Construct} */
+export const mathFlow: Construct;
+import type { Construct } from 'micromark-util-types';