create-lego-one 2.0.12 → 2.0.13

package/template/docs/framework/research/05-slot-injection-pattern.md

@@ -0,0 +1,671 @@
+# Slot Injection Pattern: UI Extension System
+
+**Project:** Lego-One (Modern.js SaaS OS)
+**Document:** 05 - Slot Injection Pattern
+**Status:** Research Phase
+
+## Executive Summary
+
+This document explains the **Slot Injection Pattern** - how plugins can inject UI components into the Host's layout (Sidebar, Topbar) without modifying the Host's source code. This enables plugins to extend the host UI in a controlled, declarative way.
+
+---
+
+## 1. The Slot Injection Problem
+
+### 1.1 Use Case Example
+
+**Scenario:** The "Stripe Plugin" needs to:
+1. Add a "Billing" link to the Host's Sidebar navigation
+2. Show a "Credit Balance" badge in the Host's Topbar
+3. Display a subscription warning banner when credits are low
+
+**Challenge:** The plugin should be able to do this **without**:
+- Directly importing/modifying Host components
+- Creating tight coupling between plugin and host
+- Breaking when the Host layout changes
+
+### 1.2 Solution: Slot Registry Pattern
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         Slot Injection Flow                             │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                           │
+│  1. PLUGIN INITIALIZATION                                                │
+│     ┌─────────────────────────────────────────────────────────────────┐  │
+│     │ Plugin reads its plugin.config.ts                               │  │
+│     │ - Defines which slots to inject                                 │  │
+│     │ - Provides component for each slot                              │  │
+│     │ - Specifies order and visibility rules                          │  │
+│     └─────────────────────────────────────────────────────────────────┘  │
+│                              │                                          │
+│                              ▼                                          │
+│  2. SLOT REGISTRATION                                                   │
+│     ┌─────────────────────────────────────────────────────────────────┐  │
+│     │ Plugin calls window.__LEGO_SLOT_REGISTRY__.register()          │  │
+│     │ - Registers component with global registry                      │  │
+│     │ - Stores slot name, component, order, visibility                │  │
+│     └─────────────────────────────────────────────────────────────────┘  │
+│                              │                                          │
+│                              ▼                                          │
+│  3. HOST RENDERING                                                       │
+│     ┌─────────────────────────────────────────────────────────────────┐  │
+│     │ Host's Sidebar/Topbar components query the registry             │  │
+│     │ - Get all items for a specific slot                            │  │
+│     │ - Sort by order                                                 │  │
+│     │ - Filter by visibility                                         │  │
+│     │ - Render each component                                        │  │
+│     └─────────────────────────────────────────────────────────────────┘  │
+│                              │                                          │
+│                              ▼                                          │
+│  4. RESULT                                                              │
+│     ┌─────────────────────────────────────────────────────────────────┐  │
+│     │ Plugin UI appears in host layout seamlessly                    │  │
+│     │ - No host code modified                                        │  │
+│     │ - Multiple plugins can inject to same slot                    │  │
+│     │ - Plugins control their own UI                                 │  │
+│     └─────────────────────────────────────────────────────────────────┘  │
+│                                                                           │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Available Slots
+
+### 2.1 Standard Slot Locations
+
+| Slot Name | Location | Description |
+|-----------|----------|-------------|
+| `sidebar:nav` | Sidebar navigation list | Navigation links |
+| `sidebar:header` | Sidebar top section | Branding, logo |
+| `sidebar:footer` | Sidebar bottom section | Version info, help |
+| `topbar:actions` | Topbar right side | Action buttons |
+| `topbar:menu` | Topbar dropdown menu | Menu items |
+| `topbar:search` | Topbar search area | Search components |
+| `dashboard:widgets` | Dashboard grid | Dashboard widgets |
+| `layout:banner` | Above main content | Notification banners |
+
+### 2.2 Slot Item Interface
+
+```typescript
+interface SlotItem {
+  // Unique identifier for this slot item
+  id: string;
+
+  // Plugin name (for debugging/unregistration)
+  pluginName: string;
+
+  // React component to render
+  component: React.ComponentType;
+
+  // Sort order (lower = higher priority)
+  order: number;
+
+  // Visibility check function
+  isVisible: () => boolean;
+
+  // Cleanup function (called on unregister)
+  onUnmount?: () => void;
+}
+```
+
+---
+
+## 3. Implementation
+
+### 3.1 Host: Slot Registry
+
+**File:** `host/src/kernel/slot-registry.ts`
+
+```typescript
+import { reactive } from '@modern-js/runtime';
+
+export type SlotName =
+  | 'sidebar:nav'
+  | 'sidebar:header'
+  | 'sidebar:footer'
+  | 'topbar:actions'
+  | 'topbar:menu'
+  | 'topbar:search'
+  | 'dashboard:widgets'
+  | 'layout:banner';
+
+export interface SlotItem {
+  id: string;
+  pluginName: string;
+  component: React.ComponentType;
+  order: number;
+  isVisible: () => boolean;
+  onUnmount?: () => void;
+}
+
+interface SlotRegistry {
+  slots: Record<SlotName, SlotItem[]>;
+  register: (slot: SlotName, item: Omit<SlotItem, 'id'>) => string;
+  unregister: (slot: SlotName, id: string) => void;
+  getItems: (slot: SlotName) => SlotItem[];
+  clearPlugin: (pluginName: string) => void;
+}
+
+// Global singleton for slot registration
+export const slotRegistry: SlotRegistry = reactive({
+  slots: {
+    'sidebar:nav': [],
+    'sidebar:header': [],
+    'sidebar:footer': [],
+    'topbar:actions': [],
+    'topbar:menu': [],
+    'topbar:search': [],
+    'dashboard:widgets': [],
+    'layout:banner': [],
+  },
+
+  register(slot: SlotName, item: Omit<SlotItem, 'id'>) {
+    const id = `${slot}-${item.pluginName}-${Date.now()}`;
+    const slotItem: SlotItem = { ...item, id };
+
+    if (!this.slots[slot]) {
+      this.slots[slot] = [];
+    }
+
+    this.slots[slot].push(slotItem);
+
+    // Sort by order (lower first)
+    this.slots[slot].sort((a, b) => a.order - b.order);
+
+    console.log(`[SlotRegistry] Registered "${id}" to "${slot}"`);
+    return id;
+  },
+
+  unregister(slot: SlotName, id: string) {
+    const items = this.slots[slot];
+    if (!items) return;
+
+    const item = items.find((i) => i.id === id);
+    if (item?.onUnmount) {
+      item.onUnmount();
+    }
+
+    this.slots[slot] = items.filter((i) => i.id !== id);
+    console.log(`[SlotRegistry] Unregistered "${id}" from "${slot}"`);
+  },
+
+  getItems(slot: SlotName) {
+    const items = this.slots[slot] || [];
+    // Filter by visibility
+    return items.filter((item) => item.isVisible());
+  },
+
+  clearPlugin(pluginName: string) {
+    for (const slot of Object.keys(this.slots) as SlotName[]) {
+      const items = this.slots[slot];
+      for (const item of items) {
+        if (item.pluginName === pluginName) {
+          this.unregister(slot, item.id);
+        }
+      }
+    }
+  },
+});
+
+// Register to window for plugin access
+export function initSlotRegistry() {
+  (window as any).__LEGO_SLOT_REGISTRY__ = slotRegistry;
+}
+```
+
+### 3.2 Host: Initialize Registry
+
+**File:** `host/src/bootstrap.tsx`
+
+```typescript
+import { initSlotRegistry } from './kernel/slot-registry';
+import { registerSharedState } from './kernel/shared-state-bridge';
+
+// Initialize systems before app starts
+initSlotRegistry();
+registerSharedState();
+```
+
+### 3.3 Host: Sidebar Component
+
+**File:** `host/src/layout/Sidebar.tsx`
+
+```typescript
+import { Link, useLocation } from '@modern-js/runtime/router';
+import { cn } from '@/lib/utils';
+import { slotRegistry } from '@/kernel/slot-registry';
+import { ScrollArea } from '@/components/ui/scroll-area';
+import { Separator } from '@/components/ui/separator';
+
+export function Sidebar() {
+  const location = useLocation();
+
+  // Get registered navigation items
+  const navItems = slotRegistry.getItems('sidebar:nav');
+  const headerItems = slotRegistry.getItems('sidebar:header');
+  const footerItems = slotRegistry.getItems('sidebar:footer');
+
+  return (
+    <div className="flex flex-col h-full border-r bg-muted/40 w-64">
+      {/* Header Slot */}
+      {headerItems.length > 0 && (
+        <div className="p-4 space-y-2">
+          {headerItems.map((item) => (
+            <item.component key={item.id} />
+          ))}
+        </div>
+      )}
+
+      <Separator />
+
+      {/* Navigation */}
+      <ScrollArea className="flex-1 px-3 py-2">
+        <div className="space-y-1">
+          {/* Default nav items */}
+          <NavLink to="/dashboard" icon="Layout">
+            Dashboard
+          </NavLink>
+          <NavLink to="/apps" icon="Grid3x3">
+            Apps
+          </NavLink>
+          <NavLink to="/settings" icon="Settings">
+            Settings
+          </NavLink>
+
+          {/* Plugin-injected nav items */}
+          {navItems.map((item) => (
+            <item.component key={item.id} />
+          ))}
+        </div>
+      </ScrollArea>
+
+      <Separator />
+
+      {/* Footer Slot */}
+      {footerItems.length > 0 && (
+        <div className="p-4 space-y-2">
+          {footerItems.map((item) => (
+            <item.component key={item.id} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function NavLink({
+  to,
+  icon,
+  children,
+}: {
+  to: string;
+  icon: string;
+  children: React.ReactNode;
+}) {
+  const location = useLocation();
+  const isActive = location.pathname === to || location.pathname.startsWith(to + '/');
+
+  return (
+    <Link
+      to={to}
+      className={cn(
+        'flex items-center gap-3 px-3 py-2 text-sm rounded-md transition-colors',
+        isActive
+          ? 'bg-primary text-primary-foreground'
+          : 'hover:bg-accent hover:text-accent-foreground'
+      )}
+    >
+      {/* Icon would be rendered here */}
+      <span>{icon}</span>
+      <span>{children}</span>
+    </Link>
+  );
+}
+```
+
+### 3.4 Host: Topbar Component
+
+**File:** `host/src/layout/Topbar.tsx`
+
+```typescript
+import { slotRegistry } from '@/kernel/slot-registry';
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { MoreVertical } from 'lucide-react';
+
+export function Topbar() {
+  // Get registered topbar items
+  const actionItems = slotRegistry.getItems('topbar:actions');
+  const menuItems = slotRegistry.getItems('topbar:menu');
+
+  return (
+    <header className="h-14 border-b flex items-center justify-between px-6">
+      <div className="flex items-center gap-4">
+        {/* Breadcrumb or page title would go here */}
+        <h1 className="font-semibold">Lego-One</h1>
+      </div>
+
+      <div className="flex items-center gap-2">
+        {/* Plugin-injected action buttons */}
+        {actionItems.map((item) => (
+          <item.component key={item.id} />
+        ))}
+
+        {/* User menu */}
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="ghost" size="icon">
+              <MoreVertical className="h-4 w-4" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem>Profile</DropdownMenuItem>
+            <DropdownMenuItem>Settings</DropdownMenuItem>
+
+            {/* Plugin-injected menu items */}
+            {menuItems.map((item) => (
+              <item.component key={item.id} />
+            ))}
+
+            <DropdownMenuItem>Logout</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </div>
+    </header>
+  );
+}
+```
+
+---
+
+## 4. Plugin: Slot Injection
+
+### 4.1 Plugin Config: Define Slots
+
+**File:** `packages/plugins/@lego/plugin-stripe/plugin.config.ts`
+
+```typescript
+import { definePluginConfig } from '@lego/kernel/plugin-config';
+
+export default definePluginConfig({
+  name: '@lego/plugin-stripe',
+  version: '1.0.0',
+  displayName: 'Stripe Integration',
+  description: 'Payment processing via Stripe',
+
+  // Define slot injections
+  slots: {
+    'sidebar:nav': {
+      component: './src/components/slots/SidebarBillingLink',
+      order: 50,
+      isVisible: () => {
+        const state = (window as any).__LEGO_KERNEL_STATE__;
+        const user = state?.useGlobalKernelState.getState().currentUser;
+        return user?.role === 'admin' || user?.role === 'billing';
+      },
+    },
+
+    'topbar:actions': {
+      component: './src/components/slots/CreditBalanceBadge',
+      order: 10,
+      isVisible: () => true, // Always visible
+    },
+
+    'topbar:menu': {
+      component: './src/components/slots/SubscriptionMenuItem',
+      order: 100,
+    },
+  },
+});
+```
+
+### 4.2 Plugin: Sidebar Link Component
+
+**File:** `packages/plugins/@lego/plugin-stripe/src/components/slots/SidebarBillingLink.tsx`
+
+```typescript
+import { Link } from '@modern-js/runtime/router';
+import { CreditCard } from 'lucide-react';
+import { cn } from '@/lib/utils';
+
+export function SidebarBillingLink() {
+  return (
+    <Link
+      to="/billing"
+      className={cn(
+        'flex items-center gap-3 px-3 py-2 text-sm rounded-md',
+        'transition-colors hover:bg-accent hover:text-accent-foreground'
+      )}
+    >
+      <CreditCard className="h-4 w-4" />
+      <span>Billing</span>
+    </Link>
+  );
+}
+
+export default SidebarBillingLink;
+```
+
+### 4.3 Plugin: Credit Badge Component
+
+**File:** `packages/plugins/@lego/plugin-stripe/src/components/slots/CreditBalanceBadge.tsx`
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { Badge } from '@/components/ui/badge';
+import { CreditCard } from 'lucide-react';
+
+export function CreditBalanceBadge() {
+  const { data: balance } = useQuery({
+    queryKey: ['stripe', 'balance'],
+    queryFn: async () => {
+      const res = await fetch('/api/stripe/balance');
+      return res.json();
+    },
+    refetchInterval: 60000, // Refresh every minute
+  });
+
+  const credits = balance?.credits || 0;
+  const isLow = credits < 10;
+
+  return (
+    <Badge
+      variant={isLow ? 'destructive' : 'secondary'}
+      className="flex items-center gap-1"
+    >
+      <CreditCard className="h-3 w-3" />
+      <span>{credits} credits</span>
+    </Badge>
+  );
+}
+
+export default CreditBalanceBadge;
+```
+
+### 4.4 Plugin: Menu Item Component
+
+**File:** `packages/plugins/@lego/plugin-stripe/src/components/slots/SubscriptionMenuItem.tsx`
+
+```typescript
+import { DropdownMenuItem } from '@/components/ui/dropdown-menu';
+import { useNavigate } from '@modern-js/runtime/router';
+
+export function SubscriptionMenuItem() {
+  const navigate = useNavigate();
+
+  return (
+    <DropdownMenuItem onClick={() => navigate('/subscription')}>
+      Manage Subscription
+    </DropdownMenuItem>
+  );
+}
+
+export default SubscriptionMenuItem;
+```
+
+### 4.5 Plugin: Register Slots on Load
+
+**File:** `packages/plugins/@lego/plugin-stripe/src/App.tsx`
+
+```typescript
+import { useEffect } from 'react';
+import { BrowserRouter, Routes, Route } from '@modern-js/runtime/router';
+import pluginConfig from '../../plugin.config';
+import { registerPluginSlots } from './lib/slots';
+
+export default function PluginApp({ basename }: { basename: string }) {
+  useEffect(() => {
+    // Register all slots defined in plugin.config.ts
+    registerPluginSlots(pluginConfig.slots, '@lego/plugin-stripe');
+  }, []);
+
+  return (
+    <BrowserRouter basename={basename}>
+      <Routes>
+        {/* Plugin routes */}
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+### 4.6 Plugin: Slot Registration Helper
+
+**File:** `packages/plugins/@lego/plugin-stripe/src/lib/slots.ts`
+
+```typescript
+interface SlotConfig {
+  component: string;
+  order: number;
+  isVisible?: () => boolean;
+}
+
+interface SlotsConfig {
+  [slotName: string]: SlotConfig;
+}
+
+export async function registerPluginSlots(
+  slots: SlotsConfig,
+  pluginName: string
+) {
+  const registry = (window as any).__LEGO_SLOT_REGISTRY__;
+
+  if (!registry) {
+    console.warn('[Slots] Registry not found. Host not initialized?');
+    return;
+  }
+
+  for (const [slotName, slotConfig] of Object.entries(slots)) {
+    try {
+      const module = await import(/* @vite-ignore */ slotConfig.component);
+      const Component = module.default;
+
+      registry.register(slotName, {
+        pluginName,
+        component: Component,
+        order: slotConfig.order,
+        isVisible: slotConfig.isVisible || (() => true),
+        onUnmount: () => {
+          console.log(`[Slots] Unmounted ${slotName} for ${pluginName}`);
+        },
+      });
+    } catch (error) {
+      console.error(`[Slots] Failed to register "${slotName}":`, error);
+    }
+  }
+}
+```
+
+---
+
+## 5. Advanced Patterns
+
+### 5.1 Dynamic Slot Items
+
+Slots can be registered/unregistered dynamically:
+
+```typescript
+// Show a notification banner only when needed
+function showLowCreditsBanner() {
+  const registry = (window as any).__LEGO_SLOT_REGISTRY__;
+
+  const id = registry.register('layout:banner', {
+    pluginName: '@lego/plugin-stripe',
+    component: LowCreditsBanner,
+    order: 1,
+    isVisible: () => true,
+  });
+
+  // Unregister after user dismisses
+  return () => registry.unregister('layout:banner', id);
+}
+```
+
+### 5.2 Slot Data Passing
+
+Pass data from host to slot components via context:
+
+```typescript
+// Host provides context
+<SlotDataProvider value={{ currentUser, theme }}>
+  <Sidebar />
+</SlotDataProvider>
+
+// Slot component consumes context
+function SidebarBillingLink() {
+  const { currentUser } = useSlotDataContext();
+  // ...
+}
+```
+
+### 5.3 Conditional Rendering
+
+Use visibility rules for complex conditions:
+
+```typescript
+isVisible: () => {
+  const state = window.__LEGO_KERNEL_STATE__;
+  const user = state?.useGlobalKernelState.getState().currentUser;
+
+  // Only show for admins with active subscription
+  return (
+    user?.role === 'admin' &&
+    user?.subscription?.status === 'active'
+  );
+}
+```
+
+---
+
+## 6. Slot Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| **Use Semantic Names** | `sidebar:nav` not `sidebar:left` |
+| **Order Predictably** | Use increments of 10 for easy reordering |
+| **Cleanup Resources** | Use `onUnmount` for subscriptions |
+| **Handle Missing Registry** | Gracefully degrade if host not ready |
+| **Type Safety** | Export slot component types |
+| **Avoid Side Effects** | Slot components should be pure |
+
+---
+
+## 7. Next Steps
+
+1. **`06-cli-strategy.md`**: CLI tool for project scaffolding
+2. **`07-deployment.md`**: Deploy host and plugins to production
+
+---
+
+## References
+
+- [Radix UI Primitives](https://www.radix-ui.com/)
+- [TanStack Query](https://tanstack.com/query/latest)
+- [Modern.js Runtime](https://modernjs.dev/guides/topic-detail/runtime/)