wu-framework 1.0.5 → 1.1.0

package/src/adapters/react.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Wu Framework React Adapter - TypeScript Definitions
+ */
+
+import { ComponentType, ReactElement, CSSProperties, RefObject } from 'react';
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+export interface WuInstance {
+  init: (config: WuConfig) => Promise<void>;
+  mount: (appName: string, container: string) => Promise<void>;
+  unmount: (appName: string) => Promise<void>;
+  define: (appName: string, lifecycle: WuLifecycle) => void;
+  app: (name: string, config: WuAppConfig) => WuApp;
+  eventBus: WuEventBus;
+  store: WuStore;
+}
+
+export interface WuConfig {
+  apps: Array<{
+    name: string;
+    url: string;
+    strategy?: 'lazy' | 'eager' | 'preload' | 'idle';
+  }>;
+}
+
+export interface WuLifecycle {
+  mount: (container: HTMLElement) => void | Promise<void>;
+  unmount: (container?: HTMLElement) => void | Promise<void>;
+}
+
+export interface WuAppConfig {
+  url: string;
+  container: string;
+  autoInit?: boolean;
+}
+
+export interface WuApp {
+  mount: (container?: string) => Promise<void>;
+  unmount: () => Promise<void>;
+  remount: () => Promise<void>;
+  reload: () => Promise<void>;
+  destroy: () => Promise<void>;
+  isMounted: boolean;
+  info: WuAppInfo;
+}
+
+export interface WuAppInfo {
+  name: string;
+  url: string;
+  mounted: boolean;
+  status: 'stable' | 'refreshed' | 'unstable';
+}
+
+export interface WuEventBus {
+  emit: (event: string, data?: any, options?: EmitOptions) => void;
+  on: (event: string, callback: EventCallback) => () => void;
+  once: (event: string, callback: EventCallback) => () => void;
+  off: (event: string, callback?: EventCallback) => void;
+}
+
+export interface WuStore {
+  get: (path?: string) => any;
+  set: (path: string, value: any) => number;
+  on: (pattern: string, callback: StoreCallback) => () => void;
+  batch: (updates: Record<string, any>) => number[];
+  clear: () => void;
+}
+
+export type EventCallback = (event: WuEvent) => void;
+export type StoreCallback = (change: { path: string; value: any }) => void;
+
+export interface WuEvent {
+  name: string;
+  data: any;
+  timestamp: number;
+  source?: string;
+}
+
+export interface EmitOptions {
+  appName?: string;
+  timestamp?: number;
+  meta?: Record<string, any>;
+}
+
+// ============================================================================
+// React Adapter Types
+// ============================================================================
+
+export interface RegisterOptions {
+  /** Wrap component in StrictMode (default: true) */
+  strictMode?: boolean;
+  /** Initial props for the component */
+  props?: Record<string, any>;
+  /** Callback after mounting */
+  onMount?: (container: HTMLElement) => void;
+  /** Callback before unmounting */
+  onUnmount?: (container: HTMLElement) => void;
+  /** Allow standalone execution (default: true) */
+  standalone?: boolean;
+  /** Selector for standalone mode (default: '#root') */
+  standaloneContainer?: string;
+}
+
+/**
+ * Register a React component as a microfrontend
+ */
+export function register<P = {}>(
+  appName: string,
+  Component: ComponentType<P>,
+  options?: RegisterOptions
+): Promise<boolean>;
+
+// ============================================================================
+// WuSlot Component Types
+// ============================================================================
+
+export interface WuSlotProps {
+  /** Display name for the microfrontend */
+  name: string;
+  /** URL where the microfrontend is hosted */
+  url: string;
+  /** App name from wu.json (defaults to name if not provided) */
+  appName?: string;
+  /** Custom fallback while loading */
+  fallback?: ReactElement | null;
+  /** Callback when microfrontend loads successfully */
+  onLoad?: (info: { name: string; url: string }) => void;
+  /** Callback when loading fails */
+  onError?: (error: Error) => void;
+  /** Callback when microfrontend mounts */
+  onMount?: (info: { name: string; container: HTMLElement }) => void;
+  /** Callback when microfrontend unmounts */
+  onUnmount?: (info: { name: string }) => void;
+  /** Additional CSS class */
+  className?: string;
+  /** Inline styles */
+  style?: CSSProperties;
+}
+
+/**
+ * Create a WuSlot component for loading microfrontends
+ * @param React - React instance
+ */
+export function createWuSlot(React: any): ComponentType<WuSlotProps>;
+
+// ============================================================================
+// Hooks Types
+// ============================================================================
+
+export interface UseWuEventsReturn {
+  /** Emit an event to the event bus */
+  emit: (event: string, data?: any, options?: EmitOptions) => void;
+  /** Subscribe to an event */
+  on: (event: string, callback: EventCallback) => () => void;
+  /** Subscribe to an event once */
+  once: (event: string, callback: EventCallback) => () => void;
+}
+
+/**
+ * Create the useWuEvents hook
+ * @param React - React instance
+ */
+export function createUseWuEvents(React: any): () => UseWuEventsReturn;
+
+export interface UseWuStoreReturn<T = any> {
+  /** Current state value (reactive) */
+  state: T | null;
+  /** Set a value in the store */
+  setState: (path: string, value: any) => void;
+  /** Get a value from the store */
+  getState: (path?: string) => any;
+}
+
+/**
+ * Create the useWuStore hook
+ * @param React - React instance
+ */
+export function createUseWuStore(React: any): <T = any>(namespace?: string) => UseWuStoreReturn<T>;
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Get the Wu Framework instance
+ */
+export function getWuInstance(): WuInstance | null;
+
+/**
+ * Wait for Wu Framework to be available
+ * @param timeout - Maximum time to wait in ms (default: 5000)
+ */
+export function waitForWu(timeout?: number): Promise<WuInstance>;
+
+// ============================================================================
+// Main Export
+// ============================================================================
+
+export interface WuReactAdapter {
+  register: typeof register;
+  createWuSlot: typeof createWuSlot;
+  createUseWuEvents: typeof createUseWuEvents;
+  createUseWuStore: typeof createUseWuStore;
+  getWuInstance: typeof getWuInstance;
+  waitForWu: typeof waitForWu;
+}
+
+export const wuReact: WuReactAdapter;
+export default wuReact;

package/src/adapters/react.js

@@ -0,0 +1,513 @@
+/**
+ * 🚀 WU-FRAMEWORK REACT ADAPTER
+ *
+ * Simplifica la integración de React con Wu Framework.
+ * Convierte componentes React en microfrontends con UNA línea de código.
+ *
+ * @example
+ * // Microfrontend (main.tsx)
+ * import { wuReact } from 'wu-framework/adapters/react';
+ * import App from './App';
+ *
+ * wuReact.register('my-app', App);
+ *
+ * @example
+ * // Shell (cargar microfrontend)
+ * import { WuSlot } from 'wu-framework/adapters/react';
+ *
+ * <WuSlot name="my-app" url="http://localhost:3001" />
+ */
+
+// Estado global del adapter
+const adapterState = {
+  roots: new Map(),
+  React: null,
+  ReactDOM: null,
+  createRoot: null,
+  initialized: false
+};
+
+/**
+ * Detecta y obtiene React del contexto global o lo importa
+ */
+async function ensureReact() {
+  if (adapterState.initialized) return true;
+
+  try {
+    // Intentar obtener de window (común en microfrontends)
+    if (typeof window !== 'undefined') {
+      if (window.React && window.ReactDOM) {
+        adapterState.React = window.React;
+        adapterState.ReactDOM = window.ReactDOM;
+        adapterState.createRoot = window.ReactDOM.createRoot;
+        adapterState.initialized = true;
+        return true;
+      }
+    }
+
+    // Intentar import dinámico
+    const [React, ReactDOM] = await Promise.all([
+      import('react'),
+      import('react-dom/client')
+    ]);
+
+    adapterState.React = React.default || React;
+    adapterState.ReactDOM = ReactDOM;
+    adapterState.createRoot = ReactDOM.createRoot;
+    adapterState.initialized = true;
+    return true;
+
+  } catch (error) {
+    console.error('[WuReact] Failed to load React:', error);
+    return false;
+  }
+}
+
+/**
+ * Obtiene la instancia de Wu Framework
+ */
+function getWuInstance() {
+  if (typeof window === 'undefined') return null;
+
+  return window.wu
+    || window.parent?.wu
+    || window.top?.wu
+    || null;
+}
+
+/**
+ * Espera a que Wu Framework esté disponible (sin polling agresivo)
+ */
+function waitForWu(timeout = 5000) {
+  return new Promise((resolve, reject) => {
+    // Check inmediato
+    const wu = getWuInstance();
+    if (wu) {
+      resolve(wu);
+      return;
+    }
+
+    // Usar MutationObserver + evento en lugar de polling
+    const startTime = Date.now();
+
+    // Escuchar evento de Wu Framework
+    const handleWuReady = (event) => {
+      cleanup();
+      resolve(getWuInstance());
+    };
+
+    window.addEventListener('wu:ready', handleWuReady);
+    window.addEventListener('wu:app:ready', handleWuReady);
+
+    // Fallback con polling conservador (cada 200ms, no 100ms)
+    const checkInterval = setInterval(() => {
+      const wu = getWuInstance();
+      if (wu) {
+        cleanup();
+        resolve(wu);
+        return;
+      }
+
+      if (Date.now() - startTime > timeout) {
+        cleanup();
+        reject(new Error(`Wu Framework not found after ${timeout}ms`));
+      }
+    }, 200);
+
+    function cleanup() {
+      clearInterval(checkInterval);
+      window.removeEventListener('wu:ready', handleWuReady);
+      window.removeEventListener('wu:app:ready', handleWuReady);
+    }
+  });
+}
+
+/**
+ * Registra un componente React como microfrontend
+ *
+ * @param {string} appName - Nombre único del microfrontend (debe coincidir con wu.json)
+ * @param {React.ComponentType} Component - Componente React principal
+ * @param {Object} options - Opciones adicionales
+ * @param {boolean} options.strictMode - Envolver en StrictMode (default: true)
+ * @param {Object} options.props - Props iniciales para el componente
+ * @param {Function} options.onMount - Callback después de montar
+ * @param {Function} options.onUnmount - Callback antes de desmontar
+ * @param {boolean} options.standalone - Permitir ejecución standalone (default: true)
+ * @param {string} options.standaloneContainer - Selector para modo standalone (default: '#root')
+ */
+async function register(appName, Component, options = {}) {
+  const {
+    strictMode = true,
+    props = {},
+    onMount = null,
+    onUnmount = null,
+    standalone = true,
+    standaloneContainer = '#root'
+  } = options;
+
+  // Asegurar que React está disponible
+  const hasReact = await ensureReact();
+  if (!hasReact) {
+    console.error(`[WuReact] Cannot register ${appName}: React not available`);
+    return false;
+  }
+
+  const { React, createRoot } = adapterState;
+
+  // Función de mount interna
+  const mountApp = (container) => {
+    if (!container) {
+      console.error(`[WuReact] Mount failed for ${appName}: container is null`);
+      return;
+    }
+
+    // Evitar doble mount
+    if (adapterState.roots.has(appName)) {
+      console.warn(`[WuReact] ${appName} already mounted, unmounting first`);
+      unmountApp();
+    }
+
+    try {
+      const root = createRoot(container);
+
+      // Crear elemento con o sin StrictMode
+      let element = React.createElement(Component, props);
+      if (strictMode && React.StrictMode) {
+        element = React.createElement(React.StrictMode, null, element);
+      }
+
+      root.render(element);
+      adapterState.roots.set(appName, { root, container });
+
+      console.log(`[WuReact] ✅ ${appName} mounted successfully`);
+
+      if (onMount) {
+        onMount(container);
+      }
+    } catch (error) {
+      console.error(`[WuReact] Mount error for ${appName}:`, error);
+      throw error;
+    }
+  };
+
+  // Función de unmount interna
+  const unmountApp = (container) => {
+    const instance = adapterState.roots.get(appName);
+
+    if (instance) {
+      try {
+        if (onUnmount) {
+          onUnmount(instance.container);
+        }
+
+        instance.root.unmount();
+        adapterState.roots.delete(appName);
+
+        console.log(`[WuReact] ✅ ${appName} unmounted successfully`);
+      } catch (error) {
+        console.error(`[WuReact] Unmount error for ${appName}:`, error);
+      }
+    }
+
+    // Limpiar container si se proporciona
+    if (container) {
+      container.innerHTML = '';
+    }
+  };
+
+  // Intentar registrar con Wu Framework
+  try {
+    const wu = await waitForWu(3000);
+
+    wu.define(appName, {
+      mount: mountApp,
+      unmount: unmountApp
+    });
+
+    console.log(`[WuReact] ✅ ${appName} registered with Wu Framework`);
+    return true;
+
+  } catch (error) {
+    // Wu no disponible
+    console.warn(`[WuReact] Wu Framework not available for ${appName}`);
+
+    // Modo standalone si está habilitado
+    if (standalone) {
+      const containerElement = document.querySelector(standaloneContainer);
+
+      if (containerElement) {
+        console.log(`[WuReact] Running ${appName} in standalone mode`);
+        mountApp(containerElement);
+        return true;
+      } else {
+        console.warn(`[WuReact] Standalone container ${standaloneContainer} not found`);
+      }
+    }
+
+    return false;
+  }
+}
+
+/**
+ * Crea un componente React para cargar microfrontends (para el Shell)
+ *
+ * @example
+ * import { createWuSlot } from 'wu-framework/adapters/react';
+ * const WuSlot = createWuSlot(React);
+ *
+ * <WuSlot name="my-app" url="http://localhost:3001" />
+ */
+function createWuSlot(React) {
+  const { useState, useEffect, useRef, useCallback } = React;
+
+  return function WuSlot({
+    name,
+    url,
+    appName = null,
+    fallback = null,
+    onLoad = null,
+    onError = null,
+    onMount = null,
+    onUnmount = null,
+    className = '',
+    style = {},
+    ...props
+  }) {
+    const containerRef = useRef(null);
+    const appInstanceRef = useRef(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+
+    const actualAppName = appName || name;
+
+    const mountMicrofrontend = useCallback(async () => {
+      if (!containerRef.current) return;
+
+      try {
+        setLoading(true);
+        setError(null);
+
+        const wu = getWuInstance();
+        if (!wu) {
+          throw new Error('Wu Framework not initialized');
+        }
+
+        // Crear container interno
+        const containerId = `wu-slot-${actualAppName}-${Date.now()}`;
+        const innerContainer = document.createElement('div');
+        innerContainer.id = containerId;
+        innerContainer.style.width = '100%';
+        innerContainer.style.height = '100%';
+        containerRef.current.innerHTML = '';
+        containerRef.current.appendChild(innerContainer);
+
+        // Crear y montar la app
+        const app = wu.app(actualAppName, {
+          url,
+          container: `#${containerId}`,
+          autoInit: true
+        });
+
+        appInstanceRef.current = app;
+        await app.mount();
+
+        setLoading(false);
+
+        if (onLoad) onLoad({ name: actualAppName, url });
+        if (onMount) onMount({ name: actualAppName, container: innerContainer });
+
+      } catch (err) {
+        console.error(`[WuSlot] Error loading ${actualAppName}:`, err);
+        setError(err.message || 'Failed to load microfrontend');
+        setLoading(false);
+
+        if (onError) onError(err);
+      }
+    }, [actualAppName, url, onLoad, onError, onMount]);
+
+    useEffect(() => {
+      mountMicrofrontend();
+
+      return () => {
+        if (appInstanceRef.current) {
+          if (onUnmount) onUnmount({ name: actualAppName });
+
+          appInstanceRef.current.unmount().catch(err => {
+            console.warn(`[WuSlot] Error unmounting ${actualAppName}:`, err);
+          });
+          appInstanceRef.current = null;
+        }
+      };
+    }, [mountMicrofrontend, actualAppName, onUnmount]);
+
+    // Render de error
+    if (error) {
+      return React.createElement('div', {
+        className: `wu-slot wu-slot-error ${className}`,
+        style: {
+          padding: '1rem',
+          border: '1px solid #f5c6cb',
+          borderRadius: '4px',
+          backgroundColor: '#f8d7da',
+          color: '#721c24',
+          ...style
+        },
+        ...props
+      }, [
+        React.createElement('strong', { key: 'title' }, `Error loading ${name}`),
+        React.createElement('p', { key: 'message', style: { margin: '0.5rem 0 0 0' } }, error)
+      ]);
+    }
+
+    // Render principal
+    return React.createElement('div', {
+      ref: containerRef,
+      className: `wu-slot ${loading ? 'wu-slot-loading' : 'wu-slot-loaded'} ${className}`,
+      style: {
+        minHeight: '100px',
+        position: 'relative',
+        ...style
+      },
+      'data-wu-app': actualAppName,
+      'data-wu-url': url,
+      ...props
+    }, loading && (fallback || React.createElement('div', {
+      style: {
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: '2rem',
+        color: '#666'
+      }
+    }, `Loading ${name}...`)));
+  };
+}
+
+/**
+ * Hook para usar el EventBus de Wu Framework en React
+ *
+ * @example
+ * const { emit, on } = useWuEvents();
+ *
+ * useEffect(() => {
+ *   const unsub = on('user:login', (data) => console.log(data));
+ *   return unsub;
+ * }, [on]);
+ */
+function createUseWuEvents(React) {
+  const { useCallback, useEffect, useRef } = React;
+
+  return function useWuEvents() {
+    const subscriptionsRef = useRef([]);
+
+    const emit = useCallback((event, data, options) => {
+      const wu = getWuInstance();
+      if (wu?.eventBus) {
+        wu.eventBus.emit(event, data, options);
+      } else {
+        console.warn('[useWuEvents] Wu Framework not available');
+      }
+    }, []);
+
+    const on = useCallback((event, callback) => {
+      const wu = getWuInstance();
+      if (wu?.eventBus) {
+        const unsubscribe = wu.eventBus.on(event, callback);
+        subscriptionsRef.current.push(unsubscribe);
+        return unsubscribe;
+      }
+      console.warn('[useWuEvents] Wu Framework not available');
+      return () => {};
+    }, []);
+
+    const once = useCallback((event, callback) => {
+      const wu = getWuInstance();
+      if (wu?.eventBus) {
+        return wu.eventBus.once(event, callback);
+      }
+      console.warn('[useWuEvents] Wu Framework not available');
+      return () => {};
+    }, []);
+
+    // Cleanup on unmount
+    useEffect(() => {
+      return () => {
+        subscriptionsRef.current.forEach(unsub => unsub());
+        subscriptionsRef.current = [];
+      };
+    }, []);
+
+    return { emit, on, once };
+  };
+}
+
+/**
+ * Hook para usar el Store de Wu Framework en React
+ *
+ * @example
+ * const { state, setState, subscribe } = useWuStore('user');
+ */
+function createUseWuStore(React) {
+  const { useState, useCallback, useEffect } = React;
+
+  return function useWuStore(namespace = '') {
+    const [state, setLocalState] = useState(() => {
+      const wu = getWuInstance();
+      return wu?.store?.get(namespace) || null;
+    });
+
+    const setState = useCallback((path, value) => {
+      const wu = getWuInstance();
+      if (wu?.store) {
+        const fullPath = namespace ? `${namespace}.${path}` : path;
+        wu.store.set(fullPath, value);
+      }
+    }, [namespace]);
+
+    const getState = useCallback((path = '') => {
+      const wu = getWuInstance();
+      if (wu?.store) {
+        const fullPath = namespace ? (path ? `${namespace}.${path}` : namespace) : path;
+        return wu.store.get(fullPath);
+      }
+      return null;
+    }, [namespace]);
+
+    // Subscribe to changes
+    useEffect(() => {
+      const wu = getWuInstance();
+      if (!wu?.store) return;
+
+      const pattern = namespace ? `${namespace}.*` : '*';
+      const unsubscribe = wu.store.on(pattern, () => {
+        setLocalState(wu.store.get(namespace));
+      });
+
+      return unsubscribe;
+    }, [namespace]);
+
+    return { state, setState, getState };
+  };
+}
+
+// API pública del adapter
+export const wuReact = {
+  register,
+  createWuSlot,
+  createUseWuEvents,
+  createUseWuStore,
+  getWuInstance,
+  waitForWu
+};
+
+// Named exports para conveniencia
+export {
+  register,
+  createWuSlot,
+  createUseWuEvents,
+  createUseWuStore,
+  getWuInstance,
+  waitForWu
+};
+
+export default wuReact;