@wonderkits/app/dist/index.d.ts

WonderKits micro-frontend SDK for sub-applications

import * as React from 'react';

/**
 * @wonderkits/app/core
 *
 * 子应用核心类型定义 - 最小化设计
 * 只包含子应用开发必需的类型
 */

/**
 * 图标组件类型
 * 支持各种图标库（heroicons、lucide 等）
 * 使用 ElementType 以兼容 ForwardRefExoticComponent
 */
type IconComponent = React.ElementType<{
    className?: string;
}>;
/**
 * 应用清单 - 精简版
 * 子应用只需要定义这些基本信息
 */
interface AppManifest {
    /** 应用唯一标识 */
    id: string;
    /** 应用名称 */
    name: string;
    /** 应用版本 */
    version: string;
    /** 显示名称（可选，默认使用 name） */
    displayName?: string;
    /** 应用描述 */
    description?: string;
    /** 应用图标 URL */
    icon?: string;
    /** 作者 */
    author?: string;
    /** 分类 */
    category?: string;
}
/**
 * 导航项配置 - 精简版
 * 子应用声明自己在主应用中的导航位置
 */
interface AppNavItem {
    /** 关联的应用 ID */
    appId: string;
    /** 导航显示名称 */
    name: string;
    /** 导航路径 */
    href: string;
    /** 路径匹配模式（用于高亮当前导航） */
    matchPath?: string;
    /** 排序权重（越小越靠前） */
    order?: number;
    /** 是否可见 */
    visible?: boolean;
    /** 图标组件 */
    icon?: IconComponent;
    /** 图标组件（路径激活状态） */
    iconPath?: IconComponent;
    /** 当前是否选中（运行时状态） */
    current?: boolean;
}
/**
 * 应用生命周期钩子 - 精简版
 * 子应用可以监听的生命周期事件
 */
interface AppLifecycleHooks {
    /** 应用安装时调用 */
    onInstall?: () => Promise<void> | void;
    /** 应用激活时调用 */
    onActivate?: () => Promise<void> | void;
    /** 应用停用时调用 */
    onDeactivate?: () => Promise<void> | void;
    /** 应用卸载时调用 */
    onUninstall?: () => Promise<void> | void;
}
/**
 * 子应用配置 - 精简版
 * 子应用开发时需要提供的配置
 */
interface SubAppConfig {
    /** 应用清单 */
    manifest: AppManifest;
    /** 导航配置（可选） */
    navigation?: AppNavItem;
    /** 生命周期钩子（可选） */
    hooks?: AppLifecycleHooks;
}
/**
 * 创建子应用配置的辅助函数
 * @param config 子应用配置
 * @returns 完整的子应用配置
 */
declare function defineSubApp(config: SubAppConfig): SubAppConfig;

/**
 * @wonderkits/app/wujie
 *
 * Wujie 微前端集成工具
 * 为子应用提供简单易用的 Wujie 环境检测和通信能力
 */
/**
 * Wujie 全局对象类型
 */
interface WujieGlobal {
    props?: Record<string, unknown>;
    bus?: WujieBus;
}
/**
 * Wujie 事件总线类型
 */
interface WujieBus {
    $emit: (event: string, data?: unknown) => void;
    $on: (event: string, callback: (data?: unknown) => void) => void;
    $off: (event: string, callback?: (data?: unknown) => void) => void;
}
/**
 * 声明全局类型
 */
declare global {
    interface Window {
        __POWERED_BY_WUJIE__?: boolean;
        $wujie?: WujieGlobal;
    }
}
/**
 * Wujie 环境信息
 */
interface WujieContext {
    /** 是否在 Wujie 环境中运行 */
    isInWujie: boolean;
    /** 父应用传递的 props */
    props: Record<string, unknown>;
    /** 应用 ID（从 props 中获取） */
    appId?: string;
}
/**
 * Wujie 通信工具
 */
interface WujieCommunication {
    /**
     * 向父应用发送事件
     * @param event 事件名称
     * @param data 事件数据
     */
    emit: (event: string, data?: unknown) => void;
    /**
     * 监听父应用事件
     * @param event 事件名称
     * @param callback 回调函数
     * @returns 取消监听的函数
     */
    on: (event: string, callback: (data?: unknown) => void) => () => void;
    /**
     * 取消监听
     * @param event 事件名称
     * @param callback 可选的回调函数
     */
    off: (event: string, callback?: (data?: unknown) => void) => void;
}
/**
 * useWujie Hook 返回值
 */
interface UseWujieResult {
    /** Wujie 环境信息 */
    context: WujieContext;
    /** 通信工具 */
    bus: WujieCommunication;
    /**
     * 通知父应用路由变化
     * @param path 当前路径
     */
    notifyRouteChange: (path: string) => void;
    /**
     * 监听父应用路由变化
     * @param callback 回调函数
     * @returns 取消监听的函数
     */
    onParentRouteChange: (callback: (path: string) => void) => () => void;
}
/**
 * 获取 Wujie 环境信息（非 Hook 版本）
 * 用于在非 React 组件中获取 Wujie 状态
 */
declare function getWujieContext(): WujieContext;
/**
 * 获取 Wujie 事件总线（非 Hook 版本）
 */
declare function getWujieBus(): WujieCommunication;
/**
 * Wujie 集成 Hook
 *
 * 提供 Wujie 环境检测、通信和路由同步功能
 *
 * @example
 * ```tsx
 * function MyComponent() {
 *   const { context, bus, notifyRouteChange } = useWujie();
 *
 *   // 检查是否在 Wujie 环境
 *   if (!context.isInWujie) {
 *     return <div>独立运行模式</div>;
 *   }
 *
 *   // 发送消息给父应用
 *   const handleClick = () => {
 *     bus.emit('child-message', { type: 'click', data: 'hello' });
 *   };
 *
 *   // 监听父应用消息
 *   useEffect(() => {
 *     return bus.on('parent-message', (data) => {
 *       console.log('收到父应用消息:', data);
 *     });
 *   }, []);
 *
 *   return <button onClick={handleClick}>发送消息</button>;
 * }
 * ```
 */
declare function useWujie(): UseWujieResult;
/**
 * 自动路由同步 Hook
 *
 * 自动监听 React Router 路由变化并通知父应用
 * 需要配合 react-router-dom 使用
 *
 * @example
 * ```tsx
 * import { useLocation } from 'react-router-dom';
 *
 * function App() {
 *   const location = useLocation();
 *   useWujieRouteSync(location.pathname);
 *   return <Routes>...</Routes>;
 * }
 * ```
 */
declare function useWujieRouteSync(currentPath: string): void;
/**
 * 预定义的事件类型
 * 子应用和主应用之间的标准通信协议
 */
declare const WujieEvents: {
    /** 子应用路由变化 */
    readonly SUB_ROUTE_CHANGE: "sub-route-change";
    /** 子应用就绪 */
    readonly SUB_APP_READY: "sub-app-ready";
    /** 子应用错误 */
    readonly SUB_APP_ERROR: "sub-app-error";
    /** 子应用消息 */
    readonly SUB_APP_MESSAGE: "sub-app-message";
    /** 父应用路由变化 */
    readonly PARENT_ROUTE_CHANGE: "parent-route-change";
    /** 父应用消息 */
    readonly PARENT_APP_MESSAGE: "parent-app-message";
};
/**
 * 子应用就绪通知
 * 在子应用初始化完成后调用
 */
declare function notifyAppReady(appId: string, version: string): void;
/**
 * 子应用错误通知
 * 在子应用发生错误时调用
 */
declare function notifyAppError(appId: string, error: string): void;

export { WujieEvents, defineSubApp, getWujieBus, getWujieContext, notifyAppError, notifyAppReady, useWujie, useWujieRouteSync };
export type { AppLifecycleHooks, AppManifest, AppNavItem, IconComponent, SubAppConfig, UseWujieResult, WujieCommunication, WujieContext };