@flightdev/ui 2.0.0

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

@@ -0,0 +1,263 @@
+/**
+ * @flightdev/ui - HTMX Adapter (Tier 3)
+ *
+ * HTMX adapter - HTML over the wire, server-driven UI.
+ *
+ * @module @flightdev/ui/htmx
+ * @version 2.0.0
+ */
+
+import { BaseUIAdapter } from '../../core/adapter.js';
+import type {
+    AdapterCapabilities,
+    Component,
+    RenderContext,
+    RenderResult,
+} from '../../core/types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type HTMXExtension =
+    | 'json-enc'
+    | 'loading-states'
+    | 'class-tools'
+    | 'morphdom-swap'
+    | 'alpine-morph'
+    | 'path-deps'
+    | 'preload'
+    | 'remove-me'
+    | 'response-targets'
+    | 'head-support'
+    | 'sse'
+    | 'ws';
+
+export interface HTMXAdapterOptions {
+    /** HTMX version */
+    version?: string;
+
+    /** Extensions to load */
+    extensions?: HTMXExtension[];
+
+    /** Enable WebSocket extension */
+    websocket?: boolean;
+
+    /** Enable SSE extension */
+    sse?: boolean;
+
+    /** CDN base URL */
+    cdnBase?: string;
+
+    /** Enable head element support */
+    headSupport?: boolean;
+}
+
+// ============================================================================
+// HTMX Adapter
+// ============================================================================
+
+export class HTMXAdapter extends BaseUIAdapter {
+    readonly id = 'htmx';
+    readonly name = 'HTMX';
+    readonly framework = 'htmx';
+    readonly frameworkVersion = '2.0+';
+    readonly tier = 'tier-3' as const;
+
+    override readonly capabilities: AdapterCapabilities = {
+        streaming: false,
+        partialHydration: false,
+        islands: false,
+        resumable: false,
+        ssg: true,
+        csr: false, // HTMX is server-driven
+        serverComponents: false,
+    };
+
+    constructor(private options: HTMXAdapterOptions = {}) {
+        super();
+    }
+
+    async renderToString(
+        component: Component,
+        _context?: RenderContext
+    ): Promise<RenderResult> {
+        const startTime = performance.now();
+
+        // HTMX components are pure HTML
+        let html: string;
+
+        if (typeof component.component === 'function') {
+            html = (component.component as (props: unknown) => string)(component.props ?? {});
+        } else if (typeof component.component === 'string') {
+            html = component.component;
+        } else {
+            throw new Error(
+                '[Flight/HTMX] Components must be HTML strings or template functions.\n' +
+                'HTMX is server-driven - use hx-* attributes for interactivity.'
+            );
+        }
+
+        return {
+            html,
+            // No hydration data - HTMX is server-driven
+            timing: this.createTiming(startTime),
+        };
+    }
+
+    override getHydrationScript(_result: RenderResult): string {
+        const {
+            version = '2.0.2',
+            extensions = [],
+            websocket = false,
+            sse = false,
+            cdnBase = 'https://unpkg.com',
+            headSupport = false,
+        } = this.options;
+
+        // Build extension list
+        const allExtensions = [
+            ...extensions,
+            ...(websocket ? ['ws'] : []),
+            ...(sse ? ['sse'] : []),
+            ...(headSupport ? ['head-support'] : []),
+        ] as HTMXExtension[];
+
+        // Extension script tags
+        const extScripts = allExtensions
+            .map((ext) =>
+                `<script src="${cdnBase}/htmx.org@${version}/dist/ext/${ext}.js"></script>`
+            )
+            .join('\n');
+
+        return `
+<!-- Flight/HTMX -->
+<script src="${cdnBase}/htmx.org@${version}"></script>
+${extScripts}
+<script>
+window.__FLIGHT_ADAPTER__ = 'htmx';
+// HTMX is ready - server-driven UI active
+</script>
+        `.trim();
+    }
+
+    override getClientEntry(): string {
+        return `
+// HTMX Client Entry
+// HTMX requires no explicit client-side initialization
+
+export function hydrate() {
+    // HTMX auto-initializes via script tag
+    // No JavaScript framework needed
+    console.log('[Flight/HTMX] Server-driven UI ready');
+}
+
+// HTMX event helpers
+export function onLoad(callback) {
+    document.addEventListener('htmx:load', callback);
+}
+
+export function onAfterSwap(callback) {
+    document.addEventListener('htmx:afterSwap', callback);
+}
+
+export function onBeforeRequest(callback) {
+    document.addEventListener('htmx:beforeRequest', callback);
+}
+        `.trim();
+    }
+}
+
+// ============================================================================
+// Template Helpers
+// ============================================================================
+
+/**
+ * Create an hx-get element
+ */
+export function hxGet(
+    url: string,
+    options: { target?: string; swap?: string; trigger?: string } = {}
+): Record<string, string> {
+    const attrs: Record<string, string> = { 'hx-get': url };
+    if (options.target) attrs['hx-target'] = options.target;
+    if (options.swap) attrs['hx-swap'] = options.swap;
+    if (options.trigger) attrs['hx-trigger'] = options.trigger;
+    return attrs;
+}
+
+/**
+ * Create an hx-post element
+ */
+export function hxPost(
+    url: string,
+    options: { target?: string; swap?: string; trigger?: string } = {}
+): Record<string, string> {
+    const attrs: Record<string, string> = { 'hx-post': url };
+    if (options.target) attrs['hx-target'] = options.target;
+    if (options.swap) attrs['hx-swap'] = options.swap;
+    if (options.trigger) attrs['hx-trigger'] = options.trigger;
+    return attrs;
+}
+
+/**
+ * Create an hx-delete element
+ */
+export function hxDelete(
+    url: string,
+    options: { target?: string; swap?: string; confirm?: string } = {}
+): Record<string, string> {
+    const attrs: Record<string, string> = { 'hx-delete': url };
+    if (options.target) attrs['hx-target'] = options.target;
+    if (options.swap) attrs['hx-swap'] = options.swap;
+    if (options.confirm) attrs['hx-confirm'] = options.confirm;
+    return attrs;
+}
+
+/**
+ * Convert attributes object to HTML string
+ */
+export function attrsToString(attrs: Record<string, string>): string {
+    return Object.entries(attrs)
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(' ');
+}
+
+/**
+ * Create a simple HTML element with hx-* attributes
+ */
+export function hx(
+    tag: string,
+    attrs: Record<string, string>,
+    content?: string
+): string {
+    const attrStr = attrsToString(attrs);
+    if (content !== undefined) {
+        return `<${tag} ${attrStr}>${content}</${tag}>`;
+    }
+    return `<${tag} ${attrStr} />`;
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Create an HTMX UI adapter.
+ *
+ * @example
+ * ```typescript
+ * import { htmx } from '@flightdev/ui/htmx';
+ * import { defineUI } from '@flightdev/ui';
+ *
+ * export default defineUI(htmx({
+ *   extensions: ['json-enc', 'loading-states'],
+ *   sse: true,
+ * }));
+ * ```
+ */
+export function htmx(options?: HTMXAdapterOptions): HTMXAdapter {
+    return new HTMXAdapter(options);
+}
+
+export default htmx;

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

@@ -0,0 +1,12 @@
+/**
+ * @flightdev/ui - Tier 3 Adapters Index
+ *
+ * Re-exports all Tier 3 (HTML-First) adapters.
+ */
+
+export { alpine, AlpineAdapter, xData, xFor, xIf, xBind, xOn, type AlpineAdapterOptions, type AlpinePlugin } from './alpine.js';
+export { htmx, HTMXAdapter, hxGet, hxPost, hxDelete, hx, attrsToString, type HTMXAdapterOptions, type HTMXExtension } from './htmx.js';
+export { hotwire, HotwireAdapter, turboFrame, turboStream, stimulusController, type HotwireAdapterOptions } from './hotwire.js';
+export { stimulus, StimulusAdapter, controller, action, target, type StimulusAdapterOptions } from './stimulus.js';
+export { petiteVue, PetiteVueAdapter, vScope, vFor, vIf, type PetiteVueAdapterOptions } from './petite-vue.js';
+export { vanilla, VanillaAdapter, shadowRoot, slot, createElementClass, type VanillaAdapterOptions } from './vanilla.js';

package/src/adapters/tier-3/petite-vue.ts

@@ -0,0 +1,163 @@
+/**
+ * @flightdev/ui - Petite-vue Adapter (Tier 3)
+ *
+ * Petite-vue adapter - minimal (~6kb) Vue subset for progressive enhancement.
+ *
+ * @module @flightdev/ui/petite-vue
+ * @version 2.0.0
+ */
+
+import { BaseUIAdapter } from '../../core/adapter.js';
+import type {
+    AdapterCapabilities,
+    Component,
+    RenderContext,
+    RenderResult,
+} from '../../core/types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PetiteVueAdapterOptions {
+    /** Petite-vue version */
+    version?: string;
+
+    /** Auto-initialize with v-scope */
+    autoInit?: boolean;
+}
+
+// ============================================================================
+// Petite-vue Adapter
+// ============================================================================
+
+export class PetiteVueAdapter extends BaseUIAdapter {
+    readonly id = 'petite-vue';
+    readonly name = 'Petite-vue';
+    readonly framework = 'petite-vue';
+    readonly frameworkVersion = '0.4+';
+    readonly tier = 'tier-3' as const;
+
+    override readonly capabilities: AdapterCapabilities = {
+        streaming: false,
+        partialHydration: false,
+        islands: false,
+        resumable: false,
+        ssg: true,
+        csr: true,
+        serverComponents: false,
+    };
+
+    constructor(private options: PetiteVueAdapterOptions = {}) {
+        super();
+    }
+
+    async renderToString(
+        component: Component,
+        _context?: RenderContext
+    ): Promise<RenderResult> {
+        const startTime = performance.now();
+
+        let html: string;
+
+        if (typeof component.component === 'function') {
+            html = (component.component as (props: unknown) => string)(component.props ?? {});
+        } else if (typeof component.component === 'string') {
+            html = component.component;
+        } else {
+            throw new Error(
+                '[Flight/Petite-vue] Components must be HTML strings or template functions.\n' +
+                'Use v-scope for state and @click, v-model, etc. for interactivity.'
+            );
+        }
+
+        return {
+            html,
+            hydrationData: component.props,
+            timing: this.createTiming(startTime),
+        };
+    }
+
+    override getHydrationScript(_result: RenderResult): string {
+        const {
+            version = '0.4.1',
+            autoInit = true,
+        } = this.options;
+
+        return `
+<!-- Flight/Petite-vue -->
+<script type="module">
+import { createApp } from 'https://esm.sh/petite-vue@${version}';
+
+window.__FLIGHT_ADAPTER__ = 'petite-vue';
+${autoInit ? `createApp().mount();` : '// Manual init: createApp().mount()'}
+
+console.log('[Flight/Petite-vue] Initialized');
+</script>
+        `.trim();
+    }
+
+    override getClientEntry(): string {
+        return `
+import { createApp, reactive } from 'petite-vue';
+
+export { createApp, reactive };
+
+export function hydrate() {
+    createApp().mount();
+    console.log('[Flight/Petite-vue] Application mounted');
+}
+
+export function createScope(initialState) {
+    return reactive(initialState);
+}
+        `.trim();
+    }
+}
+
+// ============================================================================
+// Template Helpers
+// ============================================================================
+
+/**
+ * Create a v-scope element
+ */
+export function vScope(state: Record<string, unknown>, content: string): string {
+    const stateStr = JSON.stringify(state).replace(/"/g, "'");
+    return `<div v-scope="${stateStr}">${content}</div>`;
+}
+
+/**
+ * Create v-for binding
+ */
+export function vFor(items: string, itemName: string, content: string): string {
+    return `<template v-for="${itemName} in ${items}">${content}</template>`;
+}
+
+/**
+ * Create v-if binding
+ */
+export function vIf(condition: string, content: string): string {
+    return `<template v-if="${condition}">${content}</template>`;
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Create a Petite-vue UI adapter.
+ *
+ * @example
+ * ```typescript
+ * import { petiteVue } from '@flightdev/ui/petite-vue';
+ * import { defineUI } from '@flightdev/ui';
+ *
+ * export default defineUI(petiteVue());
+ * ```
+ */
+export function petiteVue(options?: PetiteVueAdapterOptions): PetiteVueAdapter {
+    return new PetiteVueAdapter(options);
+}
+
+export default petiteVue;

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

@@ -0,0 +1,233 @@
+/**
+ * @flightdev/ui - Stimulus Adapter (Tier 3)
+ *
+ * Stimulus adapter - modest JavaScript for the HTML you already have.
+ *
+ * @module @flightdev/ui/stimulus
+ * @version 2.0.0
+ */
+
+import { BaseUIAdapter } from '../../core/adapter.js';
+import type {
+    AdapterCapabilities,
+    Component,
+    RenderContext,
+    RenderResult,
+} from '../../core/types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface StimulusAdapterOptions {
+    /** Stimulus version */
+    version?: string;
+
+    /** Controllers directory path */
+    controllersPath?: string;
+
+    /** Enable debug mode */
+    debug?: boolean;
+}
+
+// ============================================================================
+// Stimulus Adapter
+// ============================================================================
+
+export class StimulusAdapter extends BaseUIAdapter {
+    readonly id = 'stimulus';
+    readonly name = 'Stimulus';
+    readonly framework = 'stimulus';
+    readonly frameworkVersion = '3+';
+    readonly tier = 'tier-3' as const;
+
+    override readonly capabilities: AdapterCapabilities = {
+        streaming: false,
+        partialHydration: false,
+        islands: false,
+        resumable: false,
+        ssg: true,
+        csr: true,
+        serverComponents: false,
+    };
+
+    constructor(private options: StimulusAdapterOptions = {}) {
+        super();
+    }
+
+    async renderToString(
+        component: Component,
+        _context?: RenderContext
+    ): Promise<RenderResult> {
+        const startTime = performance.now();
+
+        let html: string;
+
+        if (typeof component.component === 'function') {
+            html = (component.component as (props: unknown) => string)(component.props ?? {});
+        } else if (typeof component.component === 'string') {
+            html = component.component;
+        } else {
+            throw new Error(
+                '[Flight/Stimulus] Components must be HTML strings or template functions.\n' +
+                'Use data-controller and data-action for interactivity.'
+            );
+        }
+
+        return {
+            html,
+            hydrationData: component.props,
+            timing: this.createTiming(startTime),
+        };
+    }
+
+    override getHydrationScript(_result: RenderResult): string {
+        const {
+            version = '3.2.2',
+            debug = false,
+        } = this.options;
+
+        return `
+<!-- Flight/Stimulus -->
+<script type="module">
+import { Application } from 'https://esm.sh/@hotwired/stimulus@${version}';
+
+window.Stimulus = Application.start();
+${debug ? 'window.Stimulus.debug = true;' : ''}
+
+window.__FLIGHT_ADAPTER__ = 'stimulus';
+console.log('[Flight/Stimulus] Application started');
+</script>
+        `.trim();
+    }
+
+    override getClientEntry(): string {
+        return `
+import { Application, Controller } from '@hotwired/stimulus';
+
+// Start Stimulus application
+export const application = Application.start();
+
+// Export Controller for extension
+export { Controller };
+
+// Register controller helper
+export function register(name, controller) {
+    application.register(name, controller);
+}
+
+// Bulk register controllers
+export function registerControllers(controllers) {
+    for (const [name, controller] of Object.entries(controllers)) {
+        register(name, controller);
+    }
+}
+
+// Dynamic controller loading via import.meta.glob (Vite)
+export function eagerLoadControllers(controllerModules) {
+    for (const [path, module] of Object.entries(controllerModules)) {
+        const match = path.match(/\\/([^/]+)_controller\\.[jt]s$/);
+        if (match && module.default) {
+            const name = match[1].replace(/_/g, '-');
+            register(name, module.default);
+        }
+    }
+}
+
+// Default hydration
+export function hydrate() {
+    console.log('[Flight/Stimulus] Controllers ready');
+}
+        `.trim();
+    }
+}
+
+// ============================================================================
+// Template Helpers
+// ============================================================================
+
+/**
+ * Create an element with a Stimulus controller
+ */
+export function controller(
+    name: string,
+    content: string,
+    options: {
+        values?: Record<string, unknown>;
+        classes?: Record<string, string>;
+        outlets?: Record<string, string>;
+        targets?: string[];
+    } = {}
+): string {
+    const attrs: string[] = [`data-controller="${name}"`];
+
+    // Values
+    if (options.values) {
+        for (const [key, value] of Object.entries(options.values)) {
+            attrs.push(`data-${name}-${toKebab(key)}-value="${value}"`);
+        }
+    }
+
+    // Classes
+    if (options.classes) {
+        for (const [key, value] of Object.entries(options.classes)) {
+            attrs.push(`data-${name}-${toKebab(key)}-class="${value}"`);
+        }
+    }
+
+    // Outlets
+    if (options.outlets) {
+        for (const [key, selector] of Object.entries(options.outlets)) {
+            attrs.push(`data-${name}-${toKebab(key)}-outlet="${selector}"`);
+        }
+    }
+
+    return `<div ${attrs.join(' ')}>${content}</div>`;
+}
+
+/**
+ * Create a data-action attribute
+ */
+export function action(
+    controller: string,
+    method: string,
+    event?: string
+): string {
+    const eventPart = event ? `${event}->` : '';
+    return `data-action="${eventPart}${controller}#${method}"`;
+}
+
+/**
+ * Create a data-target attribute
+ */
+export function target(controller: string, name: string): string {
+    return `data-${controller}-target="${name}"`;
+}
+
+/**
+ * Convert camelCase to kebab-case
+ */
+function toKebab(str: string): string {
+    return str.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Create a Stimulus UI adapter.
+ *
+ * @example
+ * ```typescript
+ * import { stimulus } from '@flightdev/ui/stimulus';
+ * import { defineUI } from '@flightdev/ui';
+ *
+ * export default defineUI(stimulus({ debug: true }));
+ * ```
+ */
+export function stimulus(options?: StimulusAdapterOptions): StimulusAdapter {
+    return new StimulusAdapter(options);
+}
+
+export default stimulus;