suneditor 3.0.0-rc.4 → 3.0.0

package/src/helper/converter.js

@@ -114,6 +114,8 @@ export function jsonToHtml(jsonData) {
  * @description Convert HTML string to HTML Entity
  * @param {string} content
  * @returns {string} Content string
+ * @example
+ * converter.htmlToEntity('<div>'); // '&lt;div&gt;'
  */
 export function htmlToEntity(content) {
 	return content.replace(_RE_HTML_CHARS, (m) => {
@@ -125,6 +127,8 @@ export function htmlToEntity(content) {
  * @description Convert HTML Entity to HTML string
  * @param {string} content Content string
  * @returns {string}
+ * @example
+ * converter.entityToHTML('&lt;div&gt;'); // '<div>'
  */
 export function entityToHTML(content) {
 	return content.replace(_RE_HTML_ENTITIES, (m) => {
@@ -137,6 +141,9 @@ export function entityToHTML(content) {
  * @param {(...args: *) => void} func function
  * @param {number} wait delay ms
  * @returns {*} executedFunction
+ * @example
+ * const debouncedSave = converter.debounce(() => save(), 300);
+ * input.addEventListener('input', debouncedSave);
  */
 export function debounce(func, wait) {
 	let timeout;
@@ -206,6 +213,9 @@ export function getValues(obj) {
 /**
  * @description Convert the `CamelCase` To the `KebabCase`.
  * @param {string|Array<string>} param [Camel string]
+ * @example
+ * converter.camelToKebabCase('fontSize'); // 'font-size'
+ * converter.camelToKebabCase(['fontSize', 'fontFamily']); // ['font-size', 'font-family']
  */
 export function camelToKebabCase(param) {
 	if (typeof param === 'string') {
@@ -226,6 +236,8 @@ export function camelToKebabCase(param) {
  * @overload
  * @param {Array<string>} param - Array of `Kebab-case` strings.
  * @returns {Array<string>} Array of `CamelCase` strings.
+ * @example
+ * converter.kebabToCamelCase('font-size'); // 'fontSize'
  */
 export function kebabToCamelCase(param) {
 	if (typeof param === 'string') {
@@ -334,6 +346,9 @@ export function isHexColor(str) {
  * @description Function to convert hex format to a `rgb` color
  * @param {string} rgba RGBA color format
  * @returns {string}
+ * @example
+ * converter.rgb2hex('rgb(255, 0, 0)'); // '#ff0000'
+ * converter.rgb2hex('rgba(255, 0, 0, 0.5)'); // '#ff000080'
  */
 export function rgb2hex(rgba) {
 	if (isHexColor(rgba) || !rgba) return rgba;

package/src/helper/dom/domQuery.js

@@ -75,6 +75,8 @@ export function getNodePath(node, parentNode, _newOffsets) {
  * @param {Array<number>} offsets Position array, array obtained from `helper.dom.getNodePath`
  * @param {Node} parentNode Base parent element
  * @returns {T}
+ * @example
+ * const node = dom.query.getNodeFromPath([0, 1, 0], wysiwygElement);
  */
 export function getNodeFromPath(offsets, parentNode) {
 	let current = parentNode;
@@ -170,6 +172,8 @@ export function getListChildren(element, validation, depth) {
  * @param {?(current: *) => boolean} validation Conditional function
  * @param {?number} depth Number of child levels to depth.
  * @returns {Array<T>}
+ * @example
+ * const allNodes = dom.query.getListChildNodes(container, (node) => node.nodeType === 3);
  */
 export function getListChildNodes(element, validation, depth) {
 	const children = [];
@@ -221,6 +225,8 @@ 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
+ * @example
+ * const sorted = dom.query.sortNodeByDepth([nodeA, nodeB], true);
  */
 export function sortNodeByDepth(array, des) {
 	const t = !des ? -1 : 1;
@@ -239,6 +245,9 @@ export function sortNodeByDepth(array, des) {
  * @param {Node} a Node to compare.
  * @param {Node} b Node to compare.
  * @returns {{ancestor: ?HTMLElement, a: Node, b: Node, result: number}} { ancesstor, a, b, result: (a > b ? 1 : a < b ? -1 : 0) };
+ * @example
+ * const result = dom.query.compareElements(nodeA, nodeB);
+ * // result: { ancestor: true, result: 0 } (same node), { ancestor: true, result: 1 } (a before b)
  */
 export function compareElements(a, b) {
 	let aNode = a,
@@ -439,6 +448,9 @@ export function getEventTarget(event) {
  * Not use it like jquery.
  * Only one condition can be entered at a time.
  * @returns {T|null} Not found: `null`
+ * @example
+ * const firstLeaf = dom.query.getEdgeChild(container, (n) => n.nodeType === 3, false);
+ * const lastLeaf = dom.query.getEdgeChild(container, (n) => n.nodeType === 3, true);
  */
 export function getEdgeChild(node, query, last) {
 	let valid;

package/src/helper/dom/domUtils.js

@@ -107,6 +107,8 @@ export function createTextNode(text) {
  * @param {Node} element Element object
  * @param {?Array<string>} exceptAttrs Array of attribute names to exclude from the result
  * @returns {string}
+ * @example
+ * const attrs = dom.utils.getAttributesToString(element, ['id', 'class']);
  */
 export function getAttributesToString(element, exceptAttrs) {
 	const attrs = /** @type {HTMLElement} */ (element).attributes;
@@ -227,6 +229,8 @@ export function prevIndex(array, item) {
  * @param {Node} originEl Origin element
  * @param {Node} copyEl Element to copy
  * @param {?Array<string>} [blacklist] Blacklist array(LowerCase)
+ * @example
+ * dom.utils.copyTagAttributes(newElement, originalElement, ['contenteditable']);
  */
 export function copyTagAttributes(originEl, copyEl, blacklist) {
 	const o = /** @type {HTMLElement} */ (originEl);
@@ -271,6 +275,9 @@ export function removeItem(item) {
  * @description Replace element
  * @param {Node} element Target element
  * @param {string|Node} newElement String or element of the new element to apply
+ * @example
+ * dom.utils.changeElement(oldSpan, 'STRONG');
+ * dom.utils.changeElement(oldElement, newElement);
  */
 export function changeElement(element, newElement) {
 	if (!element) return;
@@ -303,6 +310,9 @@ export function changeTxt(node, txt) {
  * @param {Node|Node[]} elements Element to set style
  * @param {string} styleName Style attribute name (`marginLeft`, `textAlign`...)
  * @param {string|number} value Style value
+ * @example
+ * dom.utils.setStyle(element, 'color', 'red');
+ * dom.utils.setStyle([el1, el2], 'display', 'none');
  */
 export function setStyle(elements, styleName, value) {
 	elements = Array.isArray(elements) ? elements : [elements];
@@ -358,13 +368,17 @@ export function setDisabled(buttonList, disabled, important) {
  */
 export function hasClass(element, className) {
 	if (!element || element.nodeType !== 1) return;
-	return /** @type {HTMLElement} */ (element).classList.contains(className);
+
+	return className.split('|').some((cls) => /** @type {HTMLElement} */ (element).classList.contains(cls));
 }
 
 /**
  * @description Append the className value of the argument value element
  * @param {Node|SunEditor.NodeCollection} element Elements to add class name
  * @param {string} className Class name to be add
+ * @example
+ * dom.utils.addClass(element, 'active');
+ * dom.utils.addClass(element.children, 'highlight');
  */
 export function addClass(element, className) {
 	if (!element) return;
@@ -385,6 +399,8 @@ export function addClass(element, className) {
  * @description Delete the className value of the argument value element
  * @param {Node|SunEditor.NodeCollection} element Elements to remove class name
  * @param {string} className Class name to be remove
+ * @example
+ * dom.utils.removeClass(element, 'active');
  */
 export function removeClass(element, className) {
 	if (!element) return;
@@ -405,25 +421,15 @@ export function removeClass(element, className) {
  * @description Argument value If there is no class name, insert it and delete the class name if it exists
  * @param {Node} element Element to replace class name
  * @param {string} className Class name to be change
- * @returns {boolean|undefined}
+ * @param {boolean} [force] If true, adds the class; if false, removes it.
  */
-export function toggleClass(element, className) {
+export function toggleClass(element, className, force) {
 	if (!element || element.nodeType !== 1) return;
 
 	const el = /** @type {HTMLElement} */ (element);
-
-	let result = false;
-	const valid = new RegExp(`(\\s|^)${className}(\\s|$)`);
-	if (valid.test(el.className)) {
-		el.className = el.className.replace(valid, ' ').trim();
-	} else {
-		el.className += ' ' + className;
-		result = true;
-	}
+	el.classList.toggle(className, force);
 
 	if (!el.className.trim()) el.removeAttribute('class');
-
-	return result;
 }
 
 /**
@@ -431,6 +437,8 @@ export function toggleClass(element, className) {
  * @param {Node} element Element to flash class name
  * @param {string} className class name
  * @param {number} [duration=120] duration milliseconds
+ * @example
+ * dom.utils.flashClass(element, 'blink', 500);
  */
 export function flashClass(element, className, duration = 120) {
 	addClass(element, className);
@@ -477,6 +485,8 @@ export function getViewportSize() {
  * @param {boolean} includeWW Include the `wwTarget` element in the copy
  * @param {Iterable<string>} styles Style list - kamel case
  * @returns
+ * @example
+ * dom.utils.applyInlineStylesAll(wysiwygElement, true, ['font-family', 'font-size']);
  */
 export function applyInlineStylesAll(wwTarget, includeWW, styles) {
 	if (!wwTarget) {
@@ -525,6 +535,8 @@ export function applyInlineStylesAll(wwTarget, includeWW, styles) {
  * @param {Node} target Target element
  * @param {number} timeout Timeout milliseconds
  * @returns {Promise<void>}
+ * @example
+ * await dom.utils.waitForMediaLoad(imgElement, 5000);
  */
 export function waitForMediaLoad(target, timeout = 5000) {
 	const doc = /** @type {HTMLElement|Document} */ (target || _d);

package/src/helper/index.js

@@ -5,6 +5,7 @@ import Dom from './dom';
 import Numbers from './numbers';
 import KeyCodeMap from './keyCodeMap';
 import Clipboard from './clipboard';
+import Markdown from './markdown';
 
 export const env = Env;
 export const unicode = Unicode;
@@ -13,6 +14,7 @@ export const dom = Dom;
 export const numbers = Numbers;
 export const keyCodeMap = KeyCodeMap;
 export const clipboard = Clipboard;
+export const markdown = Markdown;
 
 export default {
 	env,
@@ -22,4 +24,5 @@ export default {
 	numbers,
 	keyCodeMap,
 	clipboard,
+	markdown,
 };