@yh-ui/utils 0.1.0

package/dist/index.cjs

@@ -0,0 +1,378 @@
+'use strict';
+
+const isString = (val) => typeof val === "string";
+const isNumber = (val) => typeof val === "number";
+const isBoolean = (val) => typeof val === "boolean";
+const isFunction = (val) => typeof val === "function";
+const isObject = (val) => val !== null && typeof val === "object";
+const isPromise = (val) => isObject(val) && isFunction(val.then) && isFunction(val.catch);
+const isArray = Array.isArray;
+const isUndefined = (val) => val === void 0;
+const isNil = (val) => val == null;
+const isEmpty = (val) => {
+  if (isNil(val)) return true;
+  if (isArray(val)) return val.length === 0;
+  if (isString(val)) return val.trim().length === 0;
+  if (isObject(val)) return Object.keys(val).length === 0;
+  return false;
+};
+const isNumeric = (val) => !isNil(val) && !isNaN(parseFloat(String(val))) && isFinite(Number(val));
+
+const isClient = typeof window !== "undefined";
+const isServer = !isClient;
+const getStyle = (element, styleName) => {
+  if (!isClient || !element || !styleName) return "";
+  try {
+    const style = element.style[styleName];
+    if (style) return style;
+    const computed = document.defaultView?.getComputedStyle(element, "");
+    return computed ? computed[styleName] : "";
+  } catch {
+    return element.style[styleName];
+  }
+};
+const setStyle = (element, styleName, value) => {
+  if (!element || !styleName) return;
+  if (typeof styleName === "object") {
+    Object.entries(styleName).forEach(([key, val]) => {
+      setStyle(element, key, val);
+    });
+  } else {
+    element.style[styleName] = value ?? "";
+  }
+};
+const hasClass = (el, cls) => {
+  if (!el || !cls) return false;
+  if (cls.includes(" ")) throw new Error("className should not contain space.");
+  return el.classList.contains(cls);
+};
+const addClass = (el, cls) => {
+  if (!el || !cls.trim()) return;
+  el.classList.add(...cls.split(" ").filter(Boolean));
+};
+const removeClass = (el, cls) => {
+  if (!el || !cls.trim()) return;
+  el.classList.remove(...cls.split(" ").filter(Boolean));
+};
+const toggleClass = (el, cls, force) => {
+  if (!el || !cls.trim()) return;
+  el.classList.toggle(cls, force);
+};
+const getScrollContainer = (el, isVertical) => {
+  if (!isClient) return void 0;
+  let parent = el;
+  while (parent) {
+    if ([document.documentElement, document.body].includes(parent)) {
+      return window;
+    }
+    const overflow = isVertical ? getStyle(parent, "overflowY") : getStyle(parent, "overflow");
+    if (/(scroll|auto)/.test(overflow)) {
+      return parent;
+    }
+    parent = parent.parentNode;
+  }
+  return void 0;
+};
+const isInViewport = (el) => {
+  if (!isClient || !el) return false;
+  const rect = el.getBoundingClientRect();
+  return rect.top >= 0 && rect.left >= 0 && rect.bottom <= (window.innerHeight || document.documentElement.clientHeight) && rect.right <= (window.innerWidth || document.documentElement.clientWidth);
+};
+
+const withInstall = (main, extra) => {
+  main.install = (app) => {
+    for (const comp of [main, ...Object.values(extra ?? {})]) {
+      const name = comp.name || comp.__name;
+      if (name) {
+        app.component(name, comp);
+      }
+    }
+  };
+  if (extra) {
+    for (const [key, comp] of Object.entries(extra)) {
+      main[key] = comp;
+    }
+  }
+  return main;
+};
+const withNoopInstall = (component) => {
+  component.install = () => {
+  };
+  return component;
+};
+const withInstallFunction = (fn, name) => {
+  const func = fn;
+  func.install = (app) => {
+    app.config.globalProperties[name] = fn;
+  };
+  return func;
+};
+const withInstallDirective = (directive, name) => {
+  const dir = directive;
+  dir.install = (app) => {
+    app.directive(name, dir);
+  };
+  return dir;
+};
+const withInstallAll = (components, directives) => {
+  return {
+    install(app) {
+      components.forEach((component) => {
+        const name = component.name || component.__name;
+        if (name) {
+          app.component(name, component);
+        }
+      });
+      if (directives) {
+        Object.entries(directives).forEach(([name, directive]) => {
+          app.directive(name, directive);
+        });
+      }
+    }
+  };
+};
+
+let idCounter = 0;
+const generateId = (prefix = "yh") => {
+  return `${prefix}-${Date.now()}-${++idCounter}`;
+};
+const debounce = (fn, delay) => {
+  let timer = null;
+  const debounced = (...args) => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      fn(...args);
+      timer = null;
+    }, delay);
+  };
+  debounced.cancel = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+  return debounced;
+};
+const throttle = (fn, delay) => {
+  let lastTime = 0;
+  let timer = null;
+  const throttled = (...args) => {
+    const now = Date.now();
+    const remaining = delay - (now - lastTime);
+    if (remaining <= 0) {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      fn(...args);
+      lastTime = now;
+    } else if (!timer) {
+      timer = setTimeout(() => {
+        fn(...args);
+        lastTime = Date.now();
+        timer = null;
+      }, remaining);
+    }
+  };
+  throttled.cancel = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    lastTime = 0;
+  };
+  return throttled;
+};
+const deepClone = (obj) => {
+  if (obj === null || typeof obj !== "object") return obj;
+  if (obj instanceof Date) return new Date(obj.getTime());
+  if (obj instanceof Array) {
+    return obj.map((item) => deepClone(item));
+  }
+  if (obj instanceof Object) {
+    const copy = {};
+    Object.keys(obj).forEach((key) => {
+      copy[key] = deepClone(obj[key]);
+    });
+    return copy;
+  }
+  return obj;
+};
+const deepMerge = (target, ...sources) => {
+  if (!sources.length) return target;
+  const source = sources.shift();
+  if (source === void 0) return target;
+  for (const key in source) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      const targetValue = target[key];
+      const sourceValue = source[key];
+      if (typeof targetValue === "object" && targetValue !== null && typeof sourceValue === "object" && sourceValue !== null && !Array.isArray(targetValue) && !Array.isArray(sourceValue)) {
+        target[key] = deepMerge(
+          { ...targetValue },
+          sourceValue
+        );
+      } else {
+        target[key] = sourceValue;
+      }
+    }
+  }
+  return deepMerge(target, ...sources);
+};
+const toArray = (val) => {
+  return Array.isArray(val) ? val : [val];
+};
+const capitalize = (str) => {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+};
+const kebabCase = (str) => {
+  return str.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "");
+};
+const camelCase = (str) => {
+  return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+};
+const sleep = (ms) => {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+};
+const get = (obj, path, defaultValue) => {
+  const result = path.split(".").reduce((res, key) => {
+    if (res !== null && res !== void 0 && typeof res === "object") {
+      return res[key];
+    }
+    return void 0;
+  }, obj);
+  return result === void 0 ? defaultValue : result;
+};
+const set = (obj, path, value) => {
+  if (Object(obj) !== obj) return obj;
+  const keys = path.split(".");
+  const lastKey = keys.pop();
+  const node = keys.reduce(
+    (res, key) => {
+      if (res[key] === void 0) res[key] = {};
+      return res[key];
+    },
+    obj
+  );
+  node[lastKey] = value;
+  return obj;
+};
+const retry = async (fn, retries = 3, delay = 1e3) => {
+  try {
+    return await fn();
+  } catch (error) {
+    if (retries > 0) {
+      await sleep(delay);
+      return retry(fn, retries - 1, delay);
+    }
+    throw error;
+  }
+};
+
+const addUnit = (value, unit = "px") => {
+  if (value === void 0 || value === null || value === "") return void 0;
+  if (isNumeric(value)) {
+    return `${value}${unit}`;
+  }
+  return String(value);
+};
+const removeUnit = (value) => {
+  return parseFloat(value) || 0;
+};
+const hexToRgb = (hex) => {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result ? {
+    r: parseInt(result[1], 16),
+    g: parseInt(result[2], 16),
+    b: parseInt(result[3], 16)
+  } : null;
+};
+const rgbToHex = (r, g, b) => {
+  const toHex = (c) => {
+    const hex = c.toString(16);
+    return hex.length === 1 ? "0" + hex : hex;
+  };
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+};
+const adjustColorBrightness = (color, amount) => {
+  const rgb = hexToRgb(color);
+  if (!rgb) return color;
+  const adjust = (value) => {
+    const newValue = value + amount;
+    return Math.max(0, Math.min(255, newValue));
+  };
+  return rgbToHex(adjust(rgb.r), adjust(rgb.g), adjust(rgb.b));
+};
+const generateColorPalette = (baseColor, levels = [1, 2, 3, 4, 5, 6, 7, 8, 9]) => {
+  const palette = {};
+  const rgb = hexToRgb(baseColor);
+  if (!rgb) return palette;
+  levels.forEach((level) => {
+    const factor = (10 - level) / 10;
+    palette[level] = rgbToHex(
+      Math.round(rgb.r + (255 - rgb.r) * factor),
+      Math.round(rgb.g + (255 - rgb.g) * factor),
+      Math.round(rgb.b + (255 - rgb.b) * factor)
+    );
+  });
+  return palette;
+};
+const setCssVar = (name, value, element = document.documentElement) => {
+  element.style.setProperty(name, value);
+};
+const getCssVar = (name, element = document.documentElement) => {
+  return getComputedStyle(element).getPropertyValue(name).trim();
+};
+const setCssVars = (vars, element = document.documentElement) => {
+  Object.entries(vars).forEach(([name, value]) => {
+    setCssVar(name, value, element);
+  });
+};
+
+exports.addClass = addClass;
+exports.addUnit = addUnit;
+exports.adjustColorBrightness = adjustColorBrightness;
+exports.camelCase = camelCase;
+exports.capitalize = capitalize;
+exports.debounce = debounce;
+exports.deepClone = deepClone;
+exports.deepMerge = deepMerge;
+exports.generateColorPalette = generateColorPalette;
+exports.generateId = generateId;
+exports.get = get;
+exports.getCssVar = getCssVar;
+exports.getScrollContainer = getScrollContainer;
+exports.getStyle = getStyle;
+exports.hasClass = hasClass;
+exports.hexToRgb = hexToRgb;
+exports.isArray = isArray;
+exports.isBoolean = isBoolean;
+exports.isClient = isClient;
+exports.isEmpty = isEmpty;
+exports.isFunction = isFunction;
+exports.isInViewport = isInViewport;
+exports.isNil = isNil;
+exports.isNumber = isNumber;
+exports.isNumeric = isNumeric;
+exports.isObject = isObject;
+exports.isPromise = isPromise;
+exports.isServer = isServer;
+exports.isString = isString;
+exports.isUndefined = isUndefined;
+exports.kebabCase = kebabCase;
+exports.removeClass = removeClass;
+exports.removeUnit = removeUnit;
+exports.retry = retry;
+exports.rgbToHex = rgbToHex;
+exports.set = set;
+exports.setCssVar = setCssVar;
+exports.setCssVars = setCssVars;
+exports.setStyle = setStyle;
+exports.sleep = sleep;
+exports.throttle = throttle;
+exports.toArray = toArray;
+exports.toggleClass = toggleClass;
+exports.withInstall = withInstall;
+exports.withInstallAll = withInstallAll;
+exports.withInstallDirective = withInstallDirective;
+exports.withInstallFunction = withInstallFunction;
+exports.withNoopInstall = withNoopInstall;

package/dist/index.d.cts

@@ -0,0 +1,236 @@
+import { Plugin, App, Component, Directive } from 'vue';
+
+/**
+ * Type utilities
+ * @description 基础类型工具库，彻底移除 any，支持更严谨的类型推断
+ */
+
+/**
+ * 可空类型
+ */
+type Nullable<T> = T | null;
+/**
+ * 可异步类型
+ */
+type Awaitable<T> = T | Promise<T>;
+/**
+ * 数组或单值类型
+ */
+type Arrayable<T> = T | T[];
+/**
+ * 通用对象类型
+ */
+type Recordable<T = unknown> = Record<string, T>;
+/**
+ * 组件尺寸标准
+ */
+type ComponentSize = 'large' | 'default' | 'small';
+/**
+ * Vue 插件类型（带安装器）
+ */
+type SFCWithInstall<T> = T & Plugin & {
+    install: (app: App, options?: Record<string, unknown>) => void;
+};
+/**
+ * 类型判断工具函数
+ */
+declare const isString: (val: unknown) => val is string;
+declare const isNumber: (val: unknown) => val is number;
+declare const isBoolean: (val: unknown) => val is boolean;
+declare const isFunction: (val: unknown) => val is (...args: unknown[]) => unknown;
+declare const isObject: (val: unknown) => val is Record<string, unknown>;
+declare const isPromise: <T = unknown>(val: unknown) => val is Promise<T>;
+declare const isArray: (arg: any) => arg is any[];
+declare const isUndefined: (val: unknown) => val is undefined;
+declare const isNil: (val: unknown) => val is null | undefined;
+/**
+ * 判断是否为空值（null, undefined, '', [], {}）
+ */
+declare const isEmpty: (val: unknown) => boolean;
+/**
+ * 判断是否为有效的数字字符串
+ */
+declare const isNumeric: (val: unknown) => val is string | number;
+
+/**
+ * DOM utilities
+ */
+/**
+ * 判断是否在浏览器环境
+ */
+declare const isClient: boolean;
+/**
+ * 判断是否在服务端环境
+ */
+declare const isServer: boolean;
+/**
+ * 获取元素的样式
+ */
+declare const getStyle: (element: HTMLElement, styleName: string) => string;
+/**
+ * 设置元素的样式
+ */
+declare const setStyle: (element: HTMLElement, styleName: string | Record<string, string>, value?: string) => void;
+/**
+ * 检查元素是否包含某个类名
+ */
+declare const hasClass: (el: HTMLElement, cls: string) => boolean;
+/**
+ * 添加类名
+ */
+declare const addClass: (el: HTMLElement, cls: string) => void;
+/**
+ * 移除类名
+ */
+declare const removeClass: (el: HTMLElement, cls: string) => void;
+/**
+ * 切换类名
+ */
+declare const toggleClass: (el: HTMLElement, cls: string, force?: boolean) => void;
+/**
+ * 获取滚动容器
+ */
+declare const getScrollContainer: (el: HTMLElement, isVertical?: boolean) => HTMLElement | Window | undefined;
+/**
+ * 检查元素是否在视口中
+ */
+declare const isInViewport: (el: HTMLElement) => boolean;
+
+/**
+ * Vue 相关的工具函数
+ * @description 获取组件名、添加安装方法等
+ */
+
+/**
+ * 为组件添加 install 方法，使其可以作为 Vue 插件使用
+ */
+declare const withInstall: <T extends Component, E extends Record<string, unknown>>(main: T, extra?: E) => SFCWithInstall<T> & E;
+/**
+ * 空安装方法，用于不需要独立安装的子组件
+ */
+declare const withNoopInstall: <T extends Component>(component: T) => SFCWithInstall<T>;
+/**
+ * 为函数式组件或工具添加 install 方法
+ */
+declare const withInstallFunction: <T>(fn: T, name: string) => SFCWithInstall<T>;
+/**
+ * 为指令添加 install 方法
+ */
+declare const withInstallDirective: <T extends Directive>(directive: T, name: string) => SFCWithInstall<T>;
+/**
+ * 批量注册组件和指令
+ */
+declare const withInstallAll: (components: Component[], directives?: Record<string, Directive>) => Plugin;
+/**
+ * 用于 defineOptions 的类型辅助
+ */
+interface ComponentOptions {
+    name: string;
+    inheritAttrs?: boolean;
+}
+
+/**
+ * Common utilities
+ * @description 通用工具函数库，严格类型化
+ */
+declare const generateId: (prefix?: string) => string;
+/**
+ * 函数类型定义
+ */
+type AnyFunction = (...args: unknown[]) => unknown;
+/**
+ * 防抖函数
+ */
+declare const debounce: <T extends AnyFunction>(fn: T, delay: number) => ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+/**
+ * 节流函数
+ */
+declare const throttle: <T extends AnyFunction>(fn: T, delay: number) => ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+/**
+ * 深拷贝
+ */
+declare const deepClone: <T>(obj: T) => T;
+/**
+ * 深度合并对象
+ */
+declare const deepMerge: <T extends Record<string, unknown>>(target: T, ...sources: Partial<T>[]) => T;
+/**
+ * 将值转换为数组
+ */
+declare const toArray: <T>(val: T | T[]) => T[];
+/**
+ * 首字母大写
+ */
+declare const capitalize: (str: string) => string;
+/**
+ * 转换为 kebab-case
+ */
+declare const kebabCase: (str: string) => string;
+/**
+ * 转换为 camelCase
+ */
+declare const camelCase: (str: string) => string;
+/**
+ * 休眠函数
+ */
+declare const sleep: (ms: number) => Promise<void>;
+/**
+ * 访问对象嵌套路径的值
+ */
+declare const get: <T = unknown>(obj: Record<string, unknown>, path: string, defaultValue?: T) => T;
+/**
+ * 设置对象嵌套路径的值
+ */
+declare const set: <T extends Record<string, unknown>>(obj: T, path: string, value: unknown) => T;
+/**
+ * 异步函数重试
+ */
+declare const retry: <T>(fn: () => Promise<T>, retries?: number, delay?: number) => Promise<T>;
+
+/**
+ * 添加单位
+ */
+declare const addUnit: (value?: string | number, unit?: string) => string | undefined;
+/**
+ * 移除单位，返回数值
+ */
+declare const removeUnit: (value: string) => number;
+/**
+ * 将十六进制颜色转换为 RGB
+ */
+declare const hexToRgb: (hex: string) => {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/**
+ * 将 RGB 转换为十六进制颜色
+ */
+declare const rgbToHex: (r: number, g: number, b: number) => string;
+/**
+ * 调整颜色亮度
+ */
+declare const adjustColorBrightness: (color: string, amount: number) => string;
+/**
+ * 生成颜色的色阶
+ */
+declare const generateColorPalette: (baseColor: string, levels?: number[]) => Record<number, string>;
+/**
+ * 设置 CSS 变量
+ */
+declare const setCssVar: (name: string, value: string, element?: HTMLElement) => void;
+/**
+ * 获取 CSS 变量
+ */
+declare const getCssVar: (name: string, element?: HTMLElement) => string;
+/**
+ * 批量设置 CSS 变量
+ */
+declare const setCssVars: (vars: Record<string, string>, element?: HTMLElement) => void;
+
+export { addClass, addUnit, adjustColorBrightness, camelCase, capitalize, debounce, deepClone, deepMerge, generateColorPalette, generateId, get, getCssVar, getScrollContainer, getStyle, hasClass, hexToRgb, isArray, isBoolean, isClient, isEmpty, isFunction, isInViewport, isNil, isNumber, isNumeric, isObject, isPromise, isServer, isString, isUndefined, kebabCase, removeClass, removeUnit, retry, rgbToHex, set, setCssVar, setCssVars, setStyle, sleep, throttle, toArray, toggleClass, withInstall, withInstallAll, withInstallDirective, withInstallFunction, withNoopInstall };
+export type { Arrayable, Awaitable, ComponentOptions, ComponentSize, Nullable, Recordable, SFCWithInstall };