@tiptap/extension-mathematics 3.0.0-beta.17 → 3.0.0-beta.19

package/src/extensions/BlockMath.ts

@@ -1,33 +1,61 @@
 import { InputRule, mergeAttributes, Node } from '@tiptap/core'
 import type { Node as PMNode } from '@tiptap/pm/model'
-import katex from 'katex'
+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> {
-    blockMath: {
+    insertBlockMath: {
       /**
-       * Set block math node with LaTeX string.
-       * @param options - Options for setting block math.
+       * Inserts a math block node with LaTeX string.
+       * @param options - Options for inserting block math.
        * @returns ReturnType
        */
-      setBlockMath: (options: { latex: string; pos?: number }) => ReturnType
+      insertBlockMath: (options: { latex: string; pos?: number }) => ReturnType
 
       /**
-       * Unset block math node.
+       * Deletes a block math node.
        * @returns ReturnType
        */
-      unsetBlockMath: (options?: { pos?: number }) => 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
+      updateBlockMath: (options?: { latex: string; pos?: number }) => ReturnType
     }
   }
 }
@@ -39,7 +67,7 @@ declare module '@tiptap/core' {
  *
  * @example
  * ```javascript
- * import { BlockMath } from 'your-extension-path'
+ * import { BlockMath } from '@tiptap/extension-mathematics'
  * import { Editor } from '@tiptap/core'
  *
  * const editor = new Editor({
@@ -52,7 +80,7 @@ declare module '@tiptap/core' {
  *   ],
  * })
  */
-export const BlockMath = Node.create({
+export const BlockMath = Node.create<BlockMathOptions>({
   name: 'blockMath',
 
   group: 'block',
@@ -62,6 +90,7 @@ export const BlockMath = Node.create({
   addOptions() {
     return {
       onClick: undefined,
+      katexOptions: undefined,
     }
   },
 
@@ -81,17 +110,22 @@ export const BlockMath = Node.create({
 
   addCommands() {
     return {
-      setBlockMath:
+      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 },
           })
         },
 
-      unsetBlockMath:
+      deleteBlockMath:
         options =>
         ({ editor, tr }) => {
           const pos = options?.pos ?? editor.state.selection.$from.pos
@@ -160,10 +194,17 @@ export const BlockMath = Node.create({
   },
 
   addNodeView() {
+    const { katexOptions } = this.options
+
     return ({ node, getPos }) => {
       const wrapper = document.createElement('div')
       const innerWrapper = document.createElement('div')
-      wrapper.className = 'Tiptap-mathematics-render Tiptap-mathematics-render--editable'
+      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)
@@ -171,7 +212,7 @@ export const BlockMath = Node.create({
 
       function renderMath() {
         try {
-          katex.render(node.attrs.latex, innerWrapper)
+          katex.render(node.attrs.latex, innerWrapper, katexOptions)
           wrapper.classList.remove('block-math-error')
         } catch {
           wrapper.textContent = node.attrs.latex

package/src/extensions/InlineMath.ts

@@ -1,8 +1,41 @@
 import { InputRule, mergeAttributes, Node } from '@tiptap/core'
 import type { Node as PMNode } from '@tiptap/pm/model'
-import katex from 'katex'
+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
 }
 
@@ -10,17 +43,17 @@ declare module '@tiptap/core' {
   interface Commands<ReturnType> {
     inlineMath: {
       /**
-       * Set inline math node with LaTeX string.
-       * @param options - Options for setting inline math.
+       * Insert a inline math node with LaTeX string.
+       * @param options - Options for inserting inline math.
        * @returns ReturnType
        */
-      setInlineMath: (options: { latex: string; pos?: number }) => ReturnType
+      insertInlineMath: (options: { latex: string; pos?: number }) => ReturnType
 
       /**
-       * Unset inline math node.
+       * Delete an inline math node.
        * @returns ReturnType
        */
-      unsetInlineMath: (options?: { pos?: number }) => ReturnType
+      deleteInlineMath: (options?: { pos?: number }) => ReturnType
 
       /**
        * Update inline math node with optional LaTeX string.
@@ -39,7 +72,7 @@ declare module '@tiptap/core' {
  *
  * @example
  * ```javascript
- * import { InlineMath } from 'your-extension-path'
+ * import { InlineMath } from '@tiptap/extension-mathematics'
  * import { Editor } from '@tiptap/core'
  *
  * const editor = new Editor({
@@ -64,6 +97,7 @@ export const InlineMath = Node.create<InlineMathOptions>({
   addOptions() {
     return {
       onClick: undefined,
+      katexOptions: undefined,
     }
   },
 
@@ -83,21 +117,22 @@ export const InlineMath = Node.create<InlineMathOptions>({
 
   addCommands() {
     return {
-      setInlineMath:
+      insertInlineMath:
         options =>
         ({ editor, tr }) => {
-          const latex = options?.latex
-          const pos = options?.pos ?? editor.state.selection.$from.pos
+          const latex = options.latex
+
+          const from = options?.pos ?? editor.state.selection.from
 
           if (!latex) {
             return false
           }
 
-          tr.replaceWith(pos, pos, this.type.create({ latex }))
+          tr.replaceWith(from, from, this.type.create({ latex }))
           return true
         },
 
-      unsetInlineMath:
+      deleteInlineMath:
         options =>
         ({ editor, tr }) => {
           const pos = options?.pos ?? editor.state.selection.$from.pos
@@ -163,15 +198,22 @@ export const InlineMath = Node.create<InlineMathOptions>({
   },
 
   addNodeView() {
+    const { katexOptions } = this.options
+
     return ({ node, getPos }) => {
       const wrapper = document.createElement('span')
-      wrapper.className = 'Tiptap-mathematics-render Tiptap-mathematics-render--editable'
+      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)
+          katex.render(node.attrs.latex, wrapper, katexOptions)
           wrapper.classList.remove('inline-math-error')
         } catch {
           wrapper.textContent = node.attrs.latex

package/src/index.ts

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

package/src/mathematics.ts

@@ -3,7 +3,53 @@ import { Extension } from '@tiptap/core'
 import { BlockMath, InlineMath } from './extensions/index.js'
 import type { MathematicsOptions } from './types.js'
 
-export const Math = Extension.create<MathematicsOptions>({
+/**
+ * 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() {
@@ -15,10 +61,11 @@ export const Math = Extension.create<MathematicsOptions>({
   },
 
   addExtensions() {
-    return [BlockMath.configure(this.options.blockOptions), InlineMath.configure(this.options.inlineOptions)]
+    return [
+      BlockMath.configure({ ...this.options.blockOptions, katexOptions: this.options.katexOptions }),
+      InlineMath.configure({ ...this.options.inlineOptions, katexOptions: this.options.katexOptions }),
+    ]
   },
 })
 
-export const Mathematics = Math
-
-export default Math
+export default Mathematics

package/src/types.ts

@@ -3,10 +3,22 @@ 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 = {
-  inlineOptions?: InlineMathOptions
-  blockOptions?: BlockMathOptions
+  /** 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
 }
 
+/**
+ * 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 }

package/src/utils.ts

@@ -0,0 +1,101 @@
+import type { Editor } from '@tiptap/core'
+import type { Transaction } from '@tiptap/pm/state'
+
+/**
+ * Regular expression to match LaTeX math strings wrapped in single dollar signs.
+ * This should not catch dollar signs which are not part of a math expression,
+ * like those used for currency or other purposes.
+ * It ensures that the dollar signs are not preceded or followed by digits,
+ * allowing for proper identification of inline math expressions.
+ *
+ * - `$x^2 + y^2 = z^2$` will match
+ * - `This is $inline math$ in text.` will match
+ * - `This is $100$ dollars.` will not match (as it is not a math expression)
+ * - `This is $x^2 + y^2 = z^2$ and $100$ dollars.` will match both math expressions
+ */
+export const mathMigrationRegex = /(?<!\d)\$(?!\$)(?:[^$\n]|\\\$)*?(?<!\\)\$(?!\d)/g
+
+/**
+ * Creates a transaction that migrates existing math strings in the document to new math nodes.
+ * This function traverses the document and replaces LaTeX math syntax (wrapped in single dollar signs)
+ * with proper inline math nodes, preserving the mathematical content.
+ *
+ * @param editor - The editor instance containing the schema and configuration
+ * @param tr - The transaction to modify with the migration operations
+ * @returns The modified transaction with math string replacements
+ *
+ * @example
+ * ```typescript
+ * const editor = new Editor({ ... })
+ * const tr = editor.state.tr
+ * const updatedTr = createMathMigrateTransaction(editor, tr)
+ * editor.view.dispatch(updatedTr)
+ * ```
+ */
+export function createMathMigrateTransaction(editor: Editor, tr: Transaction, regex: RegExp = mathMigrationRegex) {
+  // we traverse the document and replace all math nodes with the new math nodes
+  tr.doc.descendants((node, pos) => {
+    if (!node.isText || !node.text || !node.text.includes('$')) {
+      return
+    }
+
+    const { text } = node
+
+    const match = node.text.match(regex)
+    if (!match) {
+      return
+    }
+
+    match.forEach(mathMatch => {
+      const start = text.indexOf(mathMatch)
+      const end = start + mathMatch.length
+
+      const from = tr.mapping.map(pos + start)
+
+      const $from = tr.doc.resolve(from)
+      const parent = $from.parent
+      const index = $from.index()
+
+      const { inlineMath } = editor.schema.nodes
+
+      if (!parent.canReplaceWith(index, index + 1, inlineMath)) {
+        return
+      }
+
+      // Replace the math syntax with a new math node
+      tr.replaceWith(
+        tr.mapping.map(pos + start),
+        tr.mapping.map(pos + end),
+        inlineMath.create({ latex: mathMatch.slice(1, -1) }),
+      )
+    })
+  })
+
+  // don't add to history
+  tr.setMeta('addToHistory', false)
+  return tr
+}
+
+/**
+ * Migrates existing math strings in the editor document to math nodes.
+ * This function creates and dispatches a transaction that converts LaTeX math syntax
+ * (text wrapped in single dollar signs) into proper inline math nodes. The migration
+ * happens immediately and is not added to the editor's history.
+ *
+ * @param editor - The editor instance to perform the migration on
+ *
+ * @example
+ * ```typescript
+ * const editor = new Editor({
+ *   extensions: [Mathematics],
+ *   content: 'This is inline math: $x^2 + y^2 = z^2$ in text.'
+ * })
+ *
+ * // Math strings will be automatically migrated to math nodes
+ * migrateMathStrings(editor)
+ * ```
+ */
+export function migrateMathStrings(editor: Editor, regex: RegExp = mathMigrationRegex) {
+  const tr = createMathMigrateTransaction(editor, editor.state.tr, regex)
+  editor.view.dispatch(tr)
+}