@object-ui/core 0.5.0 → 3.0.0

package/src/registry/WidgetRegistry.ts

@@ -0,0 +1,316 @@
+/**
+ * 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__/WidgetRegistry.test.ts

@@ -0,0 +1,321 @@
+/**
+ * Tests for WidgetRegistry
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { WidgetRegistry } from '../WidgetRegistry';
+import { Registry } from '../Registry';
+import type { WidgetManifest, WidgetRegistryEvent } from '@object-ui/types';
+
+function createManifest(overrides: Partial<WidgetManifest> = {}): WidgetManifest {
+  return {
+    name: 'test-widget',
+    version: '1.0.0',
+    type: 'test',
+    label: 'Test Widget',
+    source: { type: 'inline', component: () => null },
+    ...overrides,
+  };
+}
+
+describe('WidgetRegistry', () => {
+  let widgetRegistry: WidgetRegistry;
+
+  beforeEach(() => {
+    widgetRegistry = new WidgetRegistry();
+  });
+
+  describe('register / unregister', () => {
+    it('registers a widget manifest', () => {
+      const manifest = createManifest();
+      widgetRegistry.register(manifest);
+      expect(widgetRegistry.has('test-widget')).toBe(true);
+      expect(widgetRegistry.getManifest('test-widget')).toBe(manifest);
+    });
+
+    it('registers multiple manifests at once', () => {
+      widgetRegistry.registerAll([
+        createManifest({ name: 'a', type: 'a' }),
+        createManifest({ name: 'b', type: 'b' }),
+      ]);
+      expect(widgetRegistry.has('a')).toBe(true);
+      expect(widgetRegistry.has('b')).toBe(true);
+    });
+
+    it('unregisters a widget', () => {
+      widgetRegistry.register(createManifest());
+      expect(widgetRegistry.unregister('test-widget')).toBe(true);
+      expect(widgetRegistry.has('test-widget')).toBe(false);
+    });
+
+    it('returns false when unregistering a non-existent widget', () => {
+      expect(widgetRegistry.unregister('nope')).toBe(false);
+    });
+  });
+
+  describe('getAllManifests / getByCategory', () => {
+    it('returns all manifests', () => {
+      widgetRegistry.registerAll([
+        createManifest({ name: 'a', type: 'a' }),
+        createManifest({ name: 'b', type: 'b' }),
+      ]);
+      expect(widgetRegistry.getAllManifests()).toHaveLength(2);
+    });
+
+    it('filters by category', () => {
+      widgetRegistry.registerAll([
+        createManifest({ name: 'chart-1', type: 'c1', category: 'charts' }),
+        createManifest({ name: 'form-1', type: 'f1', category: 'forms' }),
+        createManifest({ name: 'chart-2', type: 'c2', category: 'charts' }),
+      ]);
+      expect(widgetRegistry.getByCategory('charts')).toHaveLength(2);
+      expect(widgetRegistry.getByCategory('forms')).toHaveLength(1);
+      expect(widgetRegistry.getByCategory('unknown')).toHaveLength(0);
+    });
+  });
+
+  describe('load', () => {
+    it('loads an inline widget', async () => {
+      const component = () => null;
+      widgetRegistry.register(
+        createManifest({ source: { type: 'inline', component } }),
+      );
+
+      const resolved = await widgetRegistry.load('test-widget');
+      expect(resolved.component).toBe(component);
+      expect(resolved.manifest.name).toBe('test-widget');
+      expect(resolved.loadedAt).toBeGreaterThan(0);
+      expect(widgetRegistry.isLoaded('test-widget')).toBe(true);
+    });
+
+    it('returns cached resolved widget on subsequent loads', async () => {
+      widgetRegistry.register(createManifest());
+      const first = await widgetRegistry.load('test-widget');
+      const second = await widgetRegistry.load('test-widget');
+      expect(first).toBe(second);
+    });
+
+    it('throws when loading an unregistered widget', async () => {
+      await expect(widgetRegistry.load('nope')).rejects.toThrow(
+        'Widget "nope" is not registered',
+      );
+    });
+
+    it('loads a widget from the component registry', async () => {
+      const componentRegistry = new Registry();
+      const component = () => null;
+      componentRegistry.register('existing-type', component);
+
+      const reg = new WidgetRegistry({ componentRegistry });
+      reg.register(
+        createManifest({
+          source: { type: 'registry', registryKey: 'existing-type' },
+        }),
+      );
+
+      const resolved = await reg.load('test-widget');
+      expect(resolved.component).toBe(component);
+    });
+
+    it('throws when registry key is not found', async () => {
+      const componentRegistry = new Registry();
+      const reg = new WidgetRegistry({ componentRegistry });
+      reg.register(
+        createManifest({
+          source: { type: 'registry', registryKey: 'missing-key' },
+        }),
+      );
+
+      await expect(reg.load('test-widget')).rejects.toThrow(
+        'references registry key "missing-key"',
+      );
+    });
+
+    it('throws when no component registry is configured for registry source', async () => {
+      widgetRegistry.register(
+        createManifest({
+          source: { type: 'registry', registryKey: 'something' },
+        }),
+      );
+
+      await expect(widgetRegistry.load('test-widget')).rejects.toThrow(
+        'no component registry is configured',
+      );
+    });
+
+    it('resolves dependencies before loading', async () => {
+      const loadOrder: string[] = [];
+
+      widgetRegistry.register(
+        createManifest({
+          name: 'dep-a',
+          type: 'dep-a',
+          source: {
+            type: 'inline',
+            component: () => {
+              loadOrder.push('dep-a');
+              return null;
+            },
+          },
+        }),
+      );
+
+      widgetRegistry.register(
+        createManifest({
+          name: 'main',
+          type: 'main',
+          dependencies: ['dep-a'],
+          source: {
+            type: 'inline',
+            component: () => {
+              loadOrder.push('main');
+              return null;
+            },
+          },
+        }),
+      );
+
+      await widgetRegistry.load('main');
+      expect(widgetRegistry.isLoaded('dep-a')).toBe(true);
+      expect(widgetRegistry.isLoaded('main')).toBe(true);
+    });
+
+    it('syncs loaded widget to component registry', async () => {
+      const componentRegistry = new Registry();
+      const reg = new WidgetRegistry({ componentRegistry });
+      const component = () => null;
+
+      reg.register(
+        createManifest({
+          name: 'sync-test',
+          type: 'custom-type',
+          label: 'Sync Test',
+          category: 'testing',
+          source: { type: 'inline', component },
+        }),
+      );
+
+      await reg.load('sync-test');
+
+      const synced = componentRegistry.get('custom-type');
+      expect(synced).toBe(component);
+    });
+  });
+
+  describe('loadAll', () => {
+    it('loads all registered widgets', async () => {
+      widgetRegistry.registerAll([
+        createManifest({ name: 'a', type: 'a' }),
+        createManifest({ name: 'b', type: 'b' }),
+      ]);
+
+      const results = await widgetRegistry.loadAll();
+      expect(results).toHaveLength(2);
+      expect(results.every((r) => !(r.result instanceof Error))).toBe(true);
+    });
+
+    it('captures errors for failed widgets', async () => {
+      widgetRegistry.register(createManifest({ name: 'good', type: 'good' }));
+      widgetRegistry.register(
+        createManifest({
+          name: 'bad',
+          type: 'bad',
+          source: { type: 'registry', registryKey: 'missing' },
+        }),
+      );
+
+      const results = await widgetRegistry.loadAll();
+      const bad = results.find((r) => r.name === 'bad');
+      expect(bad?.result).toBeInstanceOf(Error);
+    });
+  });
+
+  describe('events', () => {
+    it('emits widget:registered event', () => {
+      const events: WidgetRegistryEvent[] = [];
+      widgetRegistry.on((e) => events.push(e));
+
+      widgetRegistry.register(createManifest());
+
+      expect(events).toHaveLength(1);
+      expect(events[0].type).toBe('widget:registered');
+    });
+
+    it('emits widget:unregistered event', () => {
+      widgetRegistry.register(createManifest());
+
+      const events: WidgetRegistryEvent[] = [];
+      widgetRegistry.on((e) => events.push(e));
+
+      widgetRegistry.unregister('test-widget');
+
+      expect(events).toHaveLength(1);
+      expect(events[0].type).toBe('widget:unregistered');
+    });
+
+    it('emits widget:loaded event', async () => {
+      widgetRegistry.register(createManifest());
+
+      const events: WidgetRegistryEvent[] = [];
+      widgetRegistry.on((e) => events.push(e));
+
+      await widgetRegistry.load('test-widget');
+
+      expect(events.some((e) => e.type === 'widget:loaded')).toBe(true);
+    });
+
+    it('emits widget:error event on load failure', async () => {
+      widgetRegistry.register(
+        createManifest({
+          source: { type: 'registry', registryKey: 'missing' },
+        }),
+      );
+
+      const events: WidgetRegistryEvent[] = [];
+      widgetRegistry.on((e) => events.push(e));
+
+      await widgetRegistry.load('test-widget').catch(() => {});
+
+      expect(events.some((e) => e.type === 'widget:error')).toBe(true);
+    });
+
+    it('supports unsubscribing from events', () => {
+      const handler = vi.fn();
+      const unsub = widgetRegistry.on(handler);
+
+      widgetRegistry.register(createManifest({ name: 'a', type: 'a' }));
+      expect(handler).toHaveBeenCalledTimes(1);
+
+      unsub();
+      widgetRegistry.register(createManifest({ name: 'b', type: 'b' }));
+      expect(handler).toHaveBeenCalledTimes(1); // No new calls
+    });
+  });
+
+  describe('clear / getStats', () => {
+    it('clears all widgets', async () => {
+      widgetRegistry.register(createManifest());
+      await widgetRegistry.load('test-widget');
+
+      widgetRegistry.clear();
+
+      expect(widgetRegistry.has('test-widget')).toBe(false);
+      expect(widgetRegistry.isLoaded('test-widget')).toBe(false);
+    });
+
+    it('returns correct stats', () => {
+      widgetRegistry.registerAll([
+        createManifest({ name: 'a', type: 'a', category: 'charts' }),
+        createManifest({ name: 'b', type: 'b', category: 'forms' }),
+        createManifest({ name: 'c', type: 'c', category: 'charts' }),
+      ]);
+
+      const stats = widgetRegistry.getStats();
+      expect(stats.registered).toBe(3);
+      expect(stats.loaded).toBe(0);
+      expect(stats.categories).toContain('charts');
+      expect(stats.categories).toContain('forms');
+      expect(stats.categories).toHaveLength(2);
+    });
+  });
+});