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

package/src/core/{class → logic/dom}/nodeTransform.js

@@ -1,36 +1,42 @@
-/**
- * @fileoverview Node util class
- */
-
-import CoreInjector from '../../editorInjector/_core';
-import { dom, unicode, numbers } from '../../helper';
-
-/**
- * @typedef {Omit<NodeTransform & Partial<__se__EditorInjector>, 'nodeTransform'>} NodeTransformThis
- */
+import { dom, unicode, numbers } from '../../../helper';
 
 /**
- * @constructor
- * @this {NodeTransformThis}
  * @description Node utility class. split, merge, etc.
- * @param {__se__EditorCore} editor - The root editor instance
  */
-function NodeTransform(editor) {
-	CoreInjector.call(this, editor);
-}
+class NodeTransform {
+	#$;
+	#options;
+
+	/**
+	 * @constructor
+	 * @param {SunEditor.Kernel} kernel
+	 */
+	constructor(kernel) {
+		this.#$ = kernel.$;
+		this.#options = this.#$.options;
+	}
 
-NodeTransform.prototype = {
 	/**
-	 * @this {NodeTransformThis}
 	 * @template {HTMLElement} T
-	 * @description Split all tags based on "baseNode"
+	 * @description Split all tags based on `baseNode`
 	 * @param {Node} baseNode Element or text node on which to base
-	 * @param {?number|Node} offset Text offset of "baseNode" (Only valid when "baseNode" is a text node)
+	 * @param {?(number|Node)} offset Text offset of `baseNode` (Only valid when `baseNode` is a text node)
 	 * @param {number} [depth=0] The nesting depth of the element being split. (default: 0)
 	 * @returns {T} The last element of the splited tag.
+	 * @example
+	 * // Split at text offset
+	 * const textNode = editor.selection.getNode();
+	 * const newElement = editor.nodeTransform.split(textNode, 5, 0);
+	 *
+	 * // Split at specific depth to preserve parent structure
+	 * const paragraph = editor.selection.getNode().closest('p');
+	 * editor.nodeTransform.split(textNode, 10, 2);
+	 *
+	 * // Split by node reference
+	 * const splitResult = editor.nodeTransform.split(parentNode, childNode, 1);
 	 */
 	split(baseNode, offset, depth) {
-		if (dom.check.isWysiwygFrame(baseNode) || this.component.is(baseNode) || !baseNode) return /** @type {T} */ (baseNode);
+		if (dom.check.isWysiwygFrame(baseNode) || this.#$.component.is(baseNode) || !baseNode) return /** @type {T} */ (baseNode);
 
 		if (offset && !numbers.is(offset)) {
 			const children = baseNode.childNodes;
@@ -111,7 +117,7 @@ NodeTransform.prototype = {
 			}
 		}
 
-		if (depthEl.childNodes.length <= 1 && (!depthEl.firstChild || depthEl.firstChild.textContent.length === 0)) /** @type {HTMLElement} */ (depthEl).innerHTML = '<br>';
+		if (depthEl.nodeType === 1 && depthEl.childNodes.length <= 1 && !depthEl.firstChild?.textContent?.length) /** @type {HTMLElement} */ (depthEl).innerHTML = '<br>';
 
 		const pElement = depthEl.parentNode;
 		if (next) depthEl = depthEl.nextSibling;
@@ -130,21 +136,30 @@ NodeTransform.prototype = {
 		if (bp.childNodes.length === 0) dom.utils.removeItem(bp);
 
 		return /** @type {T} */ (newEl);
-	},
+	}
 
 	/**
-	 * @this {NodeTransformThis}
-	 * @description Use with "npdePath (dom-query-GetNodePath)" to merge the same attributes and tags if they are present and modify the nodepath.
-	 * - If "offset" has been changed, it will return as much "offset" as it has been modified.
-	 * - An array containing change offsets is returned in the order of the "nodePathArray" array.
+	 * @description Use with `npdePath` (dom-query-GetNodePath) to merge the same attributes and tags if they are present and modify the nodepath.
+	 * - If `offset` has been changed, it will return as much `offset` as it has been modified.
+	 * - An array containing change offsets is returned in the order of the `nodePathArray` array.
 	 * @param {Node} element Element
-	 * @param {?number[][]=} nodePathArray Array of NodePath object ([dom-query-GetNodePath(), ..])
-	 * @param {?boolean=} onlyText If true, non-text nodes like 'span', 'strong'.. are ignored.
+	 * @param {?number[][]} [nodePathArray] Array of `NodePath` object ([dom-query-GetNodePath(), ..])
+	 * @param {?boolean} [onlyText] If `true`, non-text nodes like `span`, `strong`.. are ignored.
 	 * @returns {Array<number>} [offset, ..]
+	 * @example
+	 * // Merge adjacent tags with same attributes
+	 * const container = editor.selection.getNode().closest('div');
+	 * editor.nodeTransform.mergeSameTags(container, null, false);
+	 *
+	 * // Merge with path tracking
+	 * const startPath = [0, 1, 2];
+	 * const endPath = [0, 2, 1];
+	 * const offsets = editor.nodeTransform.mergeSameTags(element, [startPath, endPath], false);
+	 *
+	 * // Merge only text nodes
+	 * editor.nodeTransform.mergeSameTags(paragraph, null, true);
 	 */
 	mergeSameTags(element, nodePathArray, onlyText) {
-		// eslint-disable-next-line @typescript-eslint/no-this-alias
-		const inst = this;
 		const nodePathLen = nodePathArray ? nodePathArray.length : 0;
 		let offsets = null;
 
@@ -152,7 +167,7 @@ NodeTransform.prototype = {
 			offsets = Array.apply(null, new Array(nodePathLen)).map(Number.prototype.valueOf, 0);
 		}
 
-		(function recursionFunc(current, depth, depthIndex) {
+		const recursionFunc = (current, depth, depthIndex) => {
 			const children = current.childNodes;
 
 			for (let i = 0, len = children.length, child, next; i < len; i++) {
@@ -160,7 +175,7 @@ NodeTransform.prototype = {
 				next = /** @type {HTMLElement} */ (children[i + 1]);
 				if (!child) break;
 				if (dom.check.isBreak(child) || dom.check.isMedia(child) || dom.check.isInputElement(child)) continue;
-				if ((onlyText && inst.format._isIgnoreNodeChange(child)) || (!onlyText && (dom.check.isTableElements(child) || dom.check.isListCell(child) || (inst.format.isLine(child) && !inst.format.isBrLine(child))))) {
+				if ((onlyText && this.#$.inline._isIgnoreNodeChange(child)) || (!onlyText && (dom.check.isTableElements(child) || dom.check.isListCell(child) || (this.#$.format.isLine(child) && !this.#$.format.isBrLine(child))))) {
 					if (dom.check.isTableElements(child) || dom.check.isListCell(child)) {
 						recursionFunc(child, depth + 1, i);
 					}
@@ -275,16 +290,17 @@ NodeTransform.prototype = {
 					recursionFunc(child, depth + 1, i);
 				}
 			}
-		})(element, 0, 0);
+		};
+
+		recursionFunc(element, 0, 0);
 
 		return offsets;
-	},
+	}
 
 	/**
-	 * @this {NodeTransformThis}
 	 * @description Remove nested tags without other child nodes.
 	 * @param {Node} element Element object
-	 * @param {?(current: Node) => boolean|string=} validation Validation function / String("tag1|tag2..") / If null, all tags are applicable.
+	 * @param {?(((current: Node) => boolean)|string)} [validation] Validation function / String(`tag1|tag2..`) / If `null`, all tags are applicable.
 	 */
 	mergeNestedTags(element, validation) {
 		if (typeof validation === 'string') {
@@ -309,27 +325,38 @@ NodeTransform.prototype = {
 				recursionFunc(current.children[i]);
 			}
 		})(/** @type {Element} */ (element));
-	},
+	}
 
 	/**
-	 * @this {NodeTransformThis}
 	 * @description Delete itself and all parent nodes that match the condition.
-	 * - Returns an {sc: previousSibling, ec: nextSibling}(the deleted node reference) or null.
+	 * - Returns an {sc: previousSibling, ec: nextSibling}(the deleted node reference) or `null`.
 	 * @param {Node} item Node to be remove
-	 * @param {?(current: Node) => boolean=} validation Validation function. default(Deleted if it only have breakLine and blanks)
-	 * @param {?Node=} stopParent Stop when the parent node reaches stopParent
-	 * @returns {{sc: Node|null, ec: Node|null}|null} {sc: previousSibling, ec: nextSibling} (the deleted node reference) or null.
+	 * @param {?(current: Node) => boolean} [validation] Validation function. default(Deleted if it only have `breakLine` and blanks)
+	 * @param {?Node} [stopParent] Stop when the parent node reaches `stopParent`
+	 * @returns {{sc: Node|null, ec: Node|null}|null} {sc: previousSibling, ec: nextSibling} (the deleted node reference) or `null`.
+	 * @example
+	 * // Remove empty parent elements recursively
+	 * const emptySpan = document.querySelector('span:empty');
+	 * const result = editor.nodeTransform.removeAllParents(emptySpan, null, null);
+	 *
+	 * // Remove with custom validation
+	 * editor.nodeTransform.removeAllParents(node, (current) => {
+	 *   return current.textContent.trim().length === 0;
+	 * }, null);
+	 *
+	 * // Remove up to specific parent
+	 * const stopAt = editor.selection.getNode().closest('.container');
+	 * editor.nodeTransform.removeAllParents(childNode, null, stopAt);
 	 */
 	removeAllParents(item, validation, stopParent) {
 		if (!item) return null;
 		let cc = null;
-		if (!validation) {
-			validation = (current) => {
-				if (current === stopParent || this.component.is(current)) return false;
-				const text = current.textContent.trim();
-				return text.length === 0 || /^(\n|\u200B)+$/.test(text);
-			};
-		}
+
+		validation ||= (current) => {
+			if (current === stopParent || this.#$.component.is(current)) return false;
+			const text = current.textContent.trim();
+			return text.length === 0 || /^(\n|\u200B)+$/.test(text);
+		};
 
 		(function recursionFunc(element) {
 			if (!dom.check.isWysiwygFrame(element)) {
@@ -337,7 +364,7 @@ NodeTransform.prototype = {
 				if (parent && validation(element)) {
 					cc = {
 						sc: element.previousElementSibling,
-						ec: element.nextElementSibling
+						ec: element.nextElementSibling,
 					};
 					dom.utils.removeItem(element);
 					recursionFunc(/** @type {Element} */ (parent));
@@ -346,26 +373,21 @@ NodeTransform.prototype = {
 		})(/** @type {Element} */ (item));
 
 		return cc;
-	},
+	}
 
 	/**
-	 * @this {NodeTransformThis}
 	 * @description Delete a empty child node of argument element
 	 * @param {Node} element Element node
 	 * @param {?Node} notRemoveNode Do not remove node
 	 * @param {boolean} forceDelete When all child nodes are deleted, the parent node is also deleted.
 	 */
 	removeEmptyNode(element, notRemoveNode, forceDelete) {
-		// eslint-disable-next-line @typescript-eslint/no-this-alias
-		const inst = this;
-		const allowedEmptyTags = this.options.get('allowedEmptyTags');
+		const allowedEmptyTags = this.#options.get('allowedEmptyTags');
 
-		if (notRemoveNode) {
-			notRemoveNode = dom.query.getParentElement(notRemoveNode, (current) => element === current.parentElement);
-		}
+		notRemoveNode &&= dom.query.getParentElement(notRemoveNode, (current) => element === current.parentElement);
 
-		(function recursionFunc(current) {
-			if (inst.format._notTextNode(current) || current === notRemoveNode || dom.check.isNonEditable(current)) return 0;
+		const recursionFunc = (current) => {
+			if (this.#$.format._isNotTextNode(current) || current === notRemoveNode || dom.check.isNonEditable(current)) return 0;
 			if (current !== element && dom.check.isZeroWidth(current.textContent) && (!current.firstChild || !dom.check.isBreak(current.firstChild)) && !current.querySelector(allowedEmptyTags)) {
 				if (current.parentNode) {
 					current.parentNode.removeChild(current);
@@ -374,13 +396,14 @@ NodeTransform.prototype = {
 			} else {
 				const children = current.children;
 				for (let i = 0, len = children.length, r = 0; i < len; i++) {
-					if (!children[i + r] || inst.component.is(children[i + r])) continue;
+					if (!children[i + r] || this.#$.component.is(children[i + r])) continue;
 					r += recursionFunc(children[i + r]);
 				}
 			}
 
 			return 0;
-		})(/** @type {Element} */ (element));
+		};
+		recursionFunc(/** @type {Element} */ (element));
 
 		if (element.childNodes.length === 0) {
 			if (forceDelete) {
@@ -389,13 +412,12 @@ NodeTransform.prototype = {
 				/** @type {HTMLElement} */ (element).innerHTML = '<br>';
 			}
 		}
-	},
+	}
 
 	/**
-	 * @this {NodeTransformThis}
 	 * @description Creates a nested node structure from the given array of nodes.
-	 * @param {__se__NodeCollection} nodeArray An array of nodes to clone. The first node in the array will be the top-level parent.
-	 * @param {?(current: Node) => boolean=} validate A validate function.
+	 * @param {SunEditor.NodeCollection} nodeArray An array of nodes to clone. The first node in the array will be the top-level parent.
+	 * @param {?(current: Node) => boolean} [validate] A validate function.
 	 * @returns {{ parent: Node, inner: Node }} An object containing the top-level parent node and the innermost child node.
 	 */
 	createNestedNode(nodeArray, validate) {
@@ -414,11 +436,9 @@ NodeTransform.prototype = {
 
 		return {
 			parent: el,
-			inner: n
+			inner: n,
 		};
-	},
-
-	constructor: NodeTransform
-};
+	}
+}
 
 export default NodeTransform;