@zl-ui-kit/theme 0.16.0 → 0.17.1

package/src/runtime/api.ts

@@ -1,305 +1,305 @@
-/**
- * @zl-ui-kit/theme 运行时 API（需求 §7.2.3，D7）
- * L2：defineTheme 运行时定义主题 + setTheme/getTheme/useTheme 切换（可选持久化）
- * 自定义主题与内置主题变量完全同构（--zl-* + --el-*），components 无差别渲染
- */
-
-import themesDataRaw from '../generated/themes-data.json'
-import { generateElShades, mix } from './colors'
-import type { ComputedRef } from 'vue'
-import { computed, readonly, ref } from 'vue'
-
-/** 各主题解析后的 token 值表（构建期由 themegen 生成） */
-export const themesData = themesDataRaw as Record<string, Record<string, string>>
-
-/** 内置主题清单（数据源与 generated/constants.ts 一致） */
-export const THEMES = Object.keys(themesData) as ThemeName[]
-
-export type ThemeName = string
-
-export interface DefineThemeColors {
-  /** 主色（EP primary + --zl-primary-6 联动派生） */
-  primary?: string
-  success?: string
-  warning?: string
-  danger?: string
-  info?: string
-  /** 页面底色（覆盖 --zl-bg-1..5 / --el-bg-*） */
-  bg?: string
-}
-
-export interface DefineThemeOptions {
-  /** 主题名（切换时使用） */
-  name: string
-  /** 以哪套内置主题为基线（默认 'light'），未指定的 token 全部继承 */
-  base?: string
-  /** 少量语义色定制，其余自动派生 */
-  colors?: DefineThemeColors
-  /** 任意 token 覆盖（键为原始 token 名，如 color-text-1 / color-modo-6） */
-  tokens?: Record<string, string>
-  /** 是否立即切换到该主题 */
-  apply?: boolean
-}
-
-const THEME_STORAGE_KEY = 'zl-theme'
-const customThemes = new Map<string, { cssText: string }>()
-const currentTheme = ref<string>(initThemeFromStorage())
-const persistenceEnabled = ref(false)
-const changeListeners = new Set<(theme: string) => void>()
-
-function initThemeFromStorage(): string {
-  try {
-    return localStorage.getItem(THEME_STORAGE_KEY) || 'light'
-  } catch {
-    return 'light'
-  }
-}
-
-/** 生成某主题完整变量声明文本（--zl-* + --el-* + 布局资产变量） */
-function buildCssVars(resolved: Record<string, string>, themeName: string, baseName = themeName): string {
-  const isDark = themeName.includes('dark') || baseName.includes('dark')
-  const get = (k: string, fallback = '') => resolved[`color-${k}`] ?? fallback
-  const getLevel = (name: string, level: number) => resolved[`color-${name}-${level}`] ?? ''
-
-  const decls: string[] = []
-
-  // --zl-* 业务层
-  for (const [key, value] of Object.entries(resolved)) {
-    decls.push(`--zl-${key.replace(/^color-/, '')}: ${value};`)
-  }
-  for (let i = 1; i <= 10; i++) {
-    decls.push(`--zl-primary-${i}: ${getLevel('modo', i)};`)
-    decls.push(`--zl-link-${i}: ${getLevel('link', i)};`)
-  }
-
-  // --el-* EP 层
-  const semantic: Array<[string, string]> = [
-    ['primary', getLevel('modo', 6)],
-    ['success', getLevel('green', 6)],
-    ['warning', getLevel('orange', 6)],
-    ['danger', getLevel('red', 6)],
-    // EP 2.14 起 error 是规范名（el-tag--error / el-message--error 走它），
-    // 只给 danger 会让这些组件回落到 EP 默认浅色底，深色主题下尤其刺眼
-    ['error', getLevel('red', 6)],
-    ['info', getLevel('gray', 6)],
-  ]
-  for (const [name, hex] of semantic) {
-    decls.push(`--el-color-${name}: ${hex};`)
-    for (const [shade, value] of Object.entries(generateElShades(hex))) {
-      decls.push(`--el-color-${name}-${shade}: ${value};`)
-    }
-  }
-
-  const textMap: Record<string, string> = {
-    primary: 'text-1',
-    regular: 'text-2',
-    secondary: 'text-3',
-    placeholder: 'text-4',
-    // 没有 text-5：留空会产出 `--el-text-color-disabled: ;` 这种非法声明，
-    // 浏览器整条丢弃，EP 内部又会回落默认值 —— 直接复用 placeholder
-    disabled: 'text-4',
-  }
-  for (const [el, token] of Object.entries(textMap)) decls.push(`--el-text-color-${el}: ${get(token)};`)
-
-  const borderMap: Array<[string, string]> = [
-    ['extra-light', 'border-1'],
-    ['lighter', 'border-2'],
-    ['light', 'border-3'],
-    ['', 'border-4'],
-    ['dark', 'border-4'],
-    ['darker', 'border-4'],
-  ]
-  for (const [suffix, token] of borderMap)
-    decls.push(`--el-border-color${suffix ? `-${suffix}` : ''}: ${get(token)};`)
-
-  const fillMap: Array<[string, string]> = [
-    ['extra-light', 'fill-1'],
-    ['lighter', 'fill-2'],
-    ['light', 'fill-3'],
-    ['', 'fill-4'],
-    ['dark', 'fill-4'],
-  ]
-  for (const [suffix, token] of fillMap)
-    decls.push(`--el-fill-color${suffix ? `-${suffix}` : ''}: ${get(token)};`)
-  decls.push(`--el-fill-color-blank: ${isDark ? get('bg-2') : '#ffffff'};`)
-
-  decls.push(`--el-bg-color: ${get('bg-2')};`)
-  decls.push(`--el-bg-color-page: ${get('bg-1')};`)
-  decls.push(`--el-bg-color-overlay: ${get('bg-3')};`)
-  decls.push(`--el-color-white: ${isDark ? '#141414' : '#ffffff'};`)
-  decls.push(`--el-color-black: ${isDark ? '#ffffff' : '#000000'};`)
-  decls.push(`--el-mask-color: rgb(0, 0, 0, ${isDark ? '0.8' : '0.5'});`)
-  decls.push(`color-scheme: ${isDark ? 'dark' : 'light'};`)
-  // EP 圆角 ← 形状 token（与内置主题产物同构）：`defineTheme({ tokens: { 'radius-base': ... } })`
-  // 即可同时驱动 kit 组件与 Element Plus 控件，宿主不必再用 CSS 选择器抢优先级。
-  // 基线 radius-base 4px / radius-small 2px 与 EP 默认值相同，内置主题零视觉变化。
-  decls.push(`--el-border-radius-base: ${get('radius-base')};`)
-  decls.push(`--el-border-radius-small: ${get('radius-small')};`)
-
-  // 布局 / 菜单资产变量：内置主题由 scripts/themegen.mjs 产出，运行时主题必须同构，
-  // 否则 defineTheme 造出的主题会把侧栏与菜单底色整块丢掉（退化成透明）。
-  // 浅色/深色基线用弱对比底色；以彩色主题（red-light/blue…）为基线时侧栏是深色渐变，
-  // 菜单文字必须转白 —— 所以这里要看基线名，不能只看自定义主题名。
-  const isPlainBase = baseName === 'light' || baseName === 'dark'
-  decls.push(`--zl-menu-hover-bg: ${isPlainBase ? 'var(--zl-fill-2)' : 'rgba(255, 255, 255, 0.2)'};`)
-  decls.push(`--zl-menu-text-color: ${isPlainBase ? 'var(--zl-text-1)' : 'var(--zl-white)'};`)
-  decls.push(`--zl-menu-trigger-arrow-color: ${isDark ? '#253044' : '#f6fafc'};`)
-  decls.push(`--zl-menu-trigger-bg: linear-gradient(135deg, var(--zl-modo-5), var(--zl-modo-7));`)
-  decls.push(
-    `--zl-layout-vertical-aside-bg: linear-gradient(180deg, var(--zl-modo-7) 0%, var(--zl-modo-9) 100%);`,
-  )
-  decls.push(
-    `--zl-layout-horizontal-header-bg: linear-gradient(90deg, var(--zl-modo-7) 0%, var(--zl-modo-6) 60%, var(--zl-modo-5) 100%);`,
-  )
-
-  return decls.join('\n    ')
-}
-
-function injectStyle(name: string, cssText: string) {
-  const styleId = `zl-theme-style-${name}`
-  let style = document.getElementById(styleId) as HTMLStyleElement | null
-  if (!style) {
-    style = document.createElement('style')
-    style.id = styleId
-    document.head.appendChild(style)
-  }
-  style.textContent = cssText
-}
-
-/**
- * 运行时定义主题（L2）
- * 以某内置主题为基线，覆盖语义色后自动派生 EP 色阶与业务变量并注入样式
- */
-export function defineTheme(options: DefineThemeOptions): void {
-  const { name, base = 'light', colors = {}, tokens = {}, apply = false } = options
-  if (THEMES.includes(name) && !customThemes.has(name)) {
-    throw new Error(`主题 ${name} 为内置主题，不可覆盖`)
-  }
-
-  // 基线数据克隆
-  const resolved: Record<string, string> = { ...(themesData[base] ?? themesData.light) }
-  for (const [key, value] of Object.entries(tokens)) {
-    resolved[`color-${key.replace(/^color-/, '')}`] = value
-  }
-
-  // 形状 / 字体 token：与内置主题同构产出（值表与 scripts/themegen.mjs 的 SHAPE_TOKENS 一致，
-  // 两边漂移会让 `defineTheme` 造出的主题与内置主题观感不同）。
-  // 组件里写的是 `var(--zl-radius-large, 6px)` 这类带兜底的形式，此前这些 token 从未产出，
-  // 等于「值被兜底写死、宿主改不了」。用 `??=` 播种：`tokens: { 'radius-large': '10px' }` 这类覆盖仍然生效。
-  const shapeTokens: Record<string, string> = {
-    'radius-small': '2px',
-    'radius-base': '4px',
-    'radius-medium': '4px',
-    'radius-large': '6px',
-    'radius-xl': '12px',
-    'radius-round': '99px',
-    'font-family-code': "Consolas, 'SFMono-Regular', Menlo, monospace",
-    'slogan-font-family': "'PingFang SC', 'Microsoft YaHei', sans-serif",
-  }
-  for (const [key, value] of Object.entries(shapeTokens)) {
-    resolved[`color-${key}`] ??= value
-  }
-
-  const colorEntries: Array<[keyof DefineThemeColors, string, string]> = [
-    ['primary', 'modo', '6'],
-    ['success', 'green', '6'],
-    ['warning', 'orange', '6'],
-    ['danger', 'red', '6'],
-    ['info', 'gray', '6'],
-  ]
-  for (const [semantic, palette, level] of colorEntries) {
-    const hex = colors[semantic]
-    if (hex) {
-      resolved[`color-${palette}-${level}`] = hex
-      // 主色同时派生整组色板（浅→白、深→黑，各 10 级），保证 --zl-{palette}-N 可用
-      const seedLevel = Number(level)
-      for (let i = 1; i <= 10; i++) {
-        if (i === seedLevel) continue
-        const weight = (Math.abs(i - seedLevel) / 5) * 50
-        resolved[`color-${palette}-${i}`] =
-          i < seedLevel ? mix('#ffffff', hex, 100 - weight) : mix('#000000', hex, 100 - weight)
-      }
-    }
-  }
-
-  if (colors.bg) {
-    resolved['color-bg-1'] = colors.bg
-    resolved['color-bg-2'] = colors.bg
-  }
-
-  const cssText = `body[data-theme='${name}'] {\n    ${buildCssVars(resolved, name, base)}\n}`
-  injectStyle(name, cssText)
-  customThemes.set(name, { cssText })
-  if (!THEMES.includes(name)) {
-    THEMES.push(name)
-  }
-
-  if (apply) {
-    setTheme(name)
-  }
-}
-
-export interface SetThemeOptions {
-  /** 本次切换是否持久化（需已启用持久化或显式指定） */
-  persist?: boolean
-}
-
-/** 切换主题（内置/自定义均可；light 作用于 body 本身） */
-export function setTheme(name: string, options: SetThemeOptions = {}): void {
-  currentTheme.value = name
-  if (name === 'light') {
-    document.body.removeAttribute('data-theme')
-  } else {
-    document.body.setAttribute('data-theme', name)
-  }
-
-  if (persistenceEnabled.value || options.persist) {
-    try {
-      localStorage.setItem(THEME_STORAGE_KEY, name)
-    } catch {
-      // storage 不可用时忽略
-    }
-  }
-
-  changeListeners.forEach((fn) => fn(name))
-}
-
-/** 当前主题名 */
-export function getTheme(): string {
-  return currentTheme.value
-}
-
-/** 全部可用主题（内置 + 运行时自定义） */
-export function getThemes(): string[] {
-  return [...THEMES]
-}
-
-/** 开启主题持久化（同一浏览器记住所选主题） */
-export function enableThemePersistence() {
-  persistenceEnabled.value = true
-  setTheme(currentTheme.value, { persist: true })
-}
-
-/** 主题变化监听 */
-export function onThemeChange(callback: (theme: string) => void): () => void {
-  changeListeners.add(callback)
-  return () => changeListeners.delete(callback)
-}
-
-export interface UseThemeReturn {
-  /** 当前主题（只读 ref） */
-  theme: ComputedRef<string>
-  /** 可用主题列表（只读） */
-  themes: ComputedRef<string[]>
-  /** 切换主题 */
-  setTheme: (name: string, options?: SetThemeOptions) => void
-}
-
-/** 主题 composable（配合 defineTheme 实现运行时换肤） */
-export function useTheme(): UseThemeReturn {
-  return {
-    theme: readonly(currentTheme) as unknown as ComputedRef<string>,
-    themes: computed(() => getThemes()),
-    setTheme,
-  }
-}
+/**
+ * @zl-ui-kit/theme 运行时 API（需求 §7.2.3，D7）
+ * L2：defineTheme 运行时定义主题 + setTheme/getTheme/useTheme 切换（可选持久化）
+ * 自定义主题与内置主题变量完全同构（--zl-* + --el-*），components 无差别渲染
+ */
+
+import themesDataRaw from '../generated/themes-data.json'
+import { generateElShades, mix } from './colors'
+import type { ComputedRef } from 'vue'
+import { computed, readonly, ref } from 'vue'
+
+/** 各主题解析后的 token 值表（构建期由 themegen 生成） */
+export const themesData = themesDataRaw as Record<string, Record<string, string>>
+
+/** 内置主题清单（数据源与 generated/constants.ts 一致） */
+export const THEMES = Object.keys(themesData) as ThemeName[]
+
+export type ThemeName = string
+
+export interface DefineThemeColors {
+  /** 主色（EP primary + --zl-primary-6 联动派生） */
+  primary?: string
+  success?: string
+  warning?: string
+  danger?: string
+  info?: string
+  /** 页面底色（覆盖 --zl-bg-1..5 / --el-bg-*） */
+  bg?: string
+}
+
+export interface DefineThemeOptions {
+  /** 主题名（切换时使用） */
+  name: string
+  /** 以哪套内置主题为基线（默认 'light'），未指定的 token 全部继承 */
+  base?: string
+  /** 少量语义色定制，其余自动派生 */
+  colors?: DefineThemeColors
+  /** 任意 token 覆盖（键为原始 token 名，如 color-text-1 / color-modo-6） */
+  tokens?: Record<string, string>
+  /** 是否立即切换到该主题 */
+  apply?: boolean
+}
+
+const THEME_STORAGE_KEY = 'zl-theme'
+const customThemes = new Map<string, { cssText: string }>()
+const currentTheme = ref<string>(initThemeFromStorage())
+const persistenceEnabled = ref(false)
+const changeListeners = new Set<(theme: string) => void>()
+
+function initThemeFromStorage(): string {
+  try {
+    return localStorage.getItem(THEME_STORAGE_KEY) || 'light'
+  } catch {
+    return 'light'
+  }
+}
+
+/** 生成某主题完整变量声明文本（--zl-* + --el-* + 布局资产变量） */
+function buildCssVars(resolved: Record<string, string>, themeName: string, baseName = themeName): string {
+  const isDark = themeName.includes('dark') || baseName.includes('dark')
+  const get = (k: string, fallback = '') => resolved[`color-${k}`] ?? fallback
+  const getLevel = (name: string, level: number) => resolved[`color-${name}-${level}`] ?? ''
+
+  const decls: string[] = []
+
+  // --zl-* 业务层
+  for (const [key, value] of Object.entries(resolved)) {
+    decls.push(`--zl-${key.replace(/^color-/, '')}: ${value};`)
+  }
+  for (let i = 1; i <= 10; i++) {
+    decls.push(`--zl-primary-${i}: ${getLevel('modo', i)};`)
+    decls.push(`--zl-link-${i}: ${getLevel('link', i)};`)
+  }
+
+  // --el-* EP 层
+  const semantic: Array<[string, string]> = [
+    ['primary', getLevel('modo', 6)],
+    ['success', getLevel('green', 6)],
+    ['warning', getLevel('orange', 6)],
+    ['danger', getLevel('red', 6)],
+    // EP 2.14 起 error 是规范名（el-tag--error / el-message--error 走它），
+    // 只给 danger 会让这些组件回落到 EP 默认浅色底，深色主题下尤其刺眼
+    ['error', getLevel('red', 6)],
+    ['info', getLevel('gray', 6)],
+  ]
+  for (const [name, hex] of semantic) {
+    decls.push(`--el-color-${name}: ${hex};`)
+    for (const [shade, value] of Object.entries(generateElShades(hex))) {
+      decls.push(`--el-color-${name}-${shade}: ${value};`)
+    }
+  }
+
+  const textMap: Record<string, string> = {
+    primary: 'text-1',
+    regular: 'text-2',
+    secondary: 'text-3',
+    placeholder: 'text-4',
+    // 没有 text-5：留空会产出 `--el-text-color-disabled: ;` 这种非法声明，
+    // 浏览器整条丢弃，EP 内部又会回落默认值 —— 直接复用 placeholder
+    disabled: 'text-4',
+  }
+  for (const [el, token] of Object.entries(textMap)) decls.push(`--el-text-color-${el}: ${get(token)};`)
+
+  const borderMap: Array<[string, string]> = [
+    ['extra-light', 'border-1'],
+    ['lighter', 'border-2'],
+    ['light', 'border-3'],
+    ['', 'border-4'],
+    ['dark', 'border-4'],
+    ['darker', 'border-4'],
+  ]
+  for (const [suffix, token] of borderMap)
+    decls.push(`--el-border-color${suffix ? `-${suffix}` : ''}: ${get(token)};`)
+
+  const fillMap: Array<[string, string]> = [
+    ['extra-light', 'fill-1'],
+    ['lighter', 'fill-2'],
+    ['light', 'fill-3'],
+    ['', 'fill-4'],
+    ['dark', 'fill-4'],
+  ]
+  for (const [suffix, token] of fillMap)
+    decls.push(`--el-fill-color${suffix ? `-${suffix}` : ''}: ${get(token)};`)
+  decls.push(`--el-fill-color-blank: ${isDark ? get('bg-2') : '#ffffff'};`)
+
+  decls.push(`--el-bg-color: ${get('bg-2')};`)
+  decls.push(`--el-bg-color-page: ${get('bg-1')};`)
+  decls.push(`--el-bg-color-overlay: ${get('bg-3')};`)
+  decls.push(`--el-color-white: ${isDark ? '#141414' : '#ffffff'};`)
+  decls.push(`--el-color-black: ${isDark ? '#ffffff' : '#000000'};`)
+  decls.push(`--el-mask-color: rgb(0, 0, 0, ${isDark ? '0.8' : '0.5'});`)
+  decls.push(`color-scheme: ${isDark ? 'dark' : 'light'};`)
+  // EP 圆角 ← 形状 token（与内置主题产物同构）：`defineTheme({ tokens: { 'radius-base': ... } })`
+  // 即可同时驱动 kit 组件与 Element Plus 控件，宿主不必再用 CSS 选择器抢优先级。
+  // 基线 radius-base 4px / radius-small 2px 与 EP 默认值相同，内置主题零视觉变化。
+  decls.push(`--el-border-radius-base: ${get('radius-base')};`)
+  decls.push(`--el-border-radius-small: ${get('radius-small')};`)
+
+  // 布局 / 菜单资产变量：内置主题由 scripts/themegen.mjs 产出，运行时主题必须同构，
+  // 否则 defineTheme 造出的主题会把侧栏与菜单底色整块丢掉（退化成透明）。
+  // 浅色/深色基线用弱对比底色；以彩色主题（red-light/blue…）为基线时侧栏是深色渐变，
+  // 菜单文字必须转白 —— 所以这里要看基线名，不能只看自定义主题名。
+  const isPlainBase = baseName === 'light' || baseName === 'dark'
+  decls.push(`--zl-menu-hover-bg: ${isPlainBase ? 'var(--zl-fill-2)' : 'rgba(255, 255, 255, 0.2)'};`)
+  decls.push(`--zl-menu-text-color: ${isPlainBase ? 'var(--zl-text-1)' : 'var(--zl-white)'};`)
+  decls.push(`--zl-menu-trigger-arrow-color: ${isDark ? '#253044' : '#f6fafc'};`)
+  decls.push(`--zl-menu-trigger-bg: linear-gradient(135deg, var(--zl-modo-5), var(--zl-modo-7));`)
+  decls.push(
+    `--zl-layout-vertical-aside-bg: linear-gradient(180deg, var(--zl-modo-7) 0%, var(--zl-modo-9) 100%);`,
+  )
+  decls.push(
+    `--zl-layout-horizontal-header-bg: linear-gradient(90deg, var(--zl-modo-7) 0%, var(--zl-modo-6) 60%, var(--zl-modo-5) 100%);`,
+  )
+
+  return decls.join('\n    ')
+}
+
+function injectStyle(name: string, cssText: string) {
+  const styleId = `zl-theme-style-${name}`
+  let style = document.getElementById(styleId) as HTMLStyleElement | null
+  if (!style) {
+    style = document.createElement('style')
+    style.id = styleId
+    document.head.appendChild(style)
+  }
+  style.textContent = cssText
+}
+
+/**
+ * 运行时定义主题（L2）
+ * 以某内置主题为基线，覆盖语义色后自动派生 EP 色阶与业务变量并注入样式
+ */
+export function defineTheme(options: DefineThemeOptions): void {
+  const { name, base = 'light', colors = {}, tokens = {}, apply = false } = options
+  if (THEMES.includes(name) && !customThemes.has(name)) {
+    throw new Error(`主题 ${name} 为内置主题，不可覆盖`)
+  }
+
+  // 基线数据克隆
+  const resolved: Record<string, string> = { ...(themesData[base] ?? themesData.light) }
+  for (const [key, value] of Object.entries(tokens)) {
+    resolved[`color-${key.replace(/^color-/, '')}`] = value
+  }
+
+  // 形状 / 字体 token：与内置主题同构产出（值表与 scripts/themegen.mjs 的 SHAPE_TOKENS 一致，
+  // 两边漂移会让 `defineTheme` 造出的主题与内置主题观感不同）。
+  // 组件里写的是 `var(--zl-radius-large, 6px)` 这类带兜底的形式，此前这些 token 从未产出，
+  // 等于「值被兜底写死、宿主改不了」。用 `??=` 播种：`tokens: { 'radius-large': '10px' }` 这类覆盖仍然生效。
+  const shapeTokens: Record<string, string> = {
+    'radius-small': '2px',
+    'radius-base': '4px',
+    'radius-medium': '4px',
+    'radius-large': '6px',
+    'radius-xl': '12px',
+    'radius-round': '99px',
+    'font-family-code': "Consolas, 'SFMono-Regular', Menlo, monospace",
+    'slogan-font-family': "'PingFang SC', 'Microsoft YaHei', sans-serif",
+  }
+  for (const [key, value] of Object.entries(shapeTokens)) {
+    resolved[`color-${key}`] ??= value
+  }
+
+  const colorEntries: Array<[keyof DefineThemeColors, string, string]> = [
+    ['primary', 'modo', '6'],
+    ['success', 'green', '6'],
+    ['warning', 'orange', '6'],
+    ['danger', 'red', '6'],
+    ['info', 'gray', '6'],
+  ]
+  for (const [semantic, palette, level] of colorEntries) {
+    const hex = colors[semantic]
+    if (hex) {
+      resolved[`color-${palette}-${level}`] = hex
+      // 主色同时派生整组色板（浅→白、深→黑，各 10 级），保证 --zl-{palette}-N 可用
+      const seedLevel = Number(level)
+      for (let i = 1; i <= 10; i++) {
+        if (i === seedLevel) continue
+        const weight = (Math.abs(i - seedLevel) / 5) * 50
+        resolved[`color-${palette}-${i}`] =
+          i < seedLevel ? mix('#ffffff', hex, 100 - weight) : mix('#000000', hex, 100 - weight)
+      }
+    }
+  }
+
+  if (colors.bg) {
+    resolved['color-bg-1'] = colors.bg
+    resolved['color-bg-2'] = colors.bg
+  }
+
+  const cssText = `body[data-theme='${name}'] {\n    ${buildCssVars(resolved, name, base)}\n}`
+  injectStyle(name, cssText)
+  customThemes.set(name, { cssText })
+  if (!THEMES.includes(name)) {
+    THEMES.push(name)
+  }
+
+  if (apply) {
+    setTheme(name)
+  }
+}
+
+export interface SetThemeOptions {
+  /** 本次切换是否持久化（需已启用持久化或显式指定） */
+  persist?: boolean
+}
+
+/** 切换主题（内置/自定义均可；light 作用于 body 本身） */
+export function setTheme(name: string, options: SetThemeOptions = {}): void {
+  currentTheme.value = name
+  if (name === 'light') {
+    document.body.removeAttribute('data-theme')
+  } else {
+    document.body.setAttribute('data-theme', name)
+  }
+
+  if (persistenceEnabled.value || options.persist) {
+    try {
+      localStorage.setItem(THEME_STORAGE_KEY, name)
+    } catch {
+      // storage 不可用时忽略
+    }
+  }
+
+  changeListeners.forEach((fn) => fn(name))
+}
+
+/** 当前主题名 */
+export function getTheme(): string {
+  return currentTheme.value
+}
+
+/** 全部可用主题（内置 + 运行时自定义） */
+export function getThemes(): string[] {
+  return [...THEMES]
+}
+
+/** 开启主题持久化（同一浏览器记住所选主题） */
+export function enableThemePersistence() {
+  persistenceEnabled.value = true
+  setTheme(currentTheme.value, { persist: true })
+}
+
+/** 主题变化监听 */
+export function onThemeChange(callback: (theme: string) => void): () => void {
+  changeListeners.add(callback)
+  return () => changeListeners.delete(callback)
+}
+
+export interface UseThemeReturn {
+  /** 当前主题（只读 ref） */
+  theme: ComputedRef<string>
+  /** 可用主题列表（只读） */
+  themes: ComputedRef<string[]>
+  /** 切换主题 */
+  setTheme: (name: string, options?: SetThemeOptions) => void
+}
+
+/** 主题 composable（配合 defineTheme 实现运行时换肤） */
+export function useTheme(): UseThemeReturn {
+  return {
+    theme: readonly(currentTheme) as unknown as ComputedRef<string>,
+    themes: computed(() => getThemes()),
+    setTheme,
+  }
+}