@flightdev/ui 2.0.1 → 4.0.0

package/src/core/types.ts

@@ -1,461 +0,0 @@
-/**
- * @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

@@ -1,134 +0,0 @@
-/**
- * @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;