@object-ui/core 0.3.1 → 2.0.0

package/src/registry/PluginScopeImpl.ts

@@ -0,0 +1,259 @@
+/**
+ * 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.
+ */
+
+/**
+ * @object-ui/core - Plugin Scope Implementation
+ * 
+ * Section 3.3: Implementation of scoped plugin system to prevent conflicts.
+ * Provides isolated component registration, state management, and event bus.
+ * 
+ * @module plugin-scope-impl
+ * @packageDocumentation
+ */
+
+import type { 
+  PluginScope, 
+  PluginScopeConfig, 
+  PluginEventHandler
+} from '@object-ui/types';
+import type { Registry, ComponentMeta as RegistryComponentMeta } from './Registry.js';
+
+/**
+ * Event Bus for scoped plugin events
+ */
+class EventBus {
+  private listeners = new Map<string, Set<PluginEventHandler>>();
+
+  on(event: string, handler: PluginEventHandler): () => void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event)!.add(handler);
+
+    // Return unsubscribe function
+    return () => {
+      this.listeners.get(event)?.delete(handler);
+      if (this.listeners.get(event)?.size === 0) {
+        this.listeners.delete(event);
+      }
+    };
+  }
+
+  emit(event: string, data?: any): void {
+    const handlers = this.listeners.get(event);
+    if (handlers) {
+      handlers.forEach(handler => {
+        try {
+          handler(data);
+        } catch (error) {
+          console.error(`Error in event handler for "${event}":`, error);
+        }
+      });
+    }
+  }
+
+  cleanup(): void {
+    this.listeners.clear();
+  }
+}
+
+/**
+ * Global event bus for cross-plugin communication
+ */
+const globalEventBus = new EventBus();
+
+/**
+ * Plugin Scope Implementation
+ * 
+ * Provides isolated access to registry, state, and events for each plugin.
+ */
+export class PluginScopeImpl implements PluginScope {
+  public readonly name: string;
+  public readonly version: string;
+  
+  private registry: Registry;
+  private state = new Map<string, any>();
+  private eventBus = new EventBus();
+  private config: Required<PluginScopeConfig>;
+
+  constructor(
+    name: string,
+    version: string,
+    registry: Registry,
+    config?: PluginScopeConfig
+  ) {
+    this.name = name;
+    this.version = version;
+    this.registry = registry;
+    this.config = {
+      enableStateIsolation: config?.enableStateIsolation ?? true,
+      enableEventIsolation: config?.enableEventIsolation ?? true,
+      allowGlobalEvents: config?.allowGlobalEvents ?? true,
+      maxStateSize: config?.maxStateSize ?? 5 * 1024 * 1024, // 5MB
+    };
+  }
+
+  /**
+   * Register a component in the scoped namespace
+   */
+  registerComponent(type: string, component: any, meta?: any): void {
+    // Components are registered as "pluginName:type"
+    const registryMeta: RegistryComponentMeta = {
+      ...meta,
+      namespace: this.name,
+    };
+    this.registry.register(type, component, registryMeta);
+  }
+
+  /**
+   * Get a component from the scoped namespace
+   */
+  getComponent(type: string): any | undefined {
+    // First try scoped lookup
+    const scoped = this.registry.get(`${this.name}:${type}`);
+    if (scoped) {
+      return scoped;
+    }
+    
+    // Fall back to global lookup
+    return this.registry.get(type);
+  }
+
+  /**
+   * Scoped state management
+   */
+  useState<T>(key: string, initialValue: T): [T, (value: T | ((prev: T) => T)) => void] {
+    if (!this.config.enableStateIsolation) {
+      throw new Error('State isolation is disabled for this plugin');
+    }
+
+    // Initialize state if not present
+    if (!this.state.has(key)) {
+      this.setState(key, initialValue);
+    }
+
+    const currentValue = this.getState<T>(key) ?? initialValue;
+
+    const setValue = (value: T | ((prev: T) => T)) => {
+      const newValue = typeof value === 'function' 
+        ? (value as (prev: T) => T)(this.getState<T>(key) ?? initialValue)
+        : value;
+      this.setState(key, newValue);
+    };
+
+    return [currentValue, setValue];
+  }
+
+  /**
+   * Get scoped state value
+   */
+  getState<T>(key: string): T | undefined {
+    return this.state.get(key);
+  }
+
+  /**
+   * Set scoped state value
+   */
+  setState<T>(key: string, value: T): void {
+    if (!this.config.enableStateIsolation) {
+      throw new Error('State isolation is disabled for this plugin');
+    }
+
+    // Check state size limit
+    const stateSize = this.estimateStateSize();
+    const valueSize = this.estimateValueSize(value);
+    
+    if (stateSize + valueSize > this.config.maxStateSize) {
+      throw new Error(
+        `Plugin "${this.name}" exceeded maximum state size of ${this.config.maxStateSize} bytes`
+      );
+    }
+
+    this.state.set(key, value);
+  }
+
+  /**
+   * Subscribe to scoped events
+   */
+  on(event: string, handler: PluginEventHandler): () => void {
+    if (!this.config.enableEventIsolation) {
+      // If isolation is disabled, use global event bus
+      return this.onGlobal(event, handler);
+    }
+
+    // Scoped event: prefix with plugin name
+    const scopedEvent = `${this.name}:${event}`;
+    return this.eventBus.on(scopedEvent, handler);
+  }
+
+  /**
+   * Emit a scoped event
+   */
+  emit(event: string, data?: any): void {
+    if (!this.config.enableEventIsolation) {
+      // If isolation is disabled, emit globally
+      this.emitGlobal(event, data);
+      return;
+    }
+
+    // Scoped event: prefix with plugin name
+    const scopedEvent = `${this.name}:${event}`;
+    this.eventBus.emit(scopedEvent, data);
+  }
+
+  /**
+   * Emit a global event
+   */
+  emitGlobal(event: string, data?: any): void {
+    if (!this.config.allowGlobalEvents) {
+      throw new Error('Global events are disabled for this plugin');
+    }
+    globalEventBus.emit(event, data);
+  }
+
+  /**
+   * Subscribe to global events
+   */
+  onGlobal(event: string, handler: PluginEventHandler): () => void {
+    if (!this.config.allowGlobalEvents) {
+      throw new Error('Global events are disabled for this plugin');
+    }
+    return globalEventBus.on(event, handler);
+  }
+
+  /**
+   * Clean up all plugin resources
+   */
+  cleanup(): void {
+    this.state.clear();
+    this.eventBus.cleanup();
+  }
+
+  /**
+   * Estimate total state size in bytes
+   */
+  private estimateStateSize(): number {
+    let size = 0;
+    for (const value of this.state.values()) {
+      size += this.estimateValueSize(value);
+    }
+    return size;
+  }
+
+  /**
+   * Estimate size of a value in bytes
+   */
+  private estimateValueSize(value: any): number {
+    try {
+      return JSON.stringify(value).length * 2; // UTF-16 encoding
+    } catch {
+      // If not serializable, use rough estimate
+      return 1024; // 1KB default
+    }
+  }
+}

package/src/registry/PluginSystem.ts

@@ -0,0 +1,161 @@
+/**
+ * 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 type { Registry } from './Registry.js';
+import type { PluginScope, PluginScopeConfig } from '@object-ui/types';
+import { PluginScopeImpl } from './PluginScopeImpl.js';
+
+export interface PluginDefinition {
+  name: string;
+  version: string;
+  dependencies?: string[];  // Dependencies on other plugins
+  peerDependencies?: string[];  // Peer dependencies
+  register: (registry: Registry | PluginScope) => void;  // Support both legacy and scoped registration
+  onLoad?: () => void | Promise<void>;  // Lifecycle hook: called after registration
+  onUnload?: () => void | Promise<void>;  // Lifecycle hook: called before unload
+  scopeConfig?: PluginScopeConfig;  // Optional scope configuration
+}
+
+export class PluginSystem {
+  private plugins = new Map<string, PluginDefinition>();
+  private loaded = new Set<string>();
+  private scopes = new Map<string, PluginScopeImpl>();
+
+  /**
+   * Load a plugin into the system with optional scope isolation
+   * @param plugin The plugin definition to load
+   * @param registry The component registry to use for registration
+   * @param useScope Whether to use scoped loading (default: true for better isolation)
+   * @throws Error if dependencies are missing
+   */
+  async loadPlugin(plugin: PluginDefinition, registry: Registry, useScope: boolean = true): Promise<void> {
+    // Check if already loaded
+    if (this.loaded.has(plugin.name)) {
+      console.warn(`Plugin "${plugin.name}" is already loaded. Skipping.`);
+      return;
+    }
+
+    // Check dependencies
+    for (const dep of plugin.dependencies || []) {
+      if (!this.loaded.has(dep)) {
+        throw new Error(`Missing dependency: ${dep} required by ${plugin.name}`);
+      }
+    }
+
+    try {
+      if (useScope) {
+        // Create scoped environment for plugin
+        const scope = new PluginScopeImpl(
+          plugin.name,
+          plugin.version,
+          registry,
+          plugin.scopeConfig
+        );
+        
+        // Store scope for cleanup
+        this.scopes.set(plugin.name, scope);
+        
+        // Execute registration with scope
+        plugin.register(scope);
+      } else {
+        // Legacy mode: direct registry access
+        plugin.register(registry);
+      }
+
+      // Store plugin definition
+      this.plugins.set(plugin.name, plugin);
+
+      // Execute lifecycle hook
+      await plugin.onLoad?.();
+
+      // Mark as loaded
+      this.loaded.add(plugin.name);
+    } catch (error) {
+      // Clean up on failure
+      this.plugins.delete(plugin.name);
+      this.scopes.delete(plugin.name);
+      throw error;
+    }
+  }
+
+  /**
+   * Unload a plugin from the system
+   * @param name The name of the plugin to unload
+   * @throws Error if other plugins depend on this plugin
+   */
+  async unloadPlugin(name: string): Promise<void> {
+    const plugin = this.plugins.get(name);
+    if (!plugin) {
+      throw new Error(`Plugin "${name}" is not loaded`);
+    }
+
+    // Check if any loaded plugins depend on this one
+    for (const [pluginName, pluginDef] of this.plugins.entries()) {
+      if (this.loaded.has(pluginName) && pluginDef.dependencies?.includes(name)) {
+        throw new Error(`Cannot unload plugin "${name}" - plugin "${pluginName}" depends on it`);
+      }
+    }
+
+    // Execute lifecycle hook
+    await plugin.onUnload?.();
+
+    // Clean up scope if exists
+    const scope = this.scopes.get(name);
+    if (scope) {
+      scope.cleanup();
+      this.scopes.delete(name);
+    }
+
+    // Remove from loaded set
+    this.loaded.delete(name);
+    this.plugins.delete(name);
+  }
+
+  /**
+   * Get the scope for a loaded plugin
+   * @param name The name of the plugin
+   * @returns The plugin scope or undefined
+   */
+  getScope(name: string): PluginScope | undefined {
+    return this.scopes.get(name);
+  }
+
+  /**
+   * Check if a plugin is loaded
+   * @param name The name of the plugin
+   * @returns true if the plugin is loaded
+   */
+  isLoaded(name: string): boolean {
+    return this.loaded.has(name);
+  }
+
+  /**
+   * Get a loaded plugin definition
+   * @param name The name of the plugin
+   * @returns The plugin definition or undefined
+   */
+  getPlugin(name: string): PluginDefinition | undefined {
+    return this.plugins.get(name);
+  }
+
+  /**
+   * Get all loaded plugin names
+   * @returns Array of loaded plugin names
+   */
+  getLoadedPlugins(): string[] {
+    return Array.from(this.loaded);
+  }
+
+  /**
+   * Get all plugin definitions
+   * @returns Array of all plugin definitions
+   */
+  getAllPlugins(): PluginDefinition[] {
+    return Array.from(this.plugins.values());
+  }
+}

package/src/registry/Registry.ts

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type { SchemaNode } from '../types';
+import type { SchemaNode } from '../types/index.js';
 
 export type ComponentRenderer<T = any> = T;
 
@@ -26,6 +26,17 @@ export type ComponentMeta = {
   label?: string; // Display name in designer
   icon?: string; // Icon name or svg string
   category?: string; // Grouping category
+  namespace?: string; // Component namespace (e.g., 'ui', 'plugin-grid', 'field')
+  /**
+   * When true, prevents the component from being registered with a non-namespaced fallback.
+   * Use this when a component should only be accessible via its full namespaced key.
+   * This avoids conflicts with other components that share the same base name.
+   * 
+   * @example
+   * // Register as 'view:form' only, don't overwrite 'form'
+   * registry.register('form', FormView, { namespace: 'view', skipFallback: true });
+   */
+  skipFallback?: boolean;
   inputs?: ComponentInput[];
   defaultProps?: Record<string, any>; // Default props when dropped
   defaultChildren?: SchemaNode[]; // Default children when dropped
@@ -50,36 +61,153 @@ export type ComponentConfig<T = any> = ComponentMeta & {
 export class Registry<T = any> {
   private components = new Map<string, ComponentConfig<T>>();
 
+  /**
+   * Register a component with optional namespace support.
+   * If namespace is provided in meta, the component will be registered as "namespace:type".
+   * 
+   * @param type - Component type identifier
+   * @param component - Component renderer
+   * @param meta - Component metadata (including optional namespace)
+   * 
+   * @example
+   * // Register with namespace
+   * registry.register('button', ButtonComponent, { namespace: 'ui' });
+   * // Accessible as 'ui:button' or 'button' (fallback)
+   * 
+   * @example
+   * // Register without namespace (backward compatible)
+   * registry.register('button', ButtonComponent);
+   * // Accessible as 'button'
+   */
   register(type: string, component: ComponentRenderer<T>, meta?: ComponentMeta) {
-    if (this.components.has(type)) {
-      console.warn(`Component type "${type}" is already registered. Overwriting.`);
+    const fullType = meta?.namespace ? `${meta.namespace}:${type}` : type;
+    
+    // Warn if registering without namespace (deprecated pattern)
+    if (!meta?.namespace) {
+      console.warn(
+        `Registering component "${type}" without a namespace is deprecated. ` +
+        `Please provide a namespace in the meta parameter.`
+      );
     }
-    this.components.set(type, {
-      type,
+    
+    if (this.components.has(fullType)) {
+      // console.warn(`Component type "${fullType}" is already registered. Overwriting.`);
+    }
+    
+    this.components.set(fullType, {
+      type: fullType,
       component,
       ...meta
     });
+    
+    // Also register without namespace for backward compatibility
+    // This allows "button" to work even when registered as "ui:button"
+    // Note: If multiple namespaced components share the same short name,
+    // the last registration wins for non-namespaced lookups
+    // Skip this if skipFallback is true to avoid overwriting other components
+    if (meta?.namespace && !meta?.skipFallback) {
+      this.components.set(type, {
+        type: fullType, // Keep reference to namespaced type
+        component,
+        ...meta
+      });
+    }
   }
 
-  get(type: string): ComponentRenderer<T> | undefined {
+  /**
+   * Get a component by type. Supports both namespaced and non-namespaced lookups.
+   * 
+   * @param type - Component type (e.g., 'button' or 'ui:button')
+   * @param namespace - Optional namespace for lookup priority
+   * @returns Component renderer or undefined
+   * 
+   * @example
+   * // Direct lookup
+   * registry.get('ui:button') // Gets ui:button
+   * 
+   * @example
+   * // Fallback lookup
+   * registry.get('button') // Gets first registered button
+   * 
+   * @example
+   * // Namespaced lookup with priority
+   * registry.get('button', 'ui') // Tries 'ui:button' first, then 'button'
+   */
+  get(type: string, namespace?: string): ComponentRenderer<T> | undefined {
+    // If namespace is explicitly provided, ONLY look in that namespace (no fallback)
+    if (namespace) {
+      const namespacedType = `${namespace}:${type}`;
+      return this.components.get(namespacedType)?.component;
+    }
+    
+    // When no namespace provided, use backward compatibility lookup
     return this.components.get(type)?.component;
   }
 
-  getConfig(type: string): ComponentConfig<T> | undefined {
+  /**
+   * Get component configuration by type with namespace support.
+   * 
+   * @param type - Component type (e.g., 'button' or 'ui:button')
+   * @param namespace - Optional namespace for lookup priority
+   * @returns Component configuration or undefined
+   */
+  getConfig(type: string, namespace?: string): ComponentConfig<T> | undefined {
+    // If namespace is explicitly provided, ONLY look in that namespace (no fallback)
+    if (namespace) {
+      const namespacedType = `${namespace}:${type}`;
+      return this.components.get(namespacedType);
+    }
+    
+    // When no namespace provided, use backward compatibility lookup
     return this.components.get(type);
   }
 
-  has(type: string): boolean {
+  /**
+   * Check if a component type is registered.
+   * 
+   * @param type - Component type (e.g., 'button' or 'ui:button')
+   * @param namespace - Optional namespace for lookup
+   * @returns True if component is registered
+   */
+  has(type: string, namespace?: string): boolean {
+    // If namespace is explicitly provided, ONLY look in that namespace (no fallback)
+    if (namespace) {
+      const namespacedType = `${namespace}:${type}`;
+      return this.components.has(namespacedType);
+    }
+    // When no namespace provided, use backward compatibility lookup
     return this.components.has(type);
   }
   
+  /**
+   * Get all registered component types.
+   * 
+   * @returns Array of all component type identifiers
+   */
   getAllTypes(): string[] {
     return Array.from(this.components.keys());
   }
 
+  /**
+   * Get all registered component configurations.
+   * 
+   * @returns Array of all component configurations
+   */
   getAllConfigs(): ComponentConfig<T>[] {
     return Array.from(this.components.values());
   }
+  
+  /**
+   * Get all components in a specific namespace.
+   * 
+   * @param namespace - Namespace to filter by
+   * @returns Array of component configurations in the namespace
+   */
+  getNamespaceComponents(namespace: string): ComponentConfig<T>[] {
+    return Array.from(this.components.values()).filter(
+      config => config.namespace === namespace
+    );
+  }
 }
 
 export const ComponentRegistry = new Registry<any>();