ph-utils 0.17.2 → 0.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Tenny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/dom.d.ts

@@ -7,9 +7,21 @@
  * 根据选择器获取节点
  * @param {string} selector 选择器
  */
-type FormatStyleParam = (string | undefined | null)[] | Record<string, boolean | string | undefined | null> | string;
-type FormatClassParam = (string | undefined | null | boolean)[] | Record<string, boolean | string | undefined | null | boolean> | string;
+type FormatStyleParam =
+  | (string | undefined | null)[]
+  | Record<string, boolean | string | undefined | null>
+  | string;
+type FormatClassParam =
+  | (string | undefined | null | boolean)[]
+  | Record<string, boolean | string | undefined | null | boolean>
+  | string;
 type DocumentContext = HTMLElement | ShadowRoot | Document;
+type NodeChildren =
+  | HTMLElement
+  | DocumentFragment
+  | HTMLElement[]
+  | NodeListOf<HTMLElement>
+  | HTMLCollection;
 export declare function elem(selector: string | HTMLElement, dom?: DocumentContext): HTMLElement[];
 /**
  * 根据选择器获取 DOM 元素。
@@ -22,33 +34,44 @@ export declare function $(selector: string | HTMLElement, dom?: DocumentContext)
  * 创建一个 HTML 元素，支持通过标签名或 HTML 字符串创建。
  * @param tag - 元素标签名或 HTML 字符串。
  * @param option - 元素的属性、样式、文本内容等配置。所有不是指定的属性，都会通过 setAttribute 设置
- * @param ctx - 元素的父级文档上下文。
+ * @param children - 子节点
  * @returns 创建的 HTML 元素。
  */
-export declare function create(tag: string, option?: {
+export declare function create(
+  tag: string,
+  option?: {
     class?: FormatClassParam;
     style?: FormatStyleParam;
     textContent?: string;
     innerHTML?: string;
     outerHTML?: string;
     [index: string]: any;
-}, ctx?: DocumentContext): HTMLElement;
+  },
+  children?: NodeChildren,
+): HTMLElement;
 /** 创建节点 */
-export declare function $$(tag: string, option?: {
+export declare function $$(
+  tag: string,
+  option?: {
     class?: FormatClassParam;
     style?: FormatStyleParam;
     textContent?: string;
     innerHTML?: string;
     outerHTML?: string;
     [index: string]: any;
-}, ctx?: DocumentContext): HTMLElement;
+  },
+  children?: NodeChildren,
+): HTMLElement;
 /**
  * 根据选择器获取匹配的第一个 DOM 元素。
  * @param selector - 选择器字符串或直接的 HTMLElement。
  * @param dom - 可选的父级 DOM 元素，默认为当前文档。
  * @returns 返回匹配的第一个 HTMLElement，如果没有找到则返回 null。
  */
-export declare function $one(selector: string | HTMLElement, dom?: DocumentContext): HTMLElement | null;
+export declare function $one(
+  selector: string | HTMLElement,
+  dom?: DocumentContext,
+): HTMLElement | null;
 /**
  * 为节点添加 class
  * @param {HTMLElement} elem 待添加 class 的节点
@@ -75,6 +98,22 @@ export declare function hasClass(elem: HTMLElement, clazz: string): boolean;
  * @param clazz - 要切换的类名。
  */
 export declare function toggleClass(el: HTMLElement, clazz: string): void;
+/**
+ * 替换指定元素的 CSS 类
+ *
+ * 该函数用于根据给定的旧类名或类索引，将其替换为新类名。
+ * 如果旧类不存在，则不会进行替换。
+ *
+ * @param el - 目标 HTML 元素，将对其类进行操作
+ * @param oldClazz - 要替换的旧类名或类索引（基于数字时对应 classList 的索引位置）
+ * @param newClazz - 新的类名，用于替换旧的类
+ * @returns void
+ */
+export declare function replaceClass(
+  el: HTMLElement,
+  oldClazz: string | number,
+  newClazz: string,
+): void;
 type EventHandler = EventListenerOrEventListenerObject | ((e: CustomEvent) => void);
 /**
  * 为节点添加事件处理
@@ -83,16 +122,40 @@ type EventHandler = EventListenerOrEventListenerObject | ((e: CustomEvent) => vo
  * @param {function}    fn     事件处理函数
  * @param {boolean}     option  是否是只运行一次的处理函数或者配置，其中 eventFlag 为 string，如果配置该项，则表明为委托事件
  */
-export declare function on(element: HTMLElement | ShadowRoot | Document | HTMLCollection | NodeListOf<HTMLElement> | HTMLElement[], listener: string, fn: EventHandler, option?: boolean | (AddEventListenerOptions & {
-    eventFlag?: string;
-})): void;
+export declare function on(
+  element:
+    | HTMLElement
+    | ShadowRoot
+    | Document
+    | HTMLCollection
+    | NodeListOf<HTMLElement>
+    | HTMLElement[],
+  listener: string,
+  fn: EventHandler,
+  option?:
+    | boolean
+    | (AddEventListenerOptions & {
+        eventFlag?: string;
+      }),
+): void;
 /**
  * 移除指定元素的事件监听器。
  * @param el - 要移除监听器的 HTML 元素。
  * @param listener - 事件名称。
  * @param fn - 要移除的事件监听器函数。
  */
-export declare function off(el: HTMLElement | ShadowRoot | Document | HTMLCollection | NodeListOf<HTMLElement> | HTMLElement[], listener: string, fn: EventHandler, option?: boolean | EventListenerOptions): void;
+export declare function off(
+  el:
+    | HTMLElement
+    | ShadowRoot
+    | Document
+    | HTMLCollection
+    | NodeListOf<HTMLElement>
+    | HTMLElement[],
+  listener: string,
+  fn: EventHandler,
+  option?: boolean | EventListenerOptions,
+): void;
 /**
  * 判断事件是否应该继续传递。
  * 从事件目标开始向上遍历DOM树，检查每个节点上是否存在指定的属性。
@@ -105,7 +168,11 @@ export declare function off(el: HTMLElement | ShadowRoot | Document | HTMLCollec
  * @param endRoot - 可选，如果传递该参数，则表示停止遍历的节点，如果未传递，则表示遍历到文档根节点为止
  * @returns 包含三个元素的数组：[是否继续传递事件, 属性值, 当前检查的DOM节点]
  */
-export declare function shouldEventNext(e: Event, eventFlag: string, endRoot?: HTMLElement | ShadowRoot): [boolean, string, HTMLElement];
+export declare function shouldEventNext(
+  e: Event,
+  eventFlag: string,
+  endRoot?: HTMLElement | ShadowRoot,
+): [boolean, string, HTMLElement];
 /**
  * 设置或获取节点的 innerHTML 属性
  * @param element
@@ -121,7 +188,10 @@ export declare function html(element: HTMLElement, htmlstr?: string): string | u
  */
 export declare function text(element: HTMLElement, textstr?: string): string | undefined | null;
 export declare function iterate<T>(elems: T[], fn: (el: T, index: number) => any): void;
-export declare function iterate(elems: NodeList | HTMLCollection | NodeListOf<HTMLElement>, fn: (el: HTMLElement, index: number) => any): void;
+export declare function iterate(
+  elems: NodeList | HTMLCollection | NodeListOf<HTMLElement>,
+  fn: (el: HTMLElement, index: number) => any,
+): void;
 /**
  * 设置或获取节点 data-* 属性
  * @param elem
@@ -129,7 +199,11 @@ export declare function iterate(elems: NodeList | HTMLCollection | NodeListOf<HT
  * @param value 如果传递该值表示获取；否则表示设置
  * @returns
  */
-export declare function attr(elem: HTMLElement, key: string, value?: string): string | null | undefined;
+export declare function attr(
+  elem: HTMLElement,
+  key: string,
+  value?: string,
+): string | null | undefined;
 /**
  * 获取属性值
  * @param key 属性名称
@@ -143,7 +217,11 @@ export declare function getAttr(el: HTMLElement, key: string): string;
 export declare function getAttr(el: HTMLElement, filepath: string, defaultValue: string): string;
 export declare function getAttr(el: HTMLElement, filepath: string, defaultValue: number): number;
 export declare function getAttr(el: HTMLElement, filepath: string, defaultValue: boolean): boolean;
-export declare function getAttr<T extends Record<string, string | number | boolean>>(el: HTMLElement, filepath: string, defaultValue: T): T;
+export declare function getAttr<T extends Record<string, string | number | boolean>>(
+  el: HTMLElement,
+  filepath: string,
+  defaultValue: T,
+): T;
 /**
  * 获取指定节点的父节点
  * @param el
@@ -156,9 +234,12 @@ export declare function parent(el: HTMLElement): HTMLElement;
  * @param parent - 添加临时节点的父节点, 如果传递 null, 则通过修改原始样式方式计算，默认为: body.
  * @returns The DOMRect of the element.
  */
-export declare function queryHideNodeSize(hideNode: string | HTMLElement, parent?: null | HTMLElement): {
-    width: number;
-    height: number;
+export declare function queryHideNodeSize(
+  hideNode: string | HTMLElement,
+  parent?: null | HTMLElement,
+): {
+  width: number;
+  height: number;
 };
 /**
  * 判断元素是否在父元素的可视区域内。
@@ -168,7 +249,11 @@ export declare function queryHideNodeSize(hideNode: string | HTMLElement, parent
  * @param direction 检查的方向，默认为"horizontal"
  * @returns 如果元素在父元素的可视区域内，则返回true；否则返回false。
  */
-export declare function isVisible(el: HTMLElement, parent?: HTMLElement | null | undefined, direction?: string): boolean;
+export declare function isVisible(
+  el: HTMLElement,
+  parent?: HTMLElement | null | undefined,
+  direction?: string,
+): boolean;
 /**
  * 判断当前设备是否为移动设备。
  *
@@ -185,7 +270,12 @@ export declare function isMobile(): boolean;
  * @param classObj - 类名对象或数组
  * @returns 格式化后的类名字符串
  */
-export declare function formatClass(classObj: (boolean | string | undefined | null)[] | Record<string, boolean | string | undefined | null> | string): string;
+export declare function formatClass(
+  classObj:
+    | (boolean | string | undefined | null)[]
+    | Record<string, boolean | string | undefined | null>
+    | string,
+): string;
 /**
  * 将样式对象格式化为 CSS 样式字符串。
  * @param styleObj - 样式对象，可以是字符串数组或键值对对象。
@@ -221,7 +311,12 @@ export declare function formatStyle(styleObj: FormatStyleParam): string;
  * @example <caption>动画结束后移除节点</caption>
  * transition($el, [["opacity", "0", "0.3s"]], "leave", () => {  $el.remove(); });
  */
-export declare function transition(el: HTMLElement, nameOrProperties: string | [string, string, string][], dir?: "leave" | "enter", finish?: () => void): void;
+export declare function transition(
+  el: HTMLElement,
+  nameOrProperties: string | [string, string, string][],
+  dir?: "leave" | "enter",
+  finish?: () => void,
+): void;
 /**
  * 计算光标位置
  *
@@ -245,8 +340,13 @@ export declare function transition(el: HTMLElement, nameOrProperties: string | [
  * // 替换字符时，保持位置
  * calcuteCursorPosition(2, 2, "abc", "axc"); // 返回 { start: 2, end: 2 }
  */
-export declare function calcuteCursorPosition(start: number, end: number, oldValue: string, newValue: string): {
-    start: number;
-    end: number;
+export declare function calcuteCursorPosition(
+  start: number,
+  end: number,
+  oldValue: string,
+  newValue: string,
+): {
+  start: number;
+  end: number;
 };
 export {};

package/lib/dom.js

@@ -22,7 +22,7 @@ export function $(selector, dom) {
  * @param ctx - 元素的父级文档上下文。
  * @returns 创建的 HTML 元素。
  */
-export function create(tag, option = {}, ctx) {
+export function create(tag, option = {}, children) {
     let $el;
     if (tag.startsWith("<") && tag.endsWith(">")) {
         const parser = new DOMParser();
@@ -53,7 +53,7 @@ export function create(tag, option = {}, ctx) {
                         $el.outerHTML = value;
                     }
                     else {
-                        if (value === true) {
+                        if (typeof value === "boolean" && value === true) {
                             $el.setAttribute(key, "");
                         }
                         else {
@@ -63,15 +63,30 @@ export function create(tag, option = {}, ctx) {
                 }
             }
         }
-        if (ctx) {
-            ctx.appendChild($el);
+        if (children) {
+            if (children instanceof HTMLElement || children instanceof DocumentFragment) {
+                $el.appendChild(children);
+            }
+            else {
+                let len = children.length;
+                const fragment = document.createDocumentFragment();
+                for (let i = 0; i < len; i++) {
+                    const child = children[i];
+                    if (child instanceof HTMLElement) {
+                        fragment.appendChild(child);
+                    }
+                }
+                if (len > 0) {
+                    $el.appendChild(fragment);
+                }
+            }
         }
     }
     return $el;
 }
 /** 创建节点 */
-export function $$(tag, option = {}, ctx) {
-    return create(tag, option, ctx);
+export function $$(tag, option = {}, children) {
+    return create(tag, option, children);
 }
 /**
  * 根据选择器获取匹配的第一个 DOM 元素。
@@ -124,6 +139,25 @@ export function toggleClass(el, clazz) {
         addClass(el, clazz);
     }
 }
+/**
+ * 替换指定元素的 CSS 类
+ *
+ * 该函数用于根据给定的旧类名或类索引，将其替换为新类名。
+ * 如果旧类不存在，则不会进行替换。
+ *
+ * @param el - 目标 HTML 元素，将对其类进行操作
+ * @param oldClazz - 要替换的旧类名或类索引（基于数字时对应 classList 的索引位置）
+ * @param newClazz - 新的类名，用于替换旧的类
+ * @returns void
+ */
+export function replaceClass(el, oldClazz, newClazz) {
+    // 判断 oldClazz 是否为数字，若是则通过索引从 el.classList 中获取对应类名，否则直接使用字符串值
+    let old = typeof oldClazz === "number" ? el.classList.item(oldClazz) : oldClazz;
+    // 如果旧类存在，则使用 classList.replace 方法进行替换
+    if (old) {
+        el.classList.replace(old, newClazz);
+    }
+}
 /**
  * 为节点添加事件处理
  * @param {HTMLElement} element   添加事件的节点

package/lib/src/array.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 数组排序
+ * @param arr 待排序数组
+ * @param order 排序信息, asc - 升序, desc - 倒序
+ * @param orderKey 如果是个对象数组，按哪个字段排序
+ * @returns
+ */
+export declare function order<T>(arr: T[], order?: "asc" | "desc", orderKey?: string | null): T[];
+/**
+ * 返回一个所有集合交集的新集合
+ *
+ * 如果集合本身支持 intersection, 则调用原生 intersection 函数
+ *
+ * @param arrs
+ *
+ * @returns 新集合中的元素在传入的所有集合中同时存在
+ */
+export declare function intersection<T>(...arrs: Set<T>[]): Set<T>;
+/**
+ * 返回一个所有列表交集的新列表
+ *
+ * @param arrs
+ *
+ * @returns 新列表中的元素在传入的所有列表中同时存在
+ */
+export declare function intersection<T>(...arrs: T[][]): T[];
+/**
+ * 返回一个包含第一个集合中的元素但不包含后续给定集合中元素的新集合
+ *
+ * 如果集合本身支持 difference 方法，则调用原生 difference 方法
+ *
+ * @param arrs 集合列表
+ *
+ * @returns
+ */
+export declare function difference<T>(...arrs: Set<T>[]): Set<T>;
+/**
+ * 返回一个包含第一个列表中的元素但不包含后续给定列表中元素的新列表
+ *
+ * @param arrs 二维列表
+ *
+ * @returns
+ */
+export declare function difference<T>(...arrs: T[][]): T[];
+/**
+ * 返回多个集合的并集, 如果支持 union，则调用原生 union
+ *
+ * @param arrs
+ *
+ * @returns 一个包含所有给定集合的所有元素的新集合
+ */
+export declare function union<T>(...arrs: Set<T>[]): Set<T>;
+export declare function union<T>(...arrs: T[][]): T[];
+export declare function symmetricDifference<T>(...arrs: Set<T>[]): Set<T>;
+export declare function symmetricDifference<T>(...arrs: T[][]): T[];
+/**
+ * 返回一个布尔值，指示此集合中的所有元素是否都在给定的集合中。
+ * @param a1
+ * @param a2
+ * @returns
+ */
+export declare function isSubsetOf<T>(a1: T[] | Set<T>, a2: T[] | Set<T>): boolean;
+/**
+ * 返回一个布尔值，指示给定集合中的所有元素是否都在此集合中。
+ * @param arr1
+ * @param arr2
+ * @returns
+ */
+export declare function isSupersetOf<T>(arr1: T[] | Set<T>, arr2: T[] | Set<T>): boolean;
+/**
+ * 返回一个布尔值，指示此集合是否与给定集合没有公共元素。
+ *
+ * 判断两个集合是否有交集, 也可以通过 intersection(arr1, arr2).length 判断
+ *
+ * @param arr1
+ * @param arr2
+ * @returns
+ */
+export declare function isDisjointFrom<T>(arr1: T[] | Set<T>, arr2: T[] | Set<T>): boolean;

package/lib/src/array.js

@@ -0,0 +1,212 @@
+/**
+ * 数组排序
+ * @param arr 待排序数组
+ * @param order 排序信息, asc - 升序, desc - 倒序
+ * @param orderKey 如果是个对象数组，按哪个字段排序
+ * @returns
+ */
+export function order(arr, order = "asc", orderKey = null) {
+    const collator = new Intl.Collator(undefined, { numeric: true });
+    return arr.sort((a, b) => {
+        let aValue = a;
+        let bValue = b;
+        if (typeof a === "object" && orderKey != null) {
+            // @ts-ignore
+            aValue = a[orderKey];
+            // @ts-ignore
+            bValue = b[orderKey];
+        }
+        let aGtb = -1;
+        if (typeof aValue === "string") {
+            aGtb = collator.compare(aValue, bValue);
+        }
+        else {
+            aGtb = aValue >= bValue ? 1 : -1;
+        }
+        return order === "asc" ? aGtb : -aGtb;
+    });
+}
+/**
+ * 返回所有集合交集的元素的新集合
+ */ export function intersection(...arrs) {
+    return arrs.reduce((acc, cur) => {
+        if (cur instanceof Set) {
+            //@ts-ignore
+            if (cur.intersection != null) {
+                //@ts-ignore
+                return acc.intersection(cur);
+            }
+            else {
+                const res = new Set();
+                for (const value of acc) {
+                    if (cur.has(value)) {
+                        res.add(value);
+                    }
+                }
+                return res;
+            }
+        }
+        else {
+            return acc.filter((x) => cur.includes(x));
+        }
+    });
+}
+/**
+ * 返回一个包含第一个集合中的元素但不包含后续给定集合中元素的新集合
+ * @param arrs 新集合
+ * @returns
+ */
+export function difference(...arrs) {
+    return arrs.reduce((acc, cur) => {
+        if (acc instanceof Set) {
+            //@ts-ignore
+            if (acc.difference != null) {
+                //@ts-ignore
+                return acc.difference(cur);
+            }
+            else {
+                const res = new Set();
+                for (const value of acc) {
+                    if (!cur.has(value)) {
+                        res.add(value);
+                    }
+                }
+                return res;
+            }
+        }
+        else {
+            const res = [];
+            for (const value of acc) {
+                if (!cur.includes(value)) {
+                    res.push(value);
+                }
+            }
+            return res;
+        }
+    });
+}
+export function union(...arrs) {
+    return arrs.reduce((acc, cur) => {
+        if (cur instanceof Set) {
+            //@ts-ignore
+            if (cur.union != null) {
+                //@ts-ignore
+                return acc.union(cur);
+            }
+            return new Set([...acc, ...cur]);
+        }
+        else {
+            return [...acc, ...cur];
+        }
+    });
+}
+/**
+ * 对称差: 返回一个包含此集合或给定集合中的元素的新集合，但不包含同时存在于这两个集合中的元素。
+ * @param arrs
+ * @returns
+ */
+export function symmetricDifference(...arrs) {
+    return arrs.reduce((acc, cur) => {
+        if (cur instanceof Set) {
+            //@ts-ignore
+            if (cur.symmetricDifference != null) {
+                //@ts-ignore
+                return acc.symmetricDifference(cur);
+            }
+            const res = new Set();
+            for (const item of acc) {
+                if (!cur.has(item)) {
+                    res.add(item);
+                }
+            }
+            for (const item of cur) {
+                if (!acc.has(item)) {
+                    res.add(item);
+                }
+            }
+            return res;
+        }
+        const res = [];
+        for (const item of acc) {
+            if (!cur.includes(item)) {
+                res.push(item);
+            }
+        }
+        for (const item of cur) {
+            if (!acc.includes(item)) {
+                res.push(item);
+            }
+        }
+        return res;
+    });
+}
+/**
+ * 返回一个布尔值，指示此集合中的所有元素是否都在给定的集合中。
+ * @param a1
+ * @param a2
+ * @returns
+ */
+export function isSubsetOf(a1, a2) {
+    //@ts-ignore
+    if (a1 instanceof Set && a1.isSubsetOf != null) {
+        //@ts-ignore
+        return a1.isSubsetOf(a2);
+    }
+    let is = true;
+    for (const item of a1) {
+        if (a2 instanceof Set) {
+            if (!a2.has(item)) {
+                is = false;
+                break;
+            }
+        }
+        else {
+            if (!a2.includes(item)) {
+                is = false;
+                break;
+            }
+        }
+    }
+    return is;
+}
+/**
+ * 返回一个布尔值，指示给定集合中的所有元素是否都在此集合中。
+ * @param arr1
+ * @param arr2
+ * @returns
+ */
+export function isSupersetOf(arr1, arr2) {
+    return isSubsetOf(arr2, arr1);
+}
+/**
+ * 返回一个布尔值，指示此集合是否与给定集合没有公共元素。
+ *
+ * 判断两个集合是否有交集, 也可以通过 intersection(arr1, arr2).length 判断
+ *
+ * @param arr1
+ * @param arr2
+ * @returns
+ */
+export function isDisjointFrom(arr1, arr2) {
+    //@ts-ignore
+    if (arr1 instanceof Set && arr1.isDisjointFrom != null) {
+        //@ts-ignore
+        return arr1.isDisjointFrom(arr2);
+    }
+    let is = true;
+    for (const item of arr1) {
+        if (arr2 instanceof Set) {
+            if (arr2.has(item)) {
+                is = false;
+                break;
+            }
+        }
+        else {
+            if (arr2.includes(item)) {
+                is = false;
+                break;
+            }
+        }
+    }
+    return is;
+}