@codady/utils 0.0.23 → 0.0.25

package/src/createTools.ts

@@ -0,0 +1,129 @@
+/**
+ * @since Last modified: 2026/01/07 13:37:57
+ * @function createTools
+ * @description Creates a group of icon button tools and appends them to a parent element.
+ * The `data` array can contain tool definitions, where each tool can be defined either as an object or a string shorthand.
+ * @param {toolsItem[]} data - The data representing the tools. Each item in the array can be an object with properties for the tool or a string representing a shorthand tool.
+ * @param {Element | string} parent - The DOM element or selector where the tools will be appended.
+ * @returns {HTMLElement} The container element that holds the tools.
+ * @example
+ * ax.createTools([{},{},'toggle','close']);
+ * <!-- Returns a node containing the tool buttons -->
+ */
+'use strict';
+
+import classes from './classes';
+import createEl from './createEl';
+import isEmpty from './isEmpty';
+import ALIAS from './alias';
+import NAMESPACE from './namespace';
+import addClasses from './addClasses';
+
+/**
+ * @typedef {Object} toolsItem
+ * @description Represents a single tool item with properties that define its behavior and appearance.
+ * @property {string} name - The name of the tool (required).
+ * @property {string} [nodeName='span'] - The HTML tag to use for the tool element (optional, default is 'span').
+ * @property {string} [icon] - The icon to display for the tool (optional).
+ * @property {string} [disk] - The URL of the disk image for the tool (optional).
+ * @property {string} [cube] - The URL of the cube image for the tool (optional).
+ * @property {string} [image] - The URL of the image to display for the tool (optional).
+ * @property {string | string[]} [classes] - CSS class names to apply to the tool (optional).
+ * @property {string} [styles] - Inline styles to apply to the tool (optional).
+ * @property {string} [label] - A label to display next to the tool (optional).
+ * @property {boolean} [expandable=false] - Whether the tool is expandable (optional, default is false).
+ * @property {string} [title] - A title to show as a tooltip when the user hovers over the tool (optional).
+ * @property {boolean} [focusable=false] - Whether the tool is focusable via keyboard (optional, default is false).
+ * @property {Function | null} [action=null] - A callback function to be executed when the tool is activated (optional).
+ * @property {Record<string, string>} [attrs] - Additional attributes to add to the tool element (optional).
+ * @property {any} [key: string] - Other unspecified properties that can be added dynamically.
+ */
+export type toolsItem = {
+    name: string;
+    nodeName?: string;
+    icon?: string;
+    disk?: string;
+    cube?: string;
+    image?: string;
+    classes?: string | string[];
+    styles?: string;
+    label?: string;
+    expandable?: boolean;
+    title?: string;
+    focusable?: boolean;
+    action?: null | Function;
+    attrs?: Record<string, string>;
+    [key: string]: any;
+};
+
+/**
+ * @description Creates a set of icon button tools and appends them to the specified parent element.
+ * @param {toolsItem[]} data - The tool data, each tool can be either an object or a shorthand string.
+ * @returns {HTMLElement} The container DOM element that holds the tools.
+ */
+const createTools = (data: toolsItem[]):HTMLElement  => {
+    /*!  data = [
+             {
+                 name: 'close',
+                 nodeName: 'span',
+                 icon:'',
+                 disk:'',
+                 cube:'',
+                 image:'',
+                 attrs: {},
+                 classes:'',
+                 styles:'',
+                 label:'',
+                 expandable:false,
+                 focusable:true,
+                 action: null,
+             },
+             {
+                 name: 'max',
+                 nodeName: 'span',
+                 icon:'',
+                 attrs: {},
+                 classes:'',
+                 styles:'',
+                 label:'',
+                expandable:false,
+                action: null,
+             },
+         ] */
+    const toolsEl = createEl('span', { class: `${NAMESPACE}-box-tools` }),
+        renderFn = (props: any) => {
+            const dftAttrs: any = {},
+                arrow = props.extendable ? `<i ${ALIAS}="arrow"></i>` : '',
+                iconStr = props.icon ? `<i ${ALIAS}="icon">${props.icon}</i>` : '',
+                diskStr = props.disk ? `<i ${ALIAS}="disk"><img src="${props.disk}"/></i>` : '',
+                cubeStr = props.cube ? `<i ${ALIAS}="cube"><img src="${props.cube}"/></i>` : '',
+                imageStr = props.image ? `<i ${ALIAS}="image"><img src="${props.image}"/></i>` : '',
+                label = props.label ? `<i ${ALIAS}="label">${props.label}</i>` : '',
+                html = iconStr + diskStr + cubeStr + imageStr + label + arrow;
+            //使用title提示
+            props.title && (dftAttrs.title = props.title);
+            //可聚焦，增加tabindex=1
+            props.focusable && (dftAttrs.tabindex = 1);
+            //attrs是其他属性，可能会覆盖title、tabindex
+            props.wrapEl = createEl(props.nodeName || 'span', Object.assign(dftAttrs, props.attrs), html);
+            props.iconEl = props.wrapEl.querySelector(`[${ALIAS}="icon"]`);
+            props.cubeEl = props.wrapEl.querySelector(`[${ALIAS}="cube"]`);
+            props.diskEl = props.wrapEl.querySelector(`[${ALIAS}="disk"]`);
+            props.imageEl = props.wrapEl.querySelector(`[${ALIAS}="image"]`);
+            props.labelEl = props.wrapEl.querySelector(`[${ALIAS}="label"]`);
+            //增加classes和styles
+            !isEmpty(props.classes) && addClasses(props.wrapEl,props.classes);
+            !isEmpty(props.styles) && (props.wrapEl.style.cssText += props.styles);
+        };
+
+    //此处不用map方法，是避免改变原data的内存地址指向
+    for (let item of data) {
+        //data=[{},{},'toggle','close']
+        renderFn(item);
+        toolsEl.appendChild(item.wrapEl);
+        item?.action?.(item);
+    }
+
+    return toolsEl;
+}
+export default createTools;

package/src/getClasses.js

@@ -0,0 +1,16 @@
+/**
+ * @since Last modified: 2026/01/07 12:05:04
+ * @namespace getClasses
+ * @description Utility function to retrieve the list of CSS classes applied to a DOM element.
+ * This function will fetch the `class` attribute from a DOM element and parse it into an array of class names.
+ */
+'use strict';
+import getEl from "./getEl";
+import parseClasses from "./parseClasses";
+const getClasses = (target) => {
+    // Get the DOM element from the selector or Node
+    let el = getEl(target);
+    // If the element is found, parse and return its classes; otherwise, return an empty array
+    return el ? parseClasses(el.getAttribute('class') || '') : [];
+};
+export default getClasses;

package/src/getClasses.ts

@@ -0,0 +1,20 @@
+/**
+ * @since Last modified: 2026/01/07 12:05:04
+ * @namespace getClasses
+ * @description Utility function to retrieve the list of CSS classes applied to a DOM element.
+ * This function will fetch the `class` attribute from a DOM element and parse it into an array of class names.
+ */
+'use strict';
+
+import getEl from "./getEl";
+import parseClasses from "./parseClasses";
+
+const getClasses = (target: string | Node | null): string[] => {
+    // Get the DOM element from the selector or Node
+    let el = getEl(target);
+
+    // If the element is found, parse and return its classes; otherwise, return an empty array
+    return el ? parseClasses((el as Element).getAttribute('class') || '') : [];
+}
+
+export default getClasses;

package/src/hasClasses.js

@@ -0,0 +1,36 @@
+/**
+ * @since Last modified: 2026/01/07 12:10:08
+ * @namespace hasClasses
+ * @description Checks if the given DOM element has all of the specified CSS classes.
+ *
+ * This function takes one or more class names and checks if the target DOM element contains **all** the specified classes.
+ * It returns `true` if the element has all the specified classes, otherwise `false`.
+ *
+ * @param {string | Node | null} target - The target DOM element, Node, or CSS selector to check for the classes.
+ *   - If a string, it is interpreted as a CSS selector (e.g., `#elementId`).
+ *   - If a DOM node or element is passed, it is used directly.
+ *   - If `null` is passed, the function will return `false` because there is no element to check.
+ * @param {string | string[]} classes - A string or an array of class names to check.
+ *   - A space/comma-separated string of class names (e.g., `'class1 class2'`).
+ *   - An array of class names (e.g., `['class1', 'class2']`).
+ * @returns {boolean} Returns `true` if the element has all of the specified classes, otherwise `false`.
+ *
+ * @example
+ * ax.hasClasses('#demo', 'demo01 demo02');  // Returns true if element with id 'demo' has both 'demo01' and 'demo02'
+ * ax.hasClasses('#demo', ['demo01', 'demo02']);  // Returns true if element with id 'demo' has both 'demo01' and 'demo02'
+ */
+'use strict';
+import getEl from "./getEl";
+import parseClasses from "./parseClasses";
+const hasClasses = (target, classes) => {
+    const el = getEl(target), arr = parseClasses(classes);
+    if (!el || arr.length === 0)
+        return false;
+    for (let k of arr) {
+        if (!el.classList.contains(k)) {
+            return false;
+        }
+    }
+    return true;
+};
+export default hasClasses;

package/src/hasClasses.ts

@@ -0,0 +1,39 @@
+/**
+ * @since Last modified: 2026/01/07 12:10:08
+ * @namespace hasClasses
+ * @description Checks if the given DOM element has all of the specified CSS classes.
+ * 
+ * This function takes one or more class names and checks if the target DOM element contains **all** the specified classes.
+ * It returns `true` if the element has all the specified classes, otherwise `false`.
+ * 
+ * @param {string | Node | null} target - The target DOM element, Node, or CSS selector to check for the classes.
+ *   - If a string, it is interpreted as a CSS selector (e.g., `#elementId`).
+ *   - If a DOM node or element is passed, it is used directly.
+ *   - If `null` is passed, the function will return `false` because there is no element to check.
+ * @param {string | string[]} classes - A string or an array of class names to check.
+ *   - A space/comma-separated string of class names (e.g., `'class1 class2'`).
+ *   - An array of class names (e.g., `['class1', 'class2']`).
+ * @returns {boolean} Returns `true` if the element has all of the specified classes, otherwise `false`.
+ * 
+ * @example
+ * ax.hasClasses('#demo', 'demo01 demo02');  // Returns true if element with id 'demo' has both 'demo01' and 'demo02'
+ * ax.hasClasses('#demo', ['demo01', 'demo02']);  // Returns true if element with id 'demo' has both 'demo01' and 'demo02'
+ */
+'use strict';
+
+import getEl from "./getEl";
+import parseClasses from "./parseClasses";
+
+const hasClasses = (target: string | Node | null, classes: string | string[]): boolean => {
+    const el = getEl(target),
+        arr = parseClasses(classes);
+    if (!el || arr.length === 0) return false;
+    
+    for (let k of arr) {
+        if (!(el as Element).classList.contains(k)) {
+            return false;
+        }
+    }
+    return true;
+}
+export default hasClasses;

package/src/namespace.js

@@ -0,0 +1,2 @@
+const NAMESPACE = 'ax';
+export default NAMESPACE;

package/src/namespace.ts

@@ -0,0 +1,2 @@
+const NAMESPACE = 'ax';
+export default NAMESPACE;

package/src/parseClasses.js

@@ -0,0 +1,34 @@
+/**
+ * @since Last modified: 2026/01/07 11:45:59
+ * @function parseClasses
+ * @description Converts a string or an array of class names into an array of class names.
+ * If a string is provided, it can be a comma-separated or space-separated list of class names.
+ * The function cleans up any unnecessary spaces and ensures the result is an array of strings.
+ * @param {string | string[]} data - A string containing class names separated by commas or spaces, or an array of class names.
+ * @returns {string[]} - Returns an array of class names as strings.
+ * @example
+ * parseClasses('demo01,demo02'); // Returns ['demo01', 'demo02']
+ * parseClasses('demo01 demo02'); // Returns ['demo01', 'demo02']
+ * parseClasses(['demo01', 'demo02']); // Returns ['demo01', 'demo02']
+ */
+'use strict';
+import COMMA from "./comma";
+import SPACE from "./space";
+import trim from "./trim";
+const parseClasses = (data) => {
+    let separator, result = [];
+    if (Array.isArray(data)) {
+        // If data is already an array, filter out invalid values
+        result = data.filter((k) => k && typeof k === 'string');
+    }
+    else {
+        // Trim the input string and handle multiple spaces
+        data = trim(data);
+        // Use comma as the separator if present, otherwise use space
+        separator = data.includes(COMMA) ? COMMA : SPACE;
+        result = data.split(separator);
+    }
+    // Trim each item globally and filter out any empty strings
+    return result.map((k) => trim(k, 'global')).filter(Boolean);
+};
+export default parseClasses;

package/src/parseClasses.ts

@@ -0,0 +1,39 @@
+/**
+ * @since Last modified: 2026/01/07 11:45:59
+ * @function parseClasses
+ * @description Converts a string or an array of class names into an array of class names.
+ * If a string is provided, it can be a comma-separated or space-separated list of class names.
+ * The function cleans up any unnecessary spaces and ensures the result is an array of strings.
+ * @param {string | string[]} data - A string containing class names separated by commas or spaces, or an array of class names.
+ * @returns {string[]} - Returns an array of class names as strings.
+ * @example
+ * parseClasses('demo01,demo02'); // Returns ['demo01', 'demo02']
+ * parseClasses('demo01 demo02'); // Returns ['demo01', 'demo02']
+ * parseClasses(['demo01', 'demo02']); // Returns ['demo01', 'demo02']
+ */
+'use strict';
+
+import COMMA from "./comma";
+import SPACE from "./space";
+import trim from "./trim";
+
+const parseClasses = (data: string | string[]): string[] => {
+    let separator: string,
+        result: string[] = [];
+
+    if (Array.isArray(data)) {
+        // If data is already an array, filter out invalid values
+        result = (data as string[]).filter((k: any) => k && typeof k === 'string');
+    } else {
+        // Trim the input string and handle multiple spaces
+        data = trim(data as string);
+        // Use comma as the separator if present, otherwise use space
+        separator = data.includes(COMMA) ? COMMA : SPACE;
+        result = data.split(separator);
+    }
+
+    // Trim each item globally and filter out any empty strings
+    return result.map((k: string) => trim(k, 'global')).filter(Boolean);
+};
+
+export default parseClasses;

package/src/removeClasses.js

@@ -0,0 +1,44 @@
+/**
+ * @since Last modified: 2026/01/07 12:05:02
+ * @namespace removeClasses
+ * @description Removes one or more CSS classes from a DOM element. This function can remove a list of class names
+ *   either passed as a space/comma-separated string or an array of strings.
+ *   It also supports an optional `intercept` callback to modify or intercept the class removal process.
+ *
+ * @param {string | Node | null} target - The target DOM element, Node, or CSS selector from which the classes will be removed.
+ *   It can be:
+ *   - A string representing a CSS selector (e.g., `#elementId`)
+ *   - A DOM Node or Element.
+ *   - `null` (in which case, no action will be performed).
+ * @param {string | string[]} classes - A string or an array of CSS class names to remove. This can be:
+ *   - A space/comma-separated string of class names (e.g., `'class1 class2'`)
+ *   - An array of class names (e.g., `['class1', 'class2']`)
+ * @param {Function} [intercept] - An optional callback function that intercepts the class removal process.
+ *   It takes the class name as a parameter and can return:
+ *   - `true`: to remove the class name.
+ *   - A new class name (string): to replace the class name with a new one.
+ *   - `false` or `undefined`: to skip removing the class.
+ * @returns {void} This function does not return a value. It modifies the target DOM element.
+ *
+ */
+'use strict';
+import getEl from "./getEl";
+import parseClasses from "./parseClasses";
+const removeClasses = (target, classes, intercept) => {
+    const el = getEl(target), arr = parseClasses(classes);
+    if (!el || arr.length === 0)
+        return;
+    arr.forEach((k) => {
+        let tmp;
+        if (intercept) {
+            tmp = intercept(k);
+            tmp === true ? el.classList.remove(k) :
+                (typeof tmp === 'string' && tmp) ? el.classList.remove(tmp) : null;
+        }
+        else {
+            el.classList.remove(k);
+        }
+    });
+    return;
+};
+export default removeClasses;

package/src/removeClasses.ts

@@ -0,0 +1,47 @@
+/**
+ * @since Last modified: 2026/01/07 12:05:02
+ * @namespace removeClasses
+ * @description Removes one or more CSS classes from a DOM element. This function can remove a list of class names
+ *   either passed as a space/comma-separated string or an array of strings.
+ *   It also supports an optional `intercept` callback to modify or intercept the class removal process.
+ * 
+ * @param {string | Node | null} target - The target DOM element, Node, or CSS selector from which the classes will be removed.
+ *   It can be:
+ *   - A string representing a CSS selector (e.g., `#elementId`)
+ *   - A DOM Node or Element.
+ *   - `null` (in which case, no action will be performed).
+ * @param {string | string[]} classes - A string or an array of CSS class names to remove. This can be:
+ *   - A space/comma-separated string of class names (e.g., `'class1 class2'`)
+ *   - An array of class names (e.g., `['class1', 'class2']`)
+ * @param {Function} [intercept] - An optional callback function that intercepts the class removal process.
+ *   It takes the class name as a parameter and can return:
+ *   - `true`: to remove the class name.
+ *   - A new class name (string): to replace the class name with a new one.
+ *   - `false` or `undefined`: to skip removing the class.
+ * @returns {void} This function does not return a value. It modifies the target DOM element.
+ * 
+ */
+'use strict';
+
+import getEl from "./getEl";
+import parseClasses from "./parseClasses";
+
+const removeClasses = (target: string | Node | null, classes: string | string[], intercept?: (className: string) => string | boolean | void): void => {
+    const el = getEl(target),
+        arr = parseClasses(classes);
+    if (!el || arr.length === 0) return;
+
+    arr.forEach((k: string) => {
+        let tmp: any;
+        if (intercept) {
+            tmp = intercept(k);
+            tmp === true ? (el as Element).classList.remove(k) :
+                (typeof tmp === 'string' && tmp) ? (el as Element).classList.remove(tmp) : null;
+        } else {
+            (el as Element).classList.remove(k);
+        }
+    });
+    return;
+}
+export default removeClasses;
+

package/src/space.js

@@ -0,0 +1,2 @@
+const SPACE = ' ';
+export default SPACE;

package/src/space.ts

@@ -0,0 +1,2 @@
+const SPACE = ' ';
+export default SPACE;

package/src/trim.js

@@ -0,0 +1,41 @@
+/**
+ * @since Last modified: 2026/01/07 14:15:24
+ * @function trim
+ * @description Removes spaces, newlines, and carriage returns from the string.
+ * Supports removing spaces at specific positions (start, end, or both) or globally within the string.
+ * This is more powerful than the native `trim` method.
+ * @param {string} str - The string to be trimmed.
+ * @param {string} [placement] - Defines where to remove spaces:
+ *   - 'start' to remove spaces from the beginning.
+ *   - 'end' to remove spaces from the end.
+ *   - 'both' to remove spaces from both the start and the end.
+ *   - 'global' to remove all spaces, newlines, and carriage returns globally.
+ *   If omitted, the default is ''.
+ * @returns {string} - The string after trimming, without altering the original string.
+ * @example
+ * trim('   My name     is Lily  '); // Returns 'My name is Lily'
+ * trim('   My name     is Lily  ', 'start'); // Returns 'My name     is Lily  '
+ * trim('   My name     is Lily  ', 'end'); // Returns '   My name     is Lily'
+ * trim('   My name     is Lily  ', 'both'); // Returns 'My name     is Lily'
+ * trim('   My name     is Lily  ', 'global'); // Returns 'MynameisLily'
+ */
+'use strict';
+const trim = (str, placement = '') => {
+    if (typeof str !== 'string') {
+        console.warn('Expected a string input');
+        return '';
+    }
+    switch (placement) {
+        case 'start':
+            return str.trimStart();
+        case 'end':
+            return str.trimEnd();
+        case 'both':
+            return str.trim();
+        case 'global':
+            return str.replace(/[\s\r\n]+/g, '');
+        default:
+            return str.trim().replace(/[\s\r\n]+/g, ' '); // Default behavior, trims both ends and replaces inner spaces
+    }
+};
+export default trim;

package/src/trim.ts

@@ -0,0 +1,44 @@
+/**
+ * @since Last modified: 2026/01/07 14:15:24
+ * @function trim
+ * @description Removes spaces, newlines, and carriage returns from the string. 
+ * Supports removing spaces at specific positions (start, end, or both) or globally within the string. 
+ * This is more powerful than the native `trim` method.
+ * @param {string} str - The string to be trimmed.
+ * @param {string} [placement] - Defines where to remove spaces:
+ *   - 'start' to remove spaces from the beginning.
+ *   - 'end' to remove spaces from the end.
+ *   - 'both' to remove spaces from both the start and the end.
+ *   - 'global' to remove all spaces, newlines, and carriage returns globally.
+ *   If omitted, the default is ''.
+ * @returns {string} - The string after trimming, without altering the original string.
+ * @example
+ * trim('   My name     is Lily  '); // Returns 'My name is Lily'
+ * trim('   My name     is Lily  ', 'start'); // Returns 'My name     is Lily  '
+ * trim('   My name     is Lily  ', 'end'); // Returns '   My name     is Lily'
+ * trim('   My name     is Lily  ', 'both'); // Returns 'My name     is Lily'
+ * trim('   My name     is Lily  ', 'global'); // Returns 'MynameisLily'
+ */
+'use strict';
+
+const trim = (str: string, placement: 'start' | 'end' | 'both' | 'global' | ''=''): string => {
+    if (typeof str !== 'string') {
+        console.warn('Expected a string input');
+        return '';
+    }
+
+    switch (placement) {
+        case 'start':
+            return str.trimStart();
+        case 'end':
+            return str.trimEnd();
+        case 'both':
+            return str.trim();
+        case 'global':
+            return str.replace(/[\s\r\n]+/g, '');
+        default:
+            return str.trim().replace(/[\s\r\n]+/g, ' '); // Default behavior, trims both ends and replaces inner spaces
+    }
+};
+
+export default trim;