@mtn-ui-z/utils 0.0.1

package/README.md

@@ -0,0 +1,161 @@
+# @mtn-ui-z/utils
+
+MTN UI 工具函数包，基于 VueUse 构建。
+
+## 安装
+
+```bash
+pnpm add @mtn-ui-z/utils @vueuse/core
+```
+
+## 目录结构
+
+```
+packages/utils/src/
+├── common.ts        # 通用工具函数
+├── function.ts      # 函数工具（防抖、节流）
+├── state.ts         # 状态管理工具
+├── dom.ts           # DOM 操作工具
+├── interaction.ts   # 交互工具（鼠标、滚动等）
+├── media.ts         # 媒体查询工具
+├── types.ts         # 类型定义
+└── index.ts         # 主入口（重新导出所有内容）
+```
+
+## 功能分类
+
+### 通用工具 (`common.ts`)
+
+- `classNames` - 格式化类名
+
+### 函数工具 (`function.ts`)
+
+- `useDebounceFn` - 防抖函数
+- `useThrottleFn` - 节流函数
+
+### 状态管理 (`state.ts`)
+
+本包重新导出了 VueUse 的状态管理函数，包括：
+
+- `useToggle` - 切换布尔值
+- `useCounter` - 计数器
+- `useLocalStorage` - 本地存储
+- `useSessionStorage` - 会话存储
+
+### DOM 操作 (`dom.ts`)
+
+- `onClickOutside` - 点击外部区域
+- `useEventListener` - 事件监听
+- `useElementSize` - 元素尺寸
+- `useResizeObserver` - 尺寸观察
+- `useFocus` - 焦点管理
+- `useHover` - 悬停状态
+- `useClipboard` - 剪贴板操作
+
+### 交互工具 (`interaction.ts`)
+
+- `useMouse` - 鼠标位置
+- `useScroll` - 滚动位置
+- `useWindowSize` - 窗口尺寸
+
+### 媒体查询 (`media.ts`)
+
+- `useMediaQuery` - 媒体查询
+- `usePreferredDark` - 系统暗色偏好
+- `useDark` - 暗色模式
+- `useColorMode` - 颜色模式
+
+## 使用方式
+
+### 全量导入（推荐）
+
+```typescript
+import { classNames, useDebounceFn, useToggle } from '@mtn-ui-z/utils'
+```
+
+### 按分类导入
+
+```typescript
+// 通用工具
+import { classNames } from '@mtn-ui-z/utils/common'
+
+// 函数工具
+import { useDebounceFn, useThrottleFn } from '@mtn-ui-z/utils/function'
+
+// 状态管理
+import { useToggle, useCounter } from '@mtn-ui-z/utils/state'
+
+// DOM 操作
+import { onClickOutside, useElementSize } from '@mtn-ui-z/utils/dom'
+
+// 交互工具
+import { useMouse, useScroll } from '@mtn-ui-z/utils/interaction'
+
+// 媒体查询
+import { useDark, useColorMode } from '@mtn-ui-z/utils/media'
+```
+
+### 主题与密度 (`theme.ts`)
+
+与 `@mtn-ui-z/theme` 的 CSS 变量、`data-theme`、`data-mtn-density` 对齐，并同步 Ant Design Vue `ConfigProvider` 的 `theme.token`：
+
+- `initTheme` — 尽早调用；可从 `localStorage` 恢复亮/暗与密度
+- `setThemePrimary` / `setThemeColors` / `setThemeMode` / `toggleThemeMode`
+- `setDensityMode` / `toggleDensityMode` — 紧凑与舒适
+- `antThemeConfigRef`、`themeModeRef`、`densityModeRef` — 供模板与 `ConfigProvider` 绑定
+
+接入顺序与层叠约定见 `@mtn-ui-z/theme` README 与文档站「自定义主题」。
+
+## 使用示例
+
+### 防抖和节流
+
+```typescript
+import { useDebounceFn, useThrottleFn } from '@mtn-ui-z/utils'
+
+// 防抖
+const debouncedSearch = useDebounceFn((query: string) => {
+  console.log('Search:', query)
+}, 300)
+
+// 节流
+const throttledScroll = useThrottleFn(() => {
+  console.log('Scrolled')
+}, 100)
+```
+
+### 状态管理
+
+```typescript
+import { useToggle, useCounter, useLocalStorage } from '@mtn-ui-z/utils'
+
+// 切换状态
+const [isOpen, toggle] = useToggle(false)
+
+// 计数器
+const { count, inc, dec, reset } = useCounter(0)
+
+// 本地存储
+const stored = useLocalStorage('key', 'default-value')
+```
+
+### DOM 操作
+
+```typescript
+import { onClickOutside, useElementSize } from '@mtn-ui-z/utils'
+import { ref } from 'vue'
+
+const target = ref<HTMLElement>()
+
+// 点击外部区域
+onClickOutside(target, () => {
+  console.log('Clicked outside')
+})
+
+// 元素尺寸
+const { width, height } = useElementSize(target)
+```
+
+## 更多文档
+
+查看 [VueUse 官方文档](https://vueuse.org/) 了解更多功能。

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@mtn-ui-z/utils",
+  "version": "0.0.1",
+  "description": "MTN UI Utils",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.d.ts",
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "vue": "^3.5.0",
+    "@vueuse/core": "^11.0.0"
+  },
+  "dependencies": {
+    "@vueuse/core": "^11.0.0",
+    "axios": "^1.7.0",
+    "dayjs": "^1.11.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/common.d.ts

@@ -0,0 +1,3 @@
+export function classNames(
+  ...classes: (string | undefined | null | false)[]
+): string

package/src/common.ts

@@ -0,0 +1,16 @@
+/**
+ * 通用工具函数
+ */
+
+/**
+ * 格式化类名
+ * 工具函数，用于合并多个类名
+ * 
+ * @example
+ * ```ts
+ * classNames('foo', 'bar', false, 'baz') // => 'foo bar baz'
+ * ```
+ */
+export function classNames(...classes: (string | undefined | null | false)[]): string {
+  return classes.filter(Boolean).join(' ')
+}

package/src/date.ts

@@ -0,0 +1,34 @@
+/**
+ * 日期格式化工具
+ */
+import dayjs from 'dayjs'
+
+/**
+ * 格式化日期（YYYY-MM-DD）
+ */
+export function formatDate(value: unknown): string {
+  if (!value) return ''
+  const date = dayjs(value as string | number | Date)
+  if (!date.isValid()) return String(value)
+  return date.format('YYYY-MM-DD')
+}
+
+/**
+ * 格式化日期时间（YYYY-MM-DD HH:mm:ss）
+ */
+export function formatDateTime(value: unknown): string {
+  if (!value) return ''
+  const date = dayjs(value as string | number | Date)
+  if (!date.isValid()) return String(value)
+  return date.format('YYYY-MM-DD HH:mm:ss')
+}
+
+/**
+ * 格式化年月（YYYY-MM）
+ */
+export function formatYearMonth(value: unknown): string {
+  if (!value) return ''
+  const date = dayjs(value as string | number | Date)
+  if (!date.isValid()) return String(value)
+  return date.format('YYYY-MM')
+}

package/src/dict.ts

@@ -0,0 +1,193 @@
+/**
+ * 数据字典：通过接口获取，与 DictSelect 约定一致的字典项结构
+ */
+import { ref, type Ref, inject, type InjectionKey } from 'vue'
+import { request } from './request'
+import type { Result } from './request-types'
+import { getStorage, setStorage } from './storage'
+
+/** 字典项结构（与 @mtn-ui-z/components DictSelect 一致） */
+export interface DictItem {
+  dictLabel: string
+  dictValue: string
+  /** 颜色（如状态、标签场景下的展示色），可选 */
+  dictColor?: string
+  [key: string]: unknown
+}
+
+/** 请求字典的接口：传入多个 dictKey，返回各 key 对应的字典项数组（一个接口） */
+export type FetchDictFn = (dictKeys: string[]) => Promise<Record<string, DictItem[]>>
+
+const MOCK_MAP: Record<string, DictItem[]> = {
+  order_status: [
+    { dictLabel: '待支付', dictValue: '10' },
+    { dictLabel: '已支付', dictValue: '20' },
+    { dictLabel: '已取消', dictValue: '30' },
+  ],
+  pay_type: [
+    { dictLabel: '微信', dictValue: 'wx' },
+    { dictLabel: '支付宝', dictValue: 'alipay' },
+  ],
+}
+
+const DEFAULT_LIST: DictItem[] = [
+  { dictLabel: '选项一', dictValue: '1' },
+  { dictLabel: '选项二', dictValue: '2' },
+]
+
+/** 默认假数据：一次传入多个 key，返回 key -> 字典项数组（暂无接口时使用） */
+function defaultMockFetch(dictKeys: string[]): Promise<Record<string, DictItem[]>> {
+  const res: Record<string, DictItem[]> = {}
+  dictKeys.forEach(key => {
+    res[key] = MOCK_MAP[key] ?? DEFAULT_LIST
+  })
+  return Promise.resolve(res)
+}
+
+/** localStorage 的 key 前缀，与 DictSelect 的 storageKeyPrefix 一致时可直接用 dictType 读缓存 */
+export const DEFAULT_DICT_STORAGE_PREFIX = 'dict_'
+
+/** 字典全局配置（可在 App 初始化时 provide，useDict 会 inject 读取） */
+export interface DictGlobalConfig {
+  /** 字典接口地址，传入则通过 request 请求该 URL（params: { keys }），响应需为 Result<Record<string, DictItem[]>> */
+  dictApiUrl?: string
+  /** 请求完成后是否写入 localStorage，默认 true */
+  storeInStorage?: boolean
+  /** localStorage key 前缀，默认 dict_ */
+  storageKeyPrefix?: string
+}
+
+/** 注入 key（用于 provide/inject） */
+export const DICT_CONFIG_KEY: InjectionKey<DictGlobalConfig> = Symbol('dictConfig')
+
+export interface UseDictOptions {
+  /** 字典接口地址，传入则通过 request 请求该 URL（params: { keys }），响应需为 Result<Record<string, DictItem[]>> */
+  dictApiUrl?: string
+  /** 自定义请求方法，优先级高于 dictApiUrl；不传且无 dictApiUrl 时用内置假数据 */
+  fetchDict?: FetchDictFn
+  /** 请求完成后是否写入 localStorage，默认 true；按「一个字典一个 key」存储（key = storageKeyPrefix + dictKey） */
+  storeInStorage?: boolean
+  /** localStorage key 前缀，默认 dict_，单条 key 如 dict_order_status */
+  storageKeyPrefix?: string
+}
+
+/**
+ * 按字典 key 列表调用一次接口获取多组字典，返回 key -> 字典项数组 的响应式对象。
+ * 用法：useDict(['order_status', 'pay_type'])，返回的 ref 中 result.value.order_status 即为该 key 的 DictItem[]。
+ * 暂无接口时使用内置假数据；有接口后传入 fetchDict(dictKeys) 即可（接口入参为多个 key，出参为 Record<string, DictItem[]>）。
+ */
+function fetchByRequest(dictApiUrl: string, keys: string[]): Promise<Record<string, DictItem[]>> {
+  return request
+    .post<Result<Record<string, DictItem[]>>>(dictApiUrl, { dict_code: keys })
+    .then(res => normalizeDictMap(res.data))
+}
+
+function normalizeDictItem(item: DictItem): DictItem {
+  return {
+    ...item,
+    dictLabel: String(item.dictLabel ?? item.dict_label ?? ''),
+    dictValue: String(item.dictValue ?? item.dict_value ?? ''),
+    dictColor:
+      typeof item.dictColor === 'string'
+        ? item.dictColor
+        : typeof item.dict_color === 'string'
+          ? item.dict_color
+          : undefined
+  }
+}
+
+function normalizeDictMap(data: Record<string, DictItem[]>): Record<string, DictItem[]> {
+  const normalized: Record<string, DictItem[]> = {}
+  Object.entries(data ?? {}).forEach(([dictKey, list]) => {
+    normalized[dictKey] = Array.isArray(list) ? list.map(item => normalizeDictItem(item)) : []
+  })
+  return normalized
+}
+
+/** 正在请求中的 promise（避免同一 key 并发重复请求） */
+const pendingRequests = new Map<string, Promise<Record<string, DictItem[]>>>()
+
+export function useDict(
+  keys: string[],
+  options: UseDictOptions = {}
+): Ref<Record<string, DictItem[]>> {
+  const result = ref<Record<string, DictItem[]>>({}) as Ref<Record<string, DictItem[]>>
+
+  // 读取全局配置（App 级别 provide 的），局部 options 优先级更高
+  const globalConfig = inject(DICT_CONFIG_KEY, {})
+  const dictApiUrl = options.dictApiUrl ?? globalConfig.dictApiUrl
+  const storeInStorage = options.storeInStorage ?? globalConfig.storeInStorage ?? true
+  const prefix =
+    options.storageKeyPrefix ?? globalConfig.storageKeyPrefix ?? DEFAULT_DICT_STORAGE_PREFIX
+
+  // 根据配置决定请求方式：局部 fetchDict > 全局 dictApiUrl > 内置 mock
+  const fetchDict =
+    options.fetchDict ??
+    (dictApiUrl ? (dictKeys: string[]) => fetchByRequest(dictApiUrl, dictKeys) : defaultMockFetch)
+
+  // 优先从 localStorage 读取已有缓存，减少不必要的请求
+  const cachedResult: Record<string, DictItem[]> = {}
+  const missingKeys: string[] = []
+
+  for (const key of keys) {
+    const cached = getStorage<DictItem[]>(prefix + key)
+    if (cached !== undefined && cached.length > 0) {
+      cachedResult[key] = cached.map(item => normalizeDictItem(item))
+    } else {
+      missingKeys.push(key)
+    }
+  }
+
+  // 已有缓存的处理
+  if (Object.keys(cachedResult).length > 0) {
+    result.value = cachedResult
+  }
+
+  // 全部命中缓存，无需请求
+  if (missingKeys.length === 0) {
+    return result
+  }
+
+  // 构造新请求，并缓存 promise 引用（按 sorted keys 做去重）
+  const pendingKey = missingKeys.sort().join(',')
+  const existingPending = pendingRequests.get(pendingKey)
+
+  if (existingPending) {
+    existingPending
+      .then(data => {
+        const normalizedData = normalizeDictMap(data)
+        if (storeInStorage) {
+          Object.entries(normalizedData).forEach(([dictKey, list]) => {
+            setStorage(prefix + dictKey, list)
+          })
+        }
+        result.value = { ...result.value, ...normalizedData }
+      })
+      .catch(() => {
+        result.value = { ...result.value, ...Object.fromEntries(missingKeys.map(k => [k, []])) }
+      })
+    return result
+  }
+
+  const reqPromise = fetchDict(missingKeys)
+  pendingRequests.set(pendingKey, reqPromise)
+
+  reqPromise
+    .then(data => {
+      const normalizedData = normalizeDictMap(data)
+      result.value = { ...result.value, ...normalizedData }
+      if (storeInStorage) {
+        Object.entries(normalizedData).forEach(([dictKey, list]) => {
+          setStorage(prefix + dictKey, list)
+        })
+      }
+    })
+    .catch(() => {
+      result.value = { ...result.value, ...Object.fromEntries(missingKeys.map(k => [k, []])) }
+    })
+    .finally(() => {
+      pendingRequests.delete(pendingKey)
+    })
+
+  return result
+}

package/src/dom.d.ts

@@ -0,0 +1,8 @@
+export {
+  onClickOutside,
+  useEventListener,
+  useElementSize,
+  useResizeObserver,
+  useFocus,
+  useClipboard
+} from '@vueuse/core'

package/src/dom.ts

@@ -0,0 +1,20 @@
+/*
+ * @Author: liaokt
+ * @Description: 
+ * @Date: 2026-01-21 10:19:31
+ * @LastEditors: liaokt
+ * @LastEditTime: 2026-01-26 16:09:27
+ */
+/**
+ * DOM 操作工具
+ * 与 DOM 元素交互相关的工具函数
+ */
+
+export {
+  onClickOutside,
+  useEventListener,
+  useElementSize,
+  useResizeObserver,
+  useFocus,
+  useClipboard
+} from '@vueuse/core'

package/src/function.d.ts

@@ -0,0 +1 @@
+export { useDebounceFn, useThrottleFn } from '@vueuse/core'

package/src/function.ts

@@ -0,0 +1,9 @@
+/**
+ * 函数工具
+ * 防抖、节流等函数处理工具
+ */
+
+export {
+  useDebounceFn,
+  useThrottleFn
+} from '@vueuse/core'

package/src/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @mtn-ui-z/utils 类型声明入口
+ * 供 package.json "types" 指向，避免部分环境下 TS 无法解析 node_modules 内 .ts
+ */
+export * from './common'
+export * from './function'
+export * from './state'
+export * from './storage'
+export * from './dom'
+export * from './interaction'
+export * from './media'
+export * from './permission'
+export * from './theme'
+export * from './dict'
+export * from './request-types'
+export {
+  createRequest,
+  request,
+  axiosInstance,
+  type CreateRequestOptions
+} from './request'
+
+// 表格状态管理
+export * from './useTable'
+
+// Modal 命令式调用
+export * from './useModal'
+
+// Modal 注册表
+export * from './modalRegistry'
+
+// 日期格式化
+export * from './date'
+
+// 类型定义
+export * from './types'

package/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * MTN UI Utils
+ * 
+ * 基于 VueUse 的工具函数集合
+ * 
+ * @module @mtn-ui-z/utils
+ */
+
+// 通用工具
+export * from './common'
+
+// 函数工具
+export * from './function'
+
+// 状态管理
+export * from './state'
+
+// 本地/会话存储
+export * from './storage'
+
+// DOM 操作
+export * from './dom'
+
+// 交互工具
+export * from './interaction'
+
+// 媒体查询
+export * from './media'
+
+// 权限管理
+export * from './permission'
+
+// 主题色（运行时）
+export * from './theme'
+
+// 数据字典
+export * from './dict'
+
+// 请求与 API 类型
+export * from './request-types'
+export {
+  createRequest,
+  request,
+  axiosInstance,
+  type CreateRequestOptions
+} from './request'
+
+// 表格状态管理
+export * from './useTable'
+
+// Modal 命令式调用
+export * from './useModal'
+
+// Modal 注册表
+export * from './modalRegistry'
+
+// 日期格式化
+export * from './date'
+
+// 类型定义
+export * from './types'

package/src/interaction.d.ts

@@ -0,0 +1 @@
+export { useMouse, useScroll, useWindowSize } from '@vueuse/core'

package/src/interaction.ts

@@ -0,0 +1,10 @@
+/**
+ * 交互工具
+ * 鼠标、滚动、窗口等交互相关的工具函数
+ */
+
+export {
+  useMouse,
+  useScroll,
+  useWindowSize
+} from '@vueuse/core'

package/src/media.d.ts

@@ -0,0 +1,6 @@
+export {
+  useMediaQuery,
+  usePreferredDark,
+  useDark,
+  useColorMode
+} from '@vueuse/core'

package/src/media.ts

@@ -0,0 +1,11 @@
+/**
+ * 媒体查询工具
+ * 媒体查询、主题、颜色模式相关的工具函数
+ */
+
+export {
+  useMediaQuery,
+  usePreferredDark,
+  useDark,
+  useColorMode
+} from '@vueuse/core'

package/src/modalRegistry.ts

@@ -0,0 +1,37 @@
+/**
+ * Modal 注册表
+ * 存储已注册的 Modal 组件定义，供 MxModalProvider 渲染使用
+ */
+import type { Component } from 'vue'
+
+/** Modal 组件注册项 */
+interface ModalRegistryItem {
+  component: Component
+}
+
+const registry = new Map<string, ModalRegistryItem>()
+
+export const ModalRegistry = {
+  /**
+   * 注册一个 Modal 组件
+   * @param id       唯一标识
+   * @param component Vue 组件
+   */
+  register(id: string, component: Component) {
+    registry.set(id, { component })
+  },
+
+  /**
+   * 注销一个 Modal 组件
+   */
+  unregister(id: string) {
+    registry.delete(id)
+  },
+
+  /**
+   * 根据 id 获取已注册的组件
+   */
+  get(id: string): Component | undefined {
+    return registry.get(id)?.component
+  }
+}

package/src/permission.d.ts

@@ -0,0 +1,27 @@
+import type { InjectionKey, Ref, MaybeRefOrGetter, ComputedRef } from 'vue'
+
+export type PermissionChecker = (permission: string | string[]) => boolean
+export type PermissionAction = 'hide' | 'disable'
+
+export const defaultPermissionChecker: PermissionChecker
+export const PERMISSION_CHECKER_KEY: InjectionKey<Ref<PermissionChecker>>
+export const USER_PERMISSIONS_KEY: InjectionKey<Ref<string[]>>
+
+export function createPermissionChecker(permissions: Ref<string[]>): PermissionChecker
+export function hasPermission(
+  userPermissions: string[],
+  requiredPermission: string | string[]
+): boolean
+
+export interface UsePermissionOptions {
+  permission?: MaybeRefOrGetter<string | string[] | undefined>
+  permissionAction?: MaybeRefOrGetter<PermissionAction | undefined>
+}
+
+export interface UsePermissionReturn {
+  hasPermission: ComputedRef<boolean>
+  shouldHide: ComputedRef<boolean>
+  shouldDisable: ComputedRef<boolean>
+}
+
+export function usePermission(options: UsePermissionOptions): UsePermissionReturn