@zl-ui-kit/theme 0.0.0-stage → 0.3.0

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * ============================================================
+ * @zl-ui-kit/theme 入口（运行时 API + 常量）
+ * 主题 CSS 入口：@zl-ui-kit/theme/light|dark|red-light|red-dark|blue 或 @zl-ui-kit/theme/themes.css
+ * SCSS 工具入口：@zl-ui-kit/theme/scss
+ * 自定义主题：见 docs/主题定制指南.md（L1 变量直覆 / L2 defineTheme / L3 构建时生成）
+ * ============================================================
+ */
+
+export { COLOR_TYPES, type ColorType } from './generated/constants'
+export * from './runtime/api'
+export { mix, generateElShades } from './runtime/colors'

package/src/overrides/components.css

@@ -0,0 +1,15 @@
+/*
+ * Element Plus 组件样式覆盖（占位骨架）
+ * 参考实现的 18 个组件覆盖基于原 UI 库类名体系，需按 EP 的 .el-* BEM 结构逐组件重写，
+ * 以 playground 主题预览页视觉验收为准（需求 §7.2.2 / P15）。
+ * 本文件随 per-theme CSS 一同生效；以下为首批全局性微调。
+ */
+
+/* 与 zl 设计一致的圆角与动效基调 */
+.el-button {
+  --el-button-border-radius: var(--zl-radius-base, 4px);
+}
+
+.el-dialog {
+  --el-dialog-border-radius: var(--zl-radius-base, 4px);
+}

package/src/runtime/api.ts

@@ -0,0 +1,247 @@
+/**
+ * @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): string {
+  const isDark = themeName.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)],
+    ['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', disabled: 'text-5' }
+  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']]
+  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']]
+  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(`color-scheme: ${isDark ? 'dark' : 'light'};`)
+
+  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
+  }
+
+  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)}\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,
+  }
+}

package/src/runtime/colors.ts

@@ -0,0 +1,61 @@
+/**
+ * 颜色工具：与 Element Plus theme-chalk 对齐的混色与色阶派生算法
+ * （themegen.mjs 与运行时 API 共用同一套规则，保证 L2/L3 产物一致）
+ */
+
+export function parseColor(str: string): [number, number, number] | null {
+  const s = String(str).trim()
+  if (s.startsWith('#')) {
+    let hex = s.slice(1)
+    if (hex.length === 3)
+      hex = hex.split('').map(c => c + c).join('')
+    return [Number.parseInt(hex.slice(0, 2), 16), Number.parseInt(hex.slice(2, 4), 16), Number.parseInt(hex.slice(4, 6), 16)]
+  }
+  const m = s.match(/rgba?\(([^)]+)\)/)
+  if (m) {
+    const parts = m[1]!.split(',').map(Number)
+    return [parts[0] || 0, parts[1] || 0, parts[2] || 0]
+  }
+  return null
+}
+
+export function toHex([r, g, b]: [number, number, number]): string {
+  const c = (n: number) => {
+    n = Math.max(0, Math.min(255, Math.round(n)))
+    return n.toString(16).padStart(2, '0')
+  }
+  return `#${c(r)}${c(g)}${c(b)}`
+}
+
+/** 混色：weight 为混入 color2 的百分比（与 EP mix 一致） */
+export function mix(color1: string, color2: string, weight: number): string {
+  const c1 = parseColor(color1)
+  const c2 = parseColor(color2)
+  if (!c1 || !c2)
+    return color1
+  const w = weight / 100
+  return toHex([c1[0] * (1 - w) + c2[0] * w, c1[1] * (1 - w) + c2[1] * w, c1[2] * (1 - w) + c2[2] * w])
+}
+
+export interface ElColorShades {
+  'light-1': string
+  'light-2': string
+  'light-3': string
+  'light-4': string
+  'light-5': string
+  'light-6': string
+  'light-7': string
+  'light-8': string
+  'light-9': string
+  'dark-2': string
+}
+
+/** EP 主色色阶：light-n = mix(白, 主色, n*10%)；dark-2 = mix(黑, 主色, 20%) */
+export function generateElShades(hex: string): ElColorShades {
+  const shades = {} as ElColorShades
+  for (let i = 1; i <= 9; i++) {
+    shades[`light-${i}` as keyof ElColorShades] = mix('#ffffff', hex, i * 10)
+  }
+  shades['dark-2'] = mix('#000000', hex, 20)
+  return shades
+}

package/src/utils/colors.scss

@@ -0,0 +1,27 @@
+// ============================================================
+// SCSS 工具（供消费方深度定制编译使用；变量前缀 zl-）
+// 入口：@zl/theme/scss（colors / map / theme 三个模块）
+// ============================================================
+
+@use 'sass:list';
+@use '../generated/_constants' as *;
+
+$color-gradient-range: (6, 3) !default;
+
+/** 遍历全部色彩类型 */
+@mixin colorForEach() {
+  @each $color in $color-types {
+    @content ($color);
+  }
+}
+
+/** 色板渐变背景（默认 6→3 级） */
+@mixin colorGradient($color, $direction, $range: $color-gradient-range) {
+  $color-stops: ();
+
+  @each $stop in $range {
+    $color-stops: list.append($color-stops, var(--zl-#{$color}-#{$stop}), comma);
+  }
+
+  background-image: linear-gradient($direction, $color-stops);
+}

package/src/utils/map.scss

@@ -0,0 +1,16 @@
+// 嵌套 map 取值工具
+
+@use 'sass:map';
+@use 'sass:meta';
+
+@function mapGet($map, $keys...) {
+  @each $key in $keys {
+    @if meta.type-of($map) == 'map' and map.has-key($map, $key) {
+      $map: map.get($map, $key);
+    } @else {
+      @warn "Key `#{$key}` not found in map or map is not nested.";
+      @return null;
+    }
+  }
+  @return $map;
+}

package/src/utils/theme.scss

@@ -0,0 +1,13 @@
+// 主题作用域 mixin：为每套主题生成选择器块（light 无属性选择器）
+
+@use '../generated/_constants' as *;
+
+@mixin theme() {
+  @each $theme in $themes-name {
+    $filter: if($theme == 'light', '', "[data-theme='#{$theme}']");
+
+    body#{$filter} {
+      @content ($theme);
+    }
+  }
+}