@linyjs/plugin-docs 0.0.13

package/examples/hello-world/node_modules/@linyjs/client-module-interface/src/comparison-example.tsx

@@ -0,0 +1,229 @@
+/**
+ * Hook 使用对比示例
+ * 
+ * 展示 useContext 方式 vs useClient* Hook 方式的对比
+ */
+
+import { useContext } from 'react'
+import type { IComponent } from '@linyjs/client-module-interface'
+import { ClientComponentsContext, ClientServicesContext, ClientHooksContext } from '@linyjs/client-module-interface'
+import { useClientComponent, useClientHook, useClientService } from '../src/hooks.js'
+
+// ==================== 方式1: 传统 useContext 方式 ====================
+
+/**
+ * 使用 useContext 获取组件（旧方式）
+ */
+function OldWayComponent() {
+  const components = useContext(ClientComponentsContext)
+  
+  // 需要手动从 Context 中提取组件
+  const Avatar = components['userModule.userComponents.Avatar'] as IComponent<{ userId: string }> | undefined
+  const Button = components['uiModule.uiComponents.Button'] as IComponent<any> | undefined
+  
+  return (
+    <div>
+      <h2>旧方式 - useContext</h2>
+      {Avatar && <Avatar userId="123" />}
+      {Button && <Button text="点击" variant="primary" onClick={() => {}} />}
+    </div>
+  )
+}
+
+/**
+ * 使用 useContext 获取服务（旧方式）
+ */
+interface IUserService {
+  getUser(id: string): Promise<{ id: string; name: string }>
+}
+
+function OldWayService() {
+  const services = useContext(ClientServicesContext)
+  
+  // 需要手动类型断言
+  const userService = services['userModule.userService'] as IUserService | undefined
+  
+  const handleLoad = async () => {
+    if (userService) {
+      const user = await userService.getUser('123')
+      console.log(user)
+    }
+  }
+  
+  return <button onClick={handleLoad}>加载用户</button>
+}
+
+// ==================== 方式2: 新 Hook 方式 ====================
+
+/**
+ * 使用 useClientComponent 获取组件（新方式）
+ */
+function NewWayComponent() {
+  // 更简洁的 API，自动处理类型
+  const Avatar = useClientComponent<{ userId: string }>('userModule.userComponents.Avatar')
+  const Button = useClientComponent('uiModule.uiComponents.Button')
+  
+  return (
+    <div>
+      <h2>新方式 - useClientComponent</h2>
+      {Avatar && <Avatar userId="123" />}
+      {Button && <Button text="点击" variant="primary" onClick={() => {}} />}
+    </div>
+  )
+}
+
+/**
+ * 使用 useClientService 获取服务（新方式）
+ */
+function NewWayService() {
+  // 泛型提供类型安全，无需手动断言
+  const userService = useClientService<IUserService>('userModule.userService')
+  
+  const handleLoad = async () => {
+    if (userService) {
+      const user = await userService.getUser('123')
+      console.log(user)
+    }
+  }
+  
+  return <button onClick={handleLoad}>加载用户</button>
+}
+
+/**
+ * 使用 useClientHook 获取 Hook（新方式）
+ */
+function NewWayHook() {
+  // 定义 Hook 类型
+  type UseAuthHook = () => { isAuthenticated: boolean; user: any }
+  
+  // 使用 Hook
+  const useAuth = useClientHook<UseAuthHook>('authModule.authHooks.useAuth')
+  const authState = useAuth ? useAuth() : null
+  
+  return (
+    <div>
+      <h2>新方式 - useClientHook</h2>
+      <p>认证状态: {authState?.isAuthenticated ? '已登录' : '未登录'}</p>
+    </div>
+  )
+}
+
+// ==================== 对比总结 ====================
+
+/**
+ * 两种方式对比
+ */
+export function ComparisonExample() {
+  return (
+    <div>
+      <h1>Hook 使用方式对比</h1>
+      
+      <section>
+        <h2>❌ 旧方式 - useContext</h2>
+        <pre>{`
+// 需要导入 Context
+import { useContext } from 'react'
+import { ClientComponentsContext } from '@linyjs/client-module-interface'
+
+function MyComponent() {
+  // 1. 获取整个 Context
+  const components = useContext(ClientComponentsContext)
+  
+  // 2. 手动提取需要的组件
+  const Avatar = components['userModule.userComponents.Avatar']
+  
+  // 3. 需要手动类型断言
+  const TypedAvatar = Avatar as IComponent<Props>
+  
+  return <TypedAvatar userId="123" />
+}
+        `}</pre>
+        
+        <strong>缺点：</strong>
+        <ul>
+          <li>需要手动从 Context 中提取资源</li>
+          <li>需要手动类型断言</li>
+          <li>代码冗长</li>
+          <li>容易出错</li>
+        </ul>
+      </section>
+      
+      <section>
+        <h2>✅ 新方式 - useClient* Hooks</h2>
+        <pre>{`
+// 直接导入 Hook
+import { useClientComponent } from '@linyjs/client-module-interface'
+
+function MyComponent() {
+  // 一行代码搞定，类型安全
+  const Avatar = useClientComponent<Props>('userModule.userComponents.Avatar')
+  
+  return <Avatar userId="123" />
+}
+        `}</pre>
+        
+        <strong>优点：</strong>
+        <ul>
+          <li>API 简洁直观</li>
+          <li>自动类型推断（通过泛型）</li>
+          <li>代码更短</li>
+          <li>更易维护</li>
+          <li>统一的错误处理</li>
+        </ul>
+      </section>
+      
+      <section>
+        <h2>📊 代码对比</h2>
+        <table border={1} cellPadding={8}>
+          <thead>
+            <tr>
+              <th>特性</th>
+              <th>useContext</th>
+              <th>useClient* Hooks</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>代码行数</td>
+              <td>~5 行</td>
+              <td>~1 行</td>
+            </tr>
+            <tr>
+              <td>类型安全</td>
+              <td>需要手动断言</td>
+              <td>自动推断</td>
+            </tr>
+            <tr>
+              <td>错误处理</td>
+              <td>需要手动检查</td>
+              <td>内置警告</td>
+            </tr>
+            <tr>
+              <td>可读性</td>
+              <td>一般</td>
+              <td>优秀</td>
+            </tr>
+            <tr>
+              <td>学习成本</td>
+              <td>需要了解 Context</td>
+              <td>简单直观</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+    </div>
+  )
+}
+
+// ==================== 推荐使用 ====================
+
+/**
+ * 推荐始终使用新的 Hook 方式
+ * 
+ * 原因：
+ * 1. 更简洁的 API
+ * 2. 更好的类型安全
+ * 3. 统一的错误处理
+ * 4. 更符合 React Hooks 的使用习惯
+ * 5. 更容易维护和重构
+ */

package/examples/hello-world/node_modules/@linyjs/client-module-interface/src/di.ts

@@ -0,0 +1,127 @@
+/**
+ * 基础依赖注入类型定义
+ * 详见 [依赖注入机制设计](../../spec/依赖注入机制设计.md)
+ */
+
+/** 所有服务的基础类型 */
+export type IService = object
+
+/** 服务类构造器类型 */
+export interface IServiceConstructor<S extends IService> {
+  new (...args: any[]): S
+}
+
+/** 服务工厂函数类型 */
+export type IServiceFactory<S extends IService> = (...args: any[]) => S
+
+/** 服务实现类型（类或工厂函数） */
+export type IServiceMaker<S extends IService> =
+  | IServiceConstructor<S>
+  | IServiceFactory<S>
+
+/** 服务元数据基础类型 */
+export type IServiceMetadata = Record<string, any>
+
+/** 服务定义 */
+export interface IServiceDef<
+  S extends IService = IService,
+  M extends IServiceMetadata = IServiceMetadata
+> {
+  /** 服务唯一标识（模块内唯一） */
+  serviceTag: string
+  /** 服务实现，可以是类或工厂函数 */
+  serviceImpl: IServiceMaker<S>
+  /** 依赖的其他服务列表，支持 'serviceTag' 或 'moduleName.serviceTag' 格式 */
+  dependencies?: string[]
+  /** 元数据 */
+  meta?: M
+}
+
+/** 模块定义 */
+export interface IModule {
+  /** 模块名称 */
+  name: string
+  /** 依赖的其他模块名称 */
+  moduleDependencies?: string[]
+  /** 服务定义列表 */
+  serviceDefs: IServiceDef[]
+}
+
+// ==================== 模块状态与事件 ====================
+
+/** 模块状态枚举 */
+export enum ModuleState {
+  Unloaded = 'unloaded',
+  Loading = 'loading',
+  Loaded = 'loaded',
+  Error = 'error',
+  Unloading = 'unloading',
+}
+
+/** 模块事件类型 */
+export type ModuleEventType =
+  | 'module_loaded'
+  | 'module_unloaded'
+  | 'module_error'
+  | 'module_state_changed'
+
+/** 模块事件 */
+export interface IModuleEvent {
+  type: ModuleEventType
+  moduleName: string
+  module?: ILoadedModule
+  error?: Error
+  timestamp: number
+}
+
+/** 已加载模块的运行时表示 */
+export interface ILoadedModule {
+  /** 模块名称 */
+  name: string
+  /** 模块状态 */
+  state: ModuleState
+  /** 服务实例映射表 */
+  services: Map<string, IService>
+  /** 源模块定义 */
+  sourceModule?: IModule
+  /** 加载时间戳 */
+  loadedAt?: number
+}
+
+/** 模块生命周期处理器 */
+export interface IModuleHandler {
+  /** 模块加载完成后执行 */
+  onModuleLoaded?(module: ILoadedModule): void | Promise<void>
+  /** 模块卸载后执行 */
+  onModuleUnloaded?(module: ILoadedModule): void | Promise<void>
+  /** 模块加载错误时执行 */
+  onModuleError?(moduleName: string, error: Error): void | Promise<void>
+}
+
+/** 模块容器接口 */
+export interface IModuleContainer {
+  /** 设置模块生命周期处理器 */
+  setModuleHandler(handler: IModuleHandler): void
+
+  /** 加载模块 */
+  loadModules(modules: IModule[]): Promise<void>
+
+  /** 卸载模块 */
+  unloadModule(moduleName: string): Promise<void>
+  /** 重新加载模块 */
+  reloadModule(moduleName: string, newModule?: IModule): Promise<void>
+
+  /** 检查模块是否已加载 */
+  isModuleLoaded(moduleName: string): boolean
+  /** 获取已加载模块 */
+  getLoadedModule(moduleName: string): ILoadedModule | undefined
+  /** 获取模块状态 */
+  getModuleState(moduleName: string): ModuleState
+  /** 获取服务实例 */
+  getService<T>(moduleName: string, serviceTag: string): T
+
+  /** 监听模块事件 */
+  on(event: ModuleEventType, listener: (event: IModuleEvent) => void): void
+  /** 取消监听模块事件 */
+  off(event: ModuleEventType, listener: (event: IModuleEvent) => void): void
+}

package/examples/hello-world/node_modules/@linyjs/client-module-interface/src/domain.ts

@@ -0,0 +1,52 @@
+/**
+ * 前端领域类型
+ * 详见 [前端模块接口设计](../../spec/前端模块接口设计.md)
+ */
+
+import type { ComponentType } from 'react'
+
+/** React 组件类型 */
+export type IComponent<P = any> = ComponentType<P>
+
+/** 路由守卫 */
+export interface IRouteGuard {
+  /** 进入前校验，返回 false 阻止进入，返回 string 重定向到该路径 */
+  canEnter?(params: { location: Location }): boolean | string | Promise<boolean | string>
+  /** 离开前校验 */
+  canLeave?(params: { location: Location }): boolean | Promise<boolean>
+}
+
+/** 路由 loader — 页面数据预加载 */
+export type IRouteLoader = (params: {
+  request?: Request
+  params: Record<string, string>
+  location: Location
+}) => Promise<any> | any
+
+/** 页面路由 */
+export interface IRoute {
+  path: string
+  component: IComponent
+  key?: string
+  children?: IRoute[]
+  guard?: IRouteGuard
+  loader?: IRouteLoader
+  meta?: {
+    title?: string
+    requiresAuth?: boolean
+    [key: string]: any
+  }
+}
+
+/**
+ * 全局注册标识
+ *
+ * Handler 在 onModuleLoaded 中将组件/Hook/服务注册到全局注册表时，
+ * 使用 "moduleName.serviceTag.name" 格式作为 key，确保跨模块唯一。
+ *
+ * 示例：
+ *  - 'userModule.userComponents.Avatar'  → userModule 模块中 userComponents 服务的 Avatar 组件
+ *  - 'authModule.authHooks.useAuth'       → authModule 模块中 authHooks 服务的 useAuth hook
+ *  - 'userModule.userService'             → userModule 模块中 userService 服务
+ */
+export type RegistryKey = string  // 格式："{moduleName}.{serviceTag}.{name}"

package/examples/hello-world/node_modules/@linyjs/client-module-interface/src/hooks-example.tsx

@@ -0,0 +1,275 @@
+/**
+ * 资源消费 Hooks 使用示例
+ * 
+ * 本文件展示如何在模块中使用 useClientComponent、useClientHook、useClientService
+ */
+
+import { useContext } from 'react'
+import type { IModule, IRouteService, IRoute, IComponentListService, IHooksService, INormalServiceDef } from '@linyjs/client-module-interface'
+import { useClientComponent, useClientHook, useClientService } from '@linyjs/client-module-interface'
+
+// ==================== 示例1: 在组件中使用共享组件 ====================
+
+/**
+ * 用户资料页 - 展示如何使用跨模块的共享组件
+ */
+function UserProfilePage() {
+  // 方式1: 跨模块引用（显式指定 moduleName）
+  const Avatar = useClientComponent('userModule.userComponents.Avatar')
+  const Button = useClientComponent('uiModule.uiComponents.Button')
+  
+  // 方式2: 模块内引用（省略 moduleName，需要当前模块上下文支持）
+  // const ProfileCard = useClientComponent('userComponents.ProfileCard')
+  
+  return (
+    <div>
+      <h1>用户资料</h1>
+      
+      {/* 使用从 userModule 引用的 Avatar 组件 */}
+      {Avatar && <Avatar userId="123" size="large" />}
+      
+      {/* 使用从 uiModule 引用的 Button 组件 */}
+      {Button && (
+        <Button 
+          text="编辑资料" 
+          variant="primary"
+          onClick={() => console.log('Edit clicked')}
+        />
+      )}
+    </div>
+  )
+}
+
+// ==================== 示例2: 在组件中使用共享 Hook ====================
+
+/**
+ * 认证状态显示组件 - 展示如何使用跨模块的 Hook
+ */
+function AuthStatusDisplay() {
+  // 跨模块引用 authModule 的 useAuth Hook
+  type UseAuthHook = () => { isAuthenticated: boolean; user: { id: string; name: string } | null }
+  const useAuth = useClientHook<UseAuthHook>('authModule.authHooks.useAuth')
+  
+  // 如果 Hook 存在，调用它获取认证状态
+  const authState = useAuth ? useAuth() : null
+  
+  return (
+    <div>
+      {authState?.isAuthenticated ? (
+        <p>✅ 已登录: {authState.user?.name}</p>
+      ) : (
+        <p>❌ 未登录</p>
+      )}
+    </div>
+  )
+}
+
+// ==================== 示例3: 在组件中使用服务 ====================
+
+interface IUserService {
+  getUser(id: string): Promise<{ id: string; name: string; email: string }>
+  updateUser(id: string, data: Partial<{ name: string; email: string }>): Promise<void>
+}
+
+/**
+ * 用户管理组件 - 展示如何使用跨模块的服务
+ */
+function UserManagement() {
+  // 跨模块引用 userModule 的 userService
+  const userService = useClientService<IUserService>('userModule.userService')
+  
+  const handleLoadUser = async () => {
+    if (userService) {
+      try {
+        const user = await userService.getUser('123')
+        console.log('User loaded:', user)
+      } catch (error) {
+        console.error('Failed to load user:', error)
+      }
+    }
+  }
+  
+  return (
+    <div>
+      <h2>用户管理</h2>
+      <button onClick={handleLoadUser}>加载用户</button>
+    </div>
+  )
+}
+
+// ==================== 示例4: 混合使用多种资源 ====================
+
+/**
+ * 综合示例 - 同时使用组件、Hook 和服务
+ */
+function ComprehensiveExample() {
+  // 引用组件
+  const Avatar = useClientComponent('userModule.userComponents.Avatar')
+  const Card = useClientComponent('uiModule.uiComponents.Card')
+  
+  // 引用 Hook
+  type UseAuthHook = () => { isAuthenticated: boolean; user: { id: string; name: string } | null }
+  const useAuth = useClientHook<UseAuthHook>('authModule.authHooks.useAuth')
+  const authState = useAuth ? useAuth() : null
+  
+  // 引用服务
+  const userService = useClientService<IUserService>('userModule.userService')
+  
+  const handleUpdateProfile = async () => {
+    if (userService && authState?.user) {
+      await userService.updateUser(authState.user.id, { name: 'New Name' })
+    }
+  }
+  
+  return (
+    <div>
+      {Card && (
+        <Card title="用户信息">
+          {Avatar && authState?.user && (
+            <Avatar userId={authState.user.id} size="medium" />
+          )}
+          
+          <p>用户名: {authState?.user?.name ?? '未知'}</p>
+          
+          <button onClick={handleUpdateProfile}>更新资料</button>
+        </Card>
+      )}
+    </div>
+  )
+}
+
+// ==================== 示例5: 定义提供资源的模块 ====================
+
+/**
+ * 示例 Hook - 在实际项目中应该由 authModule 提供
+ */
+export function useAuth() {
+  // 这里只是示例，实际应该从 Context 或状态管理中获取
+  return {
+    isAuthenticated: true,
+    user: { id: '123', name: '张三' },
+  }
+}
+
+/**
+ * UI 组件服务 - 提供可复用的 UI 组件
+ */
+class UIComponentService implements IComponentListService {
+  components = {
+    Button: ({ text, variant, onClick }: any) => (
+      <button 
+        onClick={onClick}
+        style={{ 
+          padding: '8px 16px',
+          backgroundColor: variant === 'primary' ? '#007bff' : '#6c757d',
+          color: 'white',
+          border: 'none',
+          borderRadius: '4px',
+          cursor: 'pointer'
+        }}
+      >
+        {text}
+      </button>
+    ),
+    Card: ({ title, children }: any) => (
+      <div style={{ border: '1px solid #ddd', borderRadius: '8px', padding: '16px' }}>
+        {title && <h3>{title}</h3>}
+        {children}
+      </div>
+    ),
+  }
+}
+
+const uiComponentsDef = {
+  serviceTag: 'uiComponents',
+  serviceImpl: UIComponentService,
+  meta: { usageType: 'component' as const },
+}
+
+/**
+ * Hooks 服务 - 提供可复用的 Hooks
+ */
+class AuthHooksService implements IHooksService {
+  hooks = {
+    useAuth,
+  }
+}
+
+const authHooksDef = {
+  serviceTag: 'authHooks',
+  serviceImpl: AuthHooksService,
+  meta: { usageType: 'hook' as const },
+}
+
+/**
+ * 普通服务 - 提供业务逻辑
+ */
+class UserServiceImpl implements IUserService {
+  async getUser(id: string) {
+    return { id, name: '张三', email: 'zhangsan@example.com' }
+  }
+  
+  async updateUser(id: string, data: Partial<{ name: string; email: string }>) {
+    console.log('Updating user:', id, data)
+  }
+}
+
+const userServiceDef: INormalServiceDef = {
+  serviceTag: 'userService',
+  serviceImpl: UserServiceImpl,
+  meta: { usageType: 'normal_service' },
+}
+
+/**
+ * 用户模块 - 提供组件、Hook 和服务
+ */
+export const userModule: IModule = {
+  name: 'userModule',
+  serviceDefs: [
+    // 这里可以添加路由服务等
+  ],
+}
+
+/**
+ * UI 模块 - 提供共享 UI 组件
+ */
+export const uiModule: IModule = {
+  name: 'uiModule',
+  serviceDefs: [uiComponentsDef],
+}
+
+/**
+ * 认证模块 - 提供认证相关的 Hook
+ */
+export const authModule: IModule = {
+  name: 'authModule',
+  serviceDefs: [authHooksDef, userServiceDef],
+}
+
+// ==================== 使用建议 ====================
+
+/**
+ * 最佳实践：
+ * 
+ * 1. 模块内引用 vs 跨模块引用
+ *    - 同一模块内的资源可以使用短路径（省略 moduleName）
+ *    - 跨模块引用必须使用完整路径（moduleName.serviceTag.name）
+ * 
+ * 2. 类型安全
+ *    - 使用泛型参数为服务和 Hook 提供类型约束
+ *    - 例如：useClientService<IUserService>('...')
+ * 
+ * 3. 空值检查
+ *    - 所有 Hook 都可能返回 undefined（资源未找到时）
+ *    - 使用前应该进行空值检查
+ * 
+ * 4. 命名规范
+ *    - 组件：PascalCase，如 Avatar、UserProfile
+ *    - Hook：camelCase 且以 use 开头，如 useAuth、useUser
+ *    - 服务：camelCase，如 userService、apiService
+ * 
+ * 5. RegistryKey 格式
+ *    - 组件：moduleName.serviceTag.componentName
+ *    - Hook：moduleName.serviceTag.hookName
+ *    - 服务：moduleName.serviceTag
+ */