@object-ui/core 0.5.0 → 3.0.0

package/dist/registry/WidgetRegistry.js

@@ -0,0 +1,275 @@
+/**
+ * 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 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 {
+    constructor(options = {}) {
+        Object.defineProperty(this, "manifests", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "resolved", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "listeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "componentRegistry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.componentRegistry = options.componentRegistry;
+    }
+    /**
+     * Register a widget manifest.
+     * Does not load the widget; call `load()` to resolve it.
+     */
+    register(manifest) {
+        this.manifests.set(manifest.name, manifest);
+        this.emit({ type: 'widget:registered', widget: manifest });
+    }
+    /**
+     * Register multiple widget manifests at once.
+     */
+    registerAll(manifests) {
+        for (const manifest of manifests) {
+            this.register(manifest);
+        }
+    }
+    /**
+     * Unregister a widget by name.
+     */
+    unregister(name) {
+        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) {
+        return this.manifests.get(name);
+    }
+    /**
+     * Get all registered widget manifests.
+     */
+    getAllManifests() {
+        return Array.from(this.manifests.values());
+    }
+    /**
+     * Get manifests filtered by category.
+     */
+    getByCategory(category) {
+        return this.getAllManifests().filter((m) => m.category === category);
+    }
+    /**
+     * Check if a widget is registered.
+     */
+    has(name) {
+        return this.manifests.has(name);
+    }
+    /**
+     * Check if a widget has been loaded (resolved).
+     */
+    isLoaded(name) {
+        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) {
+        // 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 = {
+                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, {
+                    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,
+                    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() {
+        const results = [];
+        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) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Clear all registered and loaded widgets.
+     */
+    clear() {
+        this.manifests.clear();
+        this.resolved.clear();
+    }
+    /**
+     * Get registry statistics.
+     */
+    getStats() {
+        const categories = new Set();
+        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
+    // -------------------------------------------------------------------------
+    async resolveComponent(manifest) {
+        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}"`);
+        }
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Swallow listener errors to prevent cascading failures
+            }
+        }
+    }
+}

package/dist/theme/ThemeEngine.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 - Theme Engine
+ *
+ * Converts a spec-aligned Theme JSON into CSS custom properties
+ * that can be injected into the DOM. Also handles theme inheritance
+ * (extends), media-query-aware mode resolution, and token merging.
+ *
+ * @module theme
+ * @packageDocumentation
+ */
+import type { Theme, ColorPalette, ThemeMode } from '@object-ui/types';
+/**
+ * Convert a hex color (#RRGGBB or #RGB) to an HSL string "H S% L%".
+ * Returns null if the input is not a valid hex color.
+ */
+export declare function hexToHSL(hex: string): string | null;
+/**
+ * Convert a color to a CSS-ready value.
+ * - Hex colors → HSL format for Shadcn CSS variable compatibility
+ * - Non-hex colors → passed through as-is (rgb, hsl, oklch, etc.)
+ */
+export declare function toCSSColor(color: string): string;
+/**
+ * Generate CSS custom properties from a Theme's color palette.
+ */
+export declare function generateColorVars(colors: ColorPalette): Record<string, string>;
+/**
+ * Generate CSS custom properties from a Theme's typography config.
+ */
+export declare function generateTypographyVars(typography: NonNullable<Theme['typography']>): Record<string, string>;
+/**
+ * Generate CSS custom properties from a Theme's border radius config.
+ */
+export declare function generateBorderRadiusVars(borderRadius: NonNullable<Theme['borderRadius']>): Record<string, string>;
+/**
+ * Generate CSS custom properties from a Theme's shadow config.
+ */
+export declare function generateShadowVars(shadows: NonNullable<Theme['shadows']>): Record<string, string>;
+/**
+ * Generate CSS custom properties from a Theme's animation config.
+ */
+export declare function generateAnimationVars(animation: NonNullable<Theme['animation']>): Record<string, string>;
+/**
+ * Generate CSS custom properties from a Theme's z-index config.
+ */
+export declare function generateZIndexVars(zIndex: NonNullable<Theme['zIndex']>): Record<string, string>;
+/**
+ * Generate ALL CSS custom properties from a complete Theme.
+ * This is the main entry point for theme → CSS conversion.
+ */
+export declare function generateThemeVars(theme: Theme): Record<string, string>;
+/**
+ * Deep-merge two Theme objects. The `child` overrides the `parent`.
+ * Only defined properties in child override; undefined falls back to parent.
+ */
+export declare function mergeThemes(parent: Theme, child: Partial<Theme>): Theme;
+/**
+ * Resolve theme inheritance from a registry of themes.
+ * If a theme has `extends`, the parent is looked up and merged recursively.
+ *
+ * @param theme - The theme to resolve
+ * @param registry - Map of theme name → Theme
+ * @param visited - Set of already-visited names (cycle detection)
+ * @returns The fully resolved theme
+ */
+export declare function resolveThemeInheritance(theme: Theme, registry: Map<string, Theme>, visited?: Set<string>): Theme;
+/**
+ * Resolve the effective mode from a ThemeMode value.
+ * 'auto' checks the system preference (prefers-color-scheme).
+ *
+ * @param mode - The declared mode
+ * @param systemDark - Whether the system prefers dark mode (for SSR or testing)
+ * @returns 'light' or 'dark'
+ */
+export declare function resolveMode(mode?: ThemeMode, systemDark?: boolean): 'light' | 'dark';
+/**
+ * Calculate the WCAG 2.1 contrast ratio between two hex colors.
+ * Returns a value between 1 and 21.
+ *
+ * @param hex1 - First color in hex format (#RGB or #RRGGBB)
+ * @param hex2 - Second color in hex format (#RGB or #RRGGBB)
+ * @returns Contrast ratio (1-21), or null if colors are invalid
+ */
+export declare function contrastRatio(hex1: string, hex2: string): number | null;
+/**
+ * Check if two colors meet the specified WCAG contrast level.
+ *
+ * WCAG levels:
+ * - AA: 4.5:1 for normal text, 3:1 for large text
+ * - AAA: 7:1 for normal text, 4.5:1 for large text
+ *
+ * @param hex1 - First color in hex format
+ * @param hex2 - Second color in hex format
+ * @param level - WCAG level: 'AA' or 'AAA'
+ * @param isLargeText - Whether the text is large (18pt+ or 14pt+ bold)
+ * @returns true if the color pair meets the required contrast level
+ */
+export declare function meetsContrastLevel(hex1: string, hex2: string, level?: 'AA' | 'AAA', isLargeText?: boolean): boolean;