create-lego-one 2.0.12 → 2.0.14

package/template/docs/framework/setup/06-communication-patterns.md

@@ -0,0 +1,451 @@
+# Communication Patterns
+
+**Window Bridge and Channel Bus for Plugin-Host Communication**
+
+---
+
+## Overview
+
+The Lego-One framework uses a **Window Bridge pattern** for plugin-host communication. Plugins access host services and state via global window objects, and communicate through a **Garfish Channel Bus** for pub/sub messaging.
+
+---
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              HOST KERNEL                                │
+│  ┌────────────────────────────────────────────────────────────────────┐ │
+│  │                         CHANNEL BUS (Garfish)                       │ │
+│  │  • publish(channel, message)   • subscribe(channel, callback)    │ │
+│  └────────────────────────────────────────────────────────────────────┘ │
+│                                  │                                     │
+│  ┌────────────────────────────────────────────────────────────────────┐ │
+│  │                      WINDOW BRIDGE (global)                        │ │
+│  │  • __LEGO_KERNEL_STATE__  (read-only state access)                │ │
+│  │  • __LEGO_CHANNEL_BUS__  (pub/sub messaging)                    │ │
+│  └────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                    ═══════════════════════════════════════
+                    PLUGIN BOUNDARY (Window Object)
+                    ═══════════════════════════════════════
+                                  │
+┌─────────────────────────────────────────────────────────────────────────┐
+│                                PLUGIN                                   │
+│  ┌────────────────────────────────────────────────────────────────────┐ │
+│  │                         PLUGIN CODE                                 │ │
+│  │  const state = window.__LEGO_KERNEL_STATE__                      │ │
+│  │  const bus = window.__LEGO_CHANNEL_BUS__                          │ │
+│  │  bus.publish('lego:toast', {...})                                 │ │
+│  │  bus.subscribe('lego:auth', (data) => ...)                       │ │
+│  └────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Window Bridge
+
+### __LEGO_KERNEL_STATE__
+
+**Purpose:** Read-only access to kernel global state
+
+**Available Properties:**
+```typescript
+interface KernelState {
+  user: User | null;                    // Current authenticated user
+  organization: Organization | null;    // Current selected organization
+  token: string | null;                  // Authentication token
+  isAuthenticated: boolean;              // Auth status flag
+  sidebarOpen: boolean;                 // Sidebar toggle state
+  mobileMenuOpen: boolean;              // Mobile menu state
+
+  // Access method to Zustand store
+  useGlobalKernelState: typeof import('@lego/kernel/shared-state').useGlobalKernelState;
+}
+```
+
+**Accessing State:**
+```typescript
+// In plugin component
+function MyPluginComponent() {
+  // Method 1: Direct property access
+  const kernelState = window.__LEGO_KERNEL_STATE__;
+  const user = kernelState?.user;
+  const organization = kernelState?.organization;
+
+  // Method 2: Get latest state from store
+  const latestState = kernelState?.useGlobalKernelState?.getState();
+
+  return (
+    <div>
+      <p>User: {user?.email}</p>
+      <p>Organization: {organization?.name}</p>
+    </div>
+  );
+}
+```
+
+**What You CAN Do:**
+- ✅ Read user info
+- ✅ Read organization info
+- ✅ Check authentication status
+- ✅ Get latest state from store
+
+**What You CANNOT Do:**
+- ❌ Modify kernel state directly
+- ❌ Call kernel actions (use channels instead)
+
+---
+
+### __LEGO_CHANNEL_BUS__
+
+**Purpose:** Pub/sub messaging between plugins and host
+
+**Available Methods:**
+```typescript
+interface ChannelBus {
+  publish: (channel: string, message: any) => void;
+  subscribe: (channel: string, callback: (message: any) => void) => () => void;
+}
+```
+
+**Publishing Messages:**
+```typescript
+// Publish toast notification
+window.__LEGO_CHANNEL_BUS__?.publish('lego:toast', {
+  type: 'success',
+  title: 'Saved!',
+  description: 'Your changes were saved successfully',
+});
+
+// Publish navigation request
+window.__LEGO_CHANNEL_BUS__?.publish('lego:navigation', {
+  path: '/todos/123',
+  replace: false,
+});
+```
+
+**Subscribing to Messages:**
+```typescript
+useEffect(() => {
+  const channelBus = window.__LEGO_CHANNEL_BUS__;
+  if (!channelBus) return;
+
+  // Subscribe to auth changes
+  const unsubscribe = channelBus.subscribe('lego:auth:change', (data) => {
+    console.log('Auth changed:', data);
+
+    if (data.isAuthenticated) {
+      console.log('User logged in:', data.userId);
+      // Refresh plugin data
+    } else {
+      console.log('User logged out');
+      // Clear plugin data
+    }
+  });
+
+  // Cleanup on unmount
+  return () => {
+    unsubscribe();
+  };
+}, []);
+```
+
+---
+
+## Channel Names
+
+### Standard Channels
+
+| Channel | Purpose | Published By |
+|---------|---------|-------------|
+| `lego:toast` | Show notifications | Plugins → Host |
+| `lego:navigation` | Navigate to route | Plugins → Host |
+| `lego:state:update` | Update shared state | Plugins → Host |
+| `lego:plugin:ready` | Plugin initialized | Plugins → Host |
+| `lego:plugin:error` | Plugin error | Plugins → Host |
+| `lego:auth:change` | Auth state changed | Host → All |
+| `lego:organization:change` | Organization changed | Host → All |
+
+### Channel Message Formats
+
+**Toast Channel:**
+```typescript
+{
+  type: 'success' | 'error' | 'info' | 'warning',
+  title: string,
+  description?: string,
+  duration?: number,  // milliseconds
+}
+```
+
+**Navigation Channel:**
+```typescript
+{
+  path: string,
+  replace?: boolean,
+}
+```
+
+**Auth Change Channel:**
+```typescript
+{
+  isAuthenticated: boolean,
+  userId?: string,
+  organizationId?: string,
+}
+```
+
+**Organization Change Channel:**
+```typescript
+{
+  organizationId: string,
+  organizationName: string,
+}
+```
+
+---
+
+## Communication Patterns
+
+### Pattern 1: Plugin → Host (Request Action)
+
+**Use Case:** Plugin wants host to display a toast notification
+
+```typescript
+// In plugin
+function saveTodo() {
+  // After successful save
+  window.__LEGO_CHANNEL_BUS__?.publish('lego:toast', {
+    type: 'success',
+    title: 'Todo Created',
+    description: 'Your todo was created successfully',
+  });
+}
+```
+
+**Host Integration:**
+- Host has `ToastIntegration` component listening to `lego:toast`
+- Automatically displays Shadcn toast when message received
+
+---
+
+### Pattern 2: Host → Plugin (Broadcast State)
+
+**Use Case:** User switches organizations, plugin needs to refresh data
+
+```typescript
+// In plugin
+useEffect(() => {
+  const channelBus = window.__LEGO_CHANNEL_BUS__;
+  if (!channelBus) return;
+
+  const unsubscribe = channelBus.subscribe('lego:organization:change', (data) => {
+    console.log('Organization changed to:', data.organizationName);
+
+    // Refresh plugin data for new organization
+    queryClient.invalidateQueries({ queryKey: ['todos'] });
+  });
+
+  return unsubscribe;
+}, []);
+```
+
+**Host Behavior:**
+- `ChannelProvider` automatically publishes org changes
+- All subscribed plugins receive notification
+
+---
+
+### Pattern 3: Plugin → Plugin (Direct Communication)
+
+**Use Case:** Plugin A needs to notify Plugin B
+
+**Option 1: Via Host (Recommended)**
+```typescript
+// Plugin A publishes
+window.__LEGO_CHANNEL_BUS__?.publish('custom:plugin-a-event', {
+  data: 'Something happened in Plugin A',
+});
+
+// Plugin B subscribes
+useEffect(() => {
+  const unsubscribe = window.__LEGO_CHANNEL_BUS__?.subscribe(
+    'custom:plugin-a-event',
+    (data) => console.log('Received from Plugin A:', data)
+  );
+  return unsubscribe;
+}, []);
+```
+
+**Option 2: Via Custom Channel**
+- Create a custom channel name: `lego:plugins:shared`
+- Both plugins use this channel for communication
+
+---
+
+### Pattern 4: Reading Kernel State
+
+**Use Case:** Plugin needs current organization ID for data fetching
+
+```typescript
+// Create a custom hook
+export function useCurrentOrganization() {
+  const [org, setOrg] = useState(null);
+
+  useEffect(() => {
+    const kernelState = window.__LEGO_KERNEL_STATE__;
+    const state = kernelState?.useGlobalKernelState?.getState();
+    setOrg(state?.organization || null);
+
+    // Subscribe to organization changes
+    const channelBus = window.__LEGO_CHANNEL_BUS__;
+    if (!channelBus) return;
+
+    const unsubscribe = channelBus.subscribe('lego:organization:change', (data) => {
+      const newState = kernelState?.useGlobalKernelState?.getState();
+      setOrg(newState?.organization || null);
+    });
+
+    return unsubscribe;
+  }, []);
+
+  return org;
+}
+
+// Use in component
+function MyPluginComponent() {
+  const organization = useCurrentOrganization();
+  const orgId = organization?.id;
+
+  const { data: todos } = useTodos(orgId);
+  // ...
+}
+```
+
+---
+
+## Type Safety
+
+### Plugin Type Definitions
+
+**File:** `packages/plugins/@lego/plugin-<name>/src/vite-env.d.ts`
+
+```typescript
+declare global {
+  interface Window {
+    __LEGO_KERNEL_STATE__?: {
+      user?: { id: string; email: string; name?: string } | null;
+      organization?: { id: string; name: string; slug: string } | null;
+      isAuthenticated: boolean;
+      useGlobalKernelState?: any;
+    };
+    __LEGO_CHANNEL_BUS__?: {
+      publish: (channel: string, message: any) => void;
+      subscribe: (channel: string, callback: (data: any) => void) => () => void;
+    };
+  }
+}
+
+export {};
+```
+
+---
+
+## Best Practices
+
+### DO ✅
+
+1. **Use window bridge** for all host communication
+2. **Subscribe to auth/org changes** to refresh data
+3. **Publish toast notifications** for user feedback
+4. **Read kernel state** via `__LEGO_KERNEL_STATE__`
+5. **Clean up subscriptions** in useEffect returns
+6. **Type window bridge** in vite-env.d.ts
+
+### DON'T ❌
+
+1. **Don't import from host** - Use window bridge instead
+2. **Don't modify kernel state** - It's read-only
+3. **Don't forget cleanup** - Always return unsubscribe function
+4. **Don't create circular dependencies** - Host → Plugin is OK, Plugin → Host via channels
+5. **Don't spam channels** - Use appropriate message frequency
+
+---
+
+## Complete Example: Plugin with Channel Integration
+
+```typescript
+// packages/plugins/@lego/plugin-todo/src/hooks/useChannelIntegration.ts
+import { useEffect } from 'react';
+
+export function useChannelIntegration() {
+  useEffect(() => {
+    const channelBus = window.__LEGO_CHANNEL_BUS__;
+    const kernelState = window.__LEGO_KERNEL_STATE__;
+
+    if (!channelBus || !kernelState) return;
+
+    // Subscribe to auth changes
+    const unsubAuth = channelBus.subscribe('lego:auth:change', (data) => {
+      if (data.isAuthenticated) {
+        console.log('[Todo Plugin] User logged in, loading todos');
+      } else {
+        console.log('[Todo Plugin] User logged out, clearing todos');
+      }
+    });
+
+    // Subscribe to organization changes
+    const unsubOrg = channelBus.subscribe('lego:organization:change', (data) => {
+      console.log('[Todo Plugin] Organization changed:', data.organizationName);
+      // Refresh todos for new organization
+    });
+
+    // Notify host that plugin is ready
+    channelBus.publish('lego:plugin:ready', {
+      pluginName: '@lego/plugin-todo',
+      version: '1.0.0',
+    });
+
+    // Cleanup
+    return () => {
+      unsubAuth();
+      unsubOrg();
+    };
+  }, []);
+}
+```
+
+---
+
+## Channel Hooks (Host Side)
+
+For host components, use the channel hooks:
+
+```typescript
+import {
+  useChannel,
+  usePublish,
+  useToastChannel,
+  useNavigationChannel,
+} from '@lego/kernel/channels';
+
+// Subscribe to any channel
+useChannel(ChannelName.AUTH_CHANGE, (data) => {
+  console.log('Auth changed:', data);
+});
+
+// Publish to toast channel
+const publishToast = useToastChannel();
+publishToast({ type: 'success', title: 'Done!' });
+
+// Publish to any channel
+const publish = usePublish();
+publish({ channel: ChannelName.NAVIGATION, data: {...} });
+```
+
+---
+
+**Next:** Read [`07-plugin-development.md`](./07-plugin-development.md) for complete plugin creation guide.