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

package/src/helper/dom/domQuery.js

@@ -1,7 +1,4 @@
-/**
- * @fileoverview Implements Helper for querying the DOM.
- */
-
+import { _w } from '../env';
 import { zeroWidthRegExp } from '../unicode';
 import domUtils from './domUtils';
 import domCheck from './domCheck';
@@ -20,12 +17,12 @@ export function getPositionIndex(node) {
 }
 
 /**
- * @description Returns the position of the "node" in the "parentNode" in a numerical array.
+ * @description Returns the position of the `node` in the `parentNode` in a numerical array.
  * - e.g.) <p><span>aa</span><span>bb</span></p> : getNodePath(node: "bb", parentNode: "<P>") -> [1, 0]
  * @param {Node} node The Node to find position path
- * @param {?Node} parentNode Parent node. If null, wysiwyg div area
- * @param {?{s: number, e: number}=} _newOffsets If you send an object of the form "{s: 0, e: 0}", the text nodes that are attached together are merged into one, centered on the "node" argument.
- * "_newOffsets.s" stores the length of the combined characters after "node" and "_newOffsets.e" stores the length of the combined characters before "node".
+ * @param {?Node} parentNode Parent node. If `null`, wysiwyg `div` area
+ * @param {?{s: number, e: number}} [_newOffsets] If you send an object of the form `{s: 0, e: 0}`, the text nodes that are attached together are merged into one, centered on the `node` argument.
+ * `_newOffsets.s` stores the length of the combined characters after `node` and `_newOffsets.e` stores the length of the combined characters before `node`.
  * Do not use unless absolutely necessary.
  * @returns {Array<number>}
  */
@@ -74,8 +71,8 @@ export function getNodePath(node, parentNode, _newOffsets) {
 
 /**
  * @template {Node} T
- * @description Returns the node in the location of the path array obtained from "helper.dom.getNodePath".
- * @param {Array<number>} offsets Position array, array obtained from "helper.dom.getNodePath"
+ * @description Returns the node in the location of the path array obtained from `helper.dom.getNodePath`.
+ * @param {Array<number>} offsets Position array, array obtained from `helper.dom.getNodePath`
  * @param {Node} parentNode Base parent element
  * @returns {T}
  */
@@ -98,74 +95,111 @@ export function getNodeFromPath(offsets, parentNode) {
 
 /**
  * @template {HTMLElement} T
- * @description Get all "children" of the argument value element (Without text nodes)
+ * @description Get all `child node` of the argument value element
+ * @param {Node} element element to get child node
+ * @param {?(current: *) => boolean} validation Conditional function
+ * @returns {T|null}
+ */
+export function getChildNode(element, validation) {
+	let child = null;
+	if (!element) return child;
+
+	const el = /** @type {Element} */ (element);
+	if (!el.children || el.children.length === 0) return child;
+
+	validation ||= () => true;
+
+	(function recursionFunc(current) {
+		if (el !== current && validation(current)) {
+			child = current;
+			return true;
+		}
+
+		if (current.children) {
+			for (let i = 0, len = current.children.length; i < len; i++) {
+				recursionFunc(current.children[i]);
+			}
+		}
+	})(el);
+
+	return /** @type {T} */ (child);
+}
+
+/**
+ * @template {HTMLElement} T
+ * @description Get all `children` of the argument value element (Without text nodes)
  * @param {Node} element element to get child node
  * @param {?(current: *) => boolean} validation Conditional function
+ * @param {?number} depth Number of child levels to depth.
  * @returns {Array<T>}
  */
-export function getListChildren(element, validation) {
+export function getListChildren(element, validation, depth) {
 	/** @type {Array<T>} */
 	const children = [];
-	if (!element) return children;
+	depth ??= Infinity;
+	if (!element || depth <= 0) return /** @type {Array<T>} */ (children);
 
 	const el = /** @type {Element} */ (element);
 	if (!el.children || el.children.length === 0) return children;
 
-	validation =
-		validation ||
-		function () {
-			return true;
-		};
+	validation ||= () => true;
 
-	(function recursionFunc(current) {
-		if (el !== current && validation(current)) {
+	(function recursionFunc(current, level) {
+		if (level > depth) return;
+
+		if (level > 0 && el !== current && validation(current)) {
 			children.push(/** @type {T} */ (current));
 		}
 
+		if (level === depth) return;
+
 		if (current.children) {
 			for (let i = 0, len = current.children.length; i < len; i++) {
-				recursionFunc(current.children[i]);
+				recursionFunc(current.children[i], level + 1);
 			}
 		}
-	})(el);
+	})(el, 0);
 
 	return /** @type {Array<T>} */ (children);
 }
 
 /**
  * @template {Node} T
- * @description Get all "childNodes" of the argument value element (Include text nodes)
+ * @description Get all `childNodes` of the argument value element (Include text nodes)
  * @param {Node} element element to get child node
  * @param {?(current: *) => boolean} validation Conditional function
+ * @param {?number} depth Number of child levels to depth.
  * @returns {Array<T>}
  */
-export function getListChildNodes(element, validation) {
+export function getListChildNodes(element, validation, depth) {
 	const children = [];
-	if (!element || element.childNodes.length === 0) return children;
+	depth ??= Infinity;
+	if (!element || depth <= 0 || element.childNodes.length === 0) return /** @type {Array<T>} */ (children);
 
-	validation =
-		validation ||
-		function () {
-			return true;
-		};
+	validation ||= () => true;
 
-	(function recursionFunc(current) {
-		if (element !== current && validation(current)) {
+	(function recursionFunc(current, level) {
+		if (level > depth) return;
+
+		if (level > 0 && validation(current)) {
 			children.push(current);
 		}
 
-		for (let i = 0, len = current.childNodes.length; i < len; i++) {
-			recursionFunc(current.childNodes[i]);
+		if (level === depth) return;
+
+		const nodes = current.childNodes;
+		for (let i = 0, len = nodes.length; i < len; i++) {
+			recursionFunc(nodes[i], level + 1);
 		}
-	})(element);
+	})(element, 0);
 
 	return /** @type {Array<T>} */ (children);
 }
 
 /**
  * @description Returns the number of parents nodes.
- * - "0" when the parent node is the WYSIWYG area.
- * - '-1' when the element argument is the WYSIWYG area.
+ * - `0` when the parent node is the WYSIWYG area.
+ * - `-1` when the element argument is the WYSIWYG area.
  * @param {Node} node The element to check
  * @returns {number}
  */
@@ -186,7 +220,7 @@ export function getNodeDepth(node) {
 /**
  * @description Sort a node array by depth of element.
  * @param {Array<Node>} array Node array
- * @param {boolean} des true: descending order / false: ascending order
+ * @param {boolean} des `true`: descending order / `false`: ascending order
  */
 export function sortNodeByDepth(array, des) {
 	const t = !des ? -1 : 1;
@@ -204,22 +238,41 @@ export function sortNodeByDepth(array, des) {
  * @description Compares two elements to find a common ancestor, and returns the order of the two elements.
  * @param {Node} a Node to compare.
  * @param {Node} b Node to compare.
- * @returns {{ancestor: HTMLElement|null, a: Node, b: Node, result: number}} { ancesstor, a, b, result: (a > b ? 1 : a < b ? -1 : 0) };
+ * @returns {{ancestor: ?HTMLElement, a: Node, b: Node, result: number}} { ancesstor, a, b, result: (a > b ? 1 : a < b ? -1 : 0) };
  */
 export function compareElements(a, b) {
 	let aNode = a,
 		bNode = b;
+
+	// Equalize depth
+	const aDepth = getNodeDepth(a);
+	const bDepth = getNodeDepth(b);
+
+	if (aDepth > bDepth) {
+		let diff = aDepth - bDepth;
+		while (diff > 0 && aNode) {
+			aNode = aNode.parentElement;
+			diff--;
+		}
+	} else if (bDepth > aDepth) {
+		let diff = bDepth - aDepth;
+		while (diff > 0 && bNode) {
+			bNode = bNode.parentElement;
+			diff--;
+		}
+	}
+
 	while (aNode && bNode && aNode.parentElement !== bNode.parentElement) {
 		aNode = aNode.parentElement;
 		bNode = bNode.parentElement;
 	}
 
-	if (!aNode || !bNode)
+	if (!aNode?.parentNode || !bNode?.parentNode)
 		return {
 			ancestor: null,
 			a: a,
 			b: b,
-			result: 0
+			result: 0,
 		};
 
 	const children = aNode.parentNode.childNodes;
@@ -230,7 +283,7 @@ export function compareElements(a, b) {
 		ancestor: aNode.parentElement,
 		a: aNode,
 		b: bNode,
-		result: aIndex > bIndex ? 1 : aIndex < bIndex ? -1 : 0
+		result: aIndex > bIndex ? 1 : aIndex < bIndex ? -1 : 0,
 	};
 }
 
@@ -238,12 +291,21 @@ export function compareElements(a, b) {
  * @template {HTMLElement} T
  * @description Get the parent element of the argument value.
  * - A tag that satisfies the query condition is imported.
+ * @example
+ * // Find by tag name
+ * const table = dom.query.getParentElement(cell, 'TABLE');
+ *
+ * // Find by CSS class
+ * const wrapper = dom.query.getParentElement(node, '.se-wrapper');
+ *
+ * // Find by validation function
+ * const line = dom.query.getParentElement(node, (el) => el.nodeType === 1);
  * @param {Node} element Reference element
- * @param {string|((current: *) => boolean)|Node} query Query String (nodeName, .className, #ID, :name) or validation function.
+ * @param {string|((current: *) => boolean)|Node} query Query String (`nodeName`, `.className`, `#ID`, `:name`) or validation function.
  * - Not use it like jquery.
  * - Only one condition can be entered at a time.
- * @param {?number=} depth Number of parent levels to depth.
- * @returns {T|null} Not found: null
+ * @param {?number} [depth] Number of parent levels to depth.
+ * @returns {T|null} Not found: `null`
  */
 export function getParentElement(element, query, depth) {
 	let valid;
@@ -274,7 +336,7 @@ export function getParentElement(element, query, depth) {
 		valid = (el) => regExp.test(el[attr]);
 	}
 
-	if (!depth) depth = Infinity;
+	depth ||= Infinity;
 	let index = 0;
 	while (element && !valid(element)) {
 		if (index >= depth || domCheck.isWysiwygFrame(element)) {
@@ -292,10 +354,10 @@ export function getParentElement(element, query, depth) {
  * @description Gets all ancestors of the argument value.
  * - Get all tags that satisfy the query condition.
  * @param {Node} element Reference element
- * @param {string|((current: *) => boolean)|Node} query Query String (nodeName, .className, #ID, :name) or validation function.
+ * @param {string|((current: *) => boolean)|Node} query Query String (`nodeName`, `.className`, `#ID`, `:name`) or validation function.
  * Not use it like jquery.
  * Only one condition can be entered at a time.
- * @param {?number=} depth Number of parent levels to depth.
+ * @param {?number} [depth] Number of parent levels to depth.
  * @returns {Array<T>} Returned in an array in order.
  */
 export function getParentElements(element, query, depth) {
@@ -328,7 +390,7 @@ export function getParentElements(element, query, depth) {
 	}
 
 	const elementList = [];
-	if (!depth) depth = Infinity;
+	depth ||= Infinity;
 	let index = 0;
 	while (index <= depth && element && !domCheck.isWysiwygFrame(element)) {
 		if (valid(element)) {
@@ -343,7 +405,7 @@ export function getParentElements(element, query, depth) {
 
 /**
  * @template {HTMLElement} T
- * @description Gets the element with "data-command" attribute among the parent elements.
+ * @description Gets the element with `data-command` attribute among the parent elements.
  * @param {Node} target Target element
  * @returns {T|null}
  */
@@ -372,11 +434,11 @@ export function getEventTarget(event) {
  * @description Get the child element of the argument value.
  * - A tag that satisfies the query condition is imported.
  * @param {Node} node Reference element
- * @param {string|((current: *) => boolean)|Node} query Query String (nodeName, .className, #ID, :name) or validation function.
- * @param {boolean} last If true returns the last node among the found child nodes. (default: first node)
+ * @param {string|((current: *) => boolean)|Node} query Query String (`nodeName`, `.className`, `#ID`, `:name`) or validation function.
+ * @param {boolean} last If `true` returns the last node among the found child nodes. (default: first node)
  * Not use it like jquery.
  * Only one condition can be entered at a time.
- * @returns {T|null} Not found: null
+ * @returns {T|null} Not found: `null`
  */
 export function getEdgeChild(node, query, last) {
 	let valid;
@@ -409,30 +471,30 @@ export function getEdgeChild(node, query, last) {
 		};
 	}
 
-	const childList = getListChildNodes(node, (current) => valid(current));
+	const childList = getListChildNodes(node, (current) => valid(current), null);
 
 	return /** @type {T} */ (childList[last ? childList.length - 1 : 0]);
 }
 
 /**
  * @description Get edge child nodes of the argument value.
- * - 1. The first node of all the child nodes of the "first" element is returned.
- * - 2. The last node of all the child nodes of the "last" element is returned.
- * - 3. When there is no "last" element, the first and last nodes of all the children of the "first" element are returned.
+ * - 1. The first node of all the child nodes of the `first` element is returned.
+ * - 2. The last node of all the child nodes of the `last` element is returned.
+ * - 3. When there is no `last` element, the first and last nodes of all the children of the `first` element are returned.
  * @param {Node} first First element
- * @param {Node|null} last Last element
- * @returns {{sc: Node, ec: Node}} { sc: "first", ec: "last" }
+ * @param {?Node} last Last element
+ * @returns {{sc: Node, ec: Node}} { sc: `first`, ec: `last` }
  */
 export function getEdgeChildNodes(first, last) {
 	if (!first) return;
-	if (!last) last = first;
+	last ||= first;
 
 	while (first && first.nodeType === 1 && first.childNodes.length > 0 && !domCheck.isBreak(first)) first = first.firstChild;
 	while (last && last.nodeType === 1 && last.childNodes.length > 0 && !domCheck.isBreak(last)) last = last.lastChild;
 
 	return {
 		sc: first,
-		ec: last || first
+		ec: last || first,
 	};
 }
 
@@ -440,8 +502,8 @@ export function getEdgeChildNodes(first, last) {
  * @template {Node} T
  * @description Gets the previous sibling last child. If there is no sibling, then it'll take it from the closest ancestor with child
  * @param {Node} node Reference element
- * @param {?Node=} ceiling Highest boundary allowed
- * @returns {T|null} Not found: null
+ * @param {?Node} [ceiling] Highest boundary allowed
+ * @returns {T|null} Not found: `null`
  */
 export function getPreviousDeepestNode(node, ceiling) {
 	let previousNode = node.previousSibling;
@@ -467,8 +529,8 @@ export function getPreviousDeepestNode(node, ceiling) {
  * @template {Node} T
  * @description Gets the next sibling first child. If there is no sibling, then it'll take it from the closest ancestor with child
  * @param {Node} node Reference element
- * @param {?Node=} ceiling Highest boundary allowed
- * @returns {T|null} Not found: null
+ * @param {?Node} [ceiling] Highest boundary allowed
+ * @returns {T|null} Not found: `null`
  */
 export function getNextDeepestNode(node, ceiling) {
 	let nextNode = node.nextSibling;
@@ -491,16 +553,16 @@ export function getNextDeepestNode(node, ceiling) {
 }
 
 /**
- * @description Find the index of the text node in the line element.
- * @param {Node} line Line element (p, div, etc.)
+ * @description Find the index of the text node in the `line` element.
+ * @param {Node} line `line` element (p, div, etc.)
  * @param {Node} offsetContainer Base node to start searching
  * @param {number} offset Base offset to start searching
- * @param {?(current: *) => boolean=} validate Validation function
+ * @param {?(current: *) => boolean} [validate] Validation function
  * @returns {number}
  */
 export function findTextIndexOnLine(line, offsetContainer, offset, validate) {
 	if (!line) return 0;
-	if (!validate) validate = () => true;
+	validate ||= () => true;
 
 	let index = 0;
 	let found = false;
@@ -531,7 +593,7 @@ export function findTextIndexOnLine(line, offsetContainer, offset, validate) {
 /**
  * @description Find the end index of a sequence of at least minTabSize consecutive non-breaking spaces or spaces
  * - which are interpreted as a tab key, occurring after a given base index in a text string.
- * @param {Node} line Line element (p, div, etc.)
+ * @param {Node} line `line` element (p, div, etc.)
  * @param {number} baseIndex Base index to start searching
  * @param {number} minTabSize Minimum number of consecutive spaces to consider as a tab
  * @returns {number} The adjusted index within the line element accounting for non-space characters
@@ -558,7 +620,7 @@ export function findTabEndIndex(line, baseIndex, minTabSize) {
 
 /**
  * @description Finds the table cell that appears visually at the bottom-right position,
- * considering both rowSpan and colSpan, even if smaller cells are placed after large merged cells.
+ * considering both `rowSpan` and `colSpan`, even if smaller cells are placed after large merged cells.
  *
  * @param {HTMLTableCellElement[]} cells
  * @returns {HTMLTableCellElement|null}
@@ -583,7 +645,7 @@ export function findVisualLastCell(cells) {
 		const colSpan = cell.colSpan || 1;
 
 		// 현재 행에서 visual column index 찾기
-		if (!occupied[rowIndex]) occupied[rowIndex] = [];
+		occupied[rowIndex] ||= [];
 
 		let colIndex = 0;
 		const rowOcc = occupied[rowIndex];
@@ -595,7 +657,7 @@ export function findVisualLastCell(cells) {
 
 		for (let r = 1; r < rowSpan; r++) {
 			const nextRow = rowIndex + r;
-			if (!occupied[nextRow]) occupied[nextRow] = [];
+			occupied[nextRow] ||= [];
 			for (let i = 0; i < colSpan; i++) {
 				occupied[nextRow][colIndex + i] = true;
 			}
@@ -616,26 +678,33 @@ export function findVisualLastCell(cells) {
 }
 
 /**
- * @description Get nearest scrollable parent
- * @param {Node} element Element
- * @returns {HTMLElement|null}
+ * @description Finds and returns parent containers that are scrollable.
+ * @param {HTMLElement} element - Element to start with
+ * @returns {HTMLElement[]} - Array (in descending order)
  */
-export function getScrollParent(element) {
-	if (!element || /^(body|html)$/i.test(element.nodeName)) {
-		return null;
-	}
+export function getScrollParents(element) {
+	const scrollable = [];
+	let parent = element?.parentElement;
 
-	const el = /** @type {HTMLElement} */ (element);
-	if (el.scrollHeight > el.clientHeight) {
-		return el;
-	} else {
-		return getScrollParent(el.parentNode);
+	while (parent && !/^(body|html)$/i.test(parent.nodeName)) {
+		const style = _w.getComputedStyle(parent);
+		const { overflow, overflowX, overflowY } = style;
+
+		const canScroll = [overflow, overflowX, overflowY].some((prop) => ['auto', 'scroll', 'overlay'].includes(prop));
+
+		if (canScroll) {
+			scrollable.push(parent);
+		}
+
+		parent = parent.parentElement;
 	}
+
+	return scrollable;
 }
 
 /**
- * @description Get the argument iframe's document object if use the "iframe" or "fullPage" options
- * @param {HTMLIFrameElement} iframe Iframe element (this.editor.frameContext.get('wysiwygFrame'))
+ * @description Get the argument iframe's document object if use the `iframe` or `fullPage` options
+ * @param {HTMLIFrameElement} iframe Iframe element (`this.frameContext.get('wysiwygFrame')`)
  * @returns {Document}
  */
 export function getIframeDocument(iframe) {
@@ -646,6 +715,7 @@ const query = {
 	getPositionIndex,
 	getNodePath,
 	getNodeFromPath,
+	getChildNode,
 	getListChildren,
 	getListChildNodes,
 	getNodeDepth,
@@ -662,8 +732,8 @@ const query = {
 	findTextIndexOnLine,
 	findTabEndIndex,
 	findVisualLastCell,
-	getScrollParent,
-	getIframeDocument
+	getScrollParents,
+	getIframeDocument,
 };
 
 export default query;