@flightdev/ui 2.0.0

package/docs/ADAPTERS.md

@@ -0,0 +1,946 @@
+# UI Adapter System
+
+This document provides comprehensive documentation for the `@flight-framework/ui` adapter system, including tier classifications, implementation patterns, and enterprise usage examples.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Tier Classification](#tier-classification)
+3. [Tier 1: Full Support Adapters](#tier-1-full-support-adapters)
+4. [Tier 2: Standard Support Adapters](#tier-2-standard-support-adapters)
+5. [Tier 3: HTML-First Adapters](#tier-3-html-first-adapters)
+6. [Advanced Patterns](#advanced-patterns)
+7. [Creating Custom Adapters](#creating-custom-adapters)
+8. [Performance Considerations](#performance-considerations)
+9. [Migration Guide](#migration-guide)
+
+---
+
+## Overview
+
+The Flight UI adapter system provides a unified interface for rendering components across 18+ frameworks. All adapters implement the `UIAdapterV2` interface, ensuring consistent behavior regardless of the underlying framework.
+
+### Core Concepts
+
+**Adapter**: A class that translates Flight's rendering API to a specific framework's SSR implementation.
+
+**Capabilities**: Feature flags indicating what an adapter supports (streaming, islands, resumability, etc.).
+
+**Tiers**: Classification levels indicating the depth of framework integration.
+
+### Quick Start
+
+```typescript
+import { defineUI } from '@flight-framework/ui';
+import { react } from '@flight-framework/ui/react';
+
+export default defineUI(react({
+    streaming: true,
+}));
+```
+
+---
+
+## Tier Classification
+
+Adapters are organized into three tiers based on their feature set and integration depth.
+
+| Tier | Support Level | Use Case |
+|------|---------------|----------|
+| Tier 1 | Full | Enterprise applications requiring streaming, islands, and full hydration |
+| Tier 2 | Standard | Applications needing SSR with simpler hydration requirements |
+| Tier 3 | HTML-First | Server-driven applications with minimal client-side JavaScript |
+
+### Capability Matrix
+
+| Capability | Tier 1 | Tier 2 | Tier 3 |
+|------------|--------|--------|--------|
+| SSR | Yes | Yes | Yes |
+| Streaming | Yes | Some | No |
+| Islands | Yes | Some | No |
+| Resumable | Qwik only | No | No |
+| CSR Fallback | Yes | Yes | Limited |
+| Server Components | React only | No | No |
+
+---
+
+## Tier 1: Full Support Adapters
+
+Tier 1 adapters provide complete SSR, streaming, hydration, and islands architecture support.
+
+### Available Adapters
+
+- React 18+
+- Vue 3
+- Angular 17+
+- Svelte 5
+- Solid
+- Qwik
+
+### React Adapter
+
+Full-featured React 18+ SSR adapter with streaming and hydration support.
+
+**Capabilities**:
+- Streaming SSR via `renderToReadableStream`
+- Progressive hydration
+- Islands architecture
+- React Server Components
+- SSG and CSR fallback
+
+**Basic Usage**:
+
+```typescript
+import { defineUI } from '@flight-framework/ui';
+import { react } from '@flight-framework/ui/react';
+
+export default defineUI(react());
+```
+
+**With Options**:
+
+```typescript
+import { react } from '@flight-framework/ui/react';
+
+const adapter = react({
+    streaming: true,
+    serverComponents: true,
+    onError: (error) => {
+        console.error('[SSR Error]', error.message);
+    },
+    onShellReady: () => {
+        console.log('Shell rendered');
+    },
+});
+```
+
+**Streaming SSR Example**:
+
+```typescript
+import { react } from '@flight-framework/ui/react';
+
+const adapter = react();
+
+// Component definition
+function App({ user }) {
+    return (
+        <main>
+            <h1>Welcome, {user.name}</h1>
+            <Suspense fallback={<Spinner />}>
+                <UserDashboard userId={user.id} />
+            </Suspense>
+        </main>
+    );
+}
+
+// Streaming render
+const { stream, done, abort } = adapter.renderToStream(
+    { component: App, props: { user } },
+    { url: request.url },
+    {
+        timeout: 10000,
+        onShellReady: () => {
+            // Send headers when shell is ready
+            response.writeHead(200, {
+                'Content-Type': 'text/html',
+                'Transfer-Encoding': 'chunked',
+            });
+        },
+        onError: (error) => {
+            console.error('[Stream Error]', error);
+        },
+    }
+);
+
+// Pipe stream to response
+const reader = stream.getReader();
+while (true) {
+    const { done: readerDone, value } = await reader.read();
+    if (readerDone) break;
+    response.write(value);
+}
+response.end();
+```
+
+**Islands Architecture**:
+
+```typescript
+const adapter = react();
+
+// Create an island for partial hydration
+const profileIsland = adapter.createIsland(
+    'UserProfile',
+    { userId: '123' },
+    {
+        hydrate: 'visible', // Hydrate when visible
+        priority: 10,
+    }
+);
+
+// Render island placeholder
+const html = `
+<div class="page">
+    <header>Static content</header>
+    ${profileIsland.placeholder}
+    <footer>Static content</footer>
+</div>
+`;
+```
+
+### Vue Adapter
+
+Vue 3 SSR adapter with streaming and islands support.
+
+**Basic Usage**:
+
+```typescript
+import { vue } from '@flight-framework/ui/vue';
+
+const adapter = vue({
+    streaming: true,
+});
+```
+
+**SSR Example**:
+
+```typescript
+import { vue } from '@flight-framework/ui/vue';
+import App from './App.vue';
+
+const adapter = vue();
+
+const result = await adapter.renderToString({
+    component: App,
+    props: { title: 'My Page' },
+});
+
+// result.html contains rendered HTML
+// result.hydrationData contains state for client
+```
+
+### Solid Adapter
+
+Solid SSR adapter with streaming support.
+
+```typescript
+import { solid } from '@flight-framework/ui/solid';
+
+const adapter = solid({
+    streaming: true,
+});
+
+// Streaming render
+const { stream, done } = adapter.renderToStream({
+    component: App,
+    props: { data },
+});
+```
+
+### Qwik Adapter
+
+Qwik adapter with resumable hydration support.
+
+**Resumability**: Qwik serializes component state to HTML, enabling zero-JS-until-interaction. This is the only Tier 1 adapter with `resumable: true`.
+
+```typescript
+import { qwik } from '@flight-framework/ui/qwik';
+
+const adapter = qwik();
+
+const result = await adapter.renderToString({
+    component: App,
+    props: { data },
+});
+
+// Serialize state for resumability
+const serialized = adapter.serializeState(result.hydrationData);
+
+// Resume on client (no JS needed until interaction)
+const state = adapter.resumeFromState(serialized);
+```
+
+---
+
+## Tier 2: Standard Support Adapters
+
+Tier 2 adapters provide SSR and hydration with framework-specific optimizations.
+
+### Available Adapters
+
+- Preact
+- Lit
+- Marko (with streaming)
+- Stencil
+- Mithril
+- Inferno
+
+### Preact Adapter
+
+Lightweight React alternative with smaller bundle size.
+
+```typescript
+import { preact } from '@flight-framework/ui/preact';
+
+const adapter = preact();
+
+const result = await adapter.renderToString({
+    component: App,
+    props: { count: 0 },
+});
+```
+
+### Lit Adapter
+
+Web Components SSR with declarative hydration.
+
+```typescript
+import { lit } from '@flight-framework/ui/lit';
+
+const adapter = lit();
+
+// Lit uses web components with shadow DOM
+const result = await adapter.renderToString({
+    component: 'my-element',
+    props: { data: 'value' },
+});
+```
+
+### Marko Adapter
+
+Streaming SSR with progressive enhancement.
+
+```typescript
+import { marko } from '@flight-framework/ui/marko';
+
+const adapter = marko();
+
+// Marko supports streaming out of the box
+const { stream, done } = adapter.renderToStream({
+    component: template,
+    props: { items },
+});
+```
+
+---
+
+## Tier 3: HTML-First Adapters
+
+Tier 3 adapters focus on server-rendered HTML with minimal JavaScript.
+
+### Available Adapters
+
+- HTMX
+- Alpine.js
+- Hotwire (Turbo + Stimulus)
+- Stimulus
+- Petite-vue
+- Vanilla (Pure Web Components)
+
+### HTMX Adapter
+
+Server-driven UI with HTML over the wire.
+
+**Philosophy**: HTMX keeps state on the server. Clicking a button sends a request, the server returns HTML, and HTMX swaps it into the DOM. No client-side JavaScript framework needed.
+
+**Basic Usage**:
+
+```typescript
+import { htmx } from '@flight-framework/ui/htmx';
+
+const adapter = htmx({
+    version: '2.0.2',
+    extensions: ['json-enc', 'loading-states'],
+});
+```
+
+**Template Helpers**:
+
+```typescript
+import { htmx, hxGet, hxPost, hx, attrsToString } from '@flight-framework/ui/htmx';
+
+// Create hx-get attributes
+const loadMoreAttrs = hxGet('/api/items?page=2', {
+    target: '#item-list',
+    swap: 'beforeend',
+    trigger: 'click',
+});
+
+// Build HTML with helpers
+const button = hx('button', loadMoreAttrs, 'Load More');
+// <button hx-get="/api/items?page=2" hx-target="#item-list" hx-swap="beforeend" hx-trigger="click">Load More</button>
+```
+
+**Full Page Example**:
+
+```typescript
+const adapter = htmx({
+    extensions: ['loading-states'],
+});
+
+function renderPage(items) {
+    return `
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Items</title>
+</head>
+<body>
+    <main>
+        <h1>Items</h1>
+        
+        <ul id="item-list">
+            ${items.map(item => `
+                <li>
+                    ${item.name}
+                    <button hx-delete="/api/items/${item.id}" 
+                            hx-target="closest li" 
+                            hx-swap="outerHTML"
+                            hx-confirm="Delete this item?">
+                        Delete
+                    </button>
+                </li>
+            `).join('')}
+        </ul>
+        
+        <form hx-post="/api/items" hx-target="#item-list" hx-swap="beforeend">
+            <input name="name" placeholder="New item" required />
+            <button type="submit">Add</button>
+        </form>
+    </main>
+    
+    ${adapter.getHydrationScript({ html: '' })}
+</body>
+</html>
+    `;
+}
+```
+
+### Alpine.js Adapter
+
+Declarative reactivity sprinkled on HTML.
+
+```typescript
+import { alpine, xData } from '@flight-framework/ui/alpine';
+
+const adapter = alpine({
+    plugins: ['intersect', 'persist'],
+});
+
+// x-data helper
+const counter = xData({ count: 0 }, `
+    <div>
+        <button @click="count++">Increment</button>
+        <span x-text="count"></span>
+    </div>
+`);
+```
+
+### Hotwire Adapter
+
+Turbo + Stimulus for server-rendered applications.
+
+```typescript
+import { hotwire } from '@flight-framework/ui/hotwire';
+
+const adapter = hotwire({
+    turbo: true,
+    stimulus: true,
+});
+```
+
+---
+
+## Advanced Patterns
+
+### Pattern 1: Multi-Framework Rendering
+
+Render different parts of your application with different frameworks.
+
+```typescript
+import { adapterRegistry, registerBuiltinAdapters } from '@flight-framework/ui';
+
+registerBuiltinAdapters();
+
+async function renderPage(request) {
+    // Use React for main content
+    const reactAdapter = await adapterRegistry.get('react');
+    const mainContent = await reactAdapter.renderToString({
+        component: MainApp,
+        props: { user },
+    });
+    
+    // Use HTMX for dynamic sidebar
+    const htmxAdapter = await adapterRegistry.get('htmx');
+    const sidebar = await htmxAdapter.renderToString({
+        component: () => `
+            <aside hx-get="/api/notifications" hx-trigger="every 30s">
+                Loading...
+            </aside>
+        `,
+        props: {},
+    });
+    
+    return `
+    <!DOCTYPE html>
+    <html>
+    <body>
+        <div id="main">${mainContent.html}</div>
+        ${sidebar.html}
+        ${reactAdapter.getHydrationScript(mainContent)}
+        ${htmxAdapter.getHydrationScript(sidebar)}
+    </body>
+    </html>
+    `;
+}
+```
+
+### Pattern 2: Progressive Enhancement
+
+Start with HTML, enhance with JavaScript where needed.
+
+```typescript
+import { htmx } from '@flight-framework/ui/htmx';
+import { react } from '@flight-framework/ui/react';
+
+// Render base page with HTMX
+const htmxAdapter = htmx();
+const basePage = await htmxAdapter.renderToString({
+    component: () => `
+        <main>
+            <article>${articleContent}</article>
+            
+            <!-- Island for interactive comments -->
+            <div id="comments-island" 
+                 data-flight-island="comments"
+                 data-props='${JSON.stringify({ articleId })}'>
+                <noscript>
+                    <!-- Fallback HTMX for no-JS -->
+                    <div hx-get="/api/comments/${articleId}" hx-trigger="load">
+                        Loading comments...
+                    </div>
+                </noscript>
+            </div>
+        </main>
+    `,
+    props: {},
+});
+
+// Hydrate React island on client
+// (handled by client-side code)
+```
+
+### Pattern 3: Capability-Based Adapter Selection
+
+Select adapters based on required capabilities.
+
+```typescript
+import { adapterRegistry, registerBuiltinAdapters } from '@flight-framework/ui';
+
+registerBuiltinAdapters();
+
+function getAdapterForFeatures(requirements) {
+    // List adapters with required capabilities
+    const streamingAdapters = adapterRegistry.listByCapability('streaming');
+    const islandAdapters = adapterRegistry.listByCapability('islands');
+    
+    if (requirements.streaming && requirements.islands) {
+        // Need both - find intersection
+        const both = streamingAdapters.filter(a => islandAdapters.includes(a));
+        return both[0] || 'react'; // Default to React
+    }
+    
+    if (requirements.streaming) {
+        return streamingAdapters[0] || 'react';
+    }
+    
+    if (requirements.islands) {
+        return islandAdapters[0] || 'react';
+    }
+    
+    // Default to lightweight option
+    return 'htmx';
+}
+
+const adapterId = getAdapterForFeatures({ streaming: true, islands: false });
+const adapter = await adapterRegistry.get(adapterId);
+```
+
+### Pattern 4: Error Boundaries with Streaming
+
+Handle errors gracefully during streaming SSR.
+
+```typescript
+import { react } from '@flight-framework/ui/react';
+
+const adapter = react();
+
+const { stream, done, abort } = adapter.renderToStream(
+    { component: App, props: {} },
+    { url: '/page' },
+    {
+        onShellError: (error) => {
+            // Shell failed - return error page
+            console.error('Shell error:', error);
+            abort();
+            return renderErrorPage(500);
+        },
+        onError: (error) => {
+            // Error in Suspense boundary - log but continue
+            console.error('Render error:', error);
+            // HTMX fallback for failed section
+        },
+        onAllReady: () => {
+            console.log('Page fully rendered');
+        },
+    }
+);
+```
+
+### Pattern 5: Caching SSR Results
+
+Cache rendered HTML for frequently accessed pages.
+
+```typescript
+import { react } from '@flight-framework/ui/react';
+
+const adapter = react();
+const cache = new Map();
+
+async function renderWithCache(cacheKey, component, props, ttl = 60000) {
+    const cached = cache.get(cacheKey);
+    if (cached && Date.now() - cached.time < ttl) {
+        return cached.result;
+    }
+    
+    const result = await adapter.renderToString({
+        component,
+        props,
+    });
+    
+    cache.set(cacheKey, {
+        result,
+        time: Date.now(),
+    });
+    
+    return result;
+}
+
+// Usage
+const html = await renderWithCache(
+    `product:${productId}`,
+    ProductPage,
+    { productId },
+    5 * 60 * 1000 // 5 minute TTL
+);
+```
+
+---
+
+## Creating Custom Adapters
+
+Extend `BaseUIAdapter` to create custom framework adapters.
+
+### Minimal Implementation
+
+```typescript
+import { BaseUIAdapter } from '@flight-framework/ui/core';
+import type { 
+    Component, 
+    RenderResult, 
+    RenderContext,
+    AdapterCapabilities 
+} from '@flight-framework/ui/core/types';
+
+export class MyFrameworkAdapter extends BaseUIAdapter {
+    readonly id = 'my-framework';
+    readonly name = 'My Framework';
+    readonly framework = 'my-framework';
+    readonly tier = 'tier-2' as const;
+
+    override readonly capabilities: AdapterCapabilities = {
+        streaming: false,
+        partialHydration: false,
+        islands: false,
+        resumable: false,
+        ssg: true,
+        csr: true,
+        serverComponents: false,
+    };
+
+    async renderToString(
+        component: Component,
+        context?: RenderContext
+    ): Promise<RenderResult> {
+        const startTime = performance.now();
+        
+        // Your framework's SSR logic
+        const html = await myFramework.render(
+            component.component,
+            component.props
+        );
+        
+        return {
+            html,
+            hydrationData: {
+                props: component.props,
+                componentId: this.generateId(),
+            },
+            timing: this.createTiming(startTime),
+        };
+    }
+
+    getHydrationScript(result: RenderResult): string {
+        return `
+<script>
+window.__FLIGHT_DATA__ = ${this.serializeProps(result.hydrationData)};
+// Your hydration initialization code
+</script>
+        `.trim();
+    }
+
+    getClientEntry(): string {
+        return `
+export function hydrate() {
+    const data = window.__FLIGHT_DATA__;
+    // Your hydration logic
+}
+        `.trim();
+    }
+}
+
+export function myFramework(): MyFrameworkAdapter {
+    return new MyFrameworkAdapter();
+}
+```
+
+### Adding Streaming Support
+
+```typescript
+import { StreamingRenderResult, StreamingOptions } from '@flight-framework/ui/core/types';
+
+export class MyStreamingAdapter extends BaseUIAdapter {
+    // ... base implementation ...
+
+    override readonly capabilities: AdapterCapabilities = {
+        streaming: true, // Enable streaming
+        // ... other capabilities
+    };
+
+    renderToStream(
+        component: Component,
+        context?: RenderContext,
+        options?: StreamingOptions
+    ): StreamingRenderResult {
+        let resolvePromise: () => void;
+        let rejectPromise: (error: Error) => void;
+        
+        const done = new Promise<void>((resolve, reject) => {
+            resolvePromise = resolve;
+            rejectPromise = reject;
+        });
+
+        const stream = new ReadableStream<Uint8Array>({
+            start: async (controller) => {
+                try {
+                    // Your streaming logic
+                    const chunks = myFramework.renderStream(component);
+                    
+                    for await (const chunk of chunks) {
+                        controller.enqueue(new TextEncoder().encode(chunk));
+                    }
+                    
+                    controller.close();
+                    resolvePromise();
+                } catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    options?.onError?.(err);
+                    controller.error(err);
+                    rejectPromise(err);
+                }
+            },
+        });
+
+        return {
+            stream,
+            done,
+            abort: () => {
+                resolvePromise();
+            },
+        };
+    }
+}
+```
+
+### Registering Custom Adapters
+
+```typescript
+import { adapterRegistry } from '@flight-framework/ui';
+import { myFramework } from './my-framework-adapter';
+
+// Register your adapter
+adapterRegistry.register('my-framework', () => myFramework());
+
+// Use it
+const adapter = await adapterRegistry.get('my-framework');
+```
+
+---
+
+## Performance Considerations
+
+### Streaming vs String Rendering
+
+| Approach | TTFB | Total Time | Memory | Use Case |
+|----------|------|------------|--------|----------|
+| renderToString | Slower | Faster | Higher | Small pages, caching |
+| renderToStream | Faster | Slightly slower | Lower | Large pages, real-time |
+
+**Recommendation**: Use streaming for pages with async data or Suspense boundaries.
+
+### Hydration Strategies
+
+| Strategy | Bundle Size | Interactivity | Best For |
+|----------|-------------|---------------|----------|
+| Full | Largest | Immediate | SPAs, complex UIs |
+| Progressive | Medium | Gradual | Content sites |
+| Islands | Smallest | Per-component | Mostly static sites |
+| None (HTMX) | Minimal | Server-roundtrip | CRUD applications |
+
+### Bundle Size by Tier
+
+| Tier | Typical JS Bundle | Example |
+|------|-------------------|---------|
+| Tier 1 | 50-150 KB | React, Vue, Angular |
+| Tier 2 | 10-50 KB | Preact, Lit, Inferno |
+| Tier 3 | 0-15 KB | HTMX, Alpine |
+
+---
+
+## Migration Guide
+
+### From React to Preact
+
+```diff
+- import { react } from '@flight-framework/ui/react';
++ import { preact } from '@flight-framework/ui/preact';
+
+- export default defineUI(react());
++ export default defineUI(preact());
+```
+
+Component compatibility: Most React components work in Preact. Check for:
+- Class components (prefer functional)
+- React-specific hooks (useId, useSyncExternalStore)
+- Concurrent features (Suspense for data)
+
+### From Vue to Svelte
+
+Both have similar reactivity models but different syntax.
+
+```diff
+- import { vue } from '@flight-framework/ui/vue';
++ import { svelte } from '@flight-framework/ui/svelte';
+
+- export default defineUI(vue());
++ export default defineUI(svelte());
+```
+
+### From Any Framework to HTMX
+
+For applications that can move state to the server:
+
+1. Identify interactive sections
+2. Replace with `hx-*` attributes
+3. Create server endpoints for each interaction
+4. Remove client-side state management
+
+```diff
+- // React component with client state
+- function Counter() {
+-   const [count, setCount] = useState(0);
+-   return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+- }
+
++ // HTMX with server state
++ // Server endpoint: POST /api/counter increments session counter
++ function Counter({ count }) {
++   return `
++     <button hx-post="/api/counter" hx-swap="outerHTML">
++       ${count}
++     </button>
++   `;
++ }
+```
+
+---
+
+## API Reference
+
+### UIAdapterV2 Interface
+
+All adapters implement this interface.
+
+```typescript
+interface UIAdapterV2 {
+    // Identification
+    readonly id: string;
+    readonly name: string;
+    readonly framework: string;
+    readonly frameworkVersion?: string;
+    readonly tier: AdapterTier;
+    readonly capabilities: AdapterCapabilities;
+
+    // Core rendering (required)
+    renderToString(component: Component, context?: RenderContext): Promise<RenderResult>;
+    getHydrationScript(result: RenderResult): string;
+    getClientEntry(): string;
+
+    // Streaming (optional)
+    renderToStream?(component: Component, context?: RenderContext, options?: StreamingOptions): StreamingRenderResult;
+
+    // Islands (optional)
+    createIsland?(component: unknown, props?: Record<string, unknown>, options?: IslandOptions): Island;
+    hydrateIsland?(element: Element, island: Island): void;
+
+    // Resumability (optional)
+    serializeState?(state: unknown): string;
+    resumeFromState?(serialized: string): unknown;
+
+    // Lifecycle (optional)
+    init?(): Promise<void>;
+    dispose?(): Promise<void>;
+}
+```
+
+### AdapterCapabilities
+
+```typescript
+interface AdapterCapabilities {
+    streaming: boolean;        // renderToStream support
+    partialHydration: boolean; // Selective hydration
+    islands: boolean;          // Islands architecture
+    resumable: boolean;        // Qwik-style resumability
+    ssg: boolean;              // Static generation
+    csr: boolean;              // Client-side rendering
+    serverComponents: boolean; // RSC support
+}
+```
+
+### AdapterRegistry
+
+```typescript
+// Get adapter by ID
+const adapter = await adapterRegistry.get('react');
+
+// Check if adapter exists
+const hasVue = adapterRegistry.has('vue');
+
+// List adapters by tier
+const tier1 = adapterRegistry.listByTier('tier-1');
+
+// List adapters by capability
+const streaming = adapterRegistry.listByCapability('streaming');
+
+// Register custom adapter
+adapterRegistry.register('custom', () => new CustomAdapter());
+```