@flightdev/ui 2.0.0

package/src/core/adapter.ts

@@ -0,0 +1,366 @@
+/**
+ * @flightdev/ui - Base Adapter Class
+ *
+ * Abstract base class providing common functionality for all UI adapters.
+ * Extend this class to create new framework adapters.
+ *
+ * @module @flightdev/ui/core/adapter
+ * @version 2.0.0
+ */
+
+import type {
+    UIAdapterV2,
+    UIAdapterV1,
+    AdapterTier,
+    AdapterCapabilities,
+    Component,
+    RenderContext,
+    RenderResult,
+    StreamingOptions,
+    StreamingRenderResult,
+    Island,
+    IslandOptions,
+    DEFAULT_CAPABILITIES,
+} from './types.js';
+
+// ============================================================================
+// Base Adapter Class
+// ============================================================================
+
+/**
+ * Abstract base class for UI adapters.
+ *
+ * Provides common functionality and sensible defaults.
+ * Subclasses must implement the abstract methods.
+ *
+ * @example
+ * ```typescript
+ * class MyAdapter extends BaseUIAdapter {
+ *   readonly id = 'my-framework';
+ *   readonly name = 'My Framework';
+ *   readonly framework = 'my-framework';
+ *   readonly tier = 'tier-2';
+ *
+ *   async renderToString(component: Component): Promise<RenderResult> {
+ *     // Implementation
+ *   }
+ * }
+ * ```
+ */
+export abstract class BaseUIAdapter implements UIAdapterV2 {
+    // === Abstract Properties (Must Override) ===
+
+    abstract readonly id: string;
+    abstract readonly name: string;
+    abstract readonly framework: string;
+    abstract readonly tier: AdapterTier;
+
+    // === Default Capabilities (Override as needed) ===
+
+    readonly capabilities: AdapterCapabilities = {
+        streaming: false,
+        partialHydration: false,
+        islands: false,
+        resumable: false,
+        ssg: true,
+        csr: true,
+        serverComponents: false,
+    };
+
+    readonly frameworkVersion?: string;
+
+    // === Abstract Methods (Must Implement) ===
+
+    abstract renderToString(
+        component: Component,
+        context?: RenderContext
+    ): Promise<RenderResult>;
+
+    // === Default Implementations ===
+
+    /**
+     * Generate hydration script.
+     * Override for framework-specific hydration.
+     */
+    getHydrationScript(result: RenderResult): string {
+        const data = JSON.stringify(result.hydrationData ?? {});
+        return `
+window.__FLIGHT_DATA__ = ${data};
+window.__FLIGHT_ADAPTER__ = '${this.id}';
+import('/flight-client.js').then(m => m.hydrate?.());
+        `.trim();
+    }
+
+    /**
+     * Get client entry point code.
+     * Override for framework-specific client initialization.
+     */
+    getClientEntry(): string {
+        return `
+// ${this.name} Client Entry
+// Override getClientEntry() in your adapter for custom behavior
+
+export function hydrate() {
+    console.log('[Flight] Hydrating with ${this.name}');
+    const data = window.__FLIGHT_DATA__;
+    const App = window.__FLIGHT_APP__;
+    
+    if (App && typeof App.mount === 'function') {
+        App.mount(document.getElementById('app'), data);
+    }
+}
+        `.trim();
+    }
+
+    // === Helper Methods (Available to all adapters) ===
+
+    /**
+     * Escape HTML entities to prevent XSS
+     */
+    protected escapeHtml(str: string): string {
+        const htmlEscapes: Record<string, string> = {
+            '&': '&amp;',
+            '<': '&lt;',
+            '>': '&gt;',
+            '"': '&quot;',
+            "'": '&#39;',
+        };
+        return str.replace(/[&<>"']/g, (char) => htmlEscapes[char] ?? char);
+    }
+
+    /**
+     * Serialize props to JSON for hydration
+     */
+    protected serializeProps(props: unknown): string {
+        if (props === undefined || props === null) {
+            return '{}';
+        }
+        try {
+            return JSON.stringify(props, this.jsonReplacer);
+        } catch {
+            console.warn(`[${this.id}] Failed to serialize props`);
+            return '{}';
+        }
+    }
+
+    /**
+     * JSON replacer for serialization
+     */
+    protected jsonReplacer(_key: string, value: unknown): unknown {
+        // Handle special types
+        if (value instanceof Map) {
+            return { __type: 'Map', data: Array.from(value.entries()) };
+        }
+        if (value instanceof Set) {
+            return { __type: 'Set', data: Array.from(value) };
+        }
+        if (value instanceof Date) {
+            return { __type: 'Date', data: value.toISOString() };
+        }
+        if (typeof value === 'bigint') {
+            return { __type: 'BigInt', data: value.toString() };
+        }
+        // Skip functions
+        if (typeof value === 'function') {
+            return undefined;
+        }
+        return value;
+    }
+
+    /**
+     * Create a hydration marker comment
+     */
+    protected createHydrationMarker(id: string, type: 'start' | 'end' = 'start'): string {
+        return `<!--flight:${type}:${id}-->`;
+    }
+
+    /**
+     * Wrap content with hydration markers
+     */
+    protected wrapWithMarkers(id: string, content: string): string {
+        return `${this.createHydrationMarker(id, 'start')}${content}${this.createHydrationMarker(id, 'end')}`;
+    }
+
+    /**
+     * Generate a unique component ID
+     */
+    protected generateId(): string {
+        return `f${Math.random().toString(36).slice(2, 9)}`;
+    }
+
+    /**
+     * Create timing information
+     */
+    protected createTiming(startTime: number): { total: number } {
+        return { total: performance.now() - startTime };
+    }
+
+    /**
+     * Merge render context with defaults
+     */
+    protected mergeContext(context?: RenderContext): RenderContext {
+        return {
+            url: '/',
+            ...context,
+        };
+    }
+
+    // === Optional Methods (Override if capability is enabled) ===
+
+    /**
+     * Render to stream (override if capabilities.streaming is true)
+     */
+    renderToStream?(
+        _component: Component,
+        _context?: RenderContext,
+        _options?: StreamingOptions
+    ): StreamingRenderResult;
+
+    /**
+     * Create an island (default implementation)
+     * Override for framework-specific island behavior.
+     */
+    createIsland(
+        component: unknown,
+        props?: Record<string, unknown>,
+        options?: IslandOptions
+    ): Island {
+        const id = this.generateId();
+        const componentName = typeof component === 'string' ? component : 'island-component';
+
+        return {
+            id,
+            component: componentName,
+            props: props ?? {},
+            placeholder: `<div data-island="${id}" data-component="${componentName}">Loading...</div>`,
+            options,
+        };
+    }
+
+    /**
+     * Hydrate an island on the client
+     */
+    hydrateIsland?(_element: Element, _island: Island): void;
+
+    /**
+     * Serialize state for resumability
+     */
+    serializeState?(state: unknown): string {
+        return this.serializeProps(state);
+    }
+
+    /**
+     * Resume from serialized state
+     */
+    resumeFromState?(serialized: string): unknown {
+        return JSON.parse(serialized, this.jsonReviver);
+    }
+
+    /**
+     * JSON reviver for deserialization
+     */
+    protected jsonReviver(_key: string, value: unknown): unknown {
+        if (value && typeof value === 'object' && '__type' in value) {
+            const typed = value as { __type: string; data: unknown };
+            switch (typed.__type) {
+                case 'Map':
+                    return new Map(typed.data as [unknown, unknown][]);
+                case 'Set':
+                    return new Set(typed.data as unknown[]);
+                case 'Date':
+                    return new Date(typed.data as string);
+                case 'BigInt':
+                    return BigInt(typed.data as string);
+            }
+        }
+        return value;
+    }
+
+    /**
+     * Initialize the adapter
+     */
+    async init(): Promise<void> {
+        // Override for custom initialization
+    }
+
+    /**
+     * Clean up resources
+     */
+    async dispose(): Promise<void> {
+        // Override for custom cleanup
+    }
+}
+
+// ============================================================================
+// V1 to V2 Adapter Wrapper
+// ============================================================================
+
+/**
+ * Wrap a V1 adapter to make it compatible with V2 interface.
+ *
+ * @example
+ * ```typescript
+ * const legacyAdapter = oldReact();
+ * const v2Adapter = wrapV1Adapter(legacyAdapter, 'tier-1');
+ * ```
+ */
+export function wrapV1Adapter(
+    v1Adapter: UIAdapterV1,
+    tier: AdapterTier = 'tier-2'
+): UIAdapterV2 {
+    return {
+        id: v1Adapter.name.toLowerCase().replace(/\s+/g, '-'),
+        name: v1Adapter.name,
+        framework: v1Adapter.framework,
+        tier,
+        capabilities: {
+            streaming: false,
+            partialHydration: false,
+            islands: false,
+            resumable: false,
+            ssg: true,
+            csr: true,
+            serverComponents: false,
+        },
+        renderToString: v1Adapter.renderToString.bind(v1Adapter),
+        getHydrationScript: v1Adapter.getHydrationScript.bind(v1Adapter),
+        getClientEntry: v1Adapter.getClientEntry.bind(v1Adapter),
+        transformForSSR: v1Adapter.transformForSSR?.bind(v1Adapter),
+    };
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Check if an adapter is V2 compatible
+ */
+export function isV2Adapter(adapter: unknown): adapter is UIAdapterV2 {
+    return (
+        adapter !== null &&
+        typeof adapter === 'object' &&
+        'id' in adapter &&
+        'tier' in adapter &&
+        'capabilities' in adapter
+    );
+}
+
+/**
+ * Check if an adapter supports a specific capability
+ */
+export function hasCapability(
+    adapter: UIAdapterV2,
+    capability: keyof AdapterCapabilities
+): boolean {
+    return adapter.capabilities[capability] === true;
+}
+
+/**
+ * Get all capabilities of an adapter as an array
+ */
+export function getCapabilities(adapter: UIAdapterV2): (keyof AdapterCapabilities)[] {
+    return (Object.entries(adapter.capabilities) as [keyof AdapterCapabilities, boolean][])
+        .filter(([, enabled]) => enabled)
+        .map(([capability]) => capability);
+}

package/src/core/index.ts

@@ -0,0 +1,56 @@
+/**
+ * @flightdev/ui - Core Module Index
+ *
+ * Core exports for the UI framework adapter system.
+ *
+ * @module @flightdev/ui/core
+ * @version 2.0.0
+ */
+
+// Types
+export type {
+    AdapterCapabilities,
+    AdapterTier,
+    TierInfo,
+    Component,
+    RenderContext,
+    RenderResult,
+    RenderTiming,
+    StreamingOptions,
+    StreamingRenderResult,
+    IslandHydrationStrategy,
+    IslandOptions,
+    Island,
+    UIAdapterV2,
+    UIAdapterV1,
+    UIAdapter,
+    UIConfig,
+    ComponentProps,
+    HasCapability,
+} from './types.js';
+
+export {
+    DEFAULT_CAPABILITIES,
+    TIER_INFO,
+} from './types.js';
+
+// Base Adapter
+export {
+    BaseUIAdapter,
+    wrapV1Adapter,
+    isV2Adapter,
+    hasCapability,
+    getCapabilities,
+} from './adapter.js';
+
+// Registry
+export type {
+    AdapterLoader,
+    AdapterMetadata,
+    RegistryQueryOptions,
+} from './registry.js';
+
+export {
+    adapterRegistry,
+    registerBuiltinAdapters,
+} from './registry.js';