@flightdev/ui 2.0.0

package/src/core/registry.ts

@@ -0,0 +1,518 @@
+/**
+ * @flightdev/ui - Adapter Registry
+ *
+ * Global registry for dynamic adapter loading and discovery.
+ * Enables lazy loading of adapters to minimize bundle size.
+ *
+ * @module @flightdev/ui/core/registry
+ * @version 2.0.0
+ */
+
+import type { UIAdapterV2, AdapterTier, AdapterCapabilities } from './types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Lazy loader function for an adapter
+ */
+export type AdapterLoader = () => Promise<UIAdapterV2>;
+
+/**
+ * Adapter metadata for registry
+ */
+export interface AdapterMetadata {
+    /** Unique adapter ID */
+    id: string;
+
+    /** Human-readable name */
+    name: string;
+
+    /** Framework name */
+    framework: string;
+
+    /** Tier classification */
+    tier: AdapterTier;
+
+    /** Capability hints (may be incomplete until loaded) */
+    capabilities?: Partial<AdapterCapabilities>;
+
+    /** Peer dependencies required */
+    peerDependencies?: string[];
+
+    /** Lazy loader function */
+    loader: AdapterLoader;
+}
+
+/**
+ * Registry query options
+ */
+export interface RegistryQueryOptions {
+    /** Filter by tier */
+    tier?: AdapterTier;
+
+    /** Filter by capability */
+    capability?: keyof AdapterCapabilities;
+
+    /** Filter by framework name pattern */
+    framework?: string | RegExp;
+}
+
+// ============================================================================
+// Adapter Registry Class
+// ============================================================================
+
+/**
+ * Global adapter registry for dynamic loading and discovery.
+ *
+ * @example
+ * ```typescript
+ * import { adapterRegistry } from '@flightdev/ui';
+ *
+ * // Register an adapter
+ * adapterRegistry.register({
+ *   id: 'react',
+ *   name: 'React',
+ *   framework: 'react',
+ *   tier: 'tier-1',
+ *   loader: () => import('./adapters/tier-1/react.js').then(m => m.react()),
+ * });
+ *
+ * // Get an adapter
+ * const reactAdapter = await adapterRegistry.get('react');
+ *
+ * // List all adapters
+ * const allAdapters = adapterRegistry.list();
+ * ```
+ */
+class AdapterRegistry {
+    private metadata = new Map<string, AdapterMetadata>();
+    private instances = new Map<string, UIAdapterV2>();
+    private loading = new Map<string, Promise<UIAdapterV2>>();
+
+    /**
+     * Register an adapter with the registry.
+     */
+    register(metadata: AdapterMetadata): void {
+        if (this.metadata.has(metadata.id)) {
+            console.warn(`[AdapterRegistry] Overwriting existing adapter: ${metadata.id}`);
+        }
+        this.metadata.set(metadata.id, metadata);
+    }
+
+    /**
+     * Register multiple adapters at once.
+     */
+    registerAll(adapters: AdapterMetadata[]): void {
+        for (const adapter of adapters) {
+            this.register(adapter);
+        }
+    }
+
+    /**
+     * Unregister an adapter.
+     */
+    unregister(id: string): boolean {
+        this.instances.delete(id);
+        this.loading.delete(id);
+        return this.metadata.delete(id);
+    }
+
+    /**
+     * Check if an adapter is registered.
+     */
+    has(id: string): boolean {
+        return this.metadata.has(id);
+    }
+
+    /**
+     * Get an adapter by ID (lazy loads if not already loaded).
+     */
+    async get(id: string): Promise<UIAdapterV2 | undefined> {
+        // Check if already loaded
+        const existing = this.instances.get(id);
+        if (existing) {
+            return existing;
+        }
+
+        // Check if currently loading
+        const loadingPromise = this.loading.get(id);
+        if (loadingPromise) {
+            return loadingPromise;
+        }
+
+        // Check if registered
+        const meta = this.metadata.get(id);
+        if (!meta) {
+            return undefined;
+        }
+
+        // Load the adapter
+        const promise = this.loadAdapter(meta);
+        this.loading.set(id, promise);
+
+        try {
+            const adapter = await promise;
+            this.instances.set(id, adapter);
+            this.loading.delete(id);
+            return adapter;
+        } catch (error) {
+            this.loading.delete(id);
+            throw error;
+        }
+    }
+
+    /**
+     * Get an adapter synchronously (only if already loaded).
+     */
+    getSync(id: string): UIAdapterV2 | undefined {
+        return this.instances.get(id);
+    }
+
+    /**
+     * Get adapter metadata without loading.
+     */
+    getMetadata(id: string): AdapterMetadata | undefined {
+        return this.metadata.get(id);
+    }
+
+    /**
+     * List all registered adapter IDs.
+     */
+    list(): string[] {
+        return Array.from(this.metadata.keys());
+    }
+
+    /**
+     * List adapters matching query options.
+     */
+    query(options: RegistryQueryOptions): AdapterMetadata[] {
+        const results: AdapterMetadata[] = [];
+
+        for (const meta of this.metadata.values()) {
+            // Filter by tier
+            if (options.tier && meta.tier !== options.tier) {
+                continue;
+            }
+
+            // Filter by capability
+            if (options.capability && !meta.capabilities?.[options.capability]) {
+                continue;
+            }
+
+            // Filter by framework
+            if (options.framework) {
+                if (typeof options.framework === 'string') {
+                    if (!meta.framework.includes(options.framework)) {
+                        continue;
+                    }
+                } else if (!options.framework.test(meta.framework)) {
+                    continue;
+                }
+            }
+
+            results.push(meta);
+        }
+
+        return results;
+    }
+
+    /**
+     * List adapters by tier.
+     */
+    listByTier(tier: AdapterTier): string[] {
+        return this.query({ tier }).map((m) => m.id);
+    }
+
+    /**
+     * List adapters by capability.
+     */
+    listByCapability(capability: keyof AdapterCapabilities): string[] {
+        return this.query({ capability }).map((m) => m.id);
+    }
+
+    /**
+     * Preload adapters for faster access later.
+     */
+    async preload(ids: string[]): Promise<void> {
+        await Promise.all(ids.map((id) => this.get(id)));
+    }
+
+    /**
+     * Get all loaded adapters.
+     */
+    getLoaded(): Map<string, UIAdapterV2> {
+        return new Map(this.instances);
+    }
+
+    /**
+     * Clear all cached adapter instances (but keep registrations).
+     */
+    clearCache(): void {
+        this.instances.clear();
+        this.loading.clear();
+    }
+
+    /**
+     * Clear everything (registrations and cache).
+     */
+    clear(): void {
+        this.metadata.clear();
+        this.instances.clear();
+        this.loading.clear();
+    }
+
+    /**
+     * Get registry statistics.
+     */
+    stats(): {
+        registered: number;
+        loaded: number;
+        loading: number;
+        byTier: Record<AdapterTier, number>;
+    } {
+        const byTier: Record<AdapterTier, number> = {
+            'tier-1': 0,
+            'tier-2': 0,
+            'tier-3': 0,
+        };
+
+        for (const meta of this.metadata.values()) {
+            byTier[meta.tier]++;
+        }
+
+        return {
+            registered: this.metadata.size,
+            loaded: this.instances.size,
+            loading: this.loading.size,
+            byTier,
+        };
+    }
+
+    /**
+     * Load an adapter from metadata.
+     */
+    private async loadAdapter(meta: AdapterMetadata): Promise<UIAdapterV2> {
+        try {
+            const adapter = await meta.loader();
+
+            // Initialize if needed
+            if (adapter.init) {
+                await adapter.init();
+            }
+
+            return adapter;
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(
+                `[AdapterRegistry] Failed to load adapter '${meta.id}': ${message}\n` +
+                `Required peer dependencies: ${meta.peerDependencies?.join(', ') ?? 'none'}`
+            );
+        }
+    }
+}
+
+// ============================================================================
+// Global Registry Instance
+// ============================================================================
+
+/**
+ * Global adapter registry instance.
+ *
+ * Use this to register and retrieve UI adapters.
+ */
+export const adapterRegistry = new AdapterRegistry();
+
+// ============================================================================
+// Built-in Adapter Registrations
+// ============================================================================
+
+/**
+ * Register all built-in adapters.
+ * Called automatically when the package is imported.
+ */
+export function registerBuiltinAdapters(): void {
+    // Tier 1: Full Support
+    adapterRegistry.register({
+        id: 'react',
+        name: 'React',
+        framework: 'react',
+        tier: 'tier-1',
+        capabilities: { streaming: true, partialHydration: true, serverComponents: true },
+        peerDependencies: ['react', 'react-dom'],
+        loader: () => import('../adapters/tier-1/react.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'vue',
+        name: 'Vue',
+        framework: 'vue',
+        tier: 'tier-1',
+        capabilities: { streaming: true, partialHydration: true },
+        peerDependencies: ['vue'],
+        loader: () => import('../adapters/tier-1/vue.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'svelte',
+        name: 'Svelte',
+        framework: 'svelte',
+        tier: 'tier-1',
+        capabilities: { streaming: false, partialHydration: true },
+        peerDependencies: ['svelte'],
+        loader: () => import('../adapters/tier-1/svelte.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'solid',
+        name: 'Solid',
+        framework: 'solid',
+        tier: 'tier-1',
+        capabilities: { streaming: true, partialHydration: true },
+        peerDependencies: ['solid-js'],
+        loader: () => import('../adapters/tier-1/solid.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'angular',
+        name: 'Angular',
+        framework: 'angular',
+        tier: 'tier-1',
+        capabilities: { streaming: true, partialHydration: true },
+        peerDependencies: ['@angular/core', '@angular/platform-server', '@angular/platform-browser'],
+        loader: () => import('../adapters/tier-1/angular.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'qwik',
+        name: 'Qwik',
+        framework: 'qwik',
+        tier: 'tier-1',
+        capabilities: { streaming: true, resumable: true, partialHydration: true },
+        peerDependencies: ['@builder.io/qwik'],
+        loader: () => import('../adapters/tier-1/qwik.js').then((m) => m.default()),
+    });
+
+    // Tier 2: Standard Support
+    adapterRegistry.register({
+        id: 'preact',
+        name: 'Preact',
+        framework: 'preact',
+        tier: 'tier-2',
+        capabilities: { streaming: false, partialHydration: true },
+        peerDependencies: ['preact'],
+        loader: () => import('../adapters/tier-2/preact.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'lit',
+        name: 'Lit',
+        framework: 'lit',
+        tier: 'tier-2',
+        capabilities: { islands: true },
+        peerDependencies: ['lit'],
+        loader: () => import('../adapters/tier-2/lit.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'marko',
+        name: 'Marko',
+        framework: 'marko',
+        tier: 'tier-2',
+        capabilities: { streaming: true, partialHydration: true, islands: true },
+        peerDependencies: ['marko'],
+        loader: () => import('../adapters/tier-2/marko.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'stencil',
+        name: 'Stencil',
+        framework: 'stencil',
+        tier: 'tier-2',
+        capabilities: { islands: true },
+        peerDependencies: ['@stencil/core'],
+        loader: () => import('../adapters/tier-2/stencil.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'mithril',
+        name: 'Mithril',
+        framework: 'mithril',
+        tier: 'tier-2',
+        capabilities: {},
+        peerDependencies: ['mithril'],
+        loader: () => import('../adapters/tier-2/mithril.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'inferno',
+        name: 'Inferno',
+        framework: 'inferno',
+        tier: 'tier-2',
+        capabilities: { streaming: false },
+        peerDependencies: ['inferno'],
+        loader: () => import('../adapters/tier-2/inferno.js').then((m) => m.default()),
+    });
+
+    // Tier 3: HTML-First
+    adapterRegistry.register({
+        id: 'htmx',
+        name: 'HTMX',
+        framework: 'htmx',
+        tier: 'tier-3',
+        capabilities: {},
+        peerDependencies: [],
+        loader: () => import('../adapters/tier-3/htmx.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'alpine',
+        name: 'Alpine.js',
+        framework: 'alpine',
+        tier: 'tier-3',
+        capabilities: {},
+        peerDependencies: [],
+        loader: () => import('../adapters/tier-3/alpine.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'hotwire',
+        name: 'Hotwire',
+        framework: 'hotwire',
+        tier: 'tier-3',
+        capabilities: {},
+        peerDependencies: ['@hotwired/turbo'],
+        loader: () => import('../adapters/tier-3/hotwire.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'stimulus',
+        name: 'Stimulus',
+        framework: 'stimulus',
+        tier: 'tier-3',
+        capabilities: {},
+        peerDependencies: ['@hotwired/stimulus'],
+        loader: () => import('../adapters/tier-3/stimulus.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'petite-vue',
+        name: 'Petite-vue',
+        framework: 'petite-vue',
+        tier: 'tier-3',
+        capabilities: {},
+        peerDependencies: ['petite-vue'],
+        loader: () => import('../adapters/tier-3/petite-vue.js').then((m) => m.default()),
+    });
+
+    adapterRegistry.register({
+        id: 'vanilla',
+        name: 'Vanilla Web Components',
+        framework: 'vanilla',
+        tier: 'tier-3',
+        capabilities: { islands: true },
+        peerDependencies: [],
+        loader: () => import('../adapters/tier-3/vanilla.js').then((m) => m.default()),
+    });
+}