@zl-ui-kit/theme 0.15.0 → 0.17.0

package/README.md

@@ -1,62 +1,62 @@
-# @zl-ui-kit/theme
-
-> **完整使用文档**：[`@zl-ui-kit/components` 的 README（npm 页面）](https://www.npmjs.com/package/@zl-ui-kit/components) 即 UI 组件权威文档 ——
-> 本包的 Hooks / 工具 / 主题 / 国际化用法都在其中，本文只保留本包速查与运行前提。
-
-ZL UI 主题引擎（决策 D7）：内置 5 套主题（light/dark/red-light/red-dark/blue），`body[data-theme]` 作用域 + `--zl-*`（业务层）/`--el-*`（Element Plus 层）变量体系，支持运行时自定义主题。
-
-## 快速上手
-
-**① 用默认主题：只引一个 CSS，不写任何主题代码。**
-
-```ts
-// main.ts —— 顺序不能倒：EP 样式在前、主题在后，否则被 EP 自带默认值压掉
-import 'element-plus/dist/index.css'
-import '@zl-ui-kit/theme/themes.css' // 5 套全量；只要默认一套可换成 '@zl-ui-kit/theme/light'
-```
-
-引入即得到内置 `light`：主色 `#3056D3`、hover `#6e89e0`、按下 `#2645a9`、控件圆角 `4px`；
-业务组件（`--zl-*`）与 Element Plus 控件（`--el-*`）共用同一组变量。
-
-**② 要覆盖默认主题：在宿主侧一个入口文件里于启动时调用。**
-
-```ts
-import { defineTheme, enableThemePersistence, setTheme, useTheme } from '@zl-ui-kit/theme'
-
-setTheme('dark') // 切内置主题：light / dark / red-light / red-dark / blue
-enableThemePersistence() // 可选：刷新后保持（storage: zl-theme）
-
-// 整套自定义：以内置主题为基线，只声明要改的量，色阶自动派生
-defineTheme({
-  name: 'brand',
-  base: 'light',
-  colors: { primary: '#722ED1' }, // → --zl-primary-1..10 与 --el-color-primary-light-*/dark-2
-  tokens: { 'radius-base': '2px' }, // → 同时写 --el-border-radius-base，EP 控件跟着变
-  apply: true,
-})
-
-// 组件内响应式读当前主题（theme 是只读 ref，切换仍走上面那个 setTheme）
-const { theme } = useTheme()
-```
-
-页面里只引用语义变量（`var(--el-color-primary)` / `var(--zl-*)`），不要再写色值字面量，
-也不要把主题色“回写”到另一个变量上 —— 取色单源才能避免组件一个色系、控件另一个色系。
-
-**默认与定制的完整选型（L1 变量直覆 / L2 运行时 defineTheme / L3 构建时生成）、色阶契约与不生效排查见
-`@zl-ui-kit/components` 的 README §10 主题定制**；可运行的实时版（含「当前实际生效值」读数）见 playground `/theme` 页。
-
-## 入口
-
-| 入口                                                            | 内容                                                                   |
-| --------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `.`                                                             | 运行时 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/`（勿手改）
-
-详见 `@zl-ui-kit/components` README §11；发布见 `docs/发布流程.md`。
+# @zl-ui-kit/theme
+
+> **完整使用文档**：[`@zl-ui-kit/components` 的 README（npm 页面）](https://www.npmjs.com/package/@zl-ui-kit/components) 即 UI 组件权威文档 ——
+> 本包的 Hooks / 工具 / 主题 / 国际化用法都在其中，本文只保留本包速查与运行前提。
+
+ZL UI 主题引擎（决策 D7）：内置 5 套主题（light/dark/red-light/red-dark/blue），`body[data-theme]` 作用域 + `--zl-*`（业务层）/`--el-*`（Element Plus 层）变量体系，支持运行时自定义主题。
+
+## 快速上手
+
+**① 用默认主题：只引一个 CSS，不写任何主题代码。**
+
+```ts
+// main.ts —— 顺序不能倒：EP 样式在前、主题在后，否则被 EP 自带默认值压掉
+import 'element-plus/dist/index.css'
+import '@zl-ui-kit/theme/themes.css' // 5 套全量；只要默认一套可换成 '@zl-ui-kit/theme/light'
+```
+
+引入即得到内置 `light`：主色 `#3056D3`、hover `#6e89e0`、按下 `#2645a9`、控件圆角 `4px`；
+业务组件（`--zl-*`）与 Element Plus 控件（`--el-*`）共用同一组变量。
+
+**② 要覆盖默认主题：在宿主侧一个入口文件里于启动时调用。**
+
+```ts
+import { defineTheme, enableThemePersistence, setTheme, useTheme } from '@zl-ui-kit/theme'
+
+setTheme('dark') // 切内置主题：light / dark / red-light / red-dark / blue
+enableThemePersistence() // 可选：刷新后保持（storage: zl-theme）
+
+// 整套自定义：以内置主题为基线，只声明要改的量，色阶自动派生
+defineTheme({
+  name: 'brand',
+  base: 'light',
+  colors: { primary: '#722ED1' }, // → --zl-primary-1..10 与 --el-color-primary-light-*/dark-2
+  tokens: { 'radius-base': '2px' }, // → 同时写 --el-border-radius-base，EP 控件跟着变
+  apply: true,
+})
+
+// 组件内响应式读当前主题（theme 是只读 ref，切换仍走上面那个 setTheme）
+const { theme } = useTheme()
+```
+
+页面里只引用语义变量（`var(--el-color-primary)` / `var(--zl-*)`），不要再写色值字面量，
+也不要把主题色“回写”到另一个变量上 —— 取色单源才能避免组件一个色系、控件另一个色系。
+
+**默认与定制的完整选型（L1 变量直覆 / L2 运行时 defineTheme / L3 构建时生成）、色阶契约与不生效排查见
+`@zl-ui-kit/components` 的 README §10 主题定制**；可运行的实时版（含「当前实际生效值」读数）见 playground `/theme` 页。
+
+## 入口
+
+| 入口                                                            | 内容                                                                   |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `.`                                                             | 运行时 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/`（勿手改）
+
+详见 `@zl-ui-kit/components` README §11；发布见 `docs/发布流程.md`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zl-ui-kit/theme",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "type": "module",
   "description": "ZL UI 主题引擎：内置 5 套主题（light/dark/red-light/red-dark/blue），--zl-* 业务变量 + --el-* Element Plus 变量三层体系，支持运行时自定义主题（defineTheme/setTheme）",
   "license": "MIT",

package/src/assets/fonts/NOTOSANS-OFL.txt

@@ -1,93 +1,93 @@
-Google Inc.
-
-This Font Software is licensed under the SIL Open Font License, Version 1.1.
-This license is copied below, and is also available with a FAQ at:
-http://scripts.sil.org/OFL
-
-
------------------------------------------------------------
-SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
------------------------------------------------------------
-
-PREAMBLE
-The goals of the Open Font License (OFL) are to stimulate worldwide
-development of collaborative font projects, to support the font creation
-efforts of academic and linguistic communities, and to provide a free and
-open framework in which fonts may be shared and improved in partnership
-with others.
-
-The OFL allows the licensed fonts to be used, studied, modified and
-redistributed freely as long as they are not sold by themselves. The
-fonts, including any derivative works, can be bundled, embedded,
-redistributed and/or sold with any software provided that any reserved
-names are not used by derivative works. The fonts and derivatives,
-however, cannot be released under any other type of license. The
-requirement for fonts to remain under this license does not apply
-to any document created using the fonts or their derivatives.
-
-DEFINITIONS
-"Font Software" refers to the set of files released by the Copyright
-Holder(s) under this license and clearly marked as such. This may
-include source files, build scripts and documentation.
-
-"Reserved Font Name" refers to any names specified as such after the
-copyright statement(s).
-
-"Original Version" refers to the collection of Font Software components as
-distributed by the Copyright Holder(s).
-
-"Modified Version" refers to any derivative made by adding to, deleting,
-or substituting -- in part or in whole -- any of the components of the
-Original Version, by changing formats or by porting the Font Software to a
-new environment.
-
-"Author" refers to any designer, engineer, programmer, technical
-writer or other person who contributed to the Font Software.
-
-PERMISSION & CONDITIONS
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of the Font Software, to use, study, copy, merge, embed, modify,
-redistribute, and sell modified and unmodified copies of the Font
-Software, subject to the following conditions:
-
-1) Neither the Font Software nor any of its individual components,
-in Original or Modified Versions, may be sold by itself.
-
-2) Original or Modified Versions of the Font Software may be bundled,
-redistributed and/or sold with any software, provided that each copy
-contains the above copyright notice and this license. These can be
-included either as stand-alone text files, human-readable headers or
-in the appropriate machine-readable metadata fields within text or
-binary files as long as those fields can be easily viewed by the user.
-
-3) No Modified Version of the Font Software may use the Reserved Font
-Name(s) unless explicit written permission is granted by the corresponding
-Copyright Holder. This restriction only applies to the primary font name as
-presented to the users.
-
-4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
-Software shall not be used to promote, endorse or advertise any
-Modified Version, except to acknowledge the contribution(s) of the
-Copyright Holder(s) and the Author(s) or with their explicit written
-permission.
-
-5) The Font Software, modified or unmodified, in part or in whole,
-must be distributed entirely under this license, and must not be
-distributed under any other license. The requirement for fonts to
-remain under this license does not apply to any document created
-using the Font Software.
-
-TERMINATION
-This license becomes null and void if any of the above conditions are
-not met.
-
-DISCLAIMER
-THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
-OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
-COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
-DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
-OTHER DEALINGS IN THE FONT SOFTWARE.
+Google Inc.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/assets/fonts/SMILEYSANS-OFL.txt

@@ -1,6 +1,6 @@
-Smiley Sans（得意黑）
-作者：oooooohmygosh 等字体设计师
-许可：SIL Open Font License 1.1（OFL-1.1），可免费商用，无任何限制
-项目地址：https://github.com/atelier-anchor/smiley-sans
-
-本目录内 SmileySans-Oblique.ttf.woff2 为根据上述 OFL-1.1 许可分发的字体子集包裹（@fontpkg/smiley-sans）。
+Smiley Sans（得意黑）
+作者：oooooohmygosh 等字体设计师
+许可：SIL Open Font License 1.1（OFL-1.1），可免费商用，无任何限制
+项目地址：https://github.com/atelier-anchor/smiley-sans
+
+本目录内 SmileySans-Oblique.ttf.woff2 为根据上述 OFL-1.1 许可分发的字体子集包裹（@fontpkg/smiley-sans）。

package/src/common/reset.css

@@ -1,100 +1,100 @@
-/*
- * 全局 reset（随每套主题 CSS 一并注入；变量取 --zl-*，缺省回退为浅色值）
- * 由参考实现迁移，变量命名按需求 §7.2.1 统一 zl- 前缀
- */
-
-/* ============================================================
- * 开源字体（OFL-1.1）自托管：替换参考实现中的商业授权字体
- *   - Noto Sans SC（思源黑体）：通用中文正文字体，覆盖系统字体缺失场景
- *   - Smiley Sans（得意黑）：品牌标语展示字体，替换商业「方正」系列
- * 字体文件见本包 src/assets/fonts/（经 ./assets/* 导出）
- * ============================================================ */
-@font-face {
-  font-family: 'Noto Sans SC';
-  font-style: normal;
-  font-weight: 400;
-  font-display: swap;
-  src: url(../assets/fonts/noto-sans-sc-400.woff2) format('woff2');
-}
-@font-face {
-  font-family: 'Noto Sans SC';
-  font-style: normal;
-  font-weight: 500;
-  font-display: swap;
-  src: url(../assets/fonts/noto-sans-sc-500.woff2) format('woff2');
-}
-@font-face {
-  font-family: 'Noto Sans SC';
-  font-style: normal;
-  font-weight: 700;
-  font-display: swap;
-  src: url(../assets/fonts/noto-sans-sc-700.woff2) format('woff2');
-}
-@font-face {
-  font-family: 'Smiley Sans';
-  font-style: normal;
-  font-weight: 400;
-  font-display: swap;
-  src: url(../assets/fonts/smiley-sans.woff2) format('woff2');
-}
-
-:root {
-  /* 品牌标语字体：默认得意黑（开源），回退思源黑体 / 系统字体；替换参考实现的商业字体 */
-  --zl-slogan-font-family: 'Smiley Sans', 'Noto Sans SC', 'PingFang SC', 'Microsoft YaHei', sans-serif;
-}
-
-html,
-body,
-micro-app,
-#root,
-#app {
-  height: 100%;
-}
-
-html,
-body {
-  margin: 0;
-  padding: 0;
-}
-
-#root {
-  background: var(--zl-fill-2, #f0f2f5);
-  color: var(--zl-text-2, #4d5e7d);
-  font-size: 12px;
-  line-height: 20px;
-  overscroll-behavior: contain;
-  font-family:
-    Inter,
-    -apple-system,
-    BlinkMacSystemFont,
-    'PingFang SC',
-    'Hiragino Sans GB',
-    'Noto Sans SC',
-    'Microsoft YaHei',
-    'Helvetica Neue',
-    Helvetica,
-    Arial,
-    sans-serif;
-}
-
-*,
-*::before,
-*::after {
-  box-sizing: border-box;
-}
-
-::-webkit-scrollbar {
-  width: 10px;
-  height: 10px;
-  background: transparent;
-}
-
-::-webkit-scrollbar-thumb {
-  background: var(--zl-fill-3, #e3e9ef) content-box;
-  border: 2px solid transparent;
-  border-radius: 5px;
-}
-
-::-webkit-scrollbar-thumb:hover {
-  background-color: var(--zl-fill-4, rgb(179, 192, 204));
-}
+/*
+ * 全局 reset（随每套主题 CSS 一并注入；变量取 --zl-*，缺省回退为浅色值）
+ * 由参考实现迁移，变量命名按需求 §7.2.1 统一 zl- 前缀
+ */
+
+/* ============================================================
+ * 开源字体（OFL-1.1）自托管：替换参考实现中的商业授权字体
+ *   - Noto Sans SC（思源黑体）：通用中文正文字体，覆盖系统字体缺失场景
+ *   - Smiley Sans（得意黑）：品牌标语展示字体，替换商业「方正」系列
+ * 字体文件见本包 src/assets/fonts/（经 ./assets/* 导出）
+ * ============================================================ */
+@font-face {
+  font-family: 'Noto Sans SC';
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url(../assets/fonts/noto-sans-sc-400.woff2) format('woff2');
+}
+@font-face {
+  font-family: 'Noto Sans SC';
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url(../assets/fonts/noto-sans-sc-500.woff2) format('woff2');
+}
+@font-face {
+  font-family: 'Noto Sans SC';
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url(../assets/fonts/noto-sans-sc-700.woff2) format('woff2');
+}
+@font-face {
+  font-family: 'Smiley Sans';
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url(../assets/fonts/smiley-sans.woff2) format('woff2');
+}
+
+:root {
+  /* 品牌标语字体：默认得意黑（开源），回退思源黑体 / 系统字体；替换参考实现的商业字体 */
+  --zl-slogan-font-family: 'Smiley Sans', 'Noto Sans SC', 'PingFang SC', 'Microsoft YaHei', sans-serif;
+}
+
+html,
+body,
+micro-app,
+#root,
+#app {
+  height: 100%;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+}
+
+#root {
+  background: var(--zl-fill-2, #f0f2f5);
+  color: var(--zl-text-2, #4d5e7d);
+  font-size: 12px;
+  line-height: 20px;
+  overscroll-behavior: contain;
+  font-family:
+    Inter,
+    -apple-system,
+    BlinkMacSystemFont,
+    'PingFang SC',
+    'Hiragino Sans GB',
+    'Noto Sans SC',
+    'Microsoft YaHei',
+    'Helvetica Neue',
+    Helvetica,
+    Arial,
+    sans-serif;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--zl-fill-3, #e3e9ef) content-box;
+  border: 2px solid transparent;
+  border-radius: 5px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background-color: var(--zl-fill-4, rgb(179, 192, 204));
+}