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

package/src/helper/dom/domUtils.js

@@ -1,5 +1,48 @@
 import { _d, _w } from '../env';
-import check from './domCheck';
+import { isImportantDisabled } from './domCheck';
+import { htmlToEntity } from '../converter';
+
+// ----- iframe-safe type check [START] -----
+/**
+ * @description iframe-safe : Node type [`HTMLCollection`, `NodeList`, `Array`] check.
+ * @param {*} element
+ * @returns {element is HTMLCollection|NodeList|Array}
+ */
+function IsElementArray(element) {
+	const type = Object.prototype.toString.call(element);
+	return type === '[object HTMLCollection]' || type === '[object NodeList]' || type === '[object Array]';
+}
+
+/**
+ * @description iframe-safe: check if element is an `HTMLImageElement`
+ * @param {*} element
+ * @returns {element is HTMLImageElement}
+ */
+function IsHTMLImageElement(element) {
+	const type = Object.prototype.toString.call(element);
+	return type === '[object HTMLImageElement]';
+}
+
+/**
+ * @description iframe-safe: check if element is an `HTMLMediaElement` (video or audio)
+ * @param {*} element
+ * @returns {element is HTMLMediaElement}
+ */
+function IsHTMLMediaElement(element) {
+	const type = Object.prototype.toString.call(element);
+	return type === '[object HTMLVideoElement]' || type === '[object HTMLAudioElement]';
+}
+
+/**
+ * @description iframe-safe: check if element is an `HTMLIFrameElement`
+ * @param {*} element
+ * @returns {element is HTMLIFrameElement}
+ */
+function IsHTMLIFrameElement(element) {
+	const type = Object.prototype.toString.call(element);
+	return type === '[object HTMLIFrameElement]';
+}
+// ----- iframe-safe type check [END] -----
 
 /**
  * @template {Node} T
@@ -15,9 +58,19 @@ export function clone(node, deep = false) {
 /**
  * @template {HTMLElement} T
  * @description Create Element node
+ * @example
+ * // Create with attributes
+ * const span = dom.utils.createElement('SPAN', { style: 'color:red;', class: 'highlight' });
+ *
+ * // Create with HTML string content
+ * const div = dom.utils.createElement('DIV', null, '<p>Hello</p>');
+ *
+ * // Create with a child node
+ * const br = dom.utils.createElement('BR');
+ * const p = dom.utils.createElement('P', null, br);
  * @param {string} elementName Element name
- * @param {?Object<string, string>=} attributes The attributes of the tag. {style: 'font-size:12px;..', class: 'el_class',..}
- * @param {?string|Node=} inner A innerHTML string or inner node.
+ * @param {?Object<string, string>} [attributes] The attributes of the tag. {style: 'font-size:12px;..', class: 'el_class',..}
+ * @param {?string|Node} [inner] A innerHTML string or inner node.
  * @returns {T}
  */
 export function createElement(elementName, attributes, inner) {
@@ -52,7 +105,7 @@ export function createTextNode(text) {
 /**
  * @description Get attributes of argument element to string ('class="---" name="---" ')
  * @param {Node} element Element object
- * @param {Array<string>|null} exceptAttrs Array of attribute names to exclude from the result
+ * @param {?Array<string>} exceptAttrs Array of attribute names to exclude from the result
  * @returns {string}
  */
 export function getAttributesToString(element, exceptAttrs) {
@@ -62,7 +115,7 @@ export function getAttributesToString(element, exceptAttrs) {
 	let attrString = '';
 	for (let i = 0, len = attrs.length; i < len; i++) {
 		if (exceptAttrs?.includes(attrs[i].name)) continue;
-		attrString += attrs[i].name + '="' + attrs[i].value + '" ';
+		attrString += attrs[i].name + '="' + htmlToEntity(attrs[i].value) + '" ';
 	}
 
 	return attrString;
@@ -70,18 +123,15 @@ export function getAttributesToString(element, exceptAttrs) {
 
 /**
  * @description Get the items array from the array that matches the condition.
- * @param {__se__NodeCollection} array Array to get item
+ * @param {SunEditor.NodeCollection} array Array to get item
  * @param {?(current: *) => boolean} validation Conditional function
  * @returns {Array<Node>|null}
  */
 export function arrayFilter(array, validation) {
 	if (!array || array.length === 0) return null;
 
-	validation =
-		validation ||
-		function () {
-			return true;
-		};
+	validation ||= () => true;
+
 	const arr = [];
 
 	for (let i = 0, len = array.length, a; i < len; i++) {
@@ -96,18 +146,14 @@ export function arrayFilter(array, validation) {
 
 /**
  * @description Get the item from the array that matches the condition.
- * @param {__se__NodeCollection} array Array to get item
+ * @param {SunEditor.NodeCollection} array Array to get item
  * @param {?(current: *) => boolean} validation Conditional function
  * @returns {Node|null}
  */
 export function arrayFind(array, validation) {
 	if (!array || array.length === 0) return null;
 
-	validation =
-		validation ||
-		function () {
-			return true;
-		};
+	validation ||= () => true;
 
 	for (let i = 0, len = array.length, a; i < len; i++) {
 		a = array[i];
@@ -121,7 +167,7 @@ export function arrayFind(array, validation) {
 
 /**
  * @description Check if an array contains an element
- * @param {__se__NodeCollection} array element array
+ * @param {SunEditor.NodeCollection} array element array
  * @param {Node} node The node to check for
  * @returns {boolean}
  */
@@ -136,7 +182,7 @@ export function arrayIncludes(array, node) {
 
 /**
  * @description Get the index of the argument value in the element array
- * @param {__se__NodeCollection} array element array
+ * @param {SunEditor.NodeCollection} array element array
  * @param {Node} node The element to find index
  * @returns {number}
  */
@@ -154,7 +200,7 @@ export function getArrayIndex(array, node) {
 
 /**
  * @description Get the next index of the argument value in the element array
- * @param {__se__NodeCollection} array element array
+ * @param {SunEditor.NodeCollection} array element array
  * @param {Node} item The element to find index
  * @returns {number}
  */
@@ -166,7 +212,7 @@ export function nextIndex(array, item) {
 
 /**
  * @description Get the previous index of the argument value in the element array
- * @param {__se__NodeCollection} array Element array
+ * @param {SunEditor.NodeCollection} array Element array
  * @param {Node} item The element to find index
  * @returns {number}
  */
@@ -180,12 +226,12 @@ export function prevIndex(array, item) {
  * @description Add style and className of copyEl to originEl
  * @param {Node} originEl Origin element
  * @param {Node} copyEl Element to copy
- * @param {?Array<string>=} blacklist Blacklist array(LowerCase)
+ * @param {?Array<string>} [blacklist] Blacklist array(LowerCase)
  */
 export function copyTagAttributes(originEl, copyEl, blacklist) {
 	const o = /** @type {HTMLElement} */ (originEl);
 	const c = /** @type {HTMLElement} */ (copyEl);
-	if (c.style.cssText) {
+	if (c.style.length > 0) {
 		const copyStyles = c.style;
 		for (let i = 0, len = copyStyles.length; i < len; i++) {
 			o.style[copyStyles[i]] = copyStyles[copyStyles[i]];
@@ -201,7 +247,7 @@ export function copyTagAttributes(originEl, copyEl, blacklist) {
 }
 
 /**
- * @description Copy and apply attributes of format tag that should be maintained. (style, class) Ignore "__se__format__" class
+ * @description Copy and apply attributes of format tag that should be maintained. (style, class) Ignore `__se__format__` class
  * @param {Node} originEl Origin element
  * @param {Node} copyEl Element to copy
  */
@@ -255,7 +301,7 @@ export function changeTxt(node, txt) {
 /**
  * @description Set style, if all styles are deleted, the style properties are deleted.
  * @param {Node|Node[]} elements Element to set style
- * @param {string} styleName Style attribute name (marginLeft, textAlign...)
+ * @param {string} styleName Style attribute name (`marginLeft`, `textAlign`...)
  * @param {string|number} value Style value
  */
 export function setStyle(elements, styleName, value) {
@@ -264,7 +310,7 @@ export function setStyle(elements, styleName, value) {
 	for (let i = 0, len = elements.length, e; i < len; i++) {
 		e = /** @type {HTMLElement} */ (elements[i]);
 		e.style[styleName] = value;
-		if (!e.style.cssText) {
+		if (e.style.length === 0) {
 			e.removeAttribute('style');
 		}
 	}
@@ -273,8 +319,8 @@ export function setStyle(elements, styleName, value) {
 /**
  * @description Gets the style value of the element. If the elements is an array, the style of the first element is returned.
  * @param {Node} element Element to get style from.
- * @param {string} styleName Style attribute name (e.g., 'marginLeft', 'textAlign').
- * @returns {string | undefined} The value of the style attribute, or undefined if the element does not exist.
+ * @param {string} styleName Style attribute name (e.g., `marginLeft`, `textAlign`).
+ * @returns {string | undefined} The value of the style attribute, or `undefined` if the element does not exist.
  */
 export function getStyle(element, styleName) {
 	if (element?.nodeType !== 1) {
@@ -285,15 +331,15 @@ export function getStyle(element, styleName) {
 }
 
 /**
- * @description In the predefined code view mode, the buttons except the executable button are changed to the 'disabled' state.
- * @param {Array<HTMLButtonElement|HTMLInputElement>} buttonList (Button | Input) Element array
+ * @description In the predefined code view mode, the buttons except the executable button are changed to the `disabled` state.
+ * @param {SunEditor.NodeCollection} buttonList (Button | Input) Element array
  * @param {boolean} disabled Disabled value
  * @param {boolean} [important=false] If priveleged mode should be used (Necessary to switch importantDisabled buttons)
  */
 export function setDisabled(buttonList, disabled, important) {
 	for (let i = 0, len = buttonList.length; i < len; i++) {
-		const button = buttonList[i];
-		if (important || !check.isImportantDisabled(button)) button.disabled = disabled;
+		const button = /** @type {HTMLButtonElement|HTMLInputElement} */ (buttonList[i]);
+		if (important || !isImportantDisabled(button)) button.disabled = disabled;
 		if (important) {
 			if (disabled) {
 				button.setAttribute('data-important-disabled', '');
@@ -312,19 +358,18 @@ export function setDisabled(buttonList, disabled, important) {
  */
 export function hasClass(element, className) {
 	if (!element || element.nodeType !== 1) return;
-	const valid = new RegExp(`(\\s|^)${className}(\\s|$)`);
-	return valid.test(/** @type {HTMLElement} */ (element).className);
+	return /** @type {HTMLElement} */ (element).classList.contains(className);
 }
 
 /**
  * @description Append the className value of the argument value element
- * @param {Node|__se__NodeCollection} element Elements to add class name
+ * @param {Node|SunEditor.NodeCollection} element Elements to add class name
  * @param {string} className Class name to be add
  */
 export function addClass(element, className) {
 	if (!element) return;
 
-	const elements = element instanceof HTMLCollection || element instanceof NodeList || element instanceof Array ? element : [element];
+	const elements = IsElementArray(element) ? element : [element];
 	const classNames = className.split('|');
 
 	for (let i = 0, len = elements.length; i < len; i++) {
@@ -338,13 +383,13 @@ export function addClass(element, className) {
 
 /**
  * @description Delete the className value of the argument value element
- * @param {Node|__se__NodeCollection} element Elements to remove class name
+ * @param {Node|SunEditor.NodeCollection} element Elements to remove class name
  * @param {string} className Class name to be remove
  */
 export function removeClass(element, className) {
 	if (!element) return;
 
-	const elements = element instanceof HTMLCollection || element instanceof NodeList || element instanceof Array ? element : [element];
+	const elements = IsElementArray(element) ? element : [element];
 	const classNames = className.split('|');
 
 	for (let i = 0, len = elements.length; i < len; i++) {
@@ -402,7 +447,7 @@ export function flashClass(element, className, duration = 120) {
 export function getClientSize(doc = _d) {
 	return {
 		w: doc.documentElement.clientWidth,
-		h: doc.documentElement.clientHeight
+		h: doc.documentElement.clientHeight,
 	};
 }
 
@@ -415,22 +460,22 @@ export function getViewportSize() {
 		return {
 			top: _w.visualViewport.pageTop,
 			left: _w.visualViewport.pageLeft,
-			scale: _w.visualViewport.scale
+			scale: _w.visualViewport.scale,
 		};
 	}
 
 	return {
 		top: 0,
 		left: 0,
-		scale: 1
+		scale: 1,
 	};
 }
 
 /**
- * @description Copies the "wwTarget" element and returns it with inline all styles applied.
- * @param {Node} wwTarget Target element to copy(.sun-editor.sun-editor-editable)
- * @param {boolean} includeWW Include the "wwTarget" element in the copy
- * @param {Array<string>} styles Style list - kamel case
+ * @description Copies the `wwTarget` element and returns it with inline all styles applied.
+ * @param {Node} wwTarget Target element to copy(`.sun-editor.sun-editor-editable`)
+ * @param {boolean} includeWW Include the `wwTarget` element in the copy
+ * @param {Iterable<string>} styles Style list - kamel case
  * @returns
  */
 export function applyInlineStylesAll(wwTarget, includeWW, styles) {
@@ -494,19 +539,19 @@ export function waitForMediaLoad(target, timeout = 5000) {
 
 		const mediaPromises = mediaElements.map((element) => {
 			// image
-			if (element instanceof HTMLImageElement) {
+			if (IsHTMLImageElement(element)) {
 				if (element.complete) {
 					return Promise.resolve();
 				}
 			}
 			// video, audio
-			else if (element instanceof HTMLMediaElement) {
+			else if (IsHTMLMediaElement(element)) {
 				if (element.readyState >= 2) {
 					return Promise.resolve();
 				}
 			}
 			// iframe
-			else if (element instanceof HTMLIFrameElement) {
+			else if (IsHTMLIFrameElement(element)) {
 				try {
 					if (element.contentDocument?.readyState === 'complete') {
 						return Promise.resolve();
@@ -529,6 +574,24 @@ export function waitForMediaLoad(target, timeout = 5000) {
 	});
 }
 
+/**
+ * @description Gets a CSS variable on the root element of the editor.
+ * @param {string} name - The CSS variable name (e.g. `--se-color-primary`)
+ * @return {string} The value of the CSS variable
+ */
+export function getRootCssVar(name) {
+	return _d.documentElement.style.getPropertyValue(name);
+}
+
+/**
+ * @description Sets a CSS variable on the root element of the editor.
+ * @param {string} name - The CSS variable name (e.g. `--se-color-primary`)
+ * @param {string} value - The CSS variable value
+ */
+export function setRootCssVar(name, value) {
+	_d.documentElement.style.setProperty(name, value);
+}
+
 /**
  * @description Create tooltip HTML
  * @param {string} text Tooltip text
@@ -566,7 +629,9 @@ const utils = {
 	getViewportSize,
 	applyInlineStylesAll,
 	waitForMediaLoad,
-	createTooltipInner
+	getRootCssVar,
+	setRootCssVar,
+	createTooltipInner,
 };
 
 export default utils;

package/src/helper/dom/index.js

@@ -6,7 +6,11 @@ import utils from './domUtils';
 const dom = {
 	query,
 	check,
-	utils
+	utils,
 };
 
+export const domQuery = query;
+export const domCheck = check;
+export const domUtils = utils;
+
 export default dom;

package/src/helper/env.js

@@ -1,9 +1,5 @@
-/**
- * @fileoverview Environment  helper functions
- */
-
-/** @type {Window} */
-export const _w = window;
+/** @type {SunEditor.GlobalWindow} */
+export const _w = /** @type {SunEditor.GlobalWindow} */ (window);
 /** @type {Document} */
 export const _d = document;
 
@@ -22,7 +18,7 @@ export const ON_OVER_COMPONENT = Symbol('onOverComponent');
 const userAgent = navigator.userAgent.toLowerCase();
 
 /**
- * @description Gets XMLHttpRequest object
+ * @description Gets `XMLHttpRequest` object
  * @returns {XMLHttpRequest}
  */
 export function getXMLHttpRequest() {
@@ -32,7 +28,7 @@ export function getXMLHttpRequest() {
 /**
  * @deprecated
  * @description Returns the CSS text that has been applied to the current page.
- * @param {Document|null} doc To get the CSS text of an document. If null get the current document.
+ * @param {?Document} doc To get the CSS text of an document. If `null` get the current document.
  * @returns {string} Styles string
  */
 export function getPageStyle(doc) {
@@ -40,13 +36,11 @@ export function getPageStyle(doc) {
 	const sheets = (doc || _d).styleSheets;
 
 	for (let i = 0, len = sheets.length, rules; i < len; i++) {
-		/* eslint-disable @typescript-eslint/no-unused-vars */
 		try {
 			rules = sheets[i].cssRules;
-		} catch (e) {
+		} catch {
 			continue;
 		}
-		/* eslint-disable @typescript-eslint/no-unused-vars */
 
 		if (rules) {
 			for (let c = 0, cLen = rules.length; c < cLen; c++) {
@@ -63,7 +57,7 @@ export function getPageStyle(doc) {
  * @description Get the the tag path of the arguments value
  * @param {Array<string>} nameArray File name array
  * @param {string} extension js, css
- * @returns {string} If not found, return the first found value
+ * @returns {string} If not found, return the first found value.
  */
 export function getIncludePath(nameArray, extension) {
 	let path = '';
@@ -93,34 +87,33 @@ export function getIncludePath(nameArray, extension) {
 		}
 	}
 
+	if (!path) {
+		throw new Error('[SUNEDITOR.helper.env.getIncludePath.fail] The SUNEDITOR installation path could not be automatically detected. (path: +' + path + ', extension: ' + extension + ')');
+	}
+
 	if (path === '') path = pathList.length > 0 ? pathList[0][src] : '';
 
 	if (!path.includes(':/') && '//' !== path.slice(0, 2)) {
 		path = false === path.includes('/') ? location.href.match(/^.*?:\/\/[^/]*/)[0] + path : location.href.match(/^[^?]*\/(?:)/)[0] + path;
 	}
 
-	if (!path) {
-		throw '[SUNEDITOR.helper.env.getIncludePath.fail] The SUNEDITOR installation path could not be automatically detected. (path: +' + path + ', extension: ' + extension + ')';
-	}
-
 	return path;
 }
 
 /** --- Check browser --- */
 /**
- * @description Check if support ResizeObserver function
- * @returns {boolean} Whether support ResizeObserver function or not.
+ * @description Check if support `ResizeObserver` function
+ * @returns {boolean} Whether support `ResizeObserver` function or not.
  */
 export const isResizeObserverSupported = (() => {
 	return typeof ResizeObserver === 'function';
 })();
 
 /**
- * @description Check if support navigator.clipboard
- * @returns {boolean} Whether support navigator.clipboard or not.
+ * @description Check if support `navigator.clipboard`
+ * @returns {boolean} Whether support `navigator.clipboard` or not.
  */
 export const isClipboardSupported = (() => {
-	/* eslint-disable-next-line compat/compat */
 	return typeof navigator.clipboard?.write === 'function';
 })();
 
@@ -161,7 +154,7 @@ export const isGecko = (() => {
  * @type {boolean}
  */
 export const isChromium = (() => {
-	return !!(/** @type {Window & { chrome: any }} */ (_w).chrome);
+	return !!(/** @type {window & { chrome: any }} */ (_w).chrome);
 })();
 
 /**
@@ -174,12 +167,18 @@ export const isSafari = (() => {
 
 /**
  * @description Check if User Agent is Mobile device.
- * - when the device is touchable, it is judged as a mobile device.
  * @type {boolean}
  */
 export const isMobile = (() => {
-	/* eslint-disable-next-line compat/compat */
-	return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(userAgent) || (navigator.maxTouchPoints > 0 && 'ontouchstart' in _w);
+	return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(userAgent);
+})();
+
+/**
+ * @description Check if the device is touchable.
+ * @type {boolean}
+ */
+export const isTouchDevice = (() => {
+	return navigator.maxTouchPoints > 0 && 'ontouchstart' in _w;
 })();
 
 /**
@@ -230,11 +229,12 @@ const env = {
 	isOSX_IOS,
 	isAndroid,
 	isMobile,
+	isTouchDevice,
 	cmdIcon,
 	shiftIcon,
 	DPI,
 	KATEX_WEBSITE,
-	MATHJAX_WEBSITE
+	MATHJAX_WEBSITE,
 };
 
 export default env;

package/src/helper/index.js

@@ -21,5 +21,5 @@ export default {
 	dom,
 	numbers,
 	keyCodeMap,
-	clipboard
+	clipboard,
 };