@kupola/kupola 1.9.13 → 1.9.14

package/README.md

@@ -18,6 +18,73 @@
 - [English](#english)
 - [中文](#中文)
 
+---
+
+## 📦 构建工具插件
+
+### Vite 插件
+
+```js
+// vite.config.js
+import { kupola } from '@kupola/kupola/vite';
+
+export default {
+  plugins: [kupola()]
+};
+```
+
+**配置选项：**
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `autoCSS` | boolean | `true` | 自动注入 Kupola CSS |
+| `autoImport` | boolean | `true` | 自动导入 `useDeps`/`useQuery` |
+| `devTools` | boolean | `true` | 开发模式下启用调试工具 |
+| `cssPath` | string | `null` | 自定义 CSS 路径 |
+| `themePreload` | boolean | `false` | 自动注入主题预加载脚本 |
+
+### Webpack 插件
+
+```js
+// webpack.config.js
+const KupolaWebpackPlugin = require('@kupola/kupola/webpack');
+
+module.exports = {
+  plugins: [new KupolaWebpackPlugin()]
+};
+```
+
+**配置选项：**
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `autoCSS` | boolean | `true` | 自动注入 Kupola CSS |
+| `themePreload` | boolean | `false` | 自动注入主题预加载脚本 |
+| `cssPath` | string | `null` | 自定义 CSS 路径 |
+
+### themePreload 配置说明
+
+**默认值：`false`**（v1.9.13 变更）
+
+`themePreload` 用于在 CSS 加载前设置主题属性，防止主题切换时的闪屏问题。请根据你的使用方式决定是否开启：
+
+| 使用方式 | themePreload | 说明 |
+|---------|-------------|------|
+| **ESM + initTheme()** | `false`（默认） | JS 模块加载时自动初始化，无需预加载 |
+| **UMD / 纯 CSS** | `true` | 需要在 CSS 加载前设置主题，防止闪屏 |
+
+**开启示例：**
+
+```js
+// Vite
+kupola({ themePreload: true })
+
+// Webpack
+new KupolaWebpackPlugin({ themePreload: true })
+```
+
+---
+
 ## 📖 Documentation
 
 - [**用户文档**](https://kupola-cn.github.io/kupola/docs/index.html) — 安装、组件速查、核心 API、主题、后端集成
@@ -26,6 +93,71 @@
 ---
 
 <a id="english"></a>
+## 📦 Build Tool Plugins
+
+### Vite Plugin
+
+```js
+// vite.config.js
+import { kupola } from '@kupola/kupola/vite';
+
+export default {
+  plugins: [kupola()]
+};
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|--------|-------------|
+| `autoCSS` | boolean | `true` | Auto inject Kupola CSS |
+| `autoImport` | boolean | `true` | Auto import `useDeps`/`useQuery` |
+| `devTools` | boolean | `true` | Enable dev tools in dev mode |
+| `cssPath` | string | `null` | Custom CSS path |
+| `themePreload` | boolean | `false` | Auto inject theme preload script |
+
+### Webpack Plugin
+
+```js
+// webpack.config.js
+const KupolaWebpackPlugin = require('@kupola/kupola/webpack');
+
+module.exports = {
+  plugins: [new KupolaWebpackPlugin()]
+};
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|--------|-------------|
+| `autoCSS` | boolean | `true` | Auto inject Kupola CSS |
+| `themePreload` | boolean | `false` | Auto inject theme preload script |
+| `cssPath` | string | `null` | Custom CSS path |
+
+### themePreload Configuration
+
+**Default: `false`** (Changed in v1.9.13)
+
+`themePreload` sets theme attributes before CSS loads to prevent flash of unstyled content during theme switching. Enable it based on your usage pattern:
+
+| Usage Pattern | themePreload | Reason |
+|--------------|-------------|--------|
+| **ESM + initTheme()** | `false` (default) | JS module initializes automatically on load |
+| **UMD / CSS-only** | `true` | Needs theme set before CSS loads to prevent flash |
+
+**Example with themePreload enabled:**
+
+```js
+// Vite
+kupola({ themePreload: true })
+
+// Webpack
+new KupolaWebpackPlugin({ themePreload: true })
+```
+
+---
+
 ## ✨ Features
 
 - **50+ UI Components** — Buttons, inputs, cards, modals, datepickers, timepickers, heatmap, virtual list, stat cards, and more

package/css/kupola.css

@@ -1,6 +1,5 @@
 @import url('colors-and-type.css');
-@import url('theme-dark.css');
-@import url('theme-light.css');
+@import url('theme.css');
 @import url('brand-themes.css');
 @import url('scaffold.css');
 @import url('dashboard.css');