@flightdev/ui 2.0.0

package/src/adapters/tier-3/vanilla.ts

@@ -0,0 +1,252 @@
+/**
+ * @flightdev/ui - Vanilla Web Components Adapter (Tier 3)
+ *
+ * Pure Web Components adapter - no framework, just standards.
+ *
+ * @module @flightdev/ui/vanilla
+ * @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 VanillaAdapterOptions {
+    /** Enable declarative shadow DOM */
+    declarativeShadowDom?: boolean;
+
+    /** Polyfill for older browsers */
+    polyfill?: boolean;
+}
+
+// ============================================================================
+// Vanilla Adapter
+// ============================================================================
+
+export class VanillaAdapter extends BaseUIAdapter {
+    readonly id = 'vanilla';
+    readonly name = 'Vanilla Web Components';
+    readonly framework = 'vanilla';
+    readonly frameworkVersion = 'ES2022+';
+    readonly tier = 'tier-3' as const;
+
+    override readonly capabilities: AdapterCapabilities = {
+        streaming: false,
+        partialHydration: false,
+        islands: true, // Web Components ARE islands
+        resumable: false,
+        ssg: true,
+        csr: true,
+        serverComponents: false,
+    };
+
+    constructor(private options: VanillaAdapterOptions = {}) {
+        super();
+    }
+
+    async renderToString(
+        component: Component,
+        _context?: RenderContext
+    ): Promise<RenderResult> {
+        const startTime = performance.now();
+
+        let html: string;
+
+        if (typeof component.component === 'string') {
+            // Component is a tag name
+            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(' ');
+
+            html = `<${tagName} ${attrs}></${tagName}>`;
+        } else if (typeof component.component === 'function') {
+            html = (component.component as (props: unknown) => string)(component.props ?? {});
+        } else {
+            throw new Error(
+                '[Flight/Vanilla] Components must be tag names or template functions.'
+            );
+        }
+
+        return {
+            html,
+            hydrationData: {
+                props: component.props,
+                componentId: component.id ?? this.generateId(),
+            },
+            timing: this.createTiming(startTime),
+        };
+    }
+
+    override createIsland(
+        component: unknown,
+        props?: Record<string, unknown>,
+        options?: IslandOptions
+    ): Island {
+        const tagName = component as string;
+        const id = this.generateId();
+
+        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}"
+    data-flight-hydrate="${options?.hydrate ?? 'load'}"
+></${tagName}>
+        `.trim();
+
+        return {
+            id,
+            component,
+            props,
+            options: options ?? { hydrate: 'load' },
+            placeholder,
+        };
+    }
+
+    override getHydrationScript(_result: RenderResult): string {
+        const { polyfill = false } = this.options;
+
+        let scripts = `
+<!-- Flight/Vanilla Web Components -->
+<script>
+window.__FLIGHT_ADAPTER__ = 'vanilla';
+</script>
+`;
+
+        if (polyfill) {
+            scripts += `
+<script src="https://unpkg.com/@webcomponents/webcomponentsjs@2.8.0/webcomponents-loader.js"></script>
+`;
+        }
+
+        return scripts.trim();
+    }
+
+    override getClientEntry(): string {
+        return `
+// Vanilla Web Components Client Entry
+// Components self-register when their scripts are loaded
+
+export function hydrate() {
+    // Web Components auto-upgrade when defined
+    console.log('[Flight/Vanilla] Web Components ready');
+}
+
+// Helper to define a custom element
+export function define(tagName, elementClass) {
+    if (!customElements.get(tagName)) {
+        customElements.define(tagName, elementClass);
+    }
+}
+
+// Wait for a component to be defined
+export function whenDefined(tagName) {
+    return customElements.whenDefined(tagName);
+}
+
+// Upgrade all elements matching a selector
+export function upgradeAll(selector = '*') {
+    document.querySelectorAll(selector).forEach(el => {
+        customElements.upgrade(el);
+    });
+}
+        `.trim();
+    }
+}
+
+// ============================================================================
+// Template Helpers
+// ============================================================================
+
+/**
+ * Create a custom element with declarative shadow DOM
+ */
+export function shadowRoot(content: string, mode: 'open' | 'closed' = 'open'): string {
+    return `<template shadowrootmode="${mode}">${content}</template>`;
+}
+
+/**
+ * Create a slot element
+ */
+export function slot(name?: string): string {
+    return name ? `<slot name="${name}"></slot>` : '<slot></slot>';
+}
+
+/**
+ * Create a basic custom element class string (for inline scripts)
+ */
+export function createElementClass(tagName: string, options: {
+    connectedCallback?: string;
+    observedAttributes?: string[];
+    template?: string;
+} = {}): string {
+    const className = tagName
+        .split('-')
+        .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+        .join('');
+
+    return `
+class ${className} extends HTMLElement {
+    ${options.observedAttributes ? `static observedAttributes = ${JSON.stringify(options.observedAttributes)};` : ''}
+    
+    constructor() {
+        super();
+        ${options.template ? `
+        this.attachShadow({ mode: 'open' });
+        this.shadowRoot.innerHTML = \`${options.template}\`;
+        ` : ''}
+    }
+    
+    connectedCallback() {
+        ${options.connectedCallback ?? ''}
+    }
+}
+
+customElements.define('${tagName}', ${className});
+    `.trim();
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Create a Vanilla Web Components UI adapter.
+ *
+ * @example
+ * ```typescript
+ * import { vanilla } from '@flightdev/ui/vanilla';
+ * import { defineUI } from '@flightdev/ui';
+ *
+ * export default defineUI(vanilla({
+ *   declarativeShadowDom: true,
+ * }));
+ * ```
+ */
+export function vanilla(options?: VanillaAdapterOptions): VanillaAdapter {
+    return new VanillaAdapter(options);
+}
+
+export default vanilla;

package/src/ambient.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Type declarations for UI framework peer dependencies
+ * Following 2026 best practices: specific types instead of any
+ */
+
+// ============================================================================
+// Node.js Types (for SSR)
+// ============================================================================
+
+declare namespace NodeJS {
+    interface WritableStream {
+        write(chunk: unknown): boolean;
+        end(cb?: () => void): void;
+        on(event: string, listener: (...args: unknown[]) => void): this;
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+declare const Buffer: any;
+
+// ============================================================================
+// React
+// ============================================================================
+
+declare namespace React {
+    type ComponentType<P = object> = (props: P) => ReactNode;
+    type ReactNode = string | number | boolean | null | undefined | ReactElement;
+    interface ReactElement {
+        type: string | ComponentType;
+        props: Record<string, unknown>;
+        key: string | number | null;
+    }
+}
+
+declare module 'react' {
+    export type ComponentType<P = object> = React.ComponentType<P>;
+    export type ReactNode = React.ReactNode;
+    export type ReactElement = React.ReactElement;
+
+    export function createElement<P extends object>(
+        type: string | ComponentType<P>,
+        props?: P | null,
+        ...children: ReactNode[]
+    ): ReactElement;
+}
+
+declare module 'react-dom/server' {
+    import type { ReactElement } from 'react';
+
+    export function renderToString(element: ReactElement): string;
+    export function renderToStaticMarkup(element: ReactElement): string;
+
+    export interface PipeableStream {
+        pipe<T extends NodeJS.WritableStream>(destination: T): T;
+        abort(): void;
+    }
+
+    export interface RenderToPipeableStreamOptions {
+        onShellReady?: () => void;
+        onShellError?: (error: Error) => void;
+        onAllReady?: () => void;
+        onError?: (error: Error) => void;
+    }
+
+    export function renderToPipeableStream(
+        element: ReactElement,
+        options?: RenderToPipeableStreamOptions
+    ): PipeableStream;
+
+    // Web Streams API version (for Node.js 18+, Deno, Edge runtimes)
+    export interface RenderToReadableStreamOptions {
+        signal?: AbortSignal;
+        onError?: (error: unknown) => void;
+        nonce?: string;
+        bootstrapScriptContent?: string;
+        bootstrapScripts?: string[];
+        bootstrapModules?: string[];
+    }
+
+    export function renderToReadableStream(
+        element: ReactElement,
+        options?: RenderToReadableStreamOptions
+    ): Promise<ReadableStream<Uint8Array>>;
+}
+
+declare module 'react-dom/client' {
+    import type { ReactElement } from 'react';
+
+    export interface Root {
+        render(children: ReactElement): void;
+        unmount(): void;
+    }
+
+    export function hydrateRoot(container: Element | null, children: ReactElement): Root;
+    export function createRoot(container: Element | null): Root;
+}
+
+// ============================================================================
+// Vue 3
+// ============================================================================
+
+declare module 'vue' {
+    export interface App<T = unknown> {
+        mount(selector: string | Element): T;
+        unmount(): void;
+    }
+
+    export type Component = object;
+
+    export function createSSRApp(rootComponent: Component, rootProps?: object): App;
+    export function createApp(rootComponent: Component, rootProps?: object): App;
+}
+
+declare module 'vue/server-renderer' {
+    import type { App } from 'vue';
+
+    export function renderToString(app: App): Promise<string>;
+    export function renderToWebStream(app: App): ReadableStream<Uint8Array>;
+}
+
+// ============================================================================
+// Angular
+// ============================================================================
+
+declare module '@angular/platform-server' {
+    export function renderApplication(
+        bootstrap: (document: string, url: string) => Promise<unknown>,
+        options: { document: string; url: string }
+    ): Promise<string>;
+}
+
+declare module '@angular/platform-browser' {
+    export function provideClientHydration(...features: unknown[]): unknown;
+    export function withIncrementalHydration(): unknown;
+    export function withEventReplay(): unknown;
+}
+
+// ============================================================================
+// Solid.js
+// ============================================================================
+
+declare module 'solid-js' {
+    export type JSXElement = object;
+}
+
+declare module 'solid-js/web' {
+    export function renderToString(fn: () => object): Promise<string>;
+    export function hydrate(fn: () => object, node: Element | null): void;
+    export function render(fn: () => object, node: Element | null): void;
+
+    export interface StreamResult {
+        readable: ReadableStream<Uint8Array>;
+        done: Promise<void>;
+    }
+
+    export function renderToStream(fn: () => object): StreamResult;
+}
+
+// ============================================================================
+// Svelte
+// ============================================================================
+
+declare module 'svelte' {
+    export interface SvelteComponent {
+        render(props?: object): {
+            html: string;
+            head?: string;
+            css?: { code: string };
+        };
+    }
+
+    export function mount<T>(
+        component: T,
+        options: { target: Element; props?: object }
+    ): unknown;
+
+    export function hydrate<T>(
+        component: T,
+        options: { target: Element; props?: object }
+    ): unknown;
+}
+
+declare module 'svelte/server' {
+    export function render<T>(
+        component: T,
+        options: { props?: object }
+    ): { body: string; head: string };
+}
+
+// ============================================================================
+// Qwik
+// ============================================================================
+
+declare module '@builder.io/qwik/server' {
+    export interface RenderToStringResult {
+        html: string;
+    }
+
+    export function renderToString(
+        component: () => unknown,
+        options?: { containerTagName?: string }
+    ): Promise<RenderToStringResult>;
+}
+
+// ============================================================================
+// Tier 2 Frameworks
+// ============================================================================
+
+declare namespace preact {
+    type FunctionComponent<P = object> = (props: P) => unknown;
+}
+
+declare module 'preact' {
+    export function h(
+        type: string | preact.FunctionComponent,
+        props?: object,
+        ...children: unknown[]
+    ): object;
+}
+
+declare module 'preact-render-to-string' {
+    export default function renderToString(vnode: object): string;
+    export function renderToString(vnode: object): string;
+}
+
+declare module 'lit' {
+    export function html(strings: TemplateStringsArray, ...values: unknown[]): unknown;
+}
+
+declare module '@lit-labs/ssr' {
+    export function render(template: unknown): Iterable<string>;
+}
+
+declare module '@lit-labs/ssr/lib/render-result.js' {
+    export function collectResult(result: Iterable<string>): Promise<string>;
+}
+
+declare module 'marko' { }
+
+declare module '@stencil/core/hydrate' {
+    export interface RenderToStringResult {
+        html: string;
+        diagnostics: unknown[];
+    }
+
+    export interface RenderToStringOptions {
+        fullDocument?: boolean;
+        serializeShadowRoot?: 'declarative-shadow-dom' | undefined;
+        prettyHtml?: boolean;
+    }
+
+    export function renderToString(
+        html: string,
+        options?: RenderToStringOptions
+    ): Promise<RenderToStringResult>;
+}
+
+declare namespace mithril {
+    type Component<P = object> = {
+        view: (vnode: { attrs: P }) => unknown;
+    };
+}
+
+declare module 'mithril' {
+    export default function m(
+        selector: string | mithril.Component,
+        attrs?: object,
+        ...children: unknown[]
+    ): object;
+}
+
+declare module 'mithril-node-render' {
+    export default function render(vnode: object): Promise<string>;
+}
+
+declare namespace inferno {
+    type Component<P = object> = (props: P) => unknown;
+}
+
+declare module 'inferno-server' {
+    export function renderToString(element: object): string;
+}
+
+declare module 'inferno-create-element' {
+    export function createElement(
+        type: string | inferno.Component,
+        props?: object,
+        ...children: unknown[]
+    ): object;
+}
+
+declare module 'inferno-hydrate' {
+    export function hydrate(element: object, container: Element | null): void;
+}
+
+declare module 'inferno' {
+    export function render(element: object, container: Element | null): void;
+}
+
+// ============================================================================
+// Stream (Node.js)
+// ============================================================================
+
+declare module 'stream' {
+    export class Readable {
+        constructor(options?: { read?: () => void });
+        on(event: string, listener: (...args: unknown[]) => void): this;
+        pipe<T>(destination: T): T;
+    }
+}