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

package/src/shared/utils/stack.ts

@@ -0,0 +1,103 @@
+/**
+ * @zh_CN 栈数据结构
+ */
+export class Stack<T> {
+  /**
+   * @zh_CN 栈内元素数量
+   */
+  get size() {
+    return this.items.length;
+  }
+  /**
+   * @zh_CN 是否去重
+   */
+  private readonly dedup: boolean;
+  /**
+   * @zh_CN 栈内元素
+   */
+  private items: T[] = [];
+
+  /**
+   * @zh_CN 栈的最大容量
+   */
+  private readonly maxSize?: number;
+
+  constructor(dedup = true, maxSize?: number) {
+    this.maxSize = maxSize;
+    this.dedup = dedup;
+  }
+
+  /**
+   * @zh_CN 清空栈内元素
+   */
+  clear() {
+    this.items.length = 0;
+  }
+
+  /**
+   * @zh_CN 查看栈顶元素
+   * @returns 栈顶元素
+   */
+  peek(): T | undefined {
+    return this.items[this.items.length - 1];
+  }
+
+  /**
+   * @zh_CN 出栈
+   * @returns 栈顶元素
+   */
+  pop(): T | undefined {
+    return this.items.pop();
+  }
+
+  /**
+   * @zh_CN 入栈
+   * @param items 要入栈的元素
+   */
+  push(...items: T[]) {
+    items.forEach((item) => {
+      // 去重
+      if (this.dedup) {
+        const index = this.items.indexOf(item);
+        if (index !== -1) {
+          this.items.splice(index, 1);
+        }
+      }
+      this.items.push(item);
+      if (this.maxSize && this.items.length > this.maxSize) {
+        this.items.splice(0, this.items.length - this.maxSize);
+      }
+    });
+  }
+  /**
+   * @zh_CN 移除栈内元素
+   * @param itemList 要移除的元素列表
+   */
+  remove(...itemList: T[]) {
+    this.items = this.items.filter((i) => !itemList.includes(i));
+  }
+  /**
+   * @zh_CN 保留栈内元素
+   * @param itemList 要保留的元素列表
+   */
+  retain(itemList: T[]) {
+    this.items = this.items.filter((i) => itemList.includes(i));
+  }
+
+  /**
+   * @zh_CN 转换为数组
+   * @returns 栈内元素数组
+   */
+  toArray(): T[] {
+    return [...this.items];
+  }
+}
+
+/**
+ * @zh_CN 创建一个栈实例
+ * @param dedup 是否去重
+ * @param maxSize 栈的最大容量
+ * @returns 栈实例
+ */
+export const createStack = <T>(dedup = true, maxSize?: number) =>
+  new Stack<T>(dedup, maxSize);

package/src/shared/utils/state-handler.ts

@@ -0,0 +1,61 @@
+export class StateHandler {
+  private condition: boolean = false;
+  private rejectConditions: ((reason?: Error) => void)[] = [];
+  private resolveConditions: (() => void)[] = [];
+
+  isConditionTrue(): boolean {
+    return this.condition;
+  }
+
+  reset() {
+    this.condition = false;
+    // Callers that awaited the condition must not be left pending: after a
+    // reset (e.g. unmount) the gate they wait for will not open for them.
+    const pendingRejects = this.rejectConditions;
+    this.clearPromises();
+    for (const reject of pendingRejects) {
+      reject(new Error('Condition was reset'));
+    }
+  }
+
+  // 触发状态为 false 时，reject 所有等待中的 Promise
+  setConditionFalse() {
+    this.condition = false;
+    const pendingRejects = this.rejectConditions;
+    this.clearPromises();
+    for (const reject of pendingRejects) {
+      reject(new Error('Condition was set to false'));
+    }
+  }
+
+  // 触发状态为 true 时，resolve 所有等待中的 Promise
+  setConditionTrue() {
+    this.condition = true;
+    const pendingResolves = this.resolveConditions;
+    this.clearPromises();
+    for (const resolve of pendingResolves) {
+      resolve();
+    }
+  }
+
+  // 返回一个 Promise，等待 condition 变为 true；支持多个并发等待者
+  waitForCondition(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.condition) {
+        resolve(); // 如果 condition 已经为 true，立即 resolve
+      } else {
+        // condition 变为 true/false 前可能有多个调用方同时等待，
+        // 需要把所有 resolve/reject 都收集起来，切换时一次性结算，
+        // 否则后注册者会覆盖前一个句柄，导致先注册的等待方永远挂起。
+        this.resolveConditions.push(resolve);
+        this.rejectConditions.push(reject);
+      }
+    });
+  }
+
+  // 清理所有等待中的 resolve/reject 函数
+  private clearPromises() {
+    this.resolveConditions = [];
+    this.rejectConditions = [];
+  }
+}

package/src/shared/utils/to.ts

@@ -0,0 +1,21 @@
+/**
+ * @param { Readonly<Promise> } promise
+ * @param {object=} errorExt - Additional Information you can pass to the err object
+ * @return { Promise }
+ */
+export async function to<T, U = Error>(
+  promise: Readonly<Promise<T>>,
+  errorExt?: object,
+): Promise<[null, T] | [U, undefined]> {
+  try {
+    const data = await promise;
+    const result: [null, T] = [null, data];
+    return result;
+  } catch (error) {
+    if (errorExt) {
+      const parsedError = Object.assign({}, error, errorExt);
+      return [parsedError as U, undefined];
+    }
+    return [error as U, undefined];
+  }
+}

package/src/shared/utils/tree.ts

@@ -0,0 +1,159 @@
+interface TreeConfigOptions {
+  // 子属性的名称，默认为'children'
+  childProps: string;
+}
+
+/**
+ * @zh_CN 遍历树形结构，并返回所有节点中指定的值。
+ * @param tree 树形结构数组
+ * @param getValue 获取节点值的函数
+ * @param options 作为子节点数组的可选属性名称。
+ * @returns 所有节点中指定的值的数组
+ */
+function traverseTreeValues<T, V>(
+  tree: T[],
+  getValue: (node: T) => V,
+  options?: TreeConfigOptions,
+): V[] {
+  const result: V[] = [];
+  const { childProps } = options || {
+    childProps: 'children',
+  };
+
+  const dfs = (treeNode: T) => {
+    const value = getValue(treeNode);
+    result.push(value);
+    const children = (treeNode as Record<string, any>)?.[childProps];
+    if (!children) {
+      return;
+    }
+    if (children.length > 0) {
+      for (const child of children) {
+        dfs(child);
+      }
+    }
+  };
+
+  for (const treeNode of tree) {
+    dfs(treeNode);
+  }
+  return result.filter(Boolean);
+}
+
+/**
+ * 根据条件过滤给定树结构的节点，并以原有顺序返回所有匹配节点的数组。
+ *
+ * 该函数是纯函数：不会把过滤后的结果写回传入的树（源数据不被修改）。
+ * 否则第二次用不同条件过滤同一棵树时（例如切换用户角色后重新生成路由），
+ * 上一次被过滤掉的子节点将永久丢失。
+ *
+ * 引用语义：只有当子节点序列真的发生变化时，命中的分支节点才会被浅拷贝；
+ * 子节点未发生变化（或节点没有子节点）时，仍按引用返回原节点，
+ * 因此按引用缓存或比较节点的调用方，其行为保持不变。
+ *
+ * @param tree 要过滤的树结构的根节点数组。
+ * @param filter 用于匹配每个节点的条件。
+ * @param options 作为子节点数组的可选属性名称。
+ * @returns 包含所有匹配节点的数组。
+ */
+function filterTree<T extends Record<string, any>>(
+  tree: T[],
+  filter: (node: T) => boolean,
+  options?: TreeConfigOptions,
+): T[] {
+  const { childProps } = options || {
+    childProps: 'children',
+  };
+
+  const _filterTree = (nodes: T[]): T[] => {
+    const result: T[] = [];
+
+    for (const node of nodes) {
+      if (!filter(node)) {
+        continue;
+      }
+
+      const children = (node as Record<string, any>)[childProps];
+
+      if (!children) {
+        result.push(node);
+        continue;
+      }
+
+      const filteredChildren = _filterTree(children);
+
+      // 子节点序列没有变化时按引用返回原节点，保持原有的引用语义；
+      // 只有确实需要替换子节点时才复制节点，避免污染源数据
+      const childrenUnchanged =
+        filteredChildren.length === children.length &&
+        filteredChildren.every((child, index) => child === children[index]);
+
+      result.push(
+        childrenUnchanged ? node : { ...node, [childProps]: filteredChildren },
+      );
+    }
+
+    return result;
+  };
+
+  return _filterTree(tree);
+}
+
+/**
+ * 根据条件重新映射给定树结构的节
+ * @param tree 要过滤的树结构的根节点数组。
+ * @param mapper 用于map每个节点的条件。
+ * @param options 作为子节点数组的可选属性名称。
+ */
+function mapTree<T, V extends Record<string, any>>(
+  tree: T[],
+  mapper: (node: T, parent: null | V) => V,
+  options?: TreeConfigOptions,
+  parent: null | V = null,
+): V[] {
+  const { childProps } = options || {
+    childProps: 'children',
+  };
+  return tree.map((node) => {
+    const mapperNode: Record<string, any> = mapper(node, parent);
+    if (mapperNode[childProps]) {
+      mapperNode[childProps] = mapTree(
+        mapperNode[childProps],
+        mapper,
+        options,
+        mapperNode as V,
+      );
+    }
+    return mapperNode as V;
+  });
+}
+
+/**
+ * 对树形结构数据进行递归排序
+ * @param treeData - 树形数据数组
+ * @param sortFunction - 排序函数，用于定义排序规则
+ * @param options - 配置选项，包括子节点属性名
+ * @returns 排序后的树形数据
+ */
+function sortTree<T extends Record<string, any>>(
+  treeData: T[],
+  sortFunction: (a: T, b: T) => number,
+  options?: TreeConfigOptions,
+): T[] {
+  const { childProps } = options || {
+    childProps: 'children',
+  };
+
+  return treeData.toSorted(sortFunction).map((item) => {
+    const children = item[childProps];
+    if (children && Array.isArray(children) && children.length > 0) {
+      return {
+        ...item,
+        [childProps]: sortTree(children, sortFunction, options),
+      };
+    }
+    return item;
+  });
+}
+
+export { filterTree, mapTree, sortTree, traverseTreeValues };

package/src/shared/utils/unique.ts

@@ -0,0 +1,15 @@
+/**
+ * 根据指定字段对对象数组进行去重
+ * @param arr 要去重的对象数组
+ * @param key 去重依据的字段名
+ * @returns 去重后的对象数组
+ */
+function uniqueByField<T>(arr: T[], key: keyof T): T[] {
+  const seen = new Map<any, T>();
+  return arr.filter((item) => {
+    const value = item[key];
+    return seen.has(value) ? false : (seen.set(value, item), true);
+  });
+}
+
+export { uniqueByField };

package/src/shared/utils/update-css-variables.ts

@@ -0,0 +1,47 @@
+/**
+ * 更新 CSS 变量的函数
+ * @param variables 要更新的 CSS 变量与其新值的映射
+ * @param id 内联样式表的 id，便于复用与覆盖
+ * @param selector CSS 变量挂载的选择器，默认 `:root`。
+ *  对于像 TDesign 这种将变量定义在 `:root[theme-mode='dark']` 等更高优先级选择器下的组件库，
+ *  需要传入相同（或更高）优先级的选择器才能正确覆盖。
+ */
+function updateCSSVariables(
+  variables: { [key: string]: string },
+  id = '__vben-styles__',
+  selector = ':root',
+): void {
+  // 历史实现用 setTimeout 延迟插入创建的样式标签，若同一宏任务内被连续调用
+  // （如初始化偏好后又恢复用户偏好），querySelector 尚找不到未插入的标签，
+  // 会重复创建同 id 标签：运行时只更新第一个，而级联获胜的却是第二个（旧值），
+  // 导致主题色切换后部分组件不生效、刷新页面才恢复。
+  // 这里改为同步插入消除并发窗口，并顺带清理历史遗留的重复标签。
+  const existingStyles = document.querySelectorAll<HTMLElement>(`#${id}`);
+  existingStyles.forEach((element, index) => {
+    if (index > 0) {
+      element.remove();
+    }
+  });
+
+  let styleElement = existingStyles[0] ?? null;
+
+  if (!styleElement) {
+    styleElement = document.createElement('style');
+    styleElement.id = id;
+    document.head.append(styleElement);
+  }
+
+  // 构建要更新的 CSS 变量的样式文本
+  let cssText = `${selector} {`;
+  for (const key in variables) {
+    if (Object.prototype.hasOwnProperty.call(variables, key)) {
+      cssText += `${key}: ${variables[key]};`;
+    }
+  }
+  cssText += '}';
+
+  // 将样式文本赋值给内联样式表
+  styleElement.textContent = cssText;
+}
+
+export { updateCSSVariables };

package/src/shared/utils/util.ts

@@ -0,0 +1,50 @@
+// 泛型参数是已发布的公共 API 契约（调用方以 bindMethods<MyClass>(instance)
+// 显式传参），规则只看签名内出现次数、不评估跨包调用方，不能据此删除。
+// oxlint-disable-next-line typescript/no-unnecessary-type-parameters
+export function bindMethods<T extends object>(instance: T): void {
+  const prototype = Object.getPrototypeOf(instance);
+  const propertyNames = Object.getOwnPropertyNames(prototype);
+
+  propertyNames.forEach((propertyName) => {
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, propertyName);
+    const propertyValue = instance[propertyName as keyof T];
+
+    if (
+      typeof propertyValue === 'function' &&
+      propertyName !== 'constructor' &&
+      descriptor &&
+      !descriptor.get &&
+      !descriptor.set
+    ) {
+      instance[propertyName as keyof T] = propertyValue.bind(instance);
+    }
+  });
+}
+
+/**
+ * 获取嵌套对象的字段值
+ * @param obj - 要查找的对象
+ * @param path - 用于查找字段的路径，使用小数点分隔
+ * @returns 字段值，或者未找到时返回 undefined
+ */
+// 同 bindMethods：getNestedValue<MyData>(data, path) 的显式类型实参是
+// 已发布调用契约，保留泛型。
+// oxlint-disable-next-line typescript/no-unnecessary-type-parameters
+export function getNestedValue<T>(obj: T, path: string): any {
+  if (typeof path !== 'string' || path.length === 0) {
+    throw new Error('Path must be a non-empty string');
+  }
+  // 把路径字符串按 "." 分割成数组
+  const keys = path.split('.') as (number | string)[];
+
+  let current: any = obj;
+
+  for (const key of keys) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    current = current[key as keyof typeof current];
+  }
+
+  return current;
+}

package/src/shared/utils/window.ts

@@ -0,0 +1,37 @@
+interface OpenWindowOptions {
+  noopener?: boolean;
+  noreferrer?: boolean;
+  target?: '_blank' | '_parent' | '_self' | '_top' | (string & {});
+}
+
+/**
+ * 新窗口打开URL。
+ *
+ * @param url - 需要打开的网址。
+ * @param options - 打开窗口的选项。
+ */
+function openWindow(url: string, options: OpenWindowOptions = {}): void {
+  // 解构并设置默认值
+  const { noopener = true, noreferrer = true, target = '_blank' } = options;
+
+  // 基于选项创建特性字符串
+  const features = [noopener && 'noopener=yes', noreferrer && 'noreferrer=yes']
+    .filter(Boolean)
+    .join(',');
+
+  // 打开窗口
+  window.open(url, target, features);
+}
+
+/**
+ * 在新窗口中打开路由。
+ * @param path
+ */
+function openRouteInNewWindow(path: string) {
+  const { hash, origin } = location;
+  const fullPath = path.startsWith('/') ? path : `/${path}`;
+  const url = `${origin}${hash && !fullPath.includes('/#') ? '/#' : ''}${fullPath}`;
+  openWindow(url, { target: '_blank' });
+}
+
+export { openRouteInNewWindow, openWindow };

package/src/stores/index.ts

@@ -0,0 +1,3 @@
+export * from './modules';
+export * from './setup';
+export { defineStore, storeToRefs } from 'pinia';

package/src/stores/modules/access.ts

@@ -0,0 +1,130 @@
+import type { RouteRecordRaw } from 'vue-router';
+
+import type { MenuRecordRaw } from '@melt-js/libs-vben/typings';
+
+import { acceptHMRUpdate, defineStore } from 'pinia';
+
+type AccessToken = null | string;
+
+interface AccessState {
+  /**
+   * 权限码
+   */
+  accessCodes: string[];
+  /**
+   * 可访问的菜单列表
+   */
+  accessMenus: MenuRecordRaw[];
+  /**
+   * 可访问的路由列表
+   */
+  accessRoutes: RouteRecordRaw[];
+  /**
+   * 登录 accessToken
+   */
+  accessToken: AccessToken;
+  /**
+   * 是否已经检查过权限
+   */
+  isAccessChecked: boolean;
+  /**
+   * 是否锁屏状态
+   */
+  isLockScreen: boolean;
+  /**
+   * 锁屏密码
+   */
+  lockScreenPassword?: string;
+  /**
+   * 登录是否过期
+   */
+  loginExpired: boolean;
+  /**
+   * 登录 accessToken
+   */
+  refreshToken: AccessToken;
+}
+
+/**
+ * @zh_CN 访问权限相关
+ */
+export const useAccessStore = defineStore('core-access', {
+  actions: {
+    getMenuByPath(path: string) {
+      function findMenu(
+        menus: MenuRecordRaw[],
+        path: string,
+      ): MenuRecordRaw | undefined {
+        for (const menu of menus) {
+          if (menu.path === path) {
+            return menu;
+          }
+          if (menu.children) {
+            const matched = findMenu(menu.children, path);
+            if (matched) {
+              return matched;
+            }
+          }
+        }
+        return undefined;
+      }
+      return findMenu(this.accessMenus, path);
+    },
+    lockScreen(password: string) {
+      this.isLockScreen = true;
+      this.lockScreenPassword = password;
+    },
+    setAccessCodes(codes: string[]) {
+      this.accessCodes = codes;
+    },
+    setAccessMenus(menus: MenuRecordRaw[]) {
+      this.accessMenus = menus;
+    },
+    setAccessRoutes(routes: RouteRecordRaw[]) {
+      this.accessRoutes = routes;
+    },
+    setAccessToken(token: AccessToken) {
+      this.accessToken = token;
+    },
+    setIsAccessChecked(isAccessChecked: boolean) {
+      this.isAccessChecked = isAccessChecked;
+    },
+    setLoginExpired(loginExpired: boolean) {
+      this.loginExpired = loginExpired;
+    },
+    setRefreshToken(token: AccessToken) {
+      this.refreshToken = token;
+    },
+    unlockScreen() {
+      this.isLockScreen = false;
+      this.lockScreenPassword = undefined;
+    },
+  },
+  persist: {
+    // 持久化
+    pick: [
+      'accessToken',
+      'refreshToken',
+      'accessCodes',
+      'isLockScreen',
+      'lockScreenPassword',
+    ],
+  },
+  state: (): AccessState => ({
+    accessCodes: [],
+    accessMenus: [],
+    accessRoutes: [],
+    accessToken: null,
+    isAccessChecked: false,
+    isLockScreen: false,
+    lockScreenPassword: undefined,
+    loginExpired: false,
+    refreshToken: null,
+  }),
+});
+
+// 解决热更新问题
+const hot = import.meta.hot;
+if (hot) {
+  hot.accept(acceptHMRUpdate(useAccessStore, hot));
+}