@flightdev/ui 2.0.0

package/src/adapters/tier-2/lit.ts

@@ -0,0 +1,191 @@
+/**
+ * @flightdev/ui - Lit Adapter (Tier 2)
+ *
+ * Lit Web Components adapter with SSR support.
+ *
+ * @module @flightdev/ui/lit
+ * @version 2.0.0
+ */
+
+import { BaseUIAdapter } from '../../core/adapter.js';
+import type {
+    AdapterCapabilities,
+    Component,
+    RenderContext,
+    RenderResult,
+    Island,
+    IslandOptions,
+} from '../../core/types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface LitAdapterOptions {
+    /** Enable declarative shadow DOM */
+    declarativeShadowDom?: boolean;
+
+    /** Defer hydration */
+    deferHydration?: boolean;
+}
+
+// ============================================================================
+// Lit Adapter
+// ============================================================================
+
+export class LitAdapter extends BaseUIAdapter {
+    readonly id = 'lit';
+    readonly name = 'Lit';
+    readonly framework = 'lit';
+    readonly frameworkVersion = '3+';
+    readonly tier = 'tier-2' as const;
+
+    override readonly capabilities: AdapterCapabilities = {
+        streaming: false,
+        partialHydration: true,
+        islands: true,
+        resumable: false,
+        ssg: true,
+        csr: true,
+        serverComponents: false,
+    };
+
+    constructor(private options: LitAdapterOptions = {}) {
+        super();
+    }
+
+    async renderToString(
+        component: Component,
+        _context?: RenderContext
+    ): Promise<RenderResult> {
+        const startTime = performance.now();
+
+        try {
+            const { render } = await import('@lit-labs/ssr');
+            const { html } = await import('lit');
+            const { collectResult } = await import('@lit-labs/ssr/lib/render-result.js');
+
+            // Component should be a Lit element tag or template
+            let template;
+
+            if (typeof component.component === 'string') {
+                // Tag name - create template
+                const tagName = component.component;
+                const props = component.props ?? {};
+
+                const attrs = Object.entries(props)
+                    .map(([key, value]) => {
+                        const attrName = key.replace(/([A-Z])/g, '-$1').toLowerCase();
+                        return `${attrName}="${this.escapeHtml(String(value))}"`;
+                    })
+                    .join(' ');
+
+                // Use lit html template
+                template = html`<${tagName} ${attrs}></${tagName}>`;
+            } else if (typeof component.component === 'function') {
+                // Template function
+                template = (component.component as (props: unknown) => unknown)(component.props ?? {});
+            } else {
+                template = component.component;
+            }
+
+            const ssrResult = render(template);
+            const htmlString = await collectResult(ssrResult);
+
+            return {
+                html: htmlString,
+                hydrationData: {
+                    props: component.props,
+                    componentId: component.id ?? this.generateId(),
+                },
+                timing: this.createTiming(startTime),
+            };
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+
+            if (message.includes("Cannot find module '@lit-labs/ssr'")) {
+                throw new Error(
+                    '[Flight/Lit] Lit SSR package not found.\n' +
+                    'Install required packages:\n' +
+                    '  npm install lit @lit-labs/ssr'
+                );
+            }
+
+            throw error;
+        }
+    }
+
+    override createIsland(
+        component: unknown,
+        props?: Record<string, unknown>,
+        options?: IslandOptions
+    ): Island {
+        const tagName = component as string;
+        const id = this.generateId();
+        const deferHydration = this.options.deferHydration ?? false;
+
+        const attrs = Object.entries(props ?? {})
+            .map(([key, value]) => {
+                const attrName = key.replace(/([A-Z])/g, '-$1').toLowerCase();
+                return `${attrName}="${this.escapeHtml(String(value))}"`;
+            })
+            .join(' ');
+
+        const placeholder = `
+<${tagName} 
+    ${attrs}
+    data-flight-island="${id}"
+    ${deferHydration ? 'defer-hydration' : ''}
+></${tagName}>
+        `.trim();
+
+        return {
+            id,
+            component,
+            props,
+            options: options ?? { hydrate: 'load' },
+            placeholder,
+        };
+    }
+
+    override getHydrationScript(result: RenderResult): string {
+        const data = this.serializeProps(result.hydrationData);
+        return `
+<script type="module">
+window.__FLIGHT_DATA__ = ${data};
+window.__FLIGHT_ADAPTER__ = 'lit';
+
+// Lit components hydrate when their definition is loaded
+// If using defer-hydration, call removeAttribute('defer-hydration')
+document.querySelectorAll('[defer-hydration]').forEach(el => {
+    el.removeAttribute('defer-hydration');
+});
+</script>
+        `.trim();
+    }
+
+    override getClientEntry(): string {
+        return `
+// Lit Client Entry
+// Lit components self-hydrate when their definitions are loaded
+
+export function hydrate() {
+    // Remove defer-hydration attributes to trigger hydration
+    document.querySelectorAll('[defer-hydration]').forEach(el => {
+        el.removeAttribute('defer-hydration');
+    });
+    console.log('[Flight/Lit] Components hydrated');
+}
+        `.trim();
+    }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+export function lit(options?: LitAdapterOptions): LitAdapter {
+    return new LitAdapter(options);
+}
+
+export default lit;

package/src/adapters/tier-2/marko.ts

@@ -0,0 +1,199 @@
+/**
+ * @flightdev/ui - Marko Adapter (Tier 2)
+ *
+ * Marko adapter with streaming SSR - pioneered by eBay.
+ *
+ * @module @flightdev/ui/marko
+ * @version 2.0.0
+ */
+
+import { BaseUIAdapter } from '../../core/adapter.js';
+import type {
+    AdapterCapabilities,
+    Component,
+    RenderContext,
+    RenderResult,
+    StreamingOptions,
+    StreamingRenderResult,
+} from '../../core/types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Marko template interface
+ */
+export interface MarkoTemplate {
+    render(input: Record<string, unknown>): MarkoRenderResult;
+    renderToString(input: Record<string, unknown>): Promise<string>;
+}
+
+export interface MarkoRenderResult {
+    toString(): Promise<string>;
+    pipe(stream: NodeJS.WritableStream): void;
+    on(event: 'data', callback: (chunk: Uint8Array) => void): void;
+    on(event: 'end', callback: () => void): void;
+    on(event: 'error', callback: (error: Error) => void): void;
+}
+
+export interface MarkoAdapterOptions {
+    /** Enable streaming SSR */
+    streaming?: boolean;
+
+    /** Global template data */
+    globalData?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Marko Adapter
+// ============================================================================
+
+export class MarkoAdapter extends BaseUIAdapter {
+    readonly id = 'marko';
+    readonly name = 'Marko';
+    readonly framework = 'marko';
+    readonly frameworkVersion = '5+';
+    readonly tier = 'tier-2' as const;
+
+    override readonly capabilities: AdapterCapabilities = {
+        streaming: true, // Marko pioneered streaming SSR!
+        partialHydration: true,
+        islands: true,
+        resumable: false,
+        ssg: true,
+        csr: true,
+        serverComponents: false,
+    };
+
+    constructor(private options: MarkoAdapterOptions = {}) {
+        super();
+    }
+
+    async renderToString(
+        component: Component,
+        _context?: RenderContext
+    ): Promise<RenderResult> {
+        const startTime = performance.now();
+
+        const template = component.component as MarkoTemplate;
+        const input = {
+            ...this.options.globalData,
+            ...component.props,
+        };
+
+        const html = await template.renderToString(input);
+
+        return {
+            html,
+            hydrationData: {
+                props: component.props,
+                componentId: component.id ?? this.generateId(),
+            },
+            timing: this.createTiming(startTime),
+        };
+    }
+
+    renderToStream(
+        component: Component,
+        _context?: RenderContext,
+        options?: StreamingOptions
+    ): StreamingRenderResult {
+        let aborted = false;
+        let resolvePromise: () => void;
+        let rejectPromise: (error: Error) => void;
+
+        const done = new Promise<void>((resolve, reject) => {
+            resolvePromise = resolve;
+            rejectPromise = reject;
+        });
+
+        const template = component.component as MarkoTemplate;
+        const input = {
+            ...this.options.globalData,
+            ...component.props,
+        };
+
+        const stream = new ReadableStream<Uint8Array>({
+            start(controller) {
+                const out = template.render(input);
+
+                options?.onShellReady?.();
+
+                out.on('data', (chunk: Uint8Array) => {
+                    if (!aborted) {
+                        controller.enqueue(new Uint8Array(chunk));
+                    }
+                });
+
+                out.on('end', () => {
+                    if (!aborted) {
+                        controller.close();
+                        resolvePromise();
+                        options?.onAllReady?.();
+                    }
+                });
+
+                out.on('error', (error: Error) => {
+                    options?.onError?.(error);
+                    controller.error(error);
+                    rejectPromise(error);
+                });
+            },
+        });
+
+        return {
+            stream,
+            done,
+            abort() {
+                aborted = true;
+                resolvePromise();
+            },
+        };
+    }
+
+    override getHydrationScript(result: RenderResult): string {
+        const data = this.serializeProps(result.hydrationData);
+        return `
+<script type="module">
+window.__FLIGHT_DATA__ = ${data};
+window.__FLIGHT_ADAPTER__ = 'marko';
+// Marko handles hydration via inline component scripts
+</script>
+        `.trim();
+    }
+
+    override getClientEntry(): string {
+        return `
+// Marko Client Entry
+// Marko components are self-hydrating
+
+export function hydrate() {
+    // Marko components automatically hydrate themselves
+    // No additional client-side setup needed
+    console.log('[Flight/Marko] Components are self-hydrating');
+}
+        `.trim();
+    }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Create a Marko UI adapter.
+ *
+ * @example
+ * ```typescript
+ * import { marko } from '@flightdev/ui/marko';
+ * import { defineUI } from '@flightdev/ui';
+ *
+ * export default defineUI(marko({ streaming: true }));
+ * ```
+ */
+export function marko(options?: MarkoAdapterOptions): MarkoAdapter {
+    return new MarkoAdapter(options);
+}
+
+export default marko;

package/src/adapters/tier-2/mithril.ts

@@ -0,0 +1,152 @@
+/**
+ * @flightdev/ui - Mithril Adapter (Tier 2)
+ *
+ * Mithril.js adapter - ultra-lightweight (9kb) SPA framework.
+ *
+ * @module @flightdev/ui/mithril
+ * @version 2.0.0
+ */
+
+import { BaseUIAdapter } from '../../core/adapter.js';
+import type {
+    AdapterCapabilities,
+    Component,
+    RenderContext,
+    RenderResult,
+} from '../../core/types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface MithrilAdapterOptions {
+    /** Enable strict mode */
+    strict?: boolean;
+}
+
+// ============================================================================
+// Mithril Adapter
+// ============================================================================
+
+export class MithrilAdapter extends BaseUIAdapter {
+    readonly id = 'mithril';
+    readonly name = 'Mithril';
+    readonly framework = 'mithril';
+    readonly frameworkVersion = '2+';
+    readonly tier = 'tier-2' as const;
+
+    override readonly capabilities: AdapterCapabilities = {
+        streaming: false,
+        partialHydration: false,
+        islands: false,
+        resumable: false,
+        ssg: true,
+        csr: true,
+        serverComponents: false,
+    };
+
+    constructor(private options: MithrilAdapterOptions = {}) {
+        super();
+    }
+
+    async renderToString(
+        component: Component,
+        _context?: RenderContext
+    ): Promise<RenderResult> {
+        const startTime = performance.now();
+
+        try {
+            // mithril-node-render for SSR
+            const render = await import('mithril-node-render')
+                .then((m) => m.default || m);
+            const m = await import('mithril').then((mod) => mod.default || mod);
+
+            const MithrilComponent = component.component as mithril.Component;
+            const vnode = m(MithrilComponent, component.props ?? {});
+
+            const html = await render(vnode);
+
+            return {
+                html,
+                hydrationData: {
+                    props: component.props,
+                    componentId: component.id ?? this.generateId(),
+                },
+                timing: this.createTiming(startTime),
+            };
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+
+            if (message.includes("Cannot find module 'mithril-node-render'")) {
+                throw new Error(
+                    '[Flight/Mithril] Mithril SSR package not found.\n' +
+                    'Install required packages:\n' +
+                    '  npm install mithril mithril-node-render\n' +
+                    '  npm install -D @types/mithril'
+                );
+            }
+
+            throw error;
+        }
+    }
+
+    override getHydrationScript(result: RenderResult): string {
+        const data = this.serializeProps(result.hydrationData);
+        return `
+<script type="module">
+window.__FLIGHT_DATA__ = ${data};
+window.__FLIGHT_ADAPTER__ = 'mithril';
+
+import m from 'mithril';
+
+const App = window.__FLIGHT_APP__;
+const container = document.getElementById('app');
+
+if (App && container) {
+    // Mithril mounts and diffs against existing DOM
+    m.mount(container, {
+        view: () => m(App, window.__FLIGHT_DATA__.props)
+    });
+}
+</script>
+        `.trim();
+    }
+
+    override getClientEntry(): string {
+        return `
+import m from 'mithril';
+
+export function hydrate() {
+    const container = document.getElementById('app');
+    const App = window.__FLIGHT_APP__;
+    const data = window.__FLIGHT_DATA__ ?? {};
+
+    if (!container || !App) {
+        console.warn('[Flight/Mithril] Missing container or App');
+        return;
+    }
+
+    // Mithril automatically diffs against existing DOM
+    m.mount(container, {
+        view: () => m(App, data.props)
+    });
+}
+
+export function render(App, container, props = {}) {
+    m.mount(container, {
+        view: () => m(App, props)
+    });
+}
+        `.trim();
+    }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+export function mithril(options?: MithrilAdapterOptions): MithrilAdapter {
+    return new MithrilAdapter(options);
+}
+
+export default mithril;

package/src/adapters/tier-2/preact.ts

@@ -0,0 +1,133 @@
+/**
+ * @flightdev/ui - Preact Adapter (Tier 2)
+ *
+ * Preact adapter - lightweight React alternative (3kb).
+ *
+ * @module @flightdev/ui/preact
+ * @version 2.0.0
+ */
+
+import { BaseUIAdapter } from '../../core/adapter.js';
+import type {
+    AdapterCapabilities,
+    Component,
+    RenderContext,
+    RenderResult,
+} from '../../core/types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PreactAdapterOptions {
+    /** Enable preact/compat for React compatibility */
+    compat?: boolean;
+
+    /** Pretty print HTML */
+    pretty?: boolean;
+}
+
+// ============================================================================
+// Preact Adapter
+// ============================================================================
+
+export class PreactAdapter extends BaseUIAdapter {
+    readonly id = 'preact';
+    readonly name = 'Preact';
+    readonly framework = 'preact';
+    readonly frameworkVersion = '10+';
+    readonly tier = 'tier-2' as const;
+
+    override readonly capabilities: AdapterCapabilities = {
+        streaming: false,
+        partialHydration: true,
+        islands: true,
+        resumable: false,
+        ssg: true,
+        csr: true,
+        serverComponents: false,
+    };
+
+    constructor(private options: PreactAdapterOptions = {}) {
+        super();
+    }
+
+    async renderToString(
+        component: Component,
+        _context?: RenderContext
+    ): Promise<RenderResult> {
+        const startTime = performance.now();
+
+        const renderToString = await import('preact-render-to-string')
+            .then((m) => m.default || m.renderToString);
+        const { h } = await import('preact');
+
+        const PreactComponent = component.component as preact.FunctionComponent;
+        const element = h(PreactComponent, component.props ?? {});
+
+        const html = renderToString(element);
+
+        return {
+            html,
+            hydrationData: {
+                props: component.props,
+                componentId: component.id ?? this.generateId(),
+            },
+            timing: this.createTiming(startTime),
+        };
+    }
+
+    override getHydrationScript(result: RenderResult): string {
+        const data = this.serializeProps(result.hydrationData);
+        return `
+<script type="module">
+window.__FLIGHT_DATA__ = ${data};
+window.__FLIGHT_ADAPTER__ = 'preact';
+
+import { h, hydrate } from 'preact';
+
+const App = window.__FLIGHT_APP__;
+const container = document.getElementById('app');
+
+if (App && container) {
+    hydrate(h(App, window.__FLIGHT_DATA__.props), container);
+}
+</script>
+        `.trim();
+    }
+
+    override getClientEntry(): string {
+        return `
+import { h, hydrate, render } from 'preact';
+
+export function hydrateApp() {
+    const container = document.getElementById('app');
+    const App = window.__FLIGHT_APP__;
+    const data = window.__FLIGHT_DATA__ ?? {};
+
+    if (!container || !App) {
+        console.warn('[Flight/Preact] Missing container or App');
+        return;
+    }
+
+    if (container.innerHTML.trim()) {
+        hydrate(h(App, data.props), container);
+    } else {
+        render(h(App, data.props), container);
+    }
+}
+
+export { hydrateApp as hydrate };
+        `.trim();
+    }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+export function preact(options?: PreactAdapterOptions): PreactAdapter {
+    return new PreactAdapter(options);
+}
+
+export default preact;