@melt-js/libs-vben 0.0.0-stage → 2026.11.8-2

package/src/shared/utils/dom.ts

@@ -0,0 +1,126 @@
+import { ELEMENT_ID_LAYOUT_SCROLL } from '../constants/globals';
+
+export interface VisibleDomRect {
+  bottom: number;
+  height: number;
+  left: number;
+  right: number;
+  top: number;
+  width: number;
+}
+
+/**
+ * 获取元素可见信息
+ * @param element
+ */
+export function getElementVisibleRect(
+  element?: HTMLElement | null,
+): VisibleDomRect {
+  if (!element) {
+    return {
+      bottom: 0,
+      height: 0,
+      left: 0,
+      right: 0,
+      top: 0,
+      width: 0,
+    };
+  }
+  const rect = element.getBoundingClientRect();
+  const viewHeight = Math.max(
+    document.documentElement.clientHeight,
+    window.innerHeight,
+  );
+
+  const top = Math.max(rect.top, 0);
+  const bottom = Math.min(rect.bottom, viewHeight);
+
+  const viewWidth = Math.max(
+    document.documentElement.clientWidth,
+    window.innerWidth,
+  );
+
+  const left = Math.max(rect.left, 0);
+  const right = Math.min(rect.right, viewWidth);
+
+  // 如果元素完全不可见，则返回一个空的矩形
+  if (top >= viewHeight || bottom <= 0 || left >= viewWidth || right <= 0) {
+    return {
+      bottom: 0,
+      height: 0,
+      left: 0,
+      right: 0,
+      top: 0,
+      width: 0,
+    };
+  }
+
+  return {
+    bottom,
+    height: Math.max(0, bottom - top),
+    left,
+    right,
+    top,
+    width: Math.max(0, right - left),
+  };
+}
+
+export function getScrollbarWidth() {
+  const scrollDiv = document.createElement('div');
+
+  scrollDiv.style.visibility = 'hidden';
+  scrollDiv.style.overflow = 'scroll';
+  scrollDiv.style.position = 'absolute';
+  scrollDiv.style.top = '-9999px';
+
+  document.body.append(scrollDiv);
+
+  const innerDiv = document.createElement('div');
+  scrollDiv.append(innerDiv);
+
+  const scrollbarWidth = scrollDiv.offsetWidth - innerDiv.offsetWidth;
+
+  scrollDiv.remove();
+  return scrollbarWidth;
+}
+
+export function getLayoutScrollElement() {
+  return document.querySelector<HTMLElement>(`#${ELEMENT_ID_LAYOUT_SCROLL}`);
+}
+
+function elementNeedsScrollbar(element: HTMLElement) {
+  const overflowY = window.getComputedStyle(element).overflowY;
+  if (overflowY === 'hidden' || overflowY === 'clip') {
+    return false;
+  }
+
+  return element.scrollHeight > element.clientHeight;
+}
+
+export function needsScrollbar(target?: HTMLElement | null) {
+  if (target) {
+    return elementNeedsScrollbar(target);
+  }
+
+  const doc = document.documentElement;
+  const body = document.body;
+
+  // 检查 body 的 overflow-y 样式
+  const overflowY = window.getComputedStyle(body).overflowY;
+
+  // 如果明确设置了需要滚动条的样式
+  if (overflowY === 'scroll' || overflowY === 'auto') {
+    return doc.scrollHeight > window.innerHeight;
+  }
+
+  // 在其他情况下，根据 scrollHeight 和 innerHeight 比较判断
+  return doc.scrollHeight > window.innerHeight;
+}
+
+export function triggerWindowResize(): void {
+  // 创建一个新的 resize 事件
+  const resizeEvent = new Event('resize');
+
+  // 触发 window 的 resize 事件
+  window.dispatchEvent(resizeEvent);
+}

package/src/shared/utils/download.ts

@@ -0,0 +1,186 @@
+import { openWindow } from './window';
+
+interface DownloadOptions<T = string> {
+  fileName?: string;
+  source: T;
+  target?: string;
+}
+
+const DEFAULT_FILENAME = 'downloaded_file';
+
+/**
+ * 通过 URL 下载文件，支持跨域
+ * @throws {Error} - 当下载失败时抛出错误
+ */
+export async function downloadFileFromUrl({
+  fileName,
+  source,
+  target = '_blank',
+}: DownloadOptions): Promise<void> {
+  if (!source || typeof source !== 'string') {
+    throw new Error('Invalid URL.');
+  }
+
+  const isChrome = window.navigator.userAgent.toLowerCase().includes('chrome');
+  const isSafari = window.navigator.userAgent.toLowerCase().includes('safari');
+
+  if (/iP/.test(window.navigator.userAgent)) {
+    console.error('Your browser does not support download!');
+    return;
+  }
+
+  if (isChrome || isSafari) {
+    triggerDownload(source, resolveFileName(source, fileName));
+    return;
+  }
+  if (!source.includes('?')) {
+    source += '?download';
+  }
+
+  openWindow(source, { target });
+}
+
+/**
+ * 通过 Base64 下载文件
+ */
+export function downloadFileFromBase64({ fileName, source }: DownloadOptions) {
+  if (!source || typeof source !== 'string') {
+    throw new Error('Invalid Base64 data.');
+  }
+
+  const resolvedFileName = fileName || DEFAULT_FILENAME;
+  triggerDownload(source, resolvedFileName);
+}
+
+/**
+ * 通过图片 URL 下载图片文件
+ */
+export async function downloadFileFromImageUrl({
+  fileName,
+  source,
+}: DownloadOptions) {
+  const base64 = await urlToBase64(source);
+  // urlToBase64 总是把图片重新编码为 data url，缺省名要跟随产物真实扩展名，
+  // 否则保存下来的文件没有后缀，双击打不开
+  const extension =
+    base64.slice(base64.indexOf('/') + 1, base64.indexOf(';')) || 'png';
+  const derivedName = resolveFileName(source).replace(/\.[^.]*$/, '');
+
+  downloadFileFromBase64({
+    fileName: fileName || `${derivedName}.${extension}`,
+    source: base64,
+  });
+}
+
+/**
+ * 通过 Blob 下载文件
+ */
+export function downloadFileFromBlob({
+  fileName = DEFAULT_FILENAME,
+  source,
+}: DownloadOptions<Blob>): void {
+  if (!(source instanceof Blob)) {
+    throw new TypeError('Invalid Blob data.');
+  }
+
+  const url = URL.createObjectURL(source);
+  triggerDownload(url, fileName);
+}
+
+/**
+ * 下载文件，支持 Blob、字符串和其他 BlobPart 类型
+ */
+export function downloadFileFromBlobPart({
+  fileName = DEFAULT_FILENAME,
+  source,
+}: DownloadOptions<BlobPart>): void {
+  // 如果 data 不是 Blob，则转换为 Blob
+  const blob =
+    source instanceof Blob
+      ? source
+      : new Blob([source], { type: 'application/octet-stream' });
+
+  // 创建对象 URL 并触发下载
+  const url = URL.createObjectURL(blob);
+  triggerDownload(url, fileName);
+}
+
+/**
+ * img url to base64
+ * @param url
+ */
+export function urlToBase64(url: string, mineType?: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let canvas = document.createElement('CANVAS') as HTMLCanvasElement | null;
+    const ctx = canvas?.getContext('2d');
+    const img = new Image();
+    img.crossOrigin = '';
+    img.addEventListener('load', () => {
+      if (!canvas || !ctx) {
+        return reject(new Error('Failed to create canvas.'));
+      }
+      canvas.height = img.height;
+      canvas.width = img.width;
+      ctx.drawImage(img, 0, 0);
+      const dataURL = canvas.toDataURL(mineType || 'image/png');
+      canvas = null;
+      resolve(dataURL);
+    });
+    img.src = url;
+  });
+}
+
+/**
+ * 通用下载触发函数
+ * @param href - 文件下载的 URL
+ * @param fileName - 下载文件的名称，如果未提供则自动识别
+ * @param revokeDelay - 清理 URL 的延迟时间 (毫秒)
+ */
+export function triggerDownload(
+  href: string,
+  fileName: string | undefined,
+  revokeDelay: number = 100,
+): void {
+  const defaultFileName = 'downloaded_file';
+  const finalFileName = fileName || defaultFileName;
+
+  const link = document.createElement('a');
+  link.href = href;
+  link.download = finalFileName;
+  link.style.display = 'none';
+
+  if (link.download === undefined) {
+    link.setAttribute('target', '_blank');
+  }
+
+  document.body.append(link);
+  link.click();
+  link.remove();
+
+  // 清理临时 URL 以释放内存
+  setTimeout(() => URL.revokeObjectURL(href), revokeDelay);
+}
+
+/**
+ * 解析下载文件名：显式传入优先，其次取 URL 路径的最后一段，都没有则用默认名
+ * @param url - 文件地址，data url 不携带文件名信息
+ * @param fileName - 调用方显式指定的文件名
+ */
+function resolveFileName(url: string, fileName?: string): string {
+  if (fileName) {
+    return fileName;
+  }
+  // data: 的"路径"是文件内容本身，不能当文件名，否则编码串会溜进下载名
+  if (url.startsWith('data:')) {
+    return DEFAULT_FILENAME;
+  }
+  // 查询串与锚点不属于文件名；签名链接普遍带 ?token=...
+  const path = url.split('#')[0]?.split('?')[0] ?? '';
+  const lastSegment = path.slice(path.lastIndexOf('/') + 1);
+  try {
+    return decodeURIComponent(lastSegment) || DEFAULT_FILENAME;
+  } catch {
+    // 非法百分号转义序列，退回原始片段
+    return lastSegment || DEFAULT_FILENAME;
+  }
+}

package/src/shared/utils/error.ts

@@ -0,0 +1,19 @@
+/**
+ * 从任意抛出值中提取可读的错误消息。
+ *
+ * 统一各处 `error instanceof Error ? error.message : String(error)` 的
+ * 重复三元：Error 取 message，其余值（字符串、数字、对象等）String() 化
+ * 作为兜底文案（对象会得到 '[object Object]'，调用方如需结构化信息应
+ * 自行处理，这里只保证「任何失败都有一条可打印的消息」）。
+ */
+function getErrorMessage(error: unknown): string {
+  try {
+    return error instanceof Error ? error.message : String(error);
+  } catch {
+    // String()/message 读取本身可能抛（如带抛异常 Symbol.toPrimitive 的
+    // 对象）：兜底常量保证「任何失败都有一条可打印的消息」这一契约。
+    return 'Unknown error';
+  }
+}
+
+export { getErrorMessage };

package/src/shared/utils/index.ts

@@ -0,0 +1,22 @@
+export * from './cn';
+export * from './date';
+export * from './diff';
+export * from './dom';
+export * from './download';
+export * from './error';
+export * from './inference';
+export * from './letter';
+export * from './merge';
+export * from './nprogress';
+export * from './resources';
+export * from './stack';
+export * from './state-handler';
+export * from './to';
+export * from './tree';
+export * from './unique';
+export * from './update-css-variables';
+export * from './util';
+export * from './window';
+export { debounce, get, isEqual, set } from 'es-toolkit/compat';
+// export { cloneDeep } from 'es-toolkit/object';
+export { default as cloneDeep } from 'lodash.clonedeep';

package/src/shared/utils/inference.ts

@@ -0,0 +1,164 @@
+import { isFunction, isObject, isString } from '@vue/shared';
+
+/**
+ * 检查传入的值是否为undefined。
+ *
+ * @param {unknown} value 要检查的值。
+ * @returns {boolean} 如果值是undefined，返回true，否则返回false。
+ */
+function isUndefined(value?: unknown): value is undefined {
+  return value === undefined;
+}
+
+/**
+ * 检查传入的值是否为boolean
+ * @param value
+ * @returns 如果值是布尔值，返回true，否则返回false。
+ */
+function isBoolean(value: unknown): value is boolean {
+  return typeof value === 'boolean';
+}
+
+/**
+ * 检查传入的值是否为空。
+ *
+ * 以下情况将被认为是空：
+ * - 值为null。
+ * - 值为undefined。
+ * - 值为一个空字符串。
+ * - 值为一个长度为0的数组。
+ * - 值为一个没有元素的Map或Set。
+ * - 值为一个没有属性的对象。
+ *
+ * @param {T} value 要检查的值。
+ * @returns {boolean} 如果值为空，返回true，否则返回false。
+ */
+function isEmpty<T = unknown>(value?: T): value is T {
+  if (value === null || value === undefined) {
+    return true;
+  }
+
+  if (Array.isArray(value) || isString(value)) {
+    return value.length === 0;
+  }
+
+  if (value instanceof Map || value instanceof Set) {
+    return value.size === 0;
+  }
+
+  if (isObject(value)) {
+    return Object.keys(value).length === 0;
+  }
+
+  return false;
+}
+
+/**
+ * 检查传入的字符串是否为有效的HTTP或HTTPS URL。
+ *
+ * @param {string} url 要检查的字符串。
+ * @return {boolean} 如果字符串是有效的HTTP或HTTPS URL，返回true，否则返回false。
+ */
+function isHttpUrl(url?: string): boolean {
+  if (!url) {
+    return false;
+  }
+  // 使用正则表达式测试URL是否以http:// 或 https:// 开头
+  const httpRegex = /^https?:\/\/.*$/;
+  return httpRegex.test(url);
+}
+
+/**
+ * 检查传入的值是否为window对象。
+ *
+ * @param {any} value 要检查的值。
+ * @returns {boolean} 如果值是window对象，返回true，否则返回false。
+ */
+function isWindow(value: any): value is Window {
+  return (
+    typeof window !== 'undefined' && value !== null && value === value.window
+  );
+}
+
+/**
+ * 检查当前运行环境是否为Mac OS。
+ *
+ * 这个函数通过检查navigator.userAgent字符串来判断当前运行环境。
+ * 如果userAgent字符串中包含"macintosh"或"mac os x"（不区分大小写），则认为当前环境是Mac OS。
+ *
+ * @returns {boolean} 如果当前环境是Mac OS，返回true，否则返回false。
+ */
+function isMacOs(): boolean {
+  const macRegex = /macintosh|mac os x/i;
+  return macRegex.test(navigator.userAgent);
+}
+
+/**
+ * 检查当前运行环境是否为Windows OS。
+ *
+ * 这个函数通过检查navigator.userAgent字符串来判断当前运行环境。
+ * 如果userAgent字符串中包含"windows"或"win32"（不区分大小写），则认为当前环境是Windows OS。
+ *
+ * @returns {boolean} 如果当前环境是Windows OS，返回true，否则返回false。
+ */
+function isWindowsOs(): boolean {
+  const windowsRegex = /windows|win32/i;
+  return windowsRegex.test(navigator.userAgent);
+}
+
+/**
+ * 检查传入的值是否为数字
+ * @param value
+ */
+function isNumber(value: any): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/**
+ * Returns the first value in the provided list that is neither `null` nor `undefined`.
+ *
+ * This function iterates over the input values and returns the first one that is
+ * not strictly equal to `null` or `undefined`. If all values are either `null` or
+ * `undefined`, it returns `undefined`.
+ *
+ * @template T - The type of the input values.
+ * @param {...(T | null | undefined)[]} values - A list of values to evaluate.
+ * @returns {T | undefined} - The first value that is not `null` or `undefined`, or `undefined` if none are found.
+ *
+ * @example
+ * // Returns 42 because it is the first non-null, non-undefined value.
+ * getFirstNonNullOrUndefined(undefined, null, 42, 'hello'); // 42
+ *
+ * @example
+ * // Returns 'hello' because it is the first non-null, non-undefined value.
+ * getFirstNonNullOrUndefined(null, undefined, 'hello', 123); // 'hello'
+ *
+ * @example
+ * // Returns undefined because all values are either null or undefined.
+ * getFirstNonNullOrUndefined(undefined, null); // undefined
+ */
+function getFirstNonNullOrUndefined<T>(
+  ...values: (null | T | undefined)[]
+): T | undefined {
+  for (const value of values) {
+    if (value !== undefined && value !== null) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+export {
+  getFirstNonNullOrUndefined,
+  isBoolean,
+  isEmpty,
+  isFunction,
+  isHttpUrl,
+  isMacOs,
+  isNumber,
+  isObject,
+  isString,
+  isUndefined,
+  isWindow,
+  isWindowsOs,
+};

package/src/shared/utils/letter.ts

@@ -0,0 +1,47 @@
+/**
+ * 将字符串的首字母大写
+ * @param string
+ */
+function capitalizeFirstLetter(string: string): string {
+  return string.charAt(0).toUpperCase() + string.slice(1);
+}
+
+/**
+ * 将字符串的首字母转换为小写。
+ *
+ * @param str 要转换的字符串
+ * @returns 首字母小写的字符串
+ */
+function toLowerCaseFirstLetter(str: string): string {
+  if (!str) return str; // 如果字符串为空，直接返回
+  return str.charAt(0).toLowerCase() + str.slice(1);
+}
+
+/**
+ *  生成驼峰命名法的键名
+ * @param key
+ * @param parentKey
+ */
+function toCamelCase(key: string, parentKey: string): string {
+  if (!parentKey) {
+    return key;
+  }
+  return parentKey + key.charAt(0).toUpperCase() + key.slice(1);
+}
+
+function kebabToCamelCase(str: string): string {
+  return str
+    .split('-')
+    .filter(Boolean)
+    .map((word, index) =>
+      index === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1),
+    )
+    .join('');
+}
+
+export {
+  capitalizeFirstLetter,
+  kebabToCamelCase,
+  toCamelCase,
+  toLowerCaseFirstLetter,
+};

package/src/shared/utils/merge.ts

@@ -0,0 +1,11 @@
+import { createDefu } from 'defu';
+
+export { createDefu as createMerge, defu as merge } from 'defu';
+
+export const mergeWithArrayOverride = createDefu((originObj, key, updates) => {
+  if (Array.isArray(originObj[key]) && Array.isArray(updates)) {
+    originObj[key] = updates;
+    return true;
+  }
+  return false;
+});

package/src/shared/utils/nprogress.ts

@@ -0,0 +1,52 @@
+import type NProgress from 'nprogress';
+
+// 创建一个NProgress实例的变量，初始值为null
+let nProgressInstance: null | typeof NProgress = null;
+
+/**
+ * 动态加载NProgress库，并进行配置。
+ * 此函数首先检查是否已经加载过NProgress库，如果已经加载过，则直接返回NProgress实例。
+ * 否则，动态导入NProgress库，进行配置，然后返回NProgress实例。
+ *
+ * @returns  NProgress实例的Promise对象。
+ */
+async function loadNprogress() {
+  if (nProgressInstance) {
+    return nProgressInstance;
+  }
+  nProgressInstance = await import('nprogress');
+  nProgressInstance.configure({
+    showSpinner: true,
+    speed: 300,
+  });
+  return nProgressInstance;
+}
+
+/**
+ * 开始显示进度条。
+ * 此函数首先加载NProgress库，然后调用NProgress的start方法开始显示进度条。
+ */
+async function startProgress() {
+  try {
+    const nprogress = await loadNprogress();
+    nprogress?.start();
+  } catch {
+    // 进度条是增强体验：nprogress 加载失败时静默降级（不抛出），
+    // 调用方可放心 fire-and-forget，不会产生 unhandled rejection。
+  }
+}
+
+/**
+ * 停止显示进度条，并隐藏进度条。
+ * 此函数首先加载NProgress库，然后调用NProgress的done方法停止并隐藏进度条。
+ */
+async function stopProgress() {
+  try {
+    const nprogress = await loadNprogress();
+    nprogress?.done();
+  } catch {
+    // nprogress 未加载成功时无进度条可停，保持静默
+  }
+}
+
+export { startProgress, stopProgress };

package/src/shared/utils/resources.ts

@@ -0,0 +1,21 @@
+/**
+ * 加载js文件
+ * @param src js文件地址
+ */
+function loadScript(src: string) {
+  return new Promise<void>((resolve, reject) => {
+    if (document.querySelector(`script[src="${src}"]`)) {
+      // 如果已经加载过，直接 resolve
+      return resolve();
+    }
+    const script = document.createElement('script');
+    script.src = src;
+    script.addEventListener('load', () => resolve());
+    script.addEventListener('error', () =>
+      reject(new Error(`Failed to load script: ${src}`)),
+    );
+    document.head.append(script);
+  });
+}
+
+export { loadScript };