@4399ywkf/core 5.0.11 → 5.0.13

package/dist/index.d.ts

@@ -229,28 +229,36 @@ interface I18nPluginOptions {
      */
     locales?: string[];
     /**
-     * 翻译文件目录（相对于项目根目录）
+     * 翻译 JSON 文件目录（相对于项目根目录）
+     * 非默认语言的 JSON 翻译文件存放位置
      * @default "locales"
      */
     localesDir?: string;
+    /**
+     * 默认语言 TS 源文件目录（相对于项目根目录）
+     * 开发者在此编写 TypeScript 翻译源文件，作为 i18n 的 single source of truth
+     * @default "src/locales/default"
+     */
+    sourceDir?: string;
     /**
      * 默认命名空间
      * @default ["common"]
      */
     defaultNS?: string[];
     /**
-     * 是否自动生成初始翻译文件
+     * 是否自动生成初始脚手架文件
      * @default true
      */
     autoScaffold?: boolean;
 }
 /**
- * 国际化插件
+ * 国际化插件（TS-first 工作流）
  *
- * 自动配置 i18next：
- * - 生成 i18n 初始化代码到 .ywkf/i18n.ts
- * - 注入 I18nextProvider 到启动文件
- * - 自动生成初始翻译文件（可选）
+ * 开发流程：
+ * 1. 开发者在 src/locales/default/ 中编写 TypeScript 翻译源文件（有类型推导 + IDE 补全）
+ * 2. 运行 `pnpm i18n:gen` 将 TS 源文件转换为 locales/{defaultLocale}/*.json
+ * 3. 运行 `pnpm i18n` 使用 @lobehub/i18n-cli 将默认语言 JSON 翻译为其他语言
+ * 4. 运行时：开发模式下默认语言直接 import TS，其他场景懒加载 JSON
  *
  * @example
  * ```ts
@@ -275,15 +283,20 @@ interface ThemePluginOptions {
      */
     darkMode?: boolean;
     /**
-     * 默认主题模式
-     * @default "auto"
+     * 默认主题模式（作为 store 的初始值，运行时可通过 useThemeStore 动态切换）
+     * 参考 lobe-ui 默认暗色风格
+     * @default "dark"
      */
     defaultAppearance?: "light" | "dark" | "auto";
     /**
-     * 主色调
-     * @default "blue"
+     * 主色调（作为 store 的初始值，运行时可通过 useThemeStore 动态切换）
+     * @default "#1677ff"
      */
     primaryColor?: string;
+    /**
+     * 中性色（作为 store 的初始值）
+     */
+    neutralColor?: string;
     /**
      * antd 前缀
      * @default "ant"
@@ -299,14 +312,34 @@ interface ThemePluginOptions {
      * @default true
      */
     globalReset?: boolean;
+    /**
+     * 是否启用外部主题注入（微前端场景）
+     *
+     * 启用后：
+     * - 应用启动时读取 window.__YWKF_THEME__ 作为初始覆盖
+     * - 监听 ywkf:theme-change 自定义事件，实现运行时主题同步
+     *
+     * 主应用注入示例：
+     * ```ts
+     * window.__YWKF_THEME__ = { primaryColor: "#ff4d4f", appearance: "dark" };
+     * window.dispatchEvent(new CustomEvent("ywkf:theme-change", {
+     *   detail: { primaryColor: "#52c41a" },
+     * }));
+     * ```
+     *
+     * @default false
+     */
+    externalTheme?: boolean;
 }
 /**
- * 主题系统插件
+ * 响应式主题系统插件
  *
- * 基于 antd-style 提供主题管理能力：
+ * 基于 antd-style + Zustand 提供运行时可变的主题管理能力：
  * - 生成 ThemeProvider 包裹组件到 .ywkf/theme.tsx
+ * - 生成 useThemeStore / useTheme 等 hooks 供业务消费
  * - 注入 ThemeProvider 到 bootstrap
- * - 支持亮/暗色自动切换
+ * - 支持亮/暗色/跟随系统自动切换
+ * - 支持微前端场景下主应用注入主题
  *
  * @example
  * ```ts
@@ -317,11 +350,24 @@ interface ThemePluginOptions {
  *     themePlugin({
  *       darkMode: true,
  *       defaultAppearance: "auto",
- *       primaryColor: "blue",
+ *       primaryColor: "#1677ff",
+ *       externalTheme: true,
  *     }),
  *   ],
  * });
  * ```
+ *
+ * 业务组件中使用：
+ * ```tsx
+ * import { useThemeStore, useTheme } from "@/.ywkf/theme";
+ *
+ * function ThemeSwitch() {
+ *   const { appearance, setAppearance } = useThemeStore(
+ *     (s) => ({ appearance: s.appearance, setAppearance: s.setAppearance }),
+ *   );
+ *   return <Switch checked={appearance === "dark"} onChange={(v) => setAppearance(v ? "dark" : "light")} />;
+ * }
+ * ```
  */
 declare const themePlugin: (options?: ThemePluginOptions | undefined) => YwkfPlugin;