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

package/dist/index.d.cts

@@ -1,28 +1,298 @@
-import { Editor, Extension } from '@tiptap/core';
-import { EditorState, Plugin } from '@tiptap/pm/state';
-import { Node } from '@tiptap/pm/model';
+import { Node as Node$1, Editor, Extension } from '@tiptap/core';
 import { KatexOptions } from 'katex';
-import { DecorationSet } from '@tiptap/pm/view';
+import { Node } from '@tiptap/pm/model';
+import { Transaction } from '@tiptap/pm/state';
+
+/**
+ * Configuration options for the BlockMath extension.
+ */
+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: Node, 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)
+ *       },
+ *     }),
+ *   ],
+ * })
+ */
+declare const BlockMath: Node$1<BlockMathOptions, any>;
 
+/**
+ * Configuration options for the InlineMath extension.
+ */
+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: Node, 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)
+ *       },
+ *     }),
+ *   ],
+ * })
+ */
+declare const InlineMath: Node$1<InlineMathOptions, any>;
+
+/**
+ * Configuration options for the Mathematics extension.
+ * This type defines the available customization options for both inline and block math rendering.
+ */
 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.
+ */
 type MathematicsOptionsWithEditor = MathematicsOptions & {
     editor: Editor;
 };
 
-declare const defaultShouldRender: (state: EditorState, pos: number) => boolean;
+/**
+ * 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)
+ *   }
+ * })
+ * ```
+ */
 declare const Mathematics: Extension<MathematicsOptions, any>;
 
-type PluginState = {
-    decorations: DecorationSet;
-    isEditable: boolean;
-} | {
-    decorations: undefined;
-    isEditable: undefined;
-};
-declare const MathematicsPlugin: (options: MathematicsOptionsWithEditor) => Plugin<PluginState>;
+/**
+ * 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
+ */
+declare const mathMigrationRegex: RegExp;
+/**
+ * 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)
+ * ```
+ */
+declare function createMathMigrateTransaction(editor: Editor, tr: Transaction, regex?: RegExp): Transaction;
+/**
+ * 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)
+ * ```
+ */
+declare function migrateMathStrings(editor: Editor, regex?: RegExp): void;
 
-export { Mathematics, type MathematicsOptions, type MathematicsOptionsWithEditor, MathematicsPlugin, Mathematics as default, defaultShouldRender };
+export { BlockMath, type BlockMathOptions, InlineMath, type InlineMathOptions, Mathematics, type MathematicsOptions, type MathematicsOptionsWithEditor, createMathMigrateTransaction, Mathematics as default, mathMigrationRegex, migrateMathStrings };

package/dist/index.d.ts

@@ -1,28 +1,298 @@
-import { Editor, Extension } from '@tiptap/core';
-import { EditorState, Plugin } from '@tiptap/pm/state';
-import { Node } from '@tiptap/pm/model';
+import { Node as Node$1, Editor, Extension } from '@tiptap/core';
 import { KatexOptions } from 'katex';
-import { DecorationSet } from '@tiptap/pm/view';
+import { Node } from '@tiptap/pm/model';
+import { Transaction } from '@tiptap/pm/state';
+
+/**
+ * Configuration options for the BlockMath extension.
+ */
+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: Node, 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)
+ *       },
+ *     }),
+ *   ],
+ * })
+ */
+declare const BlockMath: Node$1<BlockMathOptions, any>;
 
+/**
+ * Configuration options for the InlineMath extension.
+ */
+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: Node, 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)
+ *       },
+ *     }),
+ *   ],
+ * })
+ */
+declare const InlineMath: Node$1<InlineMathOptions, any>;
+
+/**
+ * Configuration options for the Mathematics extension.
+ * This type defines the available customization options for both inline and block math rendering.
+ */
 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.
+ */
 type MathematicsOptionsWithEditor = MathematicsOptions & {
     editor: Editor;
 };
 
-declare const defaultShouldRender: (state: EditorState, pos: number) => boolean;
+/**
+ * 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)
+ *   }
+ * })
+ * ```
+ */
 declare const Mathematics: Extension<MathematicsOptions, any>;
 
-type PluginState = {
-    decorations: DecorationSet;
-    isEditable: boolean;
-} | {
-    decorations: undefined;
-    isEditable: undefined;
-};
-declare const MathematicsPlugin: (options: MathematicsOptionsWithEditor) => Plugin<PluginState>;
+/**
+ * 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
+ */
+declare const mathMigrationRegex: RegExp;
+/**
+ * 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)
+ * ```
+ */
+declare function createMathMigrateTransaction(editor: Editor, tr: Transaction, regex?: RegExp): Transaction;
+/**
+ * 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)
+ * ```
+ */
+declare function migrateMathStrings(editor: Editor, regex?: RegExp): void;
 
-export { Mathematics, type MathematicsOptions, type MathematicsOptionsWithEditor, MathematicsPlugin, Mathematics as default, defaultShouldRender };
+export { BlockMath, type BlockMathOptions, InlineMath, type InlineMathOptions, Mathematics, type MathematicsOptions, type MathematicsOptionsWithEditor, createMathMigrateTransaction, Mathematics as default, mathMigrationRegex, migrateMathStrings };