@flightdev/ui 2.0.0

package/src/core/types.ts

@@ -0,0 +1,461 @@
+/**
+ * @flightdev/ui - Core Type Definitions
+ *
+ * Universal type system for all UI framework adapters.
+ * Supports SSR, streaming, islands architecture, and resumable hydration.
+ *
+ * @module @flightdev/ui/core/types
+ * @version 2.0.0
+ */
+
+// ============================================================================
+// Capability System
+// ============================================================================
+
+/**
+ * Adapter capabilities flags.
+ * Used for feature detection and optimization decisions.
+ */
+export interface AdapterCapabilities {
+    /** Supports streaming SSR via renderToStream */
+    streaming: boolean;
+
+    /** Supports partial/selective hydration */
+    partialHydration: boolean;
+
+    /** Supports islands architecture */
+    islands: boolean;
+
+    /** Supports resumable hydration (Qwik-style serialization) */
+    resumable: boolean;
+
+    /** Supports Static Site Generation */
+    ssg: boolean;
+
+    /** Supports Client-Side Rendering only */
+    csr: boolean;
+
+    /** Supports Server Components (React Server Components, etc) */
+    serverComponents: boolean;
+}
+
+/**
+ * Default capabilities for adapters that don't specify their own
+ */
+export const DEFAULT_CAPABILITIES: AdapterCapabilities = {
+    streaming: false,
+    partialHydration: false,
+    islands: false,
+    resumable: false,
+    ssg: true,
+    csr: true,
+    serverComponents: false,
+};
+
+// ============================================================================
+// Tier Classification
+// ============================================================================
+
+/**
+ * Adapter tier classification.
+ *
+ * - tier-1: Full support, first-class citizens (React, Vue, Angular, Svelte, Solid, Qwik)
+ * - tier-2: SSR + Hydration support (Preact, Lit, Marko, Stencil, Mithril, Inferno)
+ * - tier-3: HTML-first, minimal JS (HTMX, Alpine, Hotwire, Stimulus, Web Components)
+ */
+export type AdapterTier = 'tier-1' | 'tier-2' | 'tier-3';
+
+/**
+ * Tier metadata for documentation and tooling
+ */
+export interface TierInfo {
+    tier: AdapterTier;
+    name: string;
+    description: string;
+    features: string[];
+}
+
+export const TIER_INFO: Record<AdapterTier, TierInfo> = {
+    'tier-1': {
+        tier: 'tier-1',
+        name: 'Full Support',
+        description: 'Complete SSR, streaming, hydration, and advanced features',
+        features: ['SSR', 'Streaming', 'Hydration', 'Islands', 'DevTools'],
+    },
+    'tier-2': {
+        tier: 'tier-2',
+        name: 'Standard Support',
+        description: 'SSR and hydration with framework-specific optimizations',
+        features: ['SSR', 'Hydration', 'Partial Islands'],
+    },
+    'tier-3': {
+        tier: 'tier-3',
+        name: 'HTML-First',
+        description: 'Server-rendered HTML with minimal JavaScript enhancement',
+        features: ['SSR', 'Progressive Enhancement'],
+    },
+};
+
+// ============================================================================
+// Component & Rendering Types
+// ============================================================================
+
+/**
+ * Universal component wrapper type
+ */
+export interface Component<P = Record<string, unknown>> {
+    /** The actual component (React element, Vue component, HTML string, etc) */
+    component: unknown;
+
+    /** Props to pass to the component */
+    props?: P;
+
+    /** Slots/children content */
+    children?: unknown;
+
+    /** Component identifier for hydration */
+    id?: string;
+}
+
+/**
+ * Render context passed to adapters
+ */
+export interface RenderContext {
+    /** Current request URL */
+    url?: string;
+
+    /** Request headers */
+    headers?: Headers;
+
+    /** Server-side cookies */
+    cookies?: Map<string, string>;
+
+    /** Locale for i18n */
+    locale?: string;
+
+    /** Custom context data */
+    data?: Record<string, unknown>;
+
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+
+/**
+ * Result of a render operation
+ */
+export interface RenderResult {
+    /** The rendered HTML string */
+    html: string;
+
+    /** Head elements (meta, title, link, etc) */
+    head?: string;
+
+    /** Hydration data to pass to client */
+    hydrationData?: Record<string, unknown>;
+
+    /** CSS to inline in the document */
+    css?: string;
+
+    /** Scripts to inject */
+    scripts?: string[];
+
+    /** HTTP status code (for error pages, redirects) */
+    status?: number;
+
+    /** HTTP headers to set */
+    headers?: Record<string, string>;
+
+    /** Timing information for performance monitoring */
+    timing?: RenderTiming;
+}
+
+/**
+ * Render timing information
+ */
+export interface RenderTiming {
+    /** Total render time in milliseconds */
+    total: number;
+
+    /** Time to first byte */
+    ttfb?: number;
+
+    /** Component render times */
+    components?: Map<string, number>;
+}
+
+// ============================================================================
+// Streaming Types
+// ============================================================================
+
+/**
+ * Streaming render options
+ */
+export interface StreamingOptions {
+    /** Emit shell HTML before async content resolves */
+    emitShellEarly?: boolean;
+
+    /** Timeout for streaming (ms) */
+    timeout?: number;
+
+    /** Callback when shell is ready */
+    onShellReady?: () => void;
+
+    /** Callback when shell errors */
+    onShellError?: (error: Error) => void;
+
+    /** Callback when all content is ready */
+    onAllReady?: () => void;
+
+    /** Callback for each error during streaming */
+    onError?: (error: Error, errorInfo?: unknown) => void;
+}
+
+/**
+ * Streaming render result
+ */
+export interface StreamingRenderResult {
+    /** The readable stream of HTML chunks */
+    stream: ReadableStream<Uint8Array>;
+
+    /** Promise that resolves when streaming is complete */
+    done: Promise<void>;
+
+    /** Abort the stream */
+    abort: () => void;
+}
+
+// ============================================================================
+// Islands Architecture Types
+// ============================================================================
+
+/**
+ * Island hydration strategy
+ */
+export type IslandHydrationStrategy =
+    | 'load'           // Hydrate immediately on page load
+    | 'idle'           // Hydrate when browser is idle
+    | 'visible'        // Hydrate when island becomes visible
+    | 'media'          // Hydrate based on media query
+    | 'interaction'    // Hydrate on first interaction
+    | 'none';          // Never hydrate (static island)
+
+/**
+ * Island configuration options
+ */
+export interface IslandOptions {
+    /** Hydration strategy */
+    hydrate?: IslandHydrationStrategy;
+
+    /** For 'media' strategy: the media query */
+    media?: string;
+
+    /** For 'interaction' strategy: events to listen for */
+    on?: string[];
+
+    /** Island priority (higher = hydrate first) */
+    priority?: number;
+
+    /** Fallback content while loading */
+    fallback?: string;
+}
+
+/**
+ * Island definition
+ */
+export interface Island {
+    /** Unique island identifier */
+    id: string;
+
+    /** The component to render */
+    component: unknown;
+
+    /** Component props */
+    props?: Record<string, unknown>;
+
+    /** Island options */
+    options?: IslandOptions;
+
+    /** Rendered HTML placeholder */
+    placeholder?: string;
+}
+
+// ============================================================================
+// Adapter Interface (V2)
+// ============================================================================
+
+/**
+ * Universal UI Adapter Interface (Version 2)
+ *
+ * All UI framework adapters must implement this interface.
+ * Optional methods are for advanced features (streaming, islands, etc).
+ */
+export interface UIAdapterV2 {
+    // === Identification ===
+
+    /** Unique adapter identifier (e.g., 'react', 'vue', 'angular') */
+    readonly id: string;
+
+    /** Human-readable adapter name */
+    readonly name: string;
+
+    /** Framework name */
+    readonly framework: string;
+
+    /** Framework version compatibility */
+    readonly frameworkVersion?: string;
+
+    /** Adapter tier classification */
+    readonly tier: AdapterTier;
+
+    /** Supported capabilities */
+    readonly capabilities: AdapterCapabilities;
+
+    // === Core Rendering (Required) ===
+
+    /**
+     * Render a component to an HTML string.
+     * This is the primary SSR method.
+     */
+    renderToString(
+        component: Component,
+        context?: RenderContext
+    ): Promise<RenderResult>;
+
+    /**
+     * Generate the hydration script for client-side hydration.
+     */
+    getHydrationScript(result: RenderResult): string;
+
+    /**
+     * Get the client-side entry point code.
+     */
+    getClientEntry(): string;
+
+    // === Streaming SSR (Optional) ===
+
+    /**
+     * Render a component as a stream (for streaming SSR).
+     * Only available if capabilities.streaming is true.
+     */
+    renderToStream?(
+        component: Component,
+        context?: RenderContext,
+        options?: StreamingOptions
+    ): StreamingRenderResult;
+
+    // === Islands Architecture (Optional) ===
+
+    /**
+     * Create an island wrapper for partial hydration.
+     * Only available if capabilities.islands is true.
+     */
+    createIsland?(
+        component: unknown,
+        props?: Record<string, unknown>,
+        options?: IslandOptions
+    ): Island;
+
+    /**
+     * Hydrate an island on the client.
+     */
+    hydrateIsland?(
+        element: Element,
+        island: Island
+    ): void;
+
+    // === Resumability (Optional) ===
+
+    /**
+     * Serialize component state for resumable hydration.
+     * Only available if capabilities.resumable is true.
+     */
+    serializeState?(state: unknown): string;
+
+    /**
+     * Resume from serialized state.
+     */
+    resumeFromState?(serialized: string): unknown;
+
+    // === Lifecycle (Optional) ===
+
+    /**
+     * Initialize the adapter (load dependencies, warm up caches, etc).
+     */
+    init?(): Promise<void>;
+
+    /**
+     * Clean up resources.
+     */
+    dispose?(): Promise<void>;
+
+    // === Transform (Optional) ===
+
+    /**
+     * Transform a component for SSR if needed.
+     */
+    transformForSSR?(component: unknown): unknown;
+}
+
+// ============================================================================
+// Legacy Compatibility (V1 Adapter)
+// ============================================================================
+
+/**
+ * Legacy V1 adapter interface for backward compatibility.
+ * @deprecated Use UIAdapterV2 instead
+ */
+export interface UIAdapterV1 {
+    readonly name: string;
+    readonly framework: string;
+    renderToString(component: Component): Promise<RenderResult>;
+    getHydrationScript(result: RenderResult): string;
+    getClientEntry(): string;
+    transformForSSR?(component: unknown): unknown;
+}
+
+/**
+ * Type alias for backward compatibility
+ * @deprecated Use UIAdapterV2 instead
+ */
+export type UIAdapter = UIAdapterV1;
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+/**
+ * UI configuration for Flight
+ */
+export interface UIConfig {
+    /** The UI adapter to use */
+    adapter: UIAdapterV2 | UIAdapterV1;
+
+    /** Enable streaming SSR */
+    streaming?: boolean;
+
+    /** Hydration strategy */
+    hydration?: 'full' | 'partial' | 'progressive' | 'none';
+
+    /** Islands mode */
+    islands?: boolean;
+
+    /** Default island hydration strategy */
+    defaultIslandStrategy?: IslandHydrationStrategy;
+}
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+/**
+ * Extract props type from a component
+ */
+export type ComponentProps<C> = C extends Component<infer P> ? P : never;
+
+/**
+ * Check if adapter supports a capability
+ */
+export type HasCapability<
+    A extends UIAdapterV2,
+    C extends keyof AdapterCapabilities
+> = A['capabilities'][C] extends true ? true : false;

package/src/htmx.ts

@@ -0,0 +1,134 @@
+/**
+ * @flightdev/ui/htmx - HTMX Integration Adapter
+ * 
+ * Server-driven UI with HTMX - no JavaScript framework needed.
+ * Perfect for hypermedia-driven applications.
+ * 
+ * @example
+ * ```typescript
+ * import { htmx } from '@flightdev/ui/htmx';
+ * import { defineUI } from '@flightdev/ui';
+ * 
+ * export default defineUI(htmx({
+ *   extensions: ['json-enc', 'loading-states'],
+ * }));
+ * ```
+ */
+
+import type { UIAdapter, RenderResult, Component } from './index.js';
+
+export interface HTMXAdapterOptions {
+    /** HTMX version to use */
+    version?: string;
+    /** HTMX extensions to include */
+    extensions?: string[];
+    /** Enable WebSocket support */
+    websocket?: boolean;
+    /** Enable SSE support */
+    sse?: boolean;
+}
+
+/**
+ * Create an HTMX UI adapter
+ */
+export function htmx(options: HTMXAdapterOptions = {}): UIAdapter {
+    const {
+        version = '2.0.0',
+        extensions = [],
+        websocket = false,
+        sse = false,
+    } = options;
+
+    return {
+        name: 'htmx',
+        framework: 'htmx',
+
+        async renderToString(component: Component): Promise<RenderResult> {
+            // HTMX components are just HTML strings or template functions
+            let html: string;
+
+            if (typeof component.component === 'function') {
+                html = (component.component as (props: any) => string)(component.props ?? {});
+            } else if (typeof component.component === 'string') {
+                html = component.component;
+            } else {
+                throw new Error('HTMX components must be strings or template functions');
+            }
+
+            return {
+                html,
+                // No hydration data needed - HTMX is server-driven
+            };
+        },
+
+        getHydrationScript(_result: RenderResult): string {
+            const extScripts = extensions
+                .map(ext => `<script src="https://unpkg.com/htmx.org@${version}/dist/ext/${ext}.js"></script>`)
+                .join('\n');
+
+            const wsScript = websocket
+                ? `<script src="https://unpkg.com/htmx.org@${version}/dist/ext/ws.js"></script>`
+                : '';
+
+            const sseScript = sse
+                ? `<script src="https://unpkg.com/htmx.org@${version}/dist/ext/sse.js"></script>`
+                : '';
+
+            return `
+                <script src="https://unpkg.com/htmx.org@${version}"></script>
+                ${extScripts}
+                ${wsScript}
+                ${sseScript}
+            `;
+        },
+
+        getClientEntry(): string {
+            // HTMX doesn't need a client entry - it's declarative
+            return '// HTMX - No client-side JS needed';
+        },
+    };
+}
+
+// ============================================================================
+// HTMX Template Helpers
+// ============================================================================
+
+/**
+ * Create an HTMX-enhanced element
+ */
+export function hx(
+    tag: string,
+    attrs: Record<string, string>,
+    children?: string
+): string {
+    const attrStr = Object.entries(attrs)
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(' ');
+
+    if (children !== undefined) {
+        return `<${tag} ${attrStr}>${children}</${tag}>`;
+    }
+    return `<${tag} ${attrStr} />`;
+}
+
+/**
+ * HTMX GET trigger
+ */
+export function hxGet(url: string, target?: string, swap?: string): Record<string, string> {
+    const attrs: Record<string, string> = { 'hx-get': url };
+    if (target) attrs['hx-target'] = target;
+    if (swap) attrs['hx-swap'] = swap;
+    return attrs;
+}
+
+/**
+ * HTMX POST trigger
+ */
+export function hxPost(url: string, target?: string, swap?: string): Record<string, string> {
+    const attrs: Record<string, string> = { 'hx-post': url };
+    if (target) attrs['hx-target'] = target;
+    if (swap) attrs['hx-swap'] = swap;
+    return attrs;
+}
+
+export default htmx;