@object-ui/core 3.3.0 → 3.3.1

package/src/registry/WidgetRegistry.ts

@@ -1,316 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-/**
- * WidgetRegistry - Runtime widget management with auto-discovery.
- *
- * Provides registration, loading, and lookup of runtime widgets
- * described by WidgetManifest objects. Widgets can be loaded from
- * ES module URLs, provided inline, or resolved from the component registry.
- *
- * @module
- */
-
-import type {
-  WidgetManifest,
-  ResolvedWidget,
-  WidgetRegistryEvent,
-  WidgetRegistryListener,
-} from '@object-ui/types';
-import type { Registry } from './Registry.js';
-
-/**
- * Options for creating a WidgetRegistry instance.
- */
-export interface WidgetRegistryOptions {
-  /**
-   * Component registry to sync loaded widgets into.
-   * When a widget is loaded, its component is also registered here.
-   */
-  componentRegistry?: Registry;
-}
-
-/**
- * WidgetRegistry manages runtime-loadable widgets described by manifests.
- *
- * @example
- * ```ts
- * const widgets = new WidgetRegistry({ componentRegistry: registry });
- *
- * widgets.register({
- *   name: 'custom-chart',
- *   version: '1.0.0',
- *   type: 'chart',
- *   label: 'Custom Chart',
- *   source: { type: 'module', url: '/widgets/chart.js' },
- * });
- *
- * const resolved = await widgets.load('custom-chart');
- * ```
- */
-export class WidgetRegistry {
-  private manifests = new Map<string, WidgetManifest>();
-  private resolved = new Map<string, ResolvedWidget>();
-  private listeners = new Set<WidgetRegistryListener>();
-  private componentRegistry?: Registry;
-
-  constructor(options: WidgetRegistryOptions = {}) {
-    this.componentRegistry = options.componentRegistry;
-  }
-
-  /**
-   * Register a widget manifest.
-   * Does not load the widget; call `load()` to resolve it.
-   */
-  register(manifest: WidgetManifest): void {
-    this.manifests.set(manifest.name, manifest);
-    this.emit({ type: 'widget:registered', widget: manifest });
-  }
-
-  /**
-   * Register multiple widget manifests at once.
-   */
-  registerAll(manifests: WidgetManifest[]): void {
-    for (const manifest of manifests) {
-      this.register(manifest);
-    }
-  }
-
-  /**
-   * Unregister a widget by name.
-   */
-  unregister(name: string): boolean {
-    const existed = this.manifests.delete(name);
-    this.resolved.delete(name);
-    if (existed) {
-      this.emit({ type: 'widget:unregistered', name });
-    }
-    return existed;
-  }
-
-  /**
-   * Get a widget manifest by name.
-   */
-  getManifest(name: string): WidgetManifest | undefined {
-    return this.manifests.get(name);
-  }
-
-  /**
-   * Get all registered widget manifests.
-   */
-  getAllManifests(): WidgetManifest[] {
-    return Array.from(this.manifests.values());
-  }
-
-  /**
-   * Get manifests filtered by category.
-   */
-  getByCategory(category: string): WidgetManifest[] {
-    return this.getAllManifests().filter((m) => m.category === category);
-  }
-
-  /**
-   * Check if a widget is registered.
-   */
-  has(name: string): boolean {
-    return this.manifests.has(name);
-  }
-
-  /**
-   * Check if a widget has been loaded (resolved).
-   */
-  isLoaded(name: string): boolean {
-    return this.resolved.has(name);
-  }
-
-  /**
-   * Load (resolve) a widget by name.
-   * If already loaded, returns the cached resolved widget.
-   *
-   * @throws Error if the widget is not registered or fails to load.
-   */
-  async load(name: string): Promise<ResolvedWidget> {
-    // Return cached if already loaded
-    const cached = this.resolved.get(name);
-    if (cached) return cached;
-
-    const manifest = this.manifests.get(name);
-    if (!manifest) {
-      const error = new Error(`Widget "${name}" is not registered`);
-      this.emit({ type: 'widget:error', name, error });
-      throw error;
-    }
-
-    // Resolve dependencies first
-    if (manifest.dependencies) {
-      for (const dep of manifest.dependencies) {
-        if (!this.isLoaded(dep)) {
-          await this.load(dep);
-        }
-      }
-    }
-
-    try {
-      const component = await this.resolveComponent(manifest);
-
-      const resolved: ResolvedWidget = {
-        manifest,
-        component,
-        loadedAt: Date.now(),
-      };
-
-      this.resolved.set(name, resolved);
-
-      // Sync to component registry if available
-      if (this.componentRegistry) {
-        this.componentRegistry.register(manifest.type, component as any, {
-          label: manifest.label,
-          icon: manifest.icon,
-          category: manifest.category,
-          inputs: manifest.inputs?.map((input) => ({
-            name: input.name,
-            type: input.type,
-            label: input.label,
-            defaultValue: input.defaultValue,
-            required: input.required,
-            enum: input.options,
-            description: input.description,
-            advanced: input.advanced,
-          })),
-          defaultProps: manifest.defaultProps as Record<string, any>,
-          isContainer: manifest.isContainer,
-        });
-      }
-
-      this.emit({ type: 'widget:loaded', widget: resolved });
-      return resolved;
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      this.emit({ type: 'widget:error', name, error });
-      throw error;
-    }
-  }
-
-  /**
-   * Load all registered widgets.
-   * Returns an array of results (settled promises).
-   */
-  async loadAll(): Promise<Array<{ name: string; result: ResolvedWidget | Error }>> {
-    const results: Array<{ name: string; result: ResolvedWidget | Error }> = [];
-
-    for (const [name] of this.manifests) {
-      try {
-        const resolved = await this.load(name);
-        results.push({ name, result: resolved });
-      } catch (err) {
-        results.push({ name, result: err instanceof Error ? err : new Error(String(err)) });
-      }
-    }
-
-    return results;
-  }
-
-  /**
-   * Subscribe to widget registry events.
-   * @returns Unsubscribe function.
-   */
-  on(listener: WidgetRegistryListener): () => void {
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
-  }
-
-  /**
-   * Clear all registered and loaded widgets.
-   */
-  clear(): void {
-    this.manifests.clear();
-    this.resolved.clear();
-  }
-
-  /**
-   * Get registry statistics.
-   */
-  getStats(): { registered: number; loaded: number; categories: string[] } {
-    const categories = new Set<string>();
-    for (const m of this.manifests.values()) {
-      if (m.category) categories.add(m.category);
-    }
-    return {
-      registered: this.manifests.size,
-      loaded: this.resolved.size,
-      categories: Array.from(categories),
-    };
-  }
-
-  // -------------------------------------------------------------------------
-  // Private helpers
-  // -------------------------------------------------------------------------
-
-  private async resolveComponent(manifest: WidgetManifest): Promise<unknown> {
-    const { source } = manifest;
-
-    switch (source.type) {
-      case 'inline':
-        return source.component;
-
-      case 'registry': {
-        if (!this.componentRegistry) {
-          throw new Error(
-            `Widget "${manifest.name}" uses registry source but no component registry is configured`,
-          );
-        }
-        const component = this.componentRegistry.get(source.registryKey);
-        if (!component) {
-          throw new Error(
-            `Widget "${manifest.name}" references registry key "${source.registryKey}" which is not registered`,
-          );
-        }
-        return component;
-      }
-
-      case 'module': {
-        // Runtime-only dynamic import for loading widgets from external URLs
-        // This uses Function constructor to prevent bundlers (Webpack/Turbopack/Vite)
-        // from attempting static analysis at build time, which would fail since
-        // source.url is only known at runtime.
-        //
-        // Security: Widget URLs must be from trusted sources only. Never pass
-        // user-supplied URLs directly to WidgetManifest. URLs should be validated
-        // and controlled by the application developer.
-        //
-        // CSP Consideration: If your application uses strict Content Security Policy,
-        // ensure dynamic imports are allowed or use 'inline' or 'registry' source types.
-        const dynamicImport = new Function('url', 'return import(url)');
-        const mod = await dynamicImport(source.url);
-        const exportName = source.exportName ?? 'default';
-        const component = mod[exportName];
-        if (!component) {
-          throw new Error(
-            `Widget "${manifest.name}" module at "${source.url}" does not export "${exportName}"`,
-          );
-        }
-        return component;
-      }
-
-      default:
-        throw new Error(`Unknown widget source type for "${manifest.name}"`);
-    }
-  }
-
-  private emit(event: WidgetRegistryEvent): void {
-    for (const listener of this.listeners) {
-      try {
-        listener(event);
-      } catch {
-        // Swallow listener errors to prevent cascading failures
-      }
-    }
-  }
-}

package/src/registry/__tests__/PluginSystem.test.ts

@@ -1,309 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { PluginSystem, type PluginDefinition } from '../PluginSystem';
-import { Registry } from '../Registry';
-
-describe('PluginSystem', () => {
-  let pluginSystem: PluginSystem;
-  let registry: Registry;
-
-  beforeEach(() => {
-    pluginSystem = new PluginSystem();
-    registry = new Registry();
-  });
-
-  it('should load a simple plugin', async () => {
-    const plugin: PluginDefinition = {
-      name: 'test-plugin',
-      version: '1.0.0',
-      register: (reg) => {
-        reg.register('test', () => 'test');
-      }
-    };
-
-    // Use legacy mode (useScope: false) to test direct registry access
-    await pluginSystem.loadPlugin(plugin, registry, false);
-    
-    expect(pluginSystem.isLoaded('test-plugin')).toBe(true);
-    expect(pluginSystem.getLoadedPlugins()).toContain('test-plugin');
-    expect(registry.has('test')).toBe(true);
-  });
-
-  it('should execute onLoad lifecycle hook', async () => {
-    const onLoad = vi.fn();
-    const plugin: PluginDefinition = {
-      name: 'test-plugin',
-      version: '1.0.0',
-      register: () => {},
-      onLoad
-    };
-
-    await pluginSystem.loadPlugin(plugin, registry);
-    
-    expect(onLoad).toHaveBeenCalledTimes(1);
-  });
-
-  it('should execute async onLoad lifecycle hook', async () => {
-    const onLoad = vi.fn().mockResolvedValue(undefined);
-    const plugin: PluginDefinition = {
-      name: 'test-plugin',
-      version: '1.0.0',
-      register: () => {},
-      onLoad
-    };
-
-    await pluginSystem.loadPlugin(plugin, registry);
-    
-    expect(onLoad).toHaveBeenCalledTimes(1);
-  });
-
-  it('should not load plugin twice', async () => {
-    const onLoad = vi.fn();
-    const plugin: PluginDefinition = {
-      name: 'test-plugin',
-      version: '1.0.0',
-      register: () => {},
-      onLoad
-    };
-
-    await pluginSystem.loadPlugin(plugin, registry);
-    await pluginSystem.loadPlugin(plugin, registry);
-    
-    expect(onLoad).toHaveBeenCalledTimes(1);
-  });
-
-  it('should check dependencies before loading', async () => {
-    const plugin: PluginDefinition = {
-      name: 'dependent-plugin',
-      version: '1.0.0',
-      dependencies: ['base-plugin'],
-      register: () => {}
-    };
-
-    await expect(pluginSystem.loadPlugin(plugin, registry)).rejects.toThrow(
-      'Missing dependency: base-plugin required by dependent-plugin'
-    );
-  });
-
-  it('should load plugins with dependencies in correct order', async () => {
-    const basePlugin: PluginDefinition = {
-      name: 'base-plugin',
-      version: '1.0.0',
-      register: () => {}
-    };
-
-    const dependentPlugin: PluginDefinition = {
-      name: 'dependent-plugin',
-      version: '1.0.0',
-      dependencies: ['base-plugin'],
-      register: () => {}
-    };
-
-    await pluginSystem.loadPlugin(basePlugin, registry);
-    await pluginSystem.loadPlugin(dependentPlugin, registry);
-    
-    expect(pluginSystem.isLoaded('base-plugin')).toBe(true);
-    expect(pluginSystem.isLoaded('dependent-plugin')).toBe(true);
-  });
-
-  it('should unload a plugin', async () => {
-    const onUnload = vi.fn();
-    const plugin: PluginDefinition = {
-      name: 'test-plugin',
-      version: '1.0.0',
-      register: () => {},
-      onUnload
-    };
-
-    await pluginSystem.loadPlugin(plugin, registry);
-    expect(pluginSystem.isLoaded('test-plugin')).toBe(true);
-    
-    await pluginSystem.unloadPlugin('test-plugin');
-    
-    expect(pluginSystem.isLoaded('test-plugin')).toBe(false);
-    expect(onUnload).toHaveBeenCalledTimes(1);
-  });
-
-  it('should prevent unloading plugin with dependents', async () => {
-    const basePlugin: PluginDefinition = {
-      name: 'base-plugin',
-      version: '1.0.0',
-      register: () => {}
-    };
-
-    const dependentPlugin: PluginDefinition = {
-      name: 'dependent-plugin',
-      version: '1.0.0',
-      dependencies: ['base-plugin'],
-      register: () => {}
-    };
-
-    await pluginSystem.loadPlugin(basePlugin, registry);
-    await pluginSystem.loadPlugin(dependentPlugin, registry);
-    
-    await expect(pluginSystem.unloadPlugin('base-plugin')).rejects.toThrow(
-      'Cannot unload plugin "base-plugin" - plugin "dependent-plugin" depends on it'
-    );
-  });
-
-  it('should throw error when unloading non-existent plugin', async () => {
-    await expect(pluginSystem.unloadPlugin('non-existent')).rejects.toThrow(
-      'Plugin "non-existent" is not loaded'
-    );
-  });
-
-  it('should get plugin definition', async () => {
-    const plugin: PluginDefinition = {
-      name: 'test-plugin',
-      version: '1.0.0',
-      register: () => {}
-    };
-
-    await pluginSystem.loadPlugin(plugin, registry);
-    
-    const retrieved = pluginSystem.getPlugin('test-plugin');
-    expect(retrieved).toBe(plugin);
-  });
-
-  it('should get all plugins', async () => {
-    const plugin1: PluginDefinition = {
-      name: 'plugin-1',
-      version: '1.0.0',
-      register: () => {}
-    };
-
-    const plugin2: PluginDefinition = {
-      name: 'plugin-2',
-      version: '1.0.0',
-      register: () => {}
-    };
-
-    await pluginSystem.loadPlugin(plugin1, registry);
-    await pluginSystem.loadPlugin(plugin2, registry);
-    
-    const allPlugins = pluginSystem.getAllPlugins();
-    expect(allPlugins).toHaveLength(2);
-    expect(allPlugins).toContain(plugin1);
-    expect(allPlugins).toContain(plugin2);
-  });
-
-  it('should call register function with registry', async () => {
-    const registerFn = vi.fn();
-    const plugin: PluginDefinition = {
-      name: 'test-plugin',
-      version: '1.0.0',
-      register: registerFn
-    };
-
-    // Use legacy mode (useScope: false) to verify the raw Registry is passed
-    await pluginSystem.loadPlugin(plugin, registry, false);
-    
-    expect(registerFn).toHaveBeenCalledWith(registry);
-    expect(registerFn).toHaveBeenCalledTimes(1);
-  });
-
-  it('should cleanup on registration failure', async () => {
-    const plugin: PluginDefinition = {
-      name: 'failing-plugin',
-      version: '1.0.0',
-      register: () => {
-        throw new Error('Registration failed');
-      }
-    };
-
-    await expect(pluginSystem.loadPlugin(plugin, registry)).rejects.toThrow('Registration failed');
-    
-    expect(pluginSystem.isLoaded('failing-plugin')).toBe(false);
-    expect(pluginSystem.getPlugin('failing-plugin')).toBeUndefined();
-  });
-
-  describe('install / uninstall (AppMetadataPlugin)', () => {
-    it('should install an AppMetadataPlugin and call init + start', async () => {
-      const initFn = vi.fn();
-      const startFn = vi.fn();
-      const stopFn = vi.fn();
-
-      const appPlugin = {
-        name: '@test/my-plugin',
-        version: '1.0.0',
-        type: 'app-metadata' as const,
-        description: 'Test metadata plugin',
-        init: initFn,
-        start: startFn,
-        stop: stopFn,
-        getConfig: () => ({ objects: [] }),
-      };
-
-      await pluginSystem.install(appPlugin, registry, { logger: console });
-
-      expect(initFn).toHaveBeenCalledTimes(1);
-      expect(startFn).toHaveBeenCalledTimes(1);
-      expect(startFn).toHaveBeenCalledWith({ logger: console });
-      expect(pluginSystem.isLoaded('@test/my-plugin')).toBe(true);
-    });
-
-    it('should not install the same plugin twice', async () => {
-      const appPlugin = {
-        name: '@test/dup-plugin',
-        version: '1.0.0',
-        type: 'app-metadata' as const,
-        init: vi.fn(),
-        start: vi.fn(),
-        stop: vi.fn(),
-      };
-
-      await pluginSystem.install(appPlugin, registry);
-      await pluginSystem.install(appPlugin, registry);
-
-      expect(appPlugin.init).toHaveBeenCalledTimes(1);
-    });
-
-    it('should uninstall a plugin and call stop', async () => {
-      const stopFn = vi.fn();
-      const appPlugin = {
-        name: '@test/removable',
-        version: '1.0.0',
-        type: 'app-metadata' as const,
-        init: vi.fn(),
-        start: vi.fn(),
-        stop: stopFn,
-      };
-
-      await pluginSystem.install(appPlugin, registry);
-      expect(pluginSystem.isLoaded('@test/removable')).toBe(true);
-
-      await pluginSystem.uninstall('@test/removable');
-      expect(pluginSystem.isLoaded('@test/removable')).toBe(false);
-      expect(stopFn).toHaveBeenCalledTimes(1);
-    });
-
-    it('should throw when uninstalling a plugin that is not installed', async () => {
-      await expect(pluginSystem.uninstall('@test/nonexistent')).rejects.toThrow(
-        'Plugin "@test/nonexistent" is not loaded'
-      );
-    });
-
-    it('should provide default context when none is given', async () => {
-      const startFn = vi.fn();
-      const appPlugin = {
-        name: '@test/default-ctx',
-        version: '1.0.0',
-        type: 'app-metadata' as const,
-        init: vi.fn(),
-        start: startFn,
-        stop: vi.fn(),
-      };
-
-      await pluginSystem.install(appPlugin, registry);
-
-      expect(startFn).toHaveBeenCalledWith({ logger: console });
-    });
-  });
-});