suneditor 3.0.0-beta.9 → 3.0.0-rc.2

package/src/plugins/modal/math.js

@@ -1,15 +1,15 @@
-import EditorInjector from '../../editorInjector';
-import { Modal, Controller } from '../../modules';
+import { PluginModal } from '../../interfaces';
+import { Modal, Controller } from '../../modules/contract';
 import { dom, env, converter } from '../../helper';
 
-const { _w } = env;
+const { _w, _d } = env;
 
 /**
  * @typedef {Object} MathPluginOptions
  * @property {boolean} [canResize=true] - Whether the math modal can be resized.
  * @property {boolean} [autoHeight=false] - Whether to automatically adjust the height of the modal.
  * @property {Array<object>} [fontSizeList] - A list of font size options for rendering math expressions.
- * @property {(...args: *) => *} [onPaste] - A callback function to handle paste events in the math input area.
+ * @property {?(...args: *) => *} [onPaste] - A callback function to handle paste events in the math input area.
  * @property {Object} [formSize={}] - An object specifying the dimensions for the math modal.
  * @property {string} [formSize.width="460px"] - The default width of the math modal.
  * @property {string} [formSize.height="14em"] - The default height of the math modal.
@@ -22,31 +22,32 @@ const { _w } = env;
 /**
  * @class
  * @description Math plugin.
- * - This plugin provides support for rendering mathematical expressions using either the KaTeX or MathJax libraries.
+ * - This plugin provides support for rendering mathematical expressions using either the `KaTeX` or `MathJax` libraries.
  * - If external library is provided, a warning is issued.
  */
-class Math_ extends EditorInjector {
+class Math_ extends PluginModal {
 	static key = 'math';
-	static type = 'modal';
 	static className = '';
+
 	/**
-	 * @this {Math_}
 	 * @param {HTMLElement} node - The node to check.
 	 * @returns {HTMLElement|null} Returns a node if the node is a valid component.
 	 */
 	static component(node) {
-		return dom.utils.hasClass(node, 'se-math|katex') && dom.utils.hasClass(node, 'se-component') ? node : null;
+		return dom.utils.hasClass(node, 'se-math|katex') && dom.check.isComponentContainer(node) ? node : null;
 	}
 
+	#element = null;
+
 	/**
 	 * @constructor
-	 * @param {__se__EditorCore} editor - The root editor instance
+	 * @param {SunEditor.Kernel} editor - The core kernel
 	 * @param {MathPluginOptions} pluginOptions
 	 */
 	constructor(editor, pluginOptions) {
 		// plugin basic properties
 		super(editor);
-		this.title = this.lang.math;
+		this.title = this.$.lang.math;
 		this.icon = 'math';
 
 		// external library
@@ -54,8 +55,10 @@ class Math_ extends EditorInjector {
 		this.mathjax = null;
 
 		// exception
-		if (!(this.katex = this.#CheckKatex(editor.options.get('externalLibs').katex)) && !(this.mathjax = this.#CheckMathJax(editor.options.get('externalLibs').mathjax, editor))) {
-			console.warn('[SUNEDITOR.plugins.math.warn] The math plugin must need either "KaTeX" or "MathJax" library. Please add the katex or mathjax option.');
+		if (!(this.katex = this.#CheckKatex()) && !(this.mathjax = this.#CheckMathJax())) {
+			console.warn(
+				'[SUNEDITOR.plugins.math.warn] The math plugin must need either "KaTeX" or "MathJax" library. Please add the katex or mathjax option. See: https://github.com/ARA-developer/suneditor/blob/develop/guide/external-libraries.md',
+			);
 		}
 
 		this.pluginOptions = {
@@ -66,29 +69,29 @@ class Math_ extends EditorInjector {
 				maxHeight: '',
 				minWidth: '400px',
 				minHeight: '40px',
-				...pluginOptions.formSize
+				...pluginOptions.formSize,
 			},
 			canResize: pluginOptions.canResize ?? true,
 			autoHeight: !!pluginOptions.autoHeight,
 			fontSizeList: pluginOptions.fontSizeList || [
 				{
 					text: '1',
-					value: '1em'
+					value: '1em',
 				},
 				{
 					text: '1.5',
-					value: '1.5em'
+					value: '1.5em',
 				},
 				{
 					text: '2',
-					value: '2em'
+					value: '2em',
 				},
 				{
 					text: '2.5',
-					value: '2.5em'
-				}
+					value: '2.5em',
+				},
 			],
-			onPaste: typeof pluginOptions.onPaste === 'function' ? pluginOptions.onPaste : null
+			onPaste: typeof pluginOptions.onPaste === 'function' ? pluginOptions.onPaste : null,
 		};
 		if (this.pluginOptions.autoHeight) {
 			this.pluginOptions.formSize.height = this.pluginOptions.formSize.minHeight;
@@ -97,11 +100,11 @@ class Math_ extends EditorInjector {
 		// create HTML
 		this.defaultFontSize = null;
 		const modalEl = CreateHTML_modal(this);
-		const controllerEl = CreateHTML_controller(editor);
+		const controllerEl = CreateHTML_controller(this.$);
 
 		// modules
-		this.modal = new Modal(this, modalEl);
-		this.controller = new Controller(this, controllerEl, { position: 'bottom', disabled: true });
+		this.modal = new Modal(this, this.$, modalEl);
+		this.controller = new Controller(this, this.$, controllerEl, { position: 'bottom', disabled: true });
 
 		// members
 		/** @type {HTMLTextAreaElement} */
@@ -112,54 +115,33 @@ class Math_ extends EditorInjector {
 		this.fontSizeElement = modalEl.querySelector('.se-math-size');
 
 		this.isUpdateState = false;
-		this._element = null;
 
 		// init
 		this.previewElement.style.fontSize = this.defaultFontSize;
-		this.eventManager.addEvent(this.textArea, 'input', this.#RenderMathExp.bind(this));
-		this.eventManager.addEvent(
+		this.$.eventManager.addEvent(this.textArea, 'input', this.#RenderMathExp.bind(this));
+		this.$.eventManager.addEvent(
 			this.fontSizeElement,
 			'change',
 			function (e) {
 				this.fontSize = e.target.value;
-			}.bind(this.previewElement.style)
+			}.bind(this.previewElement.style),
 		);
 		if (this.pluginOptions.onPaste) {
-			this.eventManager.addEvent(this.textArea, 'paste', this.pluginOptions.onPaste.bind(this));
-		}
-	}
-
-	/**
-	 * @editorMethod Editor.component
-	 * @description Executes the method that is called when a component of a plugin is selected.
-	 * @param {HTMLElement} target Target component element
-	 */
-	select(target) {
-		if (dom.utils.hasClass(target, 'se-math|katex') && getValue(target)) {
-			this._element = target;
-			this.controller.open(target, null, { isWWTarget: false, initMethod: null, addOffset: null });
-			return;
+			this.$.eventManager.addEvent(this.textArea, 'paste', this.pluginOptions.onPaste.bind(this));
 		}
 	}
 
 	/**
-	 * @editorMethod Modules.Controller
-	 * @description This function is called before the "controller" before it is closed.
+	 * @override
+	 * @type {PluginModal['open']}
 	 */
-	close() {
-		this._element = null;
+	open() {
+		this.modal.open();
 	}
 
 	/**
-	 * @editorMethod Editor.core
-	 * @description This method is used to validate and preserve the format of the component within the editor.
-	 * - It ensures that the structure and attributes of the element are maintained and secure.
-	 * - The method checks if the element is already wrapped in a valid container and updates its attributes if necessary.
-	 * - If the element isn't properly contained, a new container is created to retain the format.
-	 * @returns {{query: string, method: (element: HTMLElement) => void}} The format retention object containing the query and method to process the element.
-	 * - query: The selector query to identify the relevant elements (in this case, 'audio').
-	 * - method:The function to execute on the element to validate and preserve its format.
-	 * - The function takes the element as an argument, checks if it is contained correctly, and applies necessary adjustments.
+	 * @hook Editor.Core
+	 * @type {SunEditor.Hook.Core.RetainFormat}
 	 */
 	retainFormat() {
 		return {
@@ -170,7 +152,7 @@ class Math_ extends EditorInjector {
 				const value = getValue(element);
 				if (!value) return;
 
-				const domParser = this._d.createRange().createContextualFragment(this._renderer(converter.entityToHTML(this._escapeBackslashes(value, true))));
+				const domParser = _d.createRange().createContextualFragment(this.#renderer(converter.entityToHTML(this.#escapeBackslashes(value, true))));
 				element.innerHTML = domParser.querySelector('.se-math, .katex').innerHTML;
 				element.setAttribute('contenteditable', 'false');
 				dom.utils.addClass(element, 'se-component|se-inline-component|se-disable-pointer|se-math');
@@ -184,44 +166,34 @@ class Math_ extends EditorInjector {
 				if (this.mathjax) {
 					this.#renderMathJax(this.mathjax);
 				}
-			}
+			},
 		};
 	}
 
 	/**
-	 * @editorMethod Modules.Modal
-	 * @description Executes the method that is called when a "Modal" module's is opened.
+	 * @hook Modules.Modal
+	 * @type {SunEditor.Hook.Modal.On}
 	 */
-	open() {
-		this.modal.open();
-	}
-
-	/**
-	 * @editorMethod Modules.Modal
-	 * @description Executes the method that is called when a plugin's modal is opened.
-	 * @param {boolean} isUpdate "Indicates whether the modal is for editing an existing component (true) or registering a new one (false)."
-	 */
-	on(isUpdate) {
+	modalOn(isUpdate) {
 		this.isUpdateState = isUpdate;
 		if (!isUpdate) {
-			this.init();
+			this.modalInit();
 		} else if (this.controller.currentTarget) {
 			const currentTarget = this.controller.currentTarget;
-			const exp = converter.entityToHTML(this._escapeBackslashes(getValue(currentTarget), true));
+			const exp = converter.entityToHTML(this.#escapeBackslashes(getValue(currentTarget), true));
 			const fontSize = getType(currentTarget) || '1em';
 			this.textArea.value = exp;
 			this.fontSizeElement.value = fontSize;
-			this.previewElement.innerHTML = this._renderer(exp);
+			this.previewElement.innerHTML = this.#renderer(exp);
 			this.previewElement.style.fontSize = fontSize;
 		}
 	}
 
 	/**
-	 * @editorMethod Modules.Modal
-	 * @description This function is called when a form within a modal window is "submit".
-	 * @returns {boolean} Success or failure
+	 * @hook Modules.Modal
+	 * @type {SunEditor.Hook.Modal.Action}
 	 */
-	modalAction() {
+	async modalAction() {
 		if (this.textArea.value.trim().length === 0 || dom.utils.hasClass(this.textArea, 'se-error')) {
 			this.textArea.focus();
 			return false;
@@ -235,7 +207,7 @@ class Math_ extends EditorInjector {
 		if (!mathEl) return false;
 		dom.utils.addClass(mathEl, 'se-component|se-inline-component|se-disable-pointer|se-math');
 		mathEl.setAttribute('contenteditable', 'false');
-		mathEl.setAttribute('data-se-value', converter.htmlToEntity(this._escapeBackslashes(mathExp, false)));
+		mathEl.setAttribute('data-se-value', converter.htmlToEntity(this.#escapeBackslashes(mathExp, false)));
 		mathEl.setAttribute('data-se-type', this.fontSizeElement.value);
 		mathEl.style.fontSize = this.fontSizeElement.value;
 
@@ -247,19 +219,19 @@ class Math_ extends EditorInjector {
 		}
 
 		if (!this.isUpdateState) {
-			const selectedFormats = this.format.getLines();
+			const selectedFormats = this.$.format.getLines();
 
 			if (selectedFormats.length > 1) {
 				const oFormat = dom.utils.createElement(selectedFormats[0].nodeName, null, mathEl);
-				this.component.insert(oFormat, { skipCharCount: false, skipSelection: true, skipHistory: false });
+				this.$.component.insert(oFormat, { insertBehavior: 'none', scrollTo: false });
 			} else {
-				this.component.insert(mathEl, { skipCharCount: false, skipSelection: true, skipHistory: false });
+				this.$.component.insert(mathEl, { insertBehavior: 'none', scrollTo: false });
 			}
 		} else {
 			const containerEl = dom.query.getParentElement(this.controller.currentTarget, '.se-component');
 			containerEl.replaceWith(mathEl);
-			const compInfo = this.component.get(mathEl);
-			this.component.select(compInfo.target, compInfo.pluginName);
+			const compInfo = this.$.component.get(mathEl);
+			this.$.component.select(compInfo.target, compInfo.pluginName);
 			return true;
 		}
 
@@ -267,30 +239,29 @@ class Math_ extends EditorInjector {
 			this.#renderMathJax(this.mathjax);
 		}
 
-		const r = this.selection.getNearRange(mathEl);
+		const r = this.$.selection.getNearRange(mathEl);
 		if (r) {
-			this.selection.setRange(r.container, r.offset, r.container, r.offset);
+			this.$.selection.setRange(r.container, r.offset, r.container, r.offset);
 		} else {
-			this.component.select(mathEl, Math_.key);
+			this.$.component.select(mathEl, Math_.key);
 		}
 
 		return true;
 	}
 
 	/**
-	 * @editorMethod Modules.Modal
-	 * @description This function is called before the modal window is opened, but before it is closed.
+	 * @hook Modules.Modal
+	 * @type {SunEditor.Hook.Modal.Init}
 	 */
-	init() {
+	modalInit() {
 		this.textArea.value = '';
 		this.previewElement.innerHTML = '';
 		dom.utils.removeClass(this.textArea, 'se-error');
 	}
 
 	/**
-	 * @editorMethod Modules.Controller
-	 * @description Executes the method that is called when a button is clicked in the "controller".
-	 * @param {HTMLButtonElement} target Target button element
+	 * @hook Modules.Controller
+	 * @type {SunEditor.Hook.Controller.Action}
 	 */
 	controllerAction(target) {
 		const command = target.getAttribute('data-command');
@@ -299,33 +270,52 @@ class Math_ extends EditorInjector {
 				this.modal.open();
 				break;
 			case 'copy':
-				this.#copyTextToClipboard(this._element);
+				this.#copyTextToClipboard(this.#element);
 				break;
 			case 'delete':
-				this.destroy(this.controller.currentTarget);
+				this.componentDestroy(this.controller.currentTarget);
 		}
 	}
 
 	/**
-	 * @editorMethod Editor.Component
-	 * @description Method to delete a component of a plugin, called by the "FileManager", "Controller" module.
-	 * @param {Node} target Target element
+	 * @hook Modules.Controller
+	 * @type {SunEditor.Hook.Controller.Close}
 	 */
-	destroy(target) {
+	controllerClose() {
+		this.#element = null;
+	}
+
+	/**
+	 * @hook Editor.Component
+	 * @type {SunEditor.Hook.Component.Select}
+	 */
+	componentSelect(target) {
+		if (dom.utils.hasClass(target, 'se-math|katex') && getValue(target)) {
+			this.#element = target;
+			this.controller.open(target, null, { isWWTarget: false, initMethod: null, addOffset: null });
+			return;
+		}
+	}
+
+	/**
+	 * @hook Editor.Component
+	 * @type {SunEditor.Hook.Component.Destroy}
+	 */
+	async componentDestroy(target) {
 		dom.utils.removeItem(target);
 		this.controller.close();
-		this.editor.focus();
-		this.history.push(false);
+		this.$.focusManager.focus();
+		this.$.history.push(false);
 	}
 
 	/**
-	 * @private
-	 * @description Renders the given math expression using KaTeX or MathJax.
+	 * @description Renders the given math expression using `KaTeX` or `MathJax`.
 	 * @param {string} exp - The math expression to render.
 	 * @returns {string} - The rendered math expression as HTML.
 	 */
-	_renderer(exp) {
+	#renderer(exp) {
 		let result = '';
+
 		try {
 			dom.utils.removeClass(this.textArea, 'se-error');
 			if (this.katex) {
@@ -338,23 +328,32 @@ class Math_ extends EditorInjector {
 				} else {
 					result = `<span class="se-math">${result}</span>`;
 				}
+			} else {
+				/** @type {Error & { code?: string }} */
+				const err = new Error('404 Not found. "KaTeX" or "MathJax" library');
+				err.code = 'MATH_LIB_NOT_FOUND';
+				throw err;
 			}
 		} catch (error) {
 			dom.utils.addClass(this.textArea, 'se-error');
-			result = `<span class="se-math-error">Math syntax error. (Refer ${this.katex ? `<a href="${env.KATEX_WEBSITE}" target="_blank">KaTeX</a>` : `<a href="${env.MATHJAX_WEBSITE}" target="_blank">MathJax</a>`})</span>`;
+			if (error.code === 'MATH_LIB_NOT_FOUND') {
+				result = `<span class="se-math-error">${error.message}</span>`;
+			} else {
+				result = `<span class="se-math-error">Math syntax error. (Refer ${this.katex ? `<a href="${env.KATEX_WEBSITE}" target="_blank">KaTeX</a>` : `<a href="${env.MATHJAX_WEBSITE}" target="_blank">MathJax</a>`})</span>`;
+			}
 			console.warn('[SUNEDITOR.math.error] ', error.message);
 		}
+
 		return result;
 	}
 
 	/**
-	 * @private
 	 * @description Escapes or unescapes backslashes in a given string.
 	 * @param {string} str - The input string.
-	 * @param {boolean} decode - If true, decodes escaped backslashes; otherwise, encodes them.
+	 * @param {boolean} decode - If `true`, decodes escaped backslashes; otherwise, encodes them.
 	 * @returns {string} - The processed string.
 	 */
-	_escapeBackslashes(str, decode) {
+	#escapeBackslashes(str, decode) {
 		return str.replace(/\\{2}/g, decode ? '\\' : '\\\\');
 	}
 
@@ -368,7 +367,7 @@ class Math_ extends EditorInjector {
 
 		try {
 			const text = getValue(element);
-			await this.html.copy(text);
+			await this.$.html.copy(text);
 			dom.utils.addClass(element, 'se-copy');
 			// copy effect
 			_w.setTimeout(() => {
@@ -391,7 +390,7 @@ class Math_ extends EditorInjector {
 			eventTarget.style.height = eventTarget.scrollHeight + 5 + 'px';
 		}
 
-		this.previewElement.innerHTML = this._renderer(eventTarget.value);
+		this.previewElement.innerHTML = this.#renderer(eventTarget.value);
 		if (this.mathjax) this.#renderMathJax(this.mathjax);
 	}
 
@@ -404,10 +403,10 @@ class Math_ extends EditorInjector {
 	}
 
 	/**
-	 * @param {*} katex - The KaTeX instance.
-	 * @returns {*} - The KaTeX instance or null if the instance is invalid.
+	 * @returns {*} - The `KaTeX` instance or `null` if the instance is invalid.
 	 */
-	#CheckKatex(katex) {
+	#CheckKatex() {
+		const katex = this.$.options.get('externalLibs').katex;
 		if (!katex) return null;
 		if (!katex.src) {
 			console.warn('[SUNEDITOR.math.katex.fail] The katex option is set incorrectly.');
@@ -416,9 +415,9 @@ class Math_ extends EditorInjector {
 
 		const katexOptions = [
 			{
-				throwOnError: false
+				throwOnError: false,
 			},
-			katex.options || {}
+			katex.options || {},
 		].reduce((init, option) => {
 			for (const key in option) {
 				init[key] = option[key];
@@ -431,13 +430,12 @@ class Math_ extends EditorInjector {
 	}
 
 	/**
-	 * @param {*} mathjax - The MathJax instance.
-	 * @param {__se__EditorCore} editor - The root editor instance.
 	 * @returns {*}
 	 */
-	#CheckMathJax(mathjax, editor) {
+	#CheckMathJax() {
+		const mathjax = this.$.options.get('externalLibs').mathjax;
 		if (!mathjax) return null;
-		if (editor.frameOptions.get('iframe')) {
+		if (this.$.frameOptions.get('iframe')) {
 			console.warn('[SUNEDITOR.math.mathjax.fail] The MathJax option is not supported in the iframe.');
 		}
 
@@ -450,7 +448,7 @@ class Math_ extends EditorInjector {
 
 			return mathjax.src.document(document, {
 				InputJax: tex,
-				OutputJax: chtml
+				OutputJax: chtml,
 			});
 		} catch (error) {
 			console.warn('[SUNEDITOR.math.mathjax.fail] The MathJax option is set incorrectly.', error);
@@ -459,8 +457,13 @@ class Math_ extends EditorInjector {
 	}
 }
 
+/**
+ * @param {Math_} inst - Math plugin instance
+ * @returns {HTMLElement}
+ */
 function CreateHTML_modal(inst) {
-	const { lang, icons, pluginOptions, katex } = inst;
+	const { $, pluginOptions, katex } = inst;
+	const { lang, icons } = $;
 	const { formSize, fontSizeList, canResize, autoHeight } = pluginOptions;
 	const { width, height, maxWidth, maxHeight, minWidth, minHeight } = formSize;
 	const resizeType = !canResize ? 'none' : autoHeight ? 'horizontal' : 'auto';
@@ -507,6 +510,10 @@ function CreateHTML_modal(inst) {
 	return dom.utils.createElement('DIV', { class: 'se-modal-content se-modal-responsive', style: `max-width: ${maxWidth}; max-height: ${maxHeight};` }, html);
 }
 
+/**
+ * @param {SunEditor.Deps} $ - Kernel dependencies
+ * @returns {HTMLElement}
+ */
 function CreateHTML_controller({ lang, icons }) {
 	const html = /*html*/ `
     <div class="se-arrow se-arrow-up"></div>
@@ -553,7 +560,7 @@ function getType(element) {
 	if (seAttr) return seAttr;
 
 	// v2-migration
-	const v2SeAttr = element.getAttribute(`data-exp`);
+	const v2SeAttr = element.getAttribute(`data-font-size`);
 	if (!v2SeAttr) return null;
 	element.removeAttribute(`data-font-size`);
 	element.setAttribute(`data-se-type`, v2SeAttr);