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

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @zl-ui-kit/theme
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ZL UI 主题引擎（决策 D7）：内置 5 套主题（light/dark/red-light/red-dark/blue），`body[data-theme]` 作用域 + `--zl-*`（业务层）/`--el-*`（Element Plus 层）变量体系，支持运行时自定义主题。
+
+## 快速上手
+
+```ts
+import '@zl-ui-kit/theme/themes.css'                       // 或按需 '@zl-ui-kit/theme/light'
+import { setTheme, defineTheme, useTheme } from '@zl-ui-kit/theme'
+
+setTheme('dark')
+
+defineTheme({ name: 'brand', base: 'light', colors: { primary: '#722ED1' }, apply: true })
+```
+
+**自定义主题完整指南见根目录 `docs/主题定制指南.md`**（L1 变量直覆 / L2 运行时 defineTheme / L3 构建时生成）。
+
+## 入口
+
+| 入口 | 内容 |
+| --- | --- |
+| `.` | 运行时 API（defineTheme/setTheme/useTheme/mix/generateElShades）+ 常量 |
+| `/light` `/dark` `/red-light` `/red-dark` `/blue` `/themes.css` | 每主题/合集预编译 CSS（变量 + reset + overrides） |
+| `/scss`（及 `/scss/*.scss`） | SCSS 工具（colorForEach/colorGradient/theme mixin/mapGet） |
+| `/assets/*` | 主题背景图 |
+
+## 本地调试
+
+- 改 `_json/*.json`（主题 token）→ `pnpm --filter @zl-ui-kit/theme gen` → playground `/theme` 页刷新
+- `pnpm build` = gen + tsup；themegen 产物在 `src/generated/`（勿手改）
+
+详见 `docs/调试指南.md`；发布见 `docs/发布流程.md`。

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import { ComputedRef } from 'vue';
+
+declare const COLOR_TYPES: readonly ["primary", "success", "warning", "danger", "bg", "blue", "border", "cyan", "danger", "fill", "gold", "gray", "green", "lime", "link", "magenta", "modo", "neutral", "orange", "orangered", "pinkpurple", "primary", "purple", "red", "success", "text", "warning", "yellow"];
+type ColorType = typeof COLOR_TYPES[number];
+
+/**
+ * @zl-ui-kit/theme 运行时 API（需求 §7.2.3，D7）
+ * L2：defineTheme 运行时定义主题 + setTheme/getTheme/useTheme 切换（可选持久化）
+ * 自定义主题与内置主题变量完全同构（--zl-* + --el-*），components 无差别渲染
+ */
+
+/** 各主题解析后的 token 值表（构建期由 themegen 生成） */
+declare const themesData: Record<string, Record<string, string>>;
+/** 内置主题清单（数据源与 generated/constants.ts 一致） */
+declare const THEMES: ThemeName[];
+type ThemeName = string;
+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;
+}
+interface DefineThemeOptions {
+    /** 主题名（切换时使用） */
+    name: string;
+    /** 以哪套内置主题为基线（默认 'light'），未指定的 token 全部继承 */
+    base?: string;
+    /** 少量语义色定制，其余自动派生 */
+    colors?: DefineThemeColors;
+    /** 任意 token 覆盖（键为原始 token 名，如 color-text-1 / color-modo-6） */
+    tokens?: Record<string, string>;
+    /** 是否立即切换到该主题 */
+    apply?: boolean;
+}
+/**
+ * 运行时定义主题（L2）
+ * 以某内置主题为基线，覆盖语义色后自动派生 EP 色阶与业务变量并注入样式
+ */
+declare function defineTheme(options: DefineThemeOptions): void;
+interface SetThemeOptions {
+    /** 本次切换是否持久化（需已启用持久化或显式指定） */
+    persist?: boolean;
+}
+/** 切换主题（内置/自定义均可；light 作用于 body 本身） */
+declare function setTheme(name: string, options?: SetThemeOptions): void;
+/** 当前主题名 */
+declare function getTheme(): string;
+/** 全部可用主题（内置 + 运行时自定义） */
+declare function getThemes(): string[];
+/** 开启主题持久化（同一浏览器记住所选主题） */
+declare function enableThemePersistence(): void;
+/** 主题变化监听 */
+declare function onThemeChange(callback: (theme: string) => void): () => void;
+interface UseThemeReturn {
+    /** 当前主题（只读 ref） */
+    theme: ComputedRef<string>;
+    /** 可用主题列表（只读） */
+    themes: ComputedRef<string[]>;
+    /** 切换主题 */
+    setTheme: (name: string, options?: SetThemeOptions) => void;
+}
+/** 主题 composable（配合 defineTheme 实现运行时换肤） */
+declare function useTheme(): UseThemeReturn;
+
+/** 混色：weight 为混入 color2 的百分比（与 EP mix 一致） */
+declare function mix(color1: string, color2: string, weight: number): string;
+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%) */
+declare function generateElShades(hex: string): ElColorShades;
+
+export { COLOR_TYPES, type ColorType, type DefineThemeColors, type DefineThemeOptions, type SetThemeOptions, THEMES, type ThemeName, type UseThemeReturn, defineTheme, enableThemePersistence, generateElShades, getTheme, getThemes, mix, onThemeChange, setTheme, themesData, useTheme };