@object-ui/core 0.3.1 → 2.0.0

package/dist/registry/PluginSystem.js

@@ -0,0 +1,142 @@
+/**
+ * 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 { PluginScopeImpl } from './PluginScopeImpl.js';
+export class PluginSystem {
+    constructor() {
+        Object.defineProperty(this, "plugins", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "loaded", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "scopes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    /**
+     * 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, registry, useScope = true) {
+        // 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) {
+        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) {
+        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) {
+        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) {
+        return this.plugins.get(name);
+    }
+    /**
+     * Get all loaded plugin names
+     * @returns Array of loaded plugin names
+     */
+    getLoadedPlugins() {
+        return Array.from(this.loaded);
+    }
+    /**
+     * Get all plugin definitions
+     * @returns Array of all plugin definitions
+     */
+    getAllPlugins() {
+        return Array.from(this.plugins.values());
+    }
+}

package/dist/registry/Registry.d.ts

@@ -5,7 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * 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;
 export type ComponentInput = {
     name: string;
@@ -25,6 +25,17 @@ export type ComponentMeta = {
     label?: string;
     icon?: string;
     category?: string;
+    namespace?: string;
+    /**
+     * 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>;
     defaultChildren?: SchemaNode[];
@@ -46,11 +57,79 @@ export type ComponentConfig<T = any> = ComponentMeta & {
 };
 export declare class Registry<T = any> {
     private components;
+    /**
+     * 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): void;
-    get(type: string): ComponentRenderer<T> | undefined;
-    getConfig(type: string): ComponentConfig<T> | undefined;
-    has(type: string): boolean;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Get all registered component types.
+     *
+     * @returns Array of all component type identifiers
+     */
     getAllTypes(): string[];
+    /**
+     * Get all registered component configurations.
+     *
+     * @returns Array of all component configurations
+     */
     getAllConfigs(): ComponentConfig<T>[];
+    /**
+     * 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>[];
 }
 export declare const ComponentRegistry: Registry<any>;

package/dist/registry/Registry.js

@@ -14,30 +14,136 @@ export class Registry {
             value: new Map()
         });
     }
+    /**
+     * 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, component, meta) {
-        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) {
+    /**
+     * 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, namespace) {
+        // 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) {
+    /**
+     * 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, namespace) {
+        // 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) {
+    /**
+     * 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, namespace) {
+        // 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() {
         return Array.from(this.components.keys());
     }
+    /**
+     * Get all registered component configurations.
+     *
+     * @returns Array of all component configurations
+     */
     getAllConfigs() {
         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) {
+        return Array.from(this.components.values()).filter(config => config.namespace === namespace);
+    }
 }
 export const ComponentRegistry = new Registry();

package/dist/registry/WidgetRegistry.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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, 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 declare class WidgetRegistry {
+    private manifests;
+    private resolved;
+    private listeners;
+    private componentRegistry?;
+    constructor(options?: WidgetRegistryOptions);
+    /**
+     * Register a widget manifest.
+     * Does not load the widget; call `load()` to resolve it.
+     */
+    register(manifest: WidgetManifest): void;
+    /**
+     * Register multiple widget manifests at once.
+     */
+    registerAll(manifests: WidgetManifest[]): void;
+    /**
+     * Unregister a widget by name.
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get a widget manifest by name.
+     */
+    getManifest(name: string): WidgetManifest | undefined;
+    /**
+     * Get all registered widget manifests.
+     */
+    getAllManifests(): WidgetManifest[];
+    /**
+     * Get manifests filtered by category.
+     */
+    getByCategory(category: string): WidgetManifest[];
+    /**
+     * Check if a widget is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Check if a widget has been loaded (resolved).
+     */
+    isLoaded(name: string): boolean;
+    /**
+     * 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.
+     */
+    load(name: string): Promise<ResolvedWidget>;
+    /**
+     * Load all registered widgets.
+     * Returns an array of results (settled promises).
+     */
+    loadAll(): Promise<Array<{
+        name: string;
+        result: ResolvedWidget | Error;
+    }>>;
+    /**
+     * Subscribe to widget registry events.
+     * @returns Unsubscribe function.
+     */
+    on(listener: WidgetRegistryListener): () => void;
+    /**
+     * Clear all registered and loaded widgets.
+     */
+    clear(): void;
+    /**
+     * Get registry statistics.
+     */
+    getStats(): {
+        registered: number;
+        loaded: number;
+        categories: string[];
+    };
+    private resolveComponent;
+    private emit;
+}