create-lego-one 2.0.12 → 2.0.14

package/template/docs/framework/setup/05-plugin-system.md

@@ -0,0 +1,620 @@
+# Plugin System
+
+**Plugin Architecture, Loading, and Slot Injection**
+
+---
+
+## Overview
+
+The Lego-One plugin system enables modular feature development through Garfish micro-frontends. Plugins register slots, inject UI, and communicate with the host via channels.
+
+---
+
+## Plugin Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                           HOST KERNEL                                │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │                       PLUGIN MANAGER                            │ │
+│  │  • Plugin Loader (dynamic loading)                             │ │
+│  │  • Plugin Store (state management)                            │ │
+│  │  • Slot Registry (UI injection)                               │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│                                │                                    │
+│                    ═══════════════════════════════                    │
+│                    GARFISH PLUGIN BOUNDARY                         │
+│                    ═══════════════════════════════                    │
+│                                │                                    │
+│  ┌──────────────┬──────────────┬──────────────┬──────────────┐    │
+│  │   Plugin 1   │   Plugin 2   │   Plugin 3   │   Plugin N   │    │
+│  │  Dashboard   │     Todo     │   Custom     │   Future     │    │
+│  ├──────────────┼──────────────┼──────────────┼──────────────┤    │
+│  │ plugin.config│ plugin.config│ plugin.config│ plugin.config│    │
+│  │ Slot: nav    │ Slot: nav    │ Slot: widgets│ Slot: ???    │    │
+│  │ Route: /dash │ Route: /todos│ Route: /custom│ Route: ???   │    │
+│  └──────────────┴──────────────┴──────────────┴──────────────┘    │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Plugin Structure
+
+### Standard Plugin File Layout
+
+```
+packages/plugins/@lego/plugin-<name>/
+├── package.json           # Plugin package configuration
+├── tsconfig.json          # TypeScript configuration
+├── modern.config.ts       # Modern.js + Garfish config
+├── tailwind.config.ts     # Tailwind CSS configuration
+├── postcss.config.mjs     # PostCSS configuration
+│
+└── src/
+    ├── global.css         # Global plugin styles
+    ├── plugin.config.ts   # Plugin manifest & configuration
+    ├── plugin.ts          # Garfish entry point
+    ├── App.tsx            # Root component with routing
+    ├── types.ts           # TypeScript types
+    ├── schemas.ts         # Zod validation schemas
+    │
+    ├── pages/             # Page components
+    │   └── <Plugin>Page.tsx
+    │
+    ├── components/        # React components
+    │   └── slots/         # Slot injection components
+    │       └── SidebarWidget.tsx
+    │
+    ├── hooks/             # Custom React hooks
+    │   ├── usePocketBase.ts
+    │   └── use<Feature>Data.ts
+    │
+    └── vite-env.d.ts      # Vite type declarations
+```
+
+---
+
+## Plugin Configuration
+
+### plugin.config.ts
+
+**Location:** `packages/plugins/@lego/plugin-<name>/src/plugin.config.ts`
+
+This file defines the plugin's metadata, slots, routes, and settings.
+
+```typescript
+import type { PluginConfig } from '@lego/kernel/plugins';
+import { SidebarWidget } from './components/slots/SidebarWidget';
+import { DashboardPage } from './pages/DashboardPage';
+
+export const pluginConfig: PluginConfig = {
+  // ==================== MANIFEST ====================
+  manifest: {
+    name: '@lego/plugin-dashboard',
+    version: '1.0.0',
+    displayName: 'Dashboard',
+    description: 'Organization statistics and activity feed',
+    author: 'Lego-One',
+    permissions: ['dashboard.read'],
+  },
+
+  // ==================== ENABLED STATE ====================
+  enabled: true,
+
+  // ==================== SLOT INJECTIONS ====================
+  slots: [
+    {
+      slot: 'sidebar:nav',
+      component: () => import('./components/slots/SidebarWidget').then(m => m.default),
+      order: 100,
+      props: {},
+      condition: undefined,
+    },
+    {
+      slot: 'dashboard:widgets',
+      component: () => import('./components/StatsCard').then(m => m.default),
+      order: 50,
+    },
+  ],
+
+  // ==================== ROUTES ====================
+  routes: [
+    {
+      path: '/dashboard',
+      component: () => import('./pages/DashboardPage').then(m => m.default),
+      protected: true,
+      permissions: ['dashboard.read'],
+    },
+  ],
+
+  // ==================== SETTINGS ====================
+  settings: [
+    {
+      key: 'showActivityFeed',
+      type: 'boolean',
+      label: 'Show Activity Feed',
+      description: 'Display recent activity on dashboard',
+      defaultValue: true,
+    },
+    {
+      key: 'refreshInterval',
+      type: 'number',
+      label: 'Refresh Interval (seconds)',
+      description: 'How often to refresh dashboard data',
+      defaultValue: 30,
+    },
+  ],
+};
+```
+
+---
+
+## Slot System
+
+### Available Slots
+
+| Slot Name | Location | Purpose | Example Use |
+|-----------|----------|---------|-------------|
+| `sidebar:top` | Top of sidebar | Logo, branding | Plugin logo |
+| `sidebar:nav` | Main navigation area | Navigation links | Plugin nav link |
+| `sidebar:bottom` | Bottom of sidebar | Logout, settings | Settings link |
+| `topbar:left` | Left side of header | Breadcrumbs, back button | Parent nav |
+| `topbar:center` | Center of header | Page title, search | Search bar |
+| `topbar:right` | Right side of header | Notifications, user menu | Notification icon |
+| `dashboard:widgets` | Dashboard page | Statistics, activity | Stats cards |
+| `settings:menu` | Settings page | Settings sections | Plugin settings |
+
+### Slot Injection Example
+
+**File:** `packages/plugins/@lego/plugin-dashboard/src/components/slots/SidebarWidget.tsx`
+
+```typescript
+import { NavLink } from '@modern-js/runtime/router';
+import { LayoutDashboard } from 'lucide-react';
+
+export function SidebarWidget() {
+  return (
+    <NavLink
+      to="/dashboard"
+      className={({ isActive }) =>
+        `flex items-center gap-3 rounded-lg px-3 py-2 text-sm font-medium transition-colors ${
+          isActive
+            ? 'bg-primary text-primary-foreground'
+            : 'text-muted-foreground hover:bg-muted hover:text-foreground'
+        }`
+      }
+    >
+      <LayoutDashboard className="h-5 w-5" />
+      <span>Dashboard</span>
+    </NavLink>
+  );
+}
+
+export default SidebarWidget;
+```
+
+---
+
+## Plugin Loading
+
+### Dev Mode (Separate Servers)
+
+```bash
+# Each plugin runs independently
+pnpm run dev:all
+
+# Results in:
+# Host:     http://localhost:8080
+# Dashboard: http://localhost:3001
+# Todo:     http://localhost:3002
+```
+
+**modern.runtime.ts (dev entries):**
+```typescript
+{
+  name: '@lego/plugin-dashboard',
+  entry: 'http://localhost:3001',  // Dev: separate server
+  activeWhen: '/dashboard',
+}
+```
+
+### Production Mode (Bundled)
+
+```bash
+pnpm run build
+
+# All plugins bundled into host/dist/
+```
+
+**modern.runtime.ts (prod entries):**
+```typescript
+{
+  name: '@lego/plugin-dashboard',
+  entry: () => import('@lego/plugin-dashboard'),  // Prod: dynamic import
+  activeWhen: '/dashboard',
+}
+```
+
+---
+
+## Plugin Enable/Disable
+
+### Via Config File
+
+**File:** `host/src/saas.config.ts`
+
+```typescript
+export const saasConfig = {
+  plugins: [
+    { name: '@lego/plugin-dashboard', enabled: true },
+    { name: '@lego/plugin-todo', enabled: false },  // Disabled
+  ],
+};
+```
+
+### Via Plugin Store (Runtime)
+
+```typescript
+import { usePluginStore } from '@lego/kernel/plugins';
+
+function PluginManager() {
+  const { plugins, enablePlugin, disablePlugin } = usePluginStore();
+
+  return (
+    <div>
+      {Object.values(plugins).map((plugin) => (
+        <div key={plugin.id}>
+          <span>{plugin.manifest.displayName}</span>
+          <button
+            onClick={() => plugin.enabled
+              ? disablePlugin(plugin.id)
+              : enablePlugin(plugin.id)
+            }
+          >
+            {plugin.enabled ? 'Disable' : 'Enable'}
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## Plugin Routes
+
+### Route Registration
+
+Routes are registered in `plugin.config.ts` and automatically loaded by Garfish.
+
+```typescript
+routes: [
+  {
+    path: '/my-plugin',
+    component: () => import('./pages/MyPluginPage').then(m => m.default),
+    protected: true,           // Requires authentication
+    permissions: ['plugin.read'], // Requires specific permission
+  },
+]
+```
+
+### Protected Routes
+
+Routes with `protected: true` will redirect unauthenticated users to sign-in.
+
+### Permission-Gated Routes
+
+Routes with `permissions` require the user to have the specified permissions.
+
+**Host handles this automatically** - plugins just declare requirements.
+
+---
+
+## Plugin Communication
+
+### Using Channel Bus
+
+**File:** `packages/plugins/@lego/plugin-todo/src/hooks/useToast.ts`
+
+```typescript
+export function useNotifySuccess() {
+  return (title: string, description?: string) => {
+    // Publish to channel bus
+    window.__LEGO_CHANNEL_BUS__?.publish('lego:toast', {
+      type: 'success',
+      title,
+      description,
+    });
+  };
+}
+
+// Usage
+const notifySuccess = useNotifySuccess();
+notifySuccess('Todo created', 'Your todo was created successfully');
+```
+
+### Reading Kernel State
+
+**File:** `packages/plugins/@lego/plugin-todo/src/hooks/useOrganization.ts`
+
+```typescript
+export function useCurrentOrganization() {
+  const kernelState = window.__LEGO_KERNEL_STATE__?.useGlobalKernelState?.getState();
+
+  return kernelState?.organization || null;
+}
+
+// Usage
+const organization = useCurrentOrganization();
+const orgId = organization?.id;
+```
+
+### Subscribing to Events
+
+```typescript
+useEffect(() => {
+  const channelBus = window.__LEGO_CHANNEL_BUS__;
+  if (!channelBus) return;
+
+  // Listen for auth changes
+  const unsubscribe = channelBus.subscribe('lego:auth:change', (data) => {
+    console.log('Auth changed:', data);
+    if (data.isAuthenticated) {
+      // Refresh data
+    } else {
+      // Clear data
+    }
+  });
+
+  return unsubscribe;
+}, []);
+```
+
+---
+
+## Plugin Settings
+
+### Defining Settings
+
+**In plugin.config.ts:**
+```typescript
+settings: [
+  {
+    key: 'featureEnabled',
+    type: 'boolean',
+    label: 'Enable Feature',
+    defaultValue: true,
+  },
+  {
+    key: 'apiKey',
+    type: 'string',
+    label: 'API Key',
+    description: 'External service API key',
+  },
+  {
+    key: 'refreshRate',
+    type: 'select',
+    label: 'Refresh Rate',
+    options: [
+      { label: 'Slow (60s)', value: '60' },
+      { label: 'Fast (10s)', value: '10' },
+    ],
+    defaultValue: '30',
+  },
+]
+```
+
+### Reading Settings
+
+Settings are stored in the plugin store and can be accessed via the store.
+
+```typescript
+import { usePluginStore } from '@lego/kernel/plugins';
+
+function MyPluginComponent() {
+  const pluginState = usePluginStore((state) => state.plugins['@lego/plugin-my-plugin']);
+
+  const settings = pluginState?.settings || {};
+
+  return (
+    <div>
+      <p>Feature Enabled: {settings.featureEnabled}</p>
+      <p>Refresh Rate: {settings.refreshRate}s</p>
+    </div>
+  );
+}
+```
+
+---
+
+## Creating a New Plugin
+
+### Quick Method (CLI)
+
+```bash
+pnpm run create-plugin my-new-plugin
+```
+
+### Manual Method
+
+1. **Create directory:**
+```bash
+mkdir -p packages/plugins/@lego/plugin-my-new-plugin
+cd packages/plugins/@lego/plugin-my-new-plugin
+```
+
+2. **Create package.json**
+3. **Create modern.config.ts**
+4. **Create src/plugin.config.ts**
+5. **Create src/plugin.ts**
+6. **Create src/App.tsx**
+7. **Create src/pages/MyPluginPage.tsx**
+8. **Create src/components/slots/SidebarWidget.tsx**
+
+See [`07-plugin-development.md`](./07-plugin-development.md) for complete step-by-step guide.
+
+---
+
+## Plugin Development Patterns
+
+### CRUD Plugin Pattern (Like Todo)
+
+```
+types.ts        → Data interfaces
+schemas.ts      → Zod validation
+hooks/          → Data fetching (usePocketBase, useItems, useCreate, etc.)
+components/     → List, Item, Form, Dialog components
+pages/          → Main page with filters
+```
+
+### Display Plugin Pattern (Like Dashboard)
+
+```
+hooks/          → Stats queries, activity feed
+components/     → Stat cards, activity feed, quick actions
+pages/          → Dashboard overview
+```
+
+### Calculation Plugin Pattern
+
+```
+types.ts        → Input/Output types
+hooks/          → Pure calculation functions
+components/     → Input form, result display
+pages/          → Calculator page
+```
+
+---
+
+## Multi-Tenancy in Plugins
+
+**ALL plugin data MUST be scoped to organization:**
+
+```typescript
+// ✅ CORRECT - Filter by organization
+const result = await pb.collection('my_items').getList(1, 50, {
+  filter: `organizationId = "${orgId}"`,
+});
+
+// ❌ WRONG - No organization filter
+const result = await pb.collection('my_items').getList(1, 50);
+```
+
+**PocketBase collections MUST include:**
+- `organizationId` field (relation to organizations)
+- `ownerId` field (relation to users)
+- API rules with organization filtering
+
+---
+
+## Plugin Best Practices
+
+### DO ✅
+
+1. **Follow the standard structure** - Copy from Dashboard/Todo plugins
+2. **Use window bridge** for host communication
+3. **Scope all data** to organization
+4. **Handle loading/error states**
+5. **Show toast notifications** for user feedback
+6. **Use existing UI components** from kernel
+7. **Write TypeScript types** for all data
+8. **Validate with Zod schemas**
+
+### DON'T ❌
+
+1. **Don't import from host** - Use window bridge instead
+2. **Don't skip organization filtering** - Always scope data
+3. **Don't ignore error states** - Handle failures gracefully
+4. **Don't create circular dependencies** - Plugin → Host OK, Host → Plugin bad
+5. **Don't hardcode URLs** - Use environment variables
+6. **Don't forget TypeScript strict mode** - All code must type-check
+7. **Don't skip testing** - Write tests for hooks and components
+
+---
+
+## Plugin Registry
+
+### How Plugins Are Registered
+
+**1. In saas.config.ts (Host config):**
+```typescript
+plugins: [
+  { name: '@lego/plugin-dashboard', enabled: true },
+]
+```
+
+**2. In modern.runtime.ts (Garfish config):**
+```typescript
+apps: [
+  {
+    name: '@lego/plugin-dashboard',
+    entry: isDev ? 'http://localhost:3001' : () => import('@lego/plugin-dashboard'),
+    activeWhen: '/dashboard',
+  },
+]
+```
+
+**3. In plugin's plugin.config.ts (Plugin manifest):**
+```typescript
+export const pluginConfig: PluginConfig = {
+  manifest: { name: '@lego/plugin-dashboard', ... },
+  slots: [...],
+  routes: [...],
+};
+```
+
+---
+
+## Plugin Lifecycle
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ 1. REGISTRATION                                                  │
+│    • Plugin added to saas.config.ts                            │
+│    • Plugin added to modern.runtime.ts                         │
+└─────────────────────────────────────────────────────────────────┘
+                            │
+                            v
+┌─────────────────────────────────────────────────────────────────┐
+│ 2. INITIALIZATION                                                │
+│    • Plugin loader reads plugin.config.ts                      │
+│    • Plugin store creates plugin state                         │
+│    • Slots registered in slot registry                         │
+└─────────────────────────────────────────────────────────────────┘
+                            │
+                            v
+┌─────────────────────────────────────────────────────────────────┐
+│ 3. LOADING (Dev)                                                 │
+│    • Plugin starts on dev server (:3001, :3002, etc.)          │
+│    • Garfish connects to plugin URL                            │
+└─────────────────────────────────────────────────────────────────┘
+                            │
+                            v
+┌─────────────────────────────────────────────────────────────────┐
+│ 4. LOADING (Production)                                          │
+│    • Plugin bundled into host build                            │
+│    • Garfish dynamically imports plugin                        │
+└─────────────────────────────────────────────────────────────────┘
+                            │
+                            v
+┌─────────────────────────────────────────────────────────────────┐
+│ 5. MOUNTING                                                      │
+│    • User navigates to plugin route                            │
+│    • Garfish mounts plugin App component                       │
+│    • Plugin renders in host layout                            │
+└─────────────────────────────────────────────────────────────────┘
+                            │
+                            v
+┌─────────────────────────────────────────────────────────────────┐
+│ 6. ACTIVE                                                        │
+│    • Plugin can use host services via channels                 │
+│    • Plugin slots render in host layout                        │
+│    • Plugin routes accessible                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+**Next:** Read [`06-communication-patterns.md`](./06-communication-patterns.md) for inter-plugin communication details.