@vlian/framework 1.2.61 → 1.2.62

package/dist/core-bak/types.d.ts

@@ -0,0 +1,501 @@
+import { LogLevel } from '@vlian/logger';
+import type { LangType } from '../library/locale/types';
+import { Container, RootOptions } from 'react-dom/client';
+import { type ComponentType, type PropsWithChildren, type ReactElement, type ReactNode } from 'react';
+import { type InitializationContext } from './initialization';
+import type { StorageOptions } from '../types';
+import type { ThemeConfig } from './app';
+import type { FrameworkError } from '@vlian/utils';
+import type { RouterConfig } from './router/types';
+export type UIProviderConfig = Record<string, unknown>;
+export type UIAppConfig = Record<string, unknown>;
+export type GlobalProviderComponent = ComponentType<PropsWithChildren>;
+export type GlobalProviderLoader = () => Promise<{
+    default: GlobalProviderComponent;
+}>;
+/**
+ * 生命周期钩子函数类型
+ */
+export type ManagerLifecycle = {
+    /**
+     * 在初始化之前执行
+     */
+    beforeInitialization?: () => Promise<void> | void;
+    /**
+     * 初始化
+     */
+    initialization?: () => Promise<void> | void;
+    /**
+     * 在初始化之后执行
+     *
+     * @param context - 初始化上下文，包含配置、进度、耗时等信息
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   lifecycle: {
+     *     afterInitialization: (context) => {
+     *       console.log('初始化完成', context);
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    afterInitialization?: (context: InitializationContext) => Promise<void> | void;
+};
+/**
+ * 启动配置选项
+ */
+export interface StartOptions {
+    /**
+     * React 应用的挂载容器
+     *
+     * 用于指定 React 应用渲染的目标 DOM 元素。如果不提供，框架将自动查找页面中
+     * 的根元素（通常为 id="root" 的元素）作为默认容器。
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     *
+     * // 使用默认容器（自动查找 id="root" 的元素）
+     * start({});
+     *
+     * // 指定自定义容器
+     * const container = document.getElementById('app');
+     * start({ container });
+     * ```
+     */
+    container?: Container;
+    /**
+     * React 根节点的配置选项
+     *
+     * 用于配置 React 18+ 的 createRoot 方法的选项，包括：
+     * - `onRecoverableError`: 错误恢复回调函数
+     * - `identifierPrefix`: 用于标识符前缀，用于服务端渲染的 hydration
+     *
+     * 这些选项将传递给 `react-dom/client` 的 `createRoot` 方法。
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     *
+     * start({
+     *   rootOptions: {
+     *     onRecoverableError: (error) => {
+     *       console.error('React 错误恢复:', error);
+     *     },
+     *     identifierPrefix: 'my-app-',
+     *   },
+     * });
+     * ```
+     */
+    rootOptions?: RootOptions;
+    /**
+     * 应用根组件
+     *
+     * 用于指定要渲染的 React 应用根组件。
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     * import App from './App';
+     *
+     * start({
+     *   app: <App />,
+     * });
+     * ```
+     */
+    app?: ReactElement;
+    /**
+     * 是否显示启动页
+     * - 'auto': 自动判断（推荐）
+     * - 'always': 总是显示
+     * - 'never': 从不显示
+     * - 'first-time-only': 仅首次加载显示
+     *
+     * @default 'auto'
+     */
+    showSplashScreen?: 'auto' | 'always' | 'never' | 'first-time-only';
+    /**
+     * 启动页最小显示时间（毫秒）
+     *
+     * 用于避免启动页闪烁，确保用户能看到启动过程。
+     * 如果初始化完成时间小于此值，将等待至最小时间后再隐藏启动页。
+     *
+     * @default 500
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   minSplashScreenTime: 1000, // 至少显示 1 秒
+     * });
+     * ```
+     */
+    minSplashScreenTime?: number;
+    /**
+     * 路由配置
+     *
+     * 配置应用的路由系统，支持内置路由、自定义路由和禁用路由三种模式。
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   router: {
+     *     enabled: true,
+     *     routes: [
+     *       {
+     *         path: '/login',
+     *         page: LoginPage,
+     *       },
+     *       {
+     *         path: '/',
+     *         layout: MainLayout,
+     *         children: [
+     *           {
+     *             path: 'dashboard',
+     *             page: DashboardPage,
+     *             meta: { title: '仪表盘' },
+     *           },
+     *         ],
+     *       },
+     *     ],
+     *   },
+     * });
+     * ```
+     */
+    router?: RouterConfig;
+    /**
+     * 日志级别
+     */
+    loggerLevel?: LogLevel;
+    /**
+     * 生命周期钩子
+     */
+    lifecycle?: ManagerLifecycle;
+    /**
+     * 国际化
+     */
+    locale?: Record<LangType, Record<string, unknown>>;
+    /**
+     * 启动页完成回调
+     * 仅在显示启动页时，启动页完成初始化后调用
+     * 可以在这里执行额外的操作，然后调用 complete() 继续
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   onSplashComplete: (complete, context) => {
+     *     // 执行额外操作
+     *     await doSomething();
+     *     // 完成后继续
+     *     complete();
+     *   },
+     * });
+     * ```
+     */
+    onSplashComplete?: (complete: () => void, context: InitializationContext) => Promise<void> | void;
+    /**
+     * 存储配置
+     */
+    storageOptions?: StorageOptions;
+    /**
+     * IndexedDB 表名
+     */
+    indexedDBTableName?: string;
+    /**
+     * UI Provider 配置（框架无关）
+     * 可由 UI 适配器消费，适配到 antd/shadcn 等实现。
+     */
+    uiProvider?: UIProviderConfig;
+    /**
+     * UI App 基础配置（框架无关）
+     * 可用于通知、弹窗、消息容器等能力的统一注入。
+     */
+    uiApp?: UIAppConfig;
+    /**
+     * 全局 UI 包裹组件懒加载器
+     *
+     * 组件会在 BasicLayout 中统一包裹 children。
+     * 需返回带 default 导出的 React 组件模块。
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   globalProvider: () => import('./components/AntdGlobalProvider'),
+     * });
+     * ```
+     */
+    globalProvider?: GlobalProviderLoader;
+    /**
+     * @deprecated 使用 uiProvider 替代
+     */
+    antd?: Record<string, unknown>;
+    /**
+     * @deprecated 使用 uiApp 替代
+     */
+    antdApp?: Record<string, unknown>;
+    /**
+     * 主题配置
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   theme: {
+     *     mode: 'dark',
+     *     primaryColor: '#1890ff',
+     *   },
+     * });
+     * ```
+     */
+    theme?: ThemeConfig;
+    /**
+     * 运行时安全配置
+     */
+    runtimeSecurity?: import('../utils/runtimeSecurity').RuntimeSecurityOptions;
+    /**
+     * 配置安全选项
+     */
+    configSecurity?: import('../utils/configSecurity').ConfigSecurityOptions;
+    /**
+     * 性能监控配置
+     */
+    performanceMonitor?: import('../utils/performance').PerformanceMonitorConfig;
+    /**
+     * 错误监控配置
+     */
+    errorMonitor?: import('@vlian/monitoring').ErrorMonitorConfig;
+    /**
+     * 分析服务配置
+     */
+    analytics?: import('../utils/analytics').AnalyticsConfig;
+    /**
+     * 状态管理器配置
+     *
+     * 配置框架的状态管理器，支持自定义适配器和作用域设置。
+     * 如果不提供，将使用默认配置创建状态管理器。
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     *
+     * start({
+     *   stateManager: {
+     *     enableRegistry: true,
+     *     defaultScope: 'app',
+     *     devMode: true,
+     *   },
+     * });
+     * ```
+     */
+    stateManager?: import('../state').StateManagerOptions;
+    /**
+     * 事件总线配置
+     *
+     * 配置应用级事件系统，支持事件追踪、性能监控、安全模式等。
+     * 如果不提供，将使用默认配置创建事件总线。
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     *
+     * start({
+     *   eventBus: {
+     *     enableTracking: true,
+     *     maxHistorySize: 200,
+     *     enablePerformanceMonitoring: true,
+     *     namespacePrefix: 'my-app:',
+     *   },
+     * });
+     * ```
+     */
+    eventBus?: {
+        enableTracking?: boolean;
+        maxHistorySize?: number;
+        enableValidation?: boolean;
+        validator?: (event: string, data: unknown) => boolean;
+        enablePerformanceMonitoring?: boolean;
+        namespacePrefix?: string;
+        instanceId?: string;
+        enableSecurityMode?: boolean;
+        allowedSources?: string[];
+    };
+    /**
+     * 自定义启动屏组件
+     *
+     * 如果提供，将使用自定义组件替代默认的启动屏 UI。
+     * 自定义组件将接收初始化进度、当前步骤和初始化状态作为 props。
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     *
+     * const CustomSplashScreen = ({ progress, currentStep, isInitializing }) => {
+     *   return (
+     *     <div>
+     *       <h1>加载中...</h1>
+     *       <div>进度: {progress}%</div>
+     *       <div>步骤: {currentStep}</div>
+     *     </div>
+     *   );
+     * };
+     *
+     * start({
+     *   splashScreen: CustomSplashScreen,
+     * });
+     * ```
+     */
+    splashScreen?: React.ComponentType<SplashScreenCustomProps>;
+    /**
+     * 自定义错误反馈组件
+     *
+     * 如果提供，将使用自定义的错误 UI 替代默认错误 UI。
+     * 自定义组件将接收错误对象和重置函数作为参数。
+     *
+     * @param error - 标准化后的框架错误对象
+     * @param resetError - 重置错误边界的函数，调用后可以尝试重新渲染子组件
+     * @returns 错误 UI 的 React 节点
+     *
+     * @example
+     * ```typescript
+     * import { start } from '@vlian/framework';
+     * start({
+     *   errorFallback: (error, reset) => (
+     *     <div>
+     *       <h2>自定义错误标题</h2>
+     *       <p>{error.message}</p>
+     *       <button onClick={reset}>重试</button>
+     *     </div>
+     *   ),
+     * });
+     * ```
+     */
+    errorFallback?: (error: FrameworkError, resetError: () => void) => ReactNode;
+    /**
+     * 安全配置选项
+     *
+     * 用于配置框架的安全策略，包括 XSS 防护、配置验证等。
+     * 框架默认启用所有安全策略，确保应用安全。
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   security: {
+     *     enableXSSProtection: true, // 默认启用
+     *     validateConfig: true, // 默认启用
+     *     sanitizeUserInput: true, // 默认启用
+     *   },
+     * });
+     * ```
+     */
+    security?: {
+        /**
+         * 是否启用 XSS 防护
+         * @default true
+         */
+        enableXSSProtection?: boolean;
+        /**
+         * 是否验证配置项安全性
+         * @default true
+         */
+        validateConfig?: boolean;
+        /**
+         * 是否清理用户输入
+         * @default true
+         */
+        sanitizeUserInput?: boolean;
+        /**
+         * CSP（内容安全策略）配置
+         */
+        csp?: {
+            defaultSrc?: string[];
+            scriptSrc?: string[];
+            styleSrc?: string[];
+            imgSrc?: string[];
+            connectSrc?: string[];
+            fontSrc?: string[];
+            frameSrc?: string[];
+            allowUnsafeInline?: boolean;
+            allowUnsafeEval?: boolean;
+        };
+        /**
+         * CSRF 防护配置
+         */
+        csrf?: {
+            /**
+             * 是否启用 CSRF 防护
+             * @default true
+             */
+            enabled?: boolean;
+            /**
+             * CSRF Token 获取函数
+             * 如果不提供，框架会自动从 cookie 或 header 中获取
+             */
+            getToken?: () => string | Promise<string>;
+            /**
+             * CSRF Token 验证函数
+             * 如果不提供，框架会使用默认验证逻辑
+             */
+            validateToken?: (token: string) => boolean | Promise<boolean>;
+            /**
+             * CSRF Token 请求头名称
+             * @default 'X-CSRF-Token'
+             */
+            headerName?: string;
+            /**
+             * CSRF Token Cookie 名称
+             * @default 'csrf-token'
+             */
+            cookieName?: string;
+        };
+    };
+    /**
+     * 服务初始化重试配置
+     *
+     * 用于配置服务初始化失败时的重试策略。
+     *
+     * @example
+     * ```typescript
+     * start({
+     *   serviceRetry: {
+     *     maxRetries: 3,
+     *     retryDelay: 1000,
+     *     exponentialBackoff: true,
+     *   },
+     * });
+     * ```
+     */
+    serviceRetry?: {
+        /**
+         * 最大重试次数
+         * @default 3
+         */
+        maxRetries?: number;
+        /**
+         * 重试延迟（毫秒）
+         * @default 1000
+         */
+        retryDelay?: number;
+        /**
+         * 是否启用指数退避
+         * @default true
+         */
+        exponentialBackoff?: boolean;
+    };
+}
+/**
+ * 自定义启动屏组件的 Props
+ */
+export interface SplashScreenCustomProps {
+    /**
+     * 初始化进度（0-100）
+     */
+    progress: number;
+    /**
+     * 当前步骤描述
+     */
+    currentStep: string;
+    /**
+     * 是否正在初始化
+     */
+    isInitializing: boolean;
+}

package/dist/core-bak/types.js

@@ -0,0 +1 @@
+export{};

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:true});function _export(target,all){for(var name in all)Object.defineProperty(target,name,{enumerable:true,get:Object.getOwnPropertyDescriptor(all,name).get})}_export(exports,{get $t(){return _library.$t},get Kernel(){return _kernel.Kernel},get getKernel(){return _kernel.getKernel},get kernelStartApp(){return _kernel.kernelStartApp},get setLang(){return _library.setLang},get setupI18n(){return _library.setupI18n},get startup(){return _kernel.startup}});const _library=require("./library");_export_star(require("./core"),exports);_export_star(require("./utils"),exports);_export_star(require("./state"),exports);_export_star(require("./components"),exports);const _kernel=require("./kernel");function _export_star(from,to){Object.keys(from).forEach(function(k){if(k!=="default"&&!Object.prototype.hasOwnProperty.call(to,k)){Object.defineProperty(to,k,{enumerable:true,get:function(){return from[k]}})}});return from}
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});function _export(target,all){for(var name in all)Object.defineProperty(target,name,{enumerable:true,get:Object.getOwnPropertyDescriptor(all,name).get})}_export(exports,{get $t(){return _library.$t},get Kernel(){return _kernel.Kernel},get getKernel(){return _kernel.getKernel},get kernelStartApp(){return _kernel.kernelStartApp},get setLang(){return _library.setLang},get setupI18n(){return _library.setupI18n},get startup(){return _kernel.startup}});const _library=require("./library");_export_star(require("./utils"),exports);_export_star(require("./state"),exports);_export_star(require("./components"),exports);const _kernel=require("./kernel");function _export_star(from,to){Object.keys(from).forEach(function(k){if(k!=="default"&&!Object.prototype.hasOwnProperty.call(to,k)){Object.defineProperty(to,k,{enumerable:true,get:function(){return from[k]}})}});return from}

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import { setupI18n, setLang, $t } from './library';
-export * from './core';
 export * from './utils';
 export * from './state';
 export * from './components';

package/dist/index.js

@@ -1 +1 @@
-import{setupI18n,setLang,$t}from"./library";export*from"./core";export*from"./utils";export*from"./state";export*from"./components";export{setupI18n,setLang,$t};export{Kernel,startup,getKernel,kernelStartApp}from"./kernel";
+import{setupI18n,setLang,$t}from"./library";export*from"./utils";export*from"./state";export*from"./components";export{setupI18n,setLang,$t};export{Kernel,startup,getKernel,kernelStartApp}from"./kernel";