@flightdev/ui 2.0.0 → 4.0.0

package/docs/PATTERNS.md

@@ -1,836 +0,0 @@
-# Enterprise Patterns and Best Practices
-
-This document covers production-grade patterns for using the Flight UI adapter system in enterprise applications.
-
-## Table of Contents
-
-1. [Architecture Patterns](#architecture-patterns)
-2. [Error Handling](#error-handling)
-3. [Performance Optimization](#performance-optimization)
-4. [Caching Strategies](#caching-strategies)
-5. [Monitoring and Observability](#monitoring-and-observability)
-6. [Security Considerations](#security-considerations)
-7. [Testing Strategies](#testing-strategies)
-
----
-
-## Architecture Patterns
-
-### Micro-Frontend Architecture
-
-Use different adapters for different sections of your application.
-
-```typescript
-// flight.config.ts
-import { defineConfig } from '@flight-framework/core';
-
-export default defineConfig({
-    ui: {
-        // Default adapter for main app
-        adapter: 'react',
-        
-        // Route-specific adapters
-        routes: {
-            '/admin/**': 'vue',      // Admin uses Vue
-            '/docs/**': 'htmx',      // Docs are static
-            '/dashboard': 'react',    // Dashboard needs interactivity
-        },
-    },
-});
-```
-
-**Implementation**:
-
-```typescript
-import { adapterRegistry, registerBuiltinAdapters } from '@flight-framework/ui';
-
-registerBuiltinAdapters();
-
-class RouterWithAdapters {
-    private adapters = new Map();
-    
-    async getAdapter(path: string): Promise<UIAdapterV2> {
-        const adapterName = this.resolveAdapter(path);
-        
-        if (!this.adapters.has(adapterName)) {
-            const adapter = await adapterRegistry.get(adapterName);
-            this.adapters.set(adapterName, adapter);
-        }
-        
-        return this.adapters.get(adapterName);
-    }
-    
-    private resolveAdapter(path: string): string {
-        if (path.startsWith('/admin')) return 'vue';
-        if (path.startsWith('/docs')) return 'htmx';
-        return 'react';
-    }
-}
-```
-
-### Backend for Frontend (BFF) Pattern
-
-Each client type gets optimized responses.
-
-```typescript
-import { react } from '@flight-framework/ui/react';
-import { htmx } from '@flight-framework/ui/htmx';
-
-async function handleRequest(request: Request) {
-    const userAgent = request.headers.get('User-Agent') || '';
-    const acceptsJS = !request.headers.get('X-No-JS');
-    
-    // Low-bandwidth or no-JS clients get HTMX
-    if (!acceptsJS || isLowBandwidth(request)) {
-        const adapter = htmx();
-        return renderWithAdapter(adapter, request);
-    }
-    
-    // Modern clients get React with streaming
-    const adapter = react({ streaming: true });
-    return renderWithAdapter(adapter, request);
-}
-```
-
-### Islands Architecture for Content Sites
-
-Minimize JavaScript while maintaining interactivity.
-
-```typescript
-import { react } from '@flight-framework/ui/react';
-
-const adapter = react();
-
-// Define interactive islands
-const islands = {
-    'search': {
-        component: SearchWidget,
-        hydrate: 'idle',
-        priority: 100,
-    },
-    'comments': {
-        component: CommentsSection,
-        hydrate: 'visible',
-        priority: 50,
-    },
-    'newsletter': {
-        component: NewsletterForm,
-        hydrate: 'interaction',
-        priority: 10,
-    },
-};
-
-// Render page with islands
-function renderArticle(article) {
-    const islandPlaceholders = {};
-    
-    for (const [name, config] of Object.entries(islands)) {
-        islandPlaceholders[name] = adapter.createIsland(
-            config.component,
-            { articleId: article.id },
-            { hydrate: config.hydrate, priority: config.priority }
-        );
-    }
-    
-    return `
-    <article>
-        <header>
-            <h1>${article.title}</h1>
-            ${islandPlaceholders.search.placeholder}
-        </header>
-        
-        <main>
-            ${article.content}
-        </main>
-        
-        <section id="comments">
-            ${islandPlaceholders.comments.placeholder}
-        </section>
-        
-        <aside>
-            ${islandPlaceholders.newsletter.placeholder}
-        </aside>
-    </article>
-    `;
-}
-```
-
----
-
-## Error Handling
-
-### Streaming Error Boundaries
-
-Handle errors at different levels during streaming SSR.
-
-```typescript
-import { react } from '@flight-framework/ui/react';
-
-const adapter = react();
-
-interface RenderOptions {
-    fallbackHtml: string;
-    onError: (error: Error, context: string) => void;
-}
-
-async function streamWithErrorHandling(
-    component: Component,
-    response: Response,
-    options: RenderOptions
-) {
-    const { stream, done, abort } = adapter.renderToStream(
-        component,
-        { url: request.url },
-        {
-            onShellError: (error) => {
-                // Critical error - send error page
-                options.onError(error, 'shell');
-                abort();
-                
-                response.writeHead(500, { 'Content-Type': 'text/html' });
-                response.end(options.fallbackHtml);
-            },
-            onError: (error) => {
-                // Non-critical error - log and continue
-                options.onError(error, 'content');
-                // Error boundary will show fallback UI
-            },
-            onShellReady: () => {
-                // Shell rendered successfully
-                response.writeHead(200, {
-                    'Content-Type': 'text/html',
-                    'Transfer-Encoding': 'chunked',
-                });
-            },
-        }
-    );
-    
-    try {
-        const reader = stream.getReader();
-        
-        while (true) {
-            const { done: readerDone, value } = await reader.read();
-            if (readerDone) break;
-            response.write(value);
-        }
-        
-        response.end();
-    } catch (error) {
-        options.onError(error as Error, 'stream');
-        response.end(options.fallbackHtml);
-    }
-}
-```
-
-### Graceful Degradation
-
-Fall back to simpler rendering when advanced features fail.
-
-```typescript
-async function renderWithFallback(component: Component) {
-    const reactAdapter = react({ streaming: true });
-    const htmxAdapter = htmx();
-    
-    try {
-        // Try streaming SSR
-        return await streamRender(reactAdapter, component);
-    } catch (streamError) {
-        console.warn('Streaming failed, trying string render');
-        
-        try {
-            // Fall back to string render
-            return await reactAdapter.renderToString(component);
-        } catch (renderError) {
-            console.warn('React render failed, falling back to HTMX');
-            
-            // Fall back to HTMX static render
-            return await htmxAdapter.renderToString({
-                component: () => renderStaticFallback(component),
-                props: {},
-            });
-        }
-    }
-}
-```
-
-### Timeout Handling
-
-Prevent hanging requests with proper timeouts.
-
-```typescript
-function renderWithTimeout(
-    adapter: UIAdapterV2,
-    component: Component,
-    timeoutMs: number
-): Promise<RenderResult> {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            reject(new Error(`Render timeout after ${timeoutMs}ms`));
-        }, timeoutMs);
-        
-        adapter.renderToString(component)
-            .then((result) => {
-                clearTimeout(timer);
-                resolve(result);
-            })
-            .catch((error) => {
-                clearTimeout(timer);
-                reject(error);
-            });
-    });
-}
-
-// Usage
-try {
-    const result = await renderWithTimeout(adapter, component, 5000);
-} catch (error) {
-    if (error.message.includes('timeout')) {
-        return renderCachedFallback();
-    }
-    throw error;
-}
-```
-
----
-
-## Performance Optimization
-
-### Lazy Adapter Loading
-
-Load adapters only when needed.
-
-```typescript
-const adapterLoaders = {
-    react: () => import('@flight-framework/ui/react'),
-    vue: () => import('@flight-framework/ui/vue'),
-    htmx: () => import('@flight-framework/ui/htmx'),
-};
-
-class LazyAdapterRegistry {
-    private cache = new Map<string, UIAdapterV2>();
-    
-    async get(name: string): Promise<UIAdapterV2> {
-        if (this.cache.has(name)) {
-            return this.cache.get(name)!;
-        }
-        
-        const loader = adapterLoaders[name];
-        if (!loader) {
-            throw new Error(`Unknown adapter: ${name}`);
-        }
-        
-        const module = await loader();
-        const factory = module.default || module[name];
-        const adapter = factory();
-        
-        this.cache.set(name, adapter);
-        return adapter;
-    }
-}
-```
-
-### Component Memoization
-
-Cache component render results.
-
-```typescript
-class MemoizedRenderer {
-    private cache = new Map<string, { result: RenderResult; expiry: number }>();
-    
-    constructor(
-        private adapter: UIAdapterV2,
-        private defaultTtl: number = 60000
-    ) {}
-    
-    async render(
-        component: Component,
-        cacheKey: string,
-        ttl?: number
-    ): Promise<RenderResult> {
-        const cached = this.cache.get(cacheKey);
-        const now = Date.now();
-        
-        if (cached && cached.expiry > now) {
-            return cached.result;
-        }
-        
-        const result = await this.adapter.renderToString(component);
-        
-        this.cache.set(cacheKey, {
-            result,
-            expiry: now + (ttl ?? this.defaultTtl),
-        });
-        
-        return result;
-    }
-    
-    invalidate(pattern?: string | RegExp) {
-        if (!pattern) {
-            this.cache.clear();
-            return;
-        }
-        
-        for (const key of this.cache.keys()) {
-            if (typeof pattern === 'string' ? key.includes(pattern) : pattern.test(key)) {
-                this.cache.delete(key);
-            }
-        }
-    }
-}
-```
-
-### Parallel Rendering
-
-Render multiple components simultaneously.
-
-```typescript
-async function renderPageParallel(sections: Record<string, Component>) {
-    const adapter = react();
-    
-    const renderTasks = Object.entries(sections).map(
-        async ([name, component]) => {
-            const result = await adapter.renderToString(component);
-            return [name, result] as const;
-        }
-    );
-    
-    const results = await Promise.all(renderTasks);
-    
-    return Object.fromEntries(results);
-}
-
-// Usage
-const { header, main, sidebar, footer } = await renderPageParallel({
-    header: { component: Header, props: { user } },
-    main: { component: MainContent, props: { data } },
-    sidebar: { component: Sidebar, props: { items } },
-    footer: { component: Footer, props: {} },
-});
-
-const html = `
-<!DOCTYPE html>
-<html>
-<body>
-    ${header.html}
-    <div class="layout">
-        ${main.html}
-        ${sidebar.html}
-    </div>
-    ${footer.html}
-</body>
-</html>
-`;
-```
-
----
-
-## Caching Strategies
-
-### Multi-Level Cache
-
-Implement tiered caching for optimal performance.
-
-```typescript
-interface CacheLevel {
-    get(key: string): Promise<RenderResult | null>;
-    set(key: string, value: RenderResult, ttl: number): Promise<void>;
-}
-
-class MultiLevelCache {
-    constructor(private levels: CacheLevel[]) {}
-    
-    async get(key: string): Promise<RenderResult | null> {
-        for (let i = 0; i < this.levels.length; i++) {
-            const result = await this.levels[i].get(key);
-            
-            if (result) {
-                // Populate higher levels
-                for (let j = 0; j < i; j++) {
-                    await this.levels[j].set(key, result, 60000);
-                }
-                return result;
-            }
-        }
-        
-        return null;
-    }
-    
-    async set(key: string, value: RenderResult, ttl: number): Promise<void> {
-        await Promise.all(
-            this.levels.map(level => level.set(key, value, ttl))
-        );
-    }
-}
-
-// Usage: Memory -> Redis -> CDN
-const cache = new MultiLevelCache([
-    new MemoryCache(),
-    new RedisCache(redisClient),
-    new CDNCache(cdnClient),
-]);
-```
-
-### Stale-While-Revalidate
-
-Serve stale content while refreshing in background.
-
-```typescript
-class SWRCache {
-    private cache = new Map<string, { result: RenderResult; staleAt: number; expireAt: number }>();
-    
-    async getOrRevalidate(
-        key: string,
-        fetcher: () => Promise<RenderResult>,
-        freshTtl: number,
-        staleTtl: number
-    ): Promise<RenderResult> {
-        const now = Date.now();
-        const cached = this.cache.get(key);
-        
-        if (cached) {
-            if (now < cached.staleAt) {
-                // Fresh - return immediately
-                return cached.result;
-            }
-            
-            if (now < cached.expireAt) {
-                // Stale - return and revalidate in background
-                this.revalidate(key, fetcher, freshTtl, staleTtl);
-                return cached.result;
-            }
-        }
-        
-        // Expired or missing - fetch synchronously
-        const result = await fetcher();
-        this.cache.set(key, {
-            result,
-            staleAt: now + freshTtl,
-            expireAt: now + staleTtl,
-        });
-        
-        return result;
-    }
-    
-    private async revalidate(
-        key: string,
-        fetcher: () => Promise<RenderResult>,
-        freshTtl: number,
-        staleTtl: number
-    ): Promise<void> {
-        try {
-            const result = await fetcher();
-            const now = Date.now();
-            this.cache.set(key, {
-                result,
-                staleAt: now + freshTtl,
-                expireAt: now + staleTtl,
-            });
-        } catch (error) {
-            console.error(`Revalidation failed for ${key}:`, error);
-        }
-    }
-}
-```
-
----
-
-## Monitoring and Observability
-
-### Render Metrics
-
-Track SSR performance metrics.
-
-```typescript
-interface RenderMetrics {
-    adapter: string;
-    path: string;
-    duration: number;
-    success: boolean;
-    streaming: boolean;
-    ttfb?: number;
-}
-
-class MetricsCollector {
-    private metrics: RenderMetrics[] = [];
-    
-    async trackRender<T>(
-        adapter: UIAdapterV2,
-        path: string,
-        operation: () => Promise<T>
-    ): Promise<T> {
-        const start = performance.now();
-        let success = true;
-        
-        try {
-            return await operation();
-        } catch (error) {
-            success = false;
-            throw error;
-        } finally {
-            const duration = performance.now() - start;
-            
-            this.metrics.push({
-                adapter: adapter.id,
-                path,
-                duration,
-                success,
-                streaming: adapter.capabilities.streaming,
-            });
-            
-            this.report();
-        }
-    }
-    
-    private report() {
-        if (this.metrics.length >= 100) {
-            // Send batch to monitoring service
-            sendMetrics(this.metrics);
-            this.metrics = [];
-        }
-    }
-}
-```
-
-### Structured Logging
-
-Log render operations with context.
-
-```typescript
-interface RenderLogEntry {
-    timestamp: string;
-    requestId: string;
-    adapter: string;
-    path: string;
-    component: string;
-    duration: number;
-    cacheHit: boolean;
-    error?: string;
-}
-
-function createRenderLogger(requestId: string) {
-    return {
-        logRender(entry: Omit<RenderLogEntry, 'timestamp' | 'requestId'>) {
-            const log: RenderLogEntry = {
-                timestamp: new Date().toISOString(),
-                requestId,
-                ...entry,
-            };
-            
-            console.log(JSON.stringify(log));
-        },
-    };
-}
-
-// Usage
-const logger = createRenderLogger(request.id);
-
-const result = await adapter.renderToString(component);
-
-logger.logRender({
-    adapter: adapter.id,
-    path: request.url,
-    component: 'ProductPage',
-    duration: result.timing?.total || 0,
-    cacheHit: false,
-});
-```
-
----
-
-## Security Considerations
-
-### XSS Prevention
-
-Escape user content in rendered HTML.
-
-```typescript
-function escapeHtml(unsafe: string): string {
-    return unsafe
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#039;');
-}
-
-// For HTMX templates
-function safeTemplate(user: { name: string }) {
-    return `
-    <div class="user-profile">
-        <h1>${escapeHtml(user.name)}</h1>
-    </div>
-    `;
-}
-```
-
-### CSP Headers
-
-Configure Content Security Policy for hydration scripts.
-
-```typescript
-function generateCSPHeader(nonce: string): string {
-    return [
-        `script-src 'self' 'nonce-${nonce}'`,
-        `style-src 'self' 'unsafe-inline'`,
-        `img-src 'self' data: https:`,
-        `connect-src 'self'`,
-    ].join('; ');
-}
-
-// In hydration script
-function getHydrationScript(result: RenderResult, nonce: string): string {
-    return `
-    <script nonce="${nonce}">
-        window.__FLIGHT_DATA__ = ${JSON.stringify(result.hydrationData)};
-    </script>
-    `;
-}
-```
-
-### Input Validation
-
-Validate props before rendering.
-
-```typescript
-import { z } from 'zod';
-
-const UserPropsSchema = z.object({
-    id: z.string().uuid(),
-    name: z.string().max(100),
-    role: z.enum(['user', 'admin']),
-});
-
-async function safeRender(adapter: UIAdapterV2, props: unknown) {
-    const validated = UserPropsSchema.parse(props);
-    
-    return adapter.renderToString({
-        component: UserProfile,
-        props: validated,
-    });
-}
-```
-
----
-
-## Testing Strategies
-
-### Unit Testing Adapters
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { react } from '@flight-framework/ui/react';
-
-describe('React Adapter', () => {
-    it('renders component to string', async () => {
-        const adapter = react();
-        
-        const result = await adapter.renderToString({
-            component: () => null,
-            props: {},
-        });
-        
-        expect(result.html).toBeDefined();
-        expect(result.timing).toBeDefined();
-    });
-    
-    it('generates hydration script', async () => {
-        const adapter = react();
-        
-        const script = adapter.getHydrationScript({
-            html: '<div>Test</div>',
-            hydrationData: { test: true },
-        });
-        
-        expect(script).toContain('<script');
-        expect(script).toContain('__FLIGHT_DATA__');
-    });
-});
-```
-
-### Integration Testing SSR
-
-```typescript
-import { describe, it, expect, beforeAll } from 'vitest';
-import { adapterRegistry, registerBuiltinAdapters } from '@flight-framework/ui';
-
-describe('SSR Integration', () => {
-    beforeAll(() => {
-        registerBuiltinAdapters();
-    });
-    
-    it('renders full page with React', async () => {
-        const adapter = await adapterRegistry.get('react');
-        
-        const result = await adapter.renderToString({
-            component: App,
-            props: { user: { name: 'Test' } },
-        });
-        
-        expect(result.html).toContain('Test');
-    });
-    
-    it('streams content correctly', async () => {
-        const adapter = await adapterRegistry.get('react');
-        
-        const { stream, done } = adapter.renderToStream({
-            component: App,
-            props: {},
-        });
-        
-        const chunks: Uint8Array[] = [];
-        const reader = stream.getReader();
-        
-        while (true) {
-            const { done: readerDone, value } = await reader.read();
-            if (readerDone) break;
-            chunks.push(value);
-        }
-        
-        await done;
-        
-        expect(chunks.length).toBeGreaterThan(0);
-    });
-});
-```
-
-### Performance Testing
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { react } from '@flight-framework/ui/react';
-
-describe('Performance', () => {
-    it('renders within acceptable time', async () => {
-        const adapter = react();
-        
-        const start = performance.now();
-        
-        await adapter.renderToString({
-            component: LargePage,
-            props: {},
-        });
-        
-        const duration = performance.now() - start;
-        
-        // Should render in under 100ms
-        expect(duration).toBeLessThan(100);
-    });
-    
-    it('handles concurrent renders', async () => {
-        const adapter = react();
-        
-        const renders = Array.from({ length: 10 }, () =>
-            adapter.renderToString({
-                component: TestComponent,
-                props: {},
-            })
-        );
-        
-        const results = await Promise.all(renders);
-        
-        results.forEach(result => {
-            expect(result.html).toBeDefined();
-        });
-    });
-});
-```