@tiptap/extension-mathematics 3.0.0-beta.16 → 3.0.0-beta.18

package/src/extensions/BlockMath.ts

@@ -0,0 +1,251 @@
+import { InputRule, mergeAttributes, Node } from '@tiptap/core'
+import type { Node as PMNode } from '@tiptap/pm/model'
+import katex, { type KatexOptions } from 'katex'
+
+/**
+ * Configuration options for the BlockMath extension.
+ */
+export type BlockMathOptions = {
+  /**
+   * KaTeX specific options
+   * @see https://katex.org/docs/options.html
+   * @example
+   * ```ts
+   * katexOptions: {
+   *   displayMode: true,
+   *   throwOnError: false,
+   * },
+   */
+  katexOptions?: KatexOptions
+
+  /**
+   * Optional click handler for block math nodes.
+   * Called when a user clicks on a block math expression in the editor.
+   *
+   * @param node - The ProseMirror node representing the block math element
+   * @param pos - The position of the node within the document
+   * @example
+   * ```ts
+   * onClick: (node, pos) => {
+   *   console.log('Block math clicked:', node.attrs.latex, 'at position:', pos)
+   * },
+   * ```
+   */
+  onClick?: (node: PMNode, pos: number) => void
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    insertBlockMath: {
+      /**
+       * Inserts a math block node with LaTeX string.
+       * @param options - Options for inserting block math.
+       * @returns ReturnType
+       */
+      insertBlockMath: (options: { latex: string; pos?: number }) => ReturnType
+
+      /**
+       * Deletes a block math node.
+       * @returns ReturnType
+       */
+      deleteBlockMath: (options?: { pos?: number }) => ReturnType
+
+      /**
+       * Update block math node with optional LaTeX string.
+       * @param options - Options for updating block math.
+       * @returns ReturnType
+       */
+      updateBlockMath: (options?: { latex: string; pos?: number }) => ReturnType
+    }
+  }
+}
+
+/**
+ * BlockMath is a Tiptap extension for rendering block mathematical expressions using KaTeX.
+ * It allows users to insert LaTeX formatted math expressions block within text.
+ * It supports rendering, input rules for LaTeX syntax, and click handling for interaction.
+ *
+ * @example
+ * ```javascript
+ * import { BlockMath } from '@tiptap/extension-mathematics'
+ * import { Editor } from '@tiptap/core'
+ *
+ * const editor = new Editor({
+ *   extensions: [
+ *     BlockMath.configure({
+ *       onClick: (node, pos) => {
+ *         console.log('Block math clicked:', node.attrs.latex, 'at position:', pos)
+ *       },
+ *     }),
+ *   ],
+ * })
+ */
+export const BlockMath = Node.create<BlockMathOptions>({
+  name: 'blockMath',
+
+  group: 'block',
+
+  atom: true,
+
+  addOptions() {
+    return {
+      onClick: undefined,
+      katexOptions: undefined,
+    }
+  },
+
+  addAttributes() {
+    return {
+      latex: {
+        default: '',
+        parseHTML: element => element.getAttribute('data-latex'),
+        renderHTML: attributes => {
+          return {
+            'data-latex': attributes.latex,
+          }
+        },
+      },
+    }
+  },
+
+  addCommands() {
+    return {
+      insertBlockMath:
+        options =>
+        ({ commands, editor }) => {
+          const { latex, pos } = options
+
+          if (!latex) {
+            return false
+          }
+
+          return commands.insertContentAt(pos ?? editor.state.selection.from, {
+            type: this.name,
+            attrs: { latex },
+          })
+        },
+
+      deleteBlockMath:
+        options =>
+        ({ editor, tr }) => {
+          const pos = options?.pos ?? editor.state.selection.$from.pos
+          const node = editor.state.doc.nodeAt(pos)
+
+          if (!node || node.type.name !== this.name) {
+            return false
+          }
+
+          tr.delete(pos, pos + node.nodeSize)
+          return true
+        },
+
+      updateBlockMath:
+        options =>
+        ({ editor, tr }) => {
+          const latex = options?.latex
+          let pos = options?.pos
+
+          if (pos === undefined) {
+            pos = editor.state.selection.$from.pos
+          }
+
+          const node = editor.state.doc.nodeAt(pos)
+
+          if (!node || node.type.name !== this.name) {
+            return false
+          }
+
+          tr.setNodeMarkup(pos, this.type, {
+            ...node.attrs,
+            latex: latex || node.attrs.latex,
+          })
+
+          return true
+        },
+    }
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: 'div[data-type="block-math"]',
+      },
+    ]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['div', mergeAttributes(HTMLAttributes, { 'data-type': 'block-math' })]
+  },
+
+  addInputRules() {
+    return [
+      new InputRule({
+        find: /^\$\$\$([^$]+)\$\$\$$/,
+        handler: ({ state, range, match }) => {
+          const [, latex] = match
+          const { tr } = state
+          const start = range.from
+          const end = range.to
+
+          tr.replaceWith(start, end, this.type.create({ latex }))
+        },
+      }),
+    ]
+  },
+
+  addNodeView() {
+    const { katexOptions } = this.options
+
+    return ({ node, getPos }) => {
+      const wrapper = document.createElement('div')
+      const innerWrapper = document.createElement('div')
+      wrapper.className = 'tiptap-mathematics-render'
+
+      if (this.editor.isEditable) {
+        wrapper.classList.add('tiptap-mathematics-render--editable')
+      }
+
+      innerWrapper.className = 'block-math-inner'
+      wrapper.dataset.type = 'block-math'
+      wrapper.setAttribute('data-latex', node.attrs.latex)
+      wrapper.appendChild(innerWrapper)
+
+      function renderMath() {
+        try {
+          katex.render(node.attrs.latex, innerWrapper, katexOptions)
+          wrapper.classList.remove('block-math-error')
+        } catch {
+          wrapper.textContent = node.attrs.latex
+          wrapper.classList.add('block-math-error')
+        }
+      }
+
+      const handleClick = (event: MouseEvent) => {
+        event.preventDefault()
+        event.stopPropagation()
+        const pos = getPos()
+
+        if (pos == null) {
+          return
+        }
+
+        if (this.options.onClick) {
+          this.options.onClick(node, pos)
+        }
+      }
+
+      if (this.options.onClick) {
+        wrapper.addEventListener('click', handleClick)
+      }
+
+      renderMath()
+
+      return {
+        dom: wrapper,
+        destroy() {
+          wrapper.removeEventListener('click', handleClick)
+        },
+      }
+    }
+  },
+})

package/src/extensions/InlineMath.ts

@@ -0,0 +1,252 @@
+import { InputRule, mergeAttributes, Node } from '@tiptap/core'
+import type { Node as PMNode } from '@tiptap/pm/model'
+import katex, { type KatexOptions } from 'katex'
+
+/**
+ * Configuration options for the InlineMath extension.
+ */
+export type InlineMathOptions = {
+  /**
+   * KaTeX specific options
+   * @see https://katex.org/docs/options.html
+   * @example
+   * ```ts
+   * katexOptions: {
+   *   displayMode: false,
+   *   throwOnError: false,
+   *   macros: {
+   *     '\\RR': '\\mathbb{R}',
+   *     '\\ZZ': '\\mathbb{Z}'
+   *   }
+   * }
+   * ```
+   */
+  katexOptions?: KatexOptions
+
+  /**
+   * Optional click handler for inline math nodes.
+   * Called when a user clicks on an inline math expression in the editor.
+   *
+   * @param node - The ProseMirror node representing the inline math element
+   * @param pos - The position of the node within the document
+   * @example
+   * ```ts
+   * onClick: (node, pos) => {
+   *   console.log('Inline math clicked:', node.attrs.latex, 'at position:', pos)
+   * }
+   * ```
+   */
+  onClick?: (node: PMNode, pos: number) => void
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    inlineMath: {
+      /**
+       * Insert a inline math node with LaTeX string.
+       * @param options - Options for inserting inline math.
+       * @returns ReturnType
+       */
+      insertInlineMath: (options: { latex: string; pos?: number }) => ReturnType
+
+      /**
+       * Delete an inline math node.
+       * @returns ReturnType
+       */
+      deleteInlineMath: (options?: { pos?: number }) => ReturnType
+
+      /**
+       * Update inline math node with optional LaTeX string.
+       * @param options - Options for updating inline math.
+       * @returns ReturnType
+       */
+      updateInlineMath: (options?: { latex?: string; pos?: number }) => ReturnType
+    }
+  }
+}
+
+/**
+ * InlineMath is a Tiptap extension for rendering inline mathematical expressions using KaTeX.
+ * It allows users to insert LaTeX formatted math expressions inline within text.
+ * It supports rendering, input rules for LaTeX syntax, and click handling for interaction.
+ *
+ * @example
+ * ```javascript
+ * import { InlineMath } from '@tiptap/extension-mathematics'
+ * import { Editor } from '@tiptap/core'
+ *
+ * const editor = new Editor({
+ *   extensions: [
+ *     InlineMath.configure({
+ *       onClick: (node, pos) => {
+ *         console.log('Inline math clicked:', node.attrs.latex, 'at position:', pos)
+ *       },
+ *     }),
+ *   ],
+ * })
+ */
+export const InlineMath = Node.create<InlineMathOptions>({
+  name: 'inlineMath',
+
+  group: 'inline',
+
+  inline: true,
+
+  atom: true,
+
+  addOptions() {
+    return {
+      onClick: undefined,
+      katexOptions: undefined,
+    }
+  },
+
+  addAttributes() {
+    return {
+      latex: {
+        default: '',
+        parseHTML: element => element.getAttribute('data-latex'),
+        renderHTML: attributes => {
+          return {
+            'data-latex': attributes.latex,
+          }
+        },
+      },
+    }
+  },
+
+  addCommands() {
+    return {
+      insertInlineMath:
+        options =>
+        ({ editor, tr }) => {
+          const latex = options.latex
+
+          const from = options?.pos ?? editor.state.selection.from
+
+          if (!latex) {
+            return false
+          }
+
+          tr.replaceWith(from, from, this.type.create({ latex }))
+          return true
+        },
+
+      deleteInlineMath:
+        options =>
+        ({ editor, tr }) => {
+          const pos = options?.pos ?? editor.state.selection.$from.pos
+          const node = editor.state.doc.nodeAt(pos)
+
+          if (!node || node.type.name !== this.name) {
+            return false
+          }
+
+          tr.delete(pos, pos + node.nodeSize)
+          return true
+        },
+
+      updateInlineMath:
+        options =>
+        ({ editor, tr }) => {
+          const latex = options?.latex
+          let pos = options?.pos
+
+          if (pos === undefined) {
+            pos = editor.state.selection.$from.pos
+          }
+
+          const node = editor.state.doc.nodeAt(pos)
+
+          if (!node || node.type.name !== this.name) {
+            return false
+          }
+
+          tr.setNodeMarkup(pos, this.type, { ...node.attrs, latex })
+
+          return true
+        },
+    }
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: 'span[data-type="inline-math"]',
+      },
+    ]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['span', mergeAttributes(HTMLAttributes, { 'data-type': 'inline-math' })]
+  },
+
+  addInputRules() {
+    return [
+      new InputRule({
+        find: /(?<!\$)\$\$([^$\n]+)\$\$(?!\$)$/,
+        handler: ({ state, range, match }) => {
+          const [, latex] = match
+          const { tr } = state
+          const start = range.from
+          const end = range.to
+
+          tr.replaceWith(start, end, this.type.create({ latex }))
+        },
+      }),
+    ]
+  },
+
+  addNodeView() {
+    const { katexOptions } = this.options
+
+    return ({ node, getPos }) => {
+      const wrapper = document.createElement('span')
+      wrapper.className = 'tiptap-mathematics-render'
+
+      if (this.editor.isEditable) {
+        wrapper.classList.add('tiptap-mathematics-render--editable')
+      }
+
+      wrapper.dataset.type = 'inline-math'
+      wrapper.setAttribute('data-latex', node.attrs.latex)
+
+      function renderMath() {
+        try {
+          katex.render(node.attrs.latex, wrapper, katexOptions)
+          wrapper.classList.remove('inline-math-error')
+        } catch {
+          wrapper.textContent = node.attrs.latex
+          wrapper.classList.add('inline-math-error')
+        }
+      }
+
+      const handleClick = (event: MouseEvent) => {
+        event.preventDefault()
+        event.stopPropagation()
+        const pos = getPos()
+
+        if (pos == null) {
+          return
+        }
+
+        if (this.options.onClick) {
+          this.options.onClick(node, pos)
+        }
+      }
+
+      if (this.options.onClick) {
+        wrapper.addEventListener('click', handleClick)
+      }
+
+      renderMath()
+
+      return {
+        dom: wrapper,
+        destroy() {
+          wrapper.removeEventListener('click', handleClick)
+        },
+      }
+    }
+  },
+})

package/src/extensions/index.ts

@@ -0,0 +1,2 @@
+export * from './BlockMath.js'
+export * from './InlineMath.js'

package/src/index.ts

@@ -1,7 +1,8 @@
 import { Mathematics } from './mathematics.js'
 
+export * from './extensions/index.js'
 export * from './mathematics.js'
-export * from './MathematicsPlugin.js'
 export * from './types.js'
+export * from './utils.js'
 
 export default Mathematics

package/src/mathematics.ts

@@ -1,30 +1,70 @@
 import { Extension } from '@tiptap/core'
-import type { EditorState } from '@tiptap/pm/state'
 
-import { MathematicsPlugin } from './MathematicsPlugin.js'
+import { BlockMath, InlineMath } from './extensions/index.js'
 import type { MathematicsOptions } from './types.js'
 
-export const defaultShouldRender = (state: EditorState, pos: number) => {
-  const $pos = state.doc.resolve(pos)
-  const isInCodeBlock = $pos.parent.type.name === 'codeBlock'
-
-  return !isInCodeBlock
-}
-
+/**
+ * Mathematics extension for Tiptap that provides both inline and block math support using KaTeX.
+ * This extension combines the InlineMath and BlockMath extensions to provide a complete
+ * mathematical expression solution for rich text editing. It supports LaTeX syntax,
+ * custom rendering options, and interactive math nodes.
+ *
+ * @example
+ * ```typescript
+ * import { Editor } from '@tiptap/core'
+ * import { Mathematics } from '@tiptap/extension-mathematics'
+ * import { migrateMathStrings } from '@tiptap/extension-mathematics/utils'
+ *
+ * const editor = new Editor({
+ *   extensions: [
+ *     Mathematics.configure({
+ *       inlineOptions: {
+ *         onClick: (node, pos) => {
+ *           console.log('Inline math clicked:', node.attrs.latex)
+ *         }
+ *       },
+ *       blockOptions: {
+ *         onClick: (node, pos) => {
+ *           console.log('Block math clicked:', node.attrs.latex)
+ *         }
+ *       },
+ *       katexOptions: {
+ *         displayMode: false,
+ *         throwOnError: false,
+ *         macros: {
+ *           '\\RR': '\\mathbb{R}',
+ *           '\\ZZ': '\\mathbb{Z}'
+ *         }
+ *       }
+ *     })
+ *   ],
+ *   content: `
+ *     <p>Inline math: $E = mc^2$</p>
+ *     <div data-type="block-math" data-latex="\\sum_{i=1}^{n} x_i = X"></div>
+ *   `,
+ *   onCreate({ editor }) {
+ *     // Optional: Migrate existing math strings to math nodes
+ *     migrateMathStrings(editor)
+ *   }
+ * })
+ * ```
+ */
 export const Mathematics = Extension.create<MathematicsOptions>({
   name: 'Mathematics',
 
   addOptions() {
     return {
-      // eslint-disable-next-line no-useless-escape
-      regex: /\$([^\$]*)\$/gi,
+      inlineOptions: undefined,
+      blockOptions: undefined,
       katexOptions: undefined,
-      shouldRender: defaultShouldRender,
     }
   },
 
-  addProseMirrorPlugins() {
-    return [MathematicsPlugin({ ...this.options, editor: this.editor })]
+  addExtensions() {
+    return [
+      BlockMath.configure({ ...this.options.blockOptions, katexOptions: this.options.katexOptions }),
+      InlineMath.configure({ ...this.options.inlineOptions, katexOptions: this.options.katexOptions }),
+    ]
   },
 })
 

package/src/types.ts

@@ -1,12 +1,24 @@
 import type { Editor } from '@tiptap/core'
-import type { Node } from '@tiptap/pm/model'
-import type { EditorState } from '@tiptap/pm/state'
 import type { KatexOptions } from 'katex'
 
+import type { BlockMathOptions, InlineMathOptions } from './extensions'
+
+/**
+ * Configuration options for the Mathematics extension.
+ * This type defines the available customization options for both inline and block math rendering.
+ */
 export type MathematicsOptions = {
-  regex: RegExp
+  /** Configuration options specific to inline math nodes */
+  inlineOptions?: Omit<InlineMathOptions, 'katexOptions'>
+  /** Configuration options specific to block math nodes */
+  blockOptions?: Omit<BlockMathOptions, 'katexOptions'>
+  /** KaTeX-specific rendering options passed to the KaTeX library */
   katexOptions?: KatexOptions
-  shouldRender: (state: EditorState, pos: number, node: Node) => boolean
 }
 
+/**
+ * Extended mathematics options that include an editor instance.
+ * This type combines the base mathematics options with an editor reference,
+ * typically used internally by the extension for operations that require editor access.
+ */
 export type MathematicsOptionsWithEditor = MathematicsOptions & { editor: Editor }