@flightdev/ui 2.0.1 → 4.0.0

package/docs/ADAPTERS.md

@@ -1,946 +0,0 @@
-# UI Adapter System
-
-This document provides comprehensive documentation for the `@flightdev/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 '@flightdev/ui';
-import { react } from '@flightdev/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 '@flightdev/ui';
-import { react } from '@flightdev/ui/react';
-
-export default defineUI(react());
-```
-
-**With Options**:
-
-```typescript
-import { react } from '@flightdev/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 '@flightdev/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 '@flightdev/ui/vue';
-
-const adapter = vue({
-    streaming: true,
-});
-```
-
-**SSR Example**:
-
-```typescript
-import { vue } from '@flightdev/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 '@flightdev/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 '@flightdev/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 '@flightdev/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 '@flightdev/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 '@flightdev/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 '@flightdev/ui/htmx';
-
-const adapter = htmx({
-    version: '2.0.2',
-    extensions: ['json-enc', 'loading-states'],
-});
-```
-
-**Template Helpers**:
-
-```typescript
-import { htmx, hxGet, hxPost, hx, attrsToString } from '@flightdev/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 '@flightdev/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 '@flightdev/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 '@flightdev/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 '@flightdev/ui/htmx';
-import { react } from '@flightdev/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 '@flightdev/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 '@flightdev/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 '@flightdev/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 '@flightdev/ui/core';
-import type { 
-    Component, 
-    RenderResult, 
-    RenderContext,
-    AdapterCapabilities 
-} from '@flightdev/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 '@flightdev/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 '@flightdev/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 '@flightdev/ui/react';
-+ import { preact } from '@flightdev/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 '@flightdev/ui/vue';
-+ import { svelte } from '@flightdev/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());
-```