@ice/mf-runtime 1.0.3-beta.2 → 1.0.3

package/docs/PLUGIN_SYSTEM_GUIDE.md

@@ -1,294 +0,0 @@
-# 微前端插件系统使用指南
-
-## 概述
-
-`@ice/mf-runtime` 提供了一套增强插件系统，允许开发者对远程组件进行功能扩展，如错误边界、日志记录、性能监控等。
-
-## 快速开始
-
-### 1. 安装依赖
-
-```bash
-npm install @ice/mf-runtime
-```
-
-### 2. 基本使用
-
-```tsx
-import { RemoteModule, registerEnhancedPlugins } from '@ice/mf-runtime';
-import { createEnhancedLoggingPlugin } from '@ice/mf-plugin-example';
-
-// 注册插件
-registerEnhancedPlugins([createEnhancedLoggingPlugin()]);
-
-// 使用远程组件
-function App() {
-  return (
-    <RemoteModule
-      scope="remote-app"
-      module="Button"
-    />
-  );
-}
-```
-
-## 插件开发
-
-### 插件接口
-
-```typescript
-export interface EnhancedRuntimePlugin {
-  name: string;
-  wrapComponent?: ComponentWrapper;
-  injectProps?: PropInjector;
-}
-
-export interface ComponentWrapper {
-  (
-    WrappedComponent: React.ComponentType<any>, 
-    context: WrapperContext
-  ): React.ComponentType<any>;
-}
-
-export interface PropInjector {
-  (
-    props: Record<string, any>, 
-    context: InjectionContext
-  ): Record<string, any>;
-}
-```
-
-### 上下文信息
-
-```typescript
-export interface WrapperContext {
-  remoteName: string;
-  moduleName: string;
-  props: Record<string, any>;
-  React: typeof import('react');        // 正确的 React 实例
-  ReactDOM?: typeof import('react-dom'); // 正确的 ReactDOM 实例
-}
-
-export interface InjectionContext {
-  remoteName: string;
-  moduleName: string;
-}
-```
-
-### 创建插件
-
-```typescript
-import type { EnhancedRuntimePlugin, WrapperContext } from '@ice/mf-runtime';
-
-export function createMyPlugin(options = {}): EnhancedRuntimePlugin {
-  return {
-    name: 'my-plugin',
-    
-    wrapComponent: (WrappedComponent, context: WrapperContext) => {
-      // 🔑 使用上下文提供的 React 实例
-      const { React: ContextReact } = context;
-      
-      const MyWrapper = ContextReact.forwardRef<any, any>((props, ref) => {
-        ContextReact.useEffect(() => {
-          console.log(`Component ${context.remoteName}/${context.moduleName} mounted`);
-        }, []);
-        
-        return ContextReact.createElement(WrappedComponent, { ...props, ref });
-      });
-      
-      MyWrapper.displayName = `MyWrapper(${WrappedComponent.displayName || 'Component'})`;
-      return MyWrapper;
-    },
-    
-    injectProps: (props, context) => {
-      return {
-        ...props,
-        pluginData: 'injected by my plugin'
-      };
-    }
-  };
-}
-```
-
-## 内置插件示例
-
-### 日志记录插件
-
-```typescript
-import { 
-  createEnhancedLoggingPlugin,
-  developmentEnhancedLoggingPlugin,
-  productionEnhancedLoggingPlugin
-} from '@ice/mf-plugin-example';
-
-// 自定义配置
-registerEnhancedPlugins([createEnhancedLoggingPlugin({
-  level: 'info',
-  logComponentRender: true,
-  enablePerformanceMonitoring: true
-})]);
-
-// 或使用预定义插件
-registerEnhancedPlugins([
-  process.env.NODE_ENV === 'development' 
-    ? developmentEnhancedLoggingPlugin 
-    : productionEnhancedLoggingPlugin
-]);
-```
-
-### 属性注入插件
-
-```typescript
-import { createPropsInjectionPlugin } from '@ice/mf-plugin-example';
-
-registerEnhancedPlugins([createPropsInjectionPlugin({
-  globalProps: {
-    theme: 'dark',
-    version: '1.0.0'
-  }
-})]);
-```
-
-## 插件管理
-
-### 注册插件
-
-```typescript
-import { registerEnhancedPlugins } from '@ice/mf-runtime';
-
-// 注册多个插件（推荐方式）
-registerEnhancedPlugins([plugin1, plugin2, plugin3]);
-
-// 或通过插件管理器注册
-import { getEnhancedPluginManager } from '@ice/mf-runtime';
-const manager = getEnhancedPluginManager();
-manager.register(myPlugin);
-manager.registerPlugins([plugin1, plugin2]);
-```
-
-### 获取插件管理器
-
-```typescript
-import { getEnhancedPluginManager } from '@ice/mf-runtime';
-
-const manager = getEnhancedPluginManager();
-
-// 获取所有插件
-const plugins = manager.getPlugins();
-
-// 获取插件信息
-const info = manager.getPluginInfo();
-
-// 移除插件
-manager.removePlugin('plugin-name');
-
-// 清空所有插件
-manager.clear();
-```
-
-### 在组件中使用
-
-```typescript
-import { useEnhancedPluginManager } from '@ice/mf-runtime';
-
-function MyComponent() {
-  const pluginManager = useEnhancedPluginManager();
-  
-  // 动态注册插件
-  React.useEffect(() => {
-    pluginManager.register(createMyPlugin());
-  }, []);
-  
-  return <div>My Component</div>;
-}
-```
-
-## 远程组件配置
-
-### 基本配置
-
-```tsx
-<RemoteModule
-  scope="remote-app"
-  module="Button"
-  componentProps={{ text: 'Click me' }}
-/>
-```
-
-
-## 最佳实践
-
-### 1. React 实例一致性
-
-始终使用上下文提供的 React 实例，避免使用 JSX 语法：
-
-```typescript
-// ✅ 正确 - 使用上下文的 React 实例
-wrapComponent: (WrappedComponent, context) => {
-  const { React: ContextReact } = context;
-  return ContextReact.forwardRef((props, ref) => {
-    // 使用 createElement 确保实例一致性
-    return ContextReact.createElement(WrappedComponent, { ...props, ref });
-  });
-}
-
-// ❌ 错误 - 使用导入的 React 实例
-import React from 'react';
-wrapComponent: (WrappedComponent, context) => {
-  return React.forwardRef((props, ref) => {  // 可能是错误的 React 实例
-    return <WrappedComponent {...props} ref={ref} />; // JSX 使用编译时的 React
-  });
-}
-```
-
-**为什么不能直接用 JSX？**
-
-在微前端场景中：
-- 主应用和远程模块可能使用不同版本的 React
-- JSX 编译时绑定到特定的 React 实例
-- 使用 `ContextReact.createElement` 确保运行时使用正确的实例
-
-### 2. Ref 转发
-
-确保正确转发 ref：
-
-```typescript
-const MyWrapper = ContextReact.forwardRef<any, any>((props, ref) => {
-  return ContextReact.createElement(WrappedComponent, { ...props, ref });
-});
-```
-
-## 故障排除
-
-### 常见问题
-
-1. **插件不生效**
-   - 确保插件已正确注册
-   - 检查插件名称是否唯一
-   - 验证插件函数是否正确实现
-
-2. **React Hook 错误**
-   - 确保使用上下文提供的 React 实例
-   - 检查是否在条件语句中使用 Hook
-
-3. **Ref 转发失败**
-   - 确保使用 `React.forwardRef`
-   - 检查 ref 是否正确传递给底层组件
-
-4. **类型错误**
-   - 确保导入正确的类型定义
-   - 使用 `React.ComponentType<any>` 处理动态组件类型
-
-### 调试技巧
-
-```typescript
-// 启用调试日志
-registerEnhancedPlugin(createEnhancedLoggingPlugin({
-  level: 'debug',
-  logComponentRender: true
-}));
-
-// 检查插件状态
-const manager = getEnhancedPluginManager();
-console.log('Registered plugins:', manager.getPluginInfo());
-```

package/es2017/__tests__/plugin-manager.test.d.ts

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

package/es2017/__tests__/plugin-manager.test.js

@@ -1,291 +0,0 @@
-import { _ as _object_spread } from "@swc/helpers/_/_object_spread";
-import { _ as _object_spread_props } from "@swc/helpers/_/_object_spread_props";
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { EnhancedPluginManager, getEnhancedPluginManager, registerEnhancedPlugins } from '../plugin-manager';
-import * as React from 'react';
-describe('EnhancedPluginManager', ()=>{
-    let manager;
-    beforeEach(()=>{
-        manager = new EnhancedPluginManager();
-    });
-    describe('Plugin Registration', ()=>{
-        it('should register an enhanced plugin', ()=>{
-            const enhancedPlugin = {
-                name: 'test-enhanced',
-                wrapComponent: (Component)=>Component,
-                injectProps: (props)=>props
-            };
-            manager.register(enhancedPlugin);
-            const plugins = manager.getPlugins();
-            expect(plugins).toHaveLength(1);
-            expect(plugins[0].name).toBe('test-enhanced');
-        });
-        it('should replace existing plugin with same name', ()=>{
-            const plugin1 = {
-                name: 'test-plugin',
-                wrapComponent: (Component)=>Component
-            };
-            const plugin2 = {
-                name: 'test-plugin',
-                injectProps: (props)=>props
-            };
-            manager.register(plugin1);
-            manager.register(plugin2);
-            const plugins = manager.getPlugins();
-            expect(plugins).toHaveLength(1);
-            expect(plugins[0]).toBe(plugin2);
-        });
-        it('should register multiple plugins', ()=>{
-            const plugins = [
-                {
-                    name: 'plugin1',
-                    wrapComponent: (Component)=>Component
-                },
-                {
-                    name: 'plugin2',
-                    injectProps: (props)=>props
-                }
-            ];
-            manager.registerPlugins(plugins);
-            expect(manager.getPlugins()).toHaveLength(2);
-        });
-    });
-    describe('Component Wrapping', ()=>{
-        it('should wrap component with single plugin', ()=>{
-            const TestComponent = ()=>React.createElement('div', null, 'test');
-            const mockWrapper = vi.fn((Component)=>Component);
-            const plugin = {
-                name: 'wrapper-plugin',
-                wrapComponent: mockWrapper
-            };
-            manager.register(plugin);
-            const context = {
-                remoteName: 'test-remote',
-                moduleName: 'test-module',
-                props: {
-                    test: true
-                },
-                React: React,
-                ReactDOM: undefined
-            };
-            const wrappedComponent = manager.wrapComponent(TestComponent, context);
-            expect(mockWrapper).toHaveBeenCalledWith(TestComponent, context);
-            expect(wrappedComponent).toBe(TestComponent);
-        });
-        it('should apply multiple wrappers in order', ()=>{
-            const TestComponent = ()=>React.createElement('div', null, 'original');
-            const Wrapper1 = ()=>React.createElement('div', null, 'wrapper1');
-            const Wrapper2 = ()=>React.createElement('div', null, 'wrapper2');
-            const plugin1 = {
-                name: 'wrapper1',
-                wrapComponent: ()=>Wrapper1
-            };
-            const plugin2 = {
-                name: 'wrapper2',
-                wrapComponent: ()=>Wrapper2
-            };
-            // 注册顺序很重要
-            manager.register(plugin1);
-            manager.register(plugin2);
-            const context = {
-                remoteName: 'test-remote',
-                moduleName: 'test-module',
-                props: {},
-                React: React,
-                ReactDOM: undefined
-            };
-            const result = manager.wrapComponent(TestComponent, context);
-            // plugin2 应该最后执行，所以返回 Wrapper2
-            expect(result).toBe(Wrapper2);
-        });
-        it('should handle wrapper errors gracefully', ()=>{
-            const TestComponent = ()=>React.createElement('div', null, 'test');
-            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(()=>{});
-            const plugin = {
-                name: 'error-plugin',
-                wrapComponent: ()=>{
-                    throw new Error('Wrapper error');
-                }
-            };
-            manager.register(plugin);
-            const context = {
-                remoteName: 'test-remote',
-                moduleName: 'test-module',
-                props: {},
-                React: React,
-                ReactDOM: undefined
-            };
-            const result = manager.wrapComponent(TestComponent, context);
-            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Error applying wrapper from plugin "error-plugin"'), expect.any(Error));
-            expect(result).toBe(TestComponent); // 应该返回原始组件
-            consoleSpy.mockRestore();
-        });
-    });
-    describe('Props Injection', ()=>{
-        it('should inject props with single plugin', ()=>{
-            const mockInjector = vi.fn((props)=>_object_spread_props(_object_spread({}, props), {
-                    injected: true
-                }));
-            const plugin = {
-                name: 'injector-plugin',
-                injectProps: mockInjector
-            };
-            manager.register(plugin);
-            const context = {
-                remoteName: 'test-remote',
-                moduleName: 'test-module'
-            };
-            const result = manager.injectProps({
-                original: true
-            }, context);
-            expect(mockInjector).toHaveBeenCalledWith({
-                original: true
-            }, context);
-            expect(result).toEqual({
-                original: true,
-                injected: true
-            });
-        });
-        it('should apply multiple injectors in order', ()=>{
-            const plugin1 = {
-                name: 'injector1',
-                injectProps: (props)=>_object_spread_props(_object_spread({}, props), {
-                        step1: true
-                    })
-            };
-            const plugin2 = {
-                name: 'injector2',
-                injectProps: (props)=>_object_spread_props(_object_spread({}, props), {
-                        step2: true
-                    })
-            };
-            manager.register(plugin1);
-            manager.register(plugin2);
-            const context = {
-                remoteName: 'test-remote',
-                moduleName: 'test-module'
-            };
-            const result = manager.injectProps({
-                original: true
-            }, context);
-            expect(result).toEqual({
-                original: true,
-                step1: true,
-                step2: true
-            });
-        });
-        it('should handle injection errors gracefully', ()=>{
-            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(()=>{});
-            const plugin = {
-                name: 'error-plugin',
-                injectProps: ()=>{
-                    throw new Error('Injection error');
-                }
-            };
-            manager.register(plugin);
-            const context = {
-                remoteName: 'test-remote',
-                moduleName: 'test-module'
-            };
-            const result = manager.injectProps({
-                original: true
-            }, context);
-            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Error injecting props from plugin "error-plugin"'), expect.any(Error));
-            expect(result).toEqual({
-                original: true
-            }); // 应该返回原始props
-            consoleSpy.mockRestore();
-        });
-    });
-    describe('Plugin Management', ()=>{
-        it('should get plugin info', ()=>{
-            const wrapperPlugin = {
-                name: 'wrapper-plugin',
-                wrapComponent: (Component)=>Component
-            };
-            const injectorPlugin = {
-                name: 'injector-plugin',
-                injectProps: (props)=>props
-            };
-            const hybridPlugin = {
-                name: 'hybrid-plugin',
-                wrapComponent: (Component)=>Component,
-                injectProps: (props)=>props
-            };
-            manager.register(wrapperPlugin);
-            manager.register(injectorPlugin);
-            manager.register(hybridPlugin);
-            const info = manager.getPluginInfo();
-            expect(info).toHaveLength(3);
-            expect(info[0]).toEqual({
-                name: 'wrapper-plugin',
-                hasWrapper: true,
-                hasInjector: false
-            });
-            expect(info[1]).toEqual({
-                name: 'injector-plugin',
-                hasWrapper: false,
-                hasInjector: true
-            });
-            expect(info[2]).toEqual({
-                name: 'hybrid-plugin',
-                hasWrapper: true,
-                hasInjector: true
-            });
-        });
-        it('should remove plugin', ()=>{
-            const plugin = {
-                name: 'test-plugin',
-                wrapComponent: (Component)=>Component
-            };
-            manager.register(plugin);
-            expect(manager.getPlugins()).toHaveLength(1);
-            const removed = manager.removePlugin('test-plugin');
-            expect(removed).toBe(true);
-            expect(manager.getPlugins()).toHaveLength(0);
-        });
-        it('should return false when removing non-existent plugin', ()=>{
-            const removed = manager.removePlugin('non-existent');
-            expect(removed).toBe(false);
-        });
-        it('should clear all plugins', ()=>{
-            manager.register({
-                name: 'plugin1',
-                wrapComponent: (Component)=>Component
-            });
-            manager.register({
-                name: 'plugin2',
-                injectProps: (props)=>props
-            });
-            expect(manager.getPlugins()).toHaveLength(2);
-            manager.clear();
-            expect(manager.getPlugins()).toHaveLength(0);
-        });
-    });
-    describe('Global Enhanced Plugin Manager', ()=>{
-        beforeEach(()=>{
-            // 清理全局状态
-            getEnhancedPluginManager().clear();
-        });
-        it('should provide singleton instance', ()=>{
-            const manager1 = getEnhancedPluginManager();
-            const manager2 = getEnhancedPluginManager();
-            expect(manager1).toBe(manager2);
-        });
-        it('should register multiple plugins via convenience function', ()=>{
-            const plugins = [
-                {
-                    name: 'plugin1',
-                    wrapComponent: (Component)=>Component
-                },
-                {
-                    name: 'plugin2',
-                    injectProps: (props)=>props
-                }
-            ];
-            registerEnhancedPlugins(plugins);
-            const manager = getEnhancedPluginManager();
-            expect(manager.getPlugins()).toHaveLength(2);
-        });
-    });
-});

package/es2017/__tests__/setup.d.ts

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

package/es2017/__tests__/setup.js

@@ -1,28 +0,0 @@
-import { vi } from 'vitest';
-// Test setup for ice-mf-runtime
-// Mock @ice/stark-app dependency
-vi.mock('@ice/stark-app', ()=>({
-        getBasename: ()=>'/app'
-    }));
-// Mock @module-federation/runtime
-vi.mock('@module-federation/runtime', ()=>({
-        init: vi.fn(),
-        registerPlugins: vi.fn(),
-        loadRemote: vi.fn()
-    }));
-// Mock performance API
-Object.defineProperty(globalThis, 'performance', {
-    value: {
-        now: ()=>Date.now()
-    },
-    writable: true
-});
-// Suppress console warnings during tests
-const originalWarn = console.warn;
-console.warn = (...args)=>{
-    var _args__includes, _args_;
-    if ((_args_ = args[0]) === null || _args_ === void 0 ? void 0 : (_args__includes = _args_.includes) === null || _args__includes === void 0 ? void 0 : _args__includes.call(_args_, 'Warning: ReactDOM.render is no longer supported')) {
-        return;
-    }
-    originalWarn.call(console, ...args);
-};

package/es2017/plugin-manager.d.ts

@@ -1,74 +0,0 @@
-import type { EnhancedRuntimePlugin, WrapperContext, InjectionContext } from './types';
-import * as React from 'react';
-/**
- * 增强插件管理器 - 专门负责管理和执行增强运行时插件
- * 标准 MF 插件交由底层 @module-federation/runtime 管理
- */
-export declare class EnhancedPluginManager {
-    private plugins;
-    /**
-     * 注册增强插件
-     * @param plugin 增强运行时插件
-     */
-    register(plugin: EnhancedRuntimePlugin): void;
-    /**
-     * 注册多个增强插件
-     * @param plugins 增强插件数组
-     */
-    registerPlugins(plugins: EnhancedRuntimePlugin[]): void;
-    /**
-     * 获取所有增强插件列表
-     * @returns 增强插件数组
-     */
-    getPlugins(): EnhancedRuntimePlugin[];
-    /**
-     * 应用组件包装器
-     * 按插件注册顺序依次应用所有组件包装器
-     * @param Component 原始组件
-     * @param context 包装器上下文
-     * @returns 包装后的组件
-     */
-    wrapComponent(Component: React.ComponentType, context: WrapperContext): React.ComponentType;
-    /**
-     * 注入属性
-     * 按插件注册顺序依次应用所有属性注入器
-     * @param props 原始属性
-     * @param context 注入上下文
-     * @returns 注入后的属性
-     */
-    injectProps(props: Record<string, any>, context: InjectionContext): Record<string, any>;
-    /**
-     * 获取所有插件信息
-     * @returns 插件信息数组
-     */
-    getPluginInfo(): Array<{
-        name: string;
-        hasWrapper: boolean;
-        hasInjector: boolean;
-    }>;
-    /**
-     * 移除插件
-     * @param name 插件名称
-     * @returns 是否成功移除
-     */
-    removePlugin(name: string): boolean;
-    /**
-     * 清空所有插件
-     */
-    clear(): void;
-}
-/**
- * 获取全局增强插件管理器实例
- * @returns 增强插件管理器实例
- */
-export declare function getEnhancedPluginManager(): EnhancedPluginManager;
-/**
- * 注册多个增强插件（便捷函数）
- * @param plugins 增强插件数组
- */
-export declare function registerEnhancedPlugins(plugins: EnhancedRuntimePlugin[]): void;
-/**
- * React Hook：使用增强插件管理器
- * @returns 增强插件管理器实例
- */
-export declare function useEnhancedPluginManager(): EnhancedPluginManager;