@uistate/core 2.0.0 → 3.0.0

package/src/index.js

@@ -3,58 +3,211 @@
  * 
  * A unified system that combines CSS and Event-based state management with templating
  * Integrates CSS variables, event-based state, and template management for optimal performance
+ * Provides a simple, declarative API for state management
+ * Uses the DOM as the source of truth for state
+ * Supports plugins through a clean composition system
  */
-import { createCssState } from './cssState.js';
+import createCssState from './cssState.js';
 import { createEventState } from './eventState.js';
 import { createTemplateManager } from './templateManager.js';
 
+/**
+ * Utility function to convert hierarchical path notation to CSS variable notation
+ * Converts dot notation (e.g., 'user.profile.name') to dash notation (e.g., 'user-profile-name')
+ * @param {string} path - Hierarchical path with dot notation
+ * @returns {string} - CSS-compatible path with dash notation
+ */
+function convertPathToCssPath(path) {
+    return path.replace(/\./g, "-");
+}
+
 const createUnifiedState = (initialState = {}) => {
-    // Initialize state store
-    const store = JSON.parse(JSON.stringify(initialState));
-    
-    // Create the CSS state manager
+    // Create the CSS state manager with integrated serialization
     const cssState = createCssState(initialState);
     
     // Create the event state manager with the same initial state
     const eventState = createEventState(initialState);
     
+    // Plugin system
+    const plugins = new Map();
+    const middlewares = [];
+    const lifecycleHooks = {
+        beforeStateChange: [],
+        afterStateChange: [],
+        onInit: [],
+        onDestroy: []
+    };
+    
     // Create a unified API
     const unifiedState = {
-        _isNotifying: false, // Flag to prevent recursive notifications
+        _isNotifying: false,
+        _cssState: cssState, // Reference to cssState for direct access to advanced features
         
         // Get state with hierarchical path support
         getState(path) {
-            if (!path) return store;
-            
-            // Try to get from event state first (faster)
+            // Always use eventState as the source of truth
+            // This ensures consistency with the DOM state
             const value = eventState.get(path);
             
-            if (value !== undefined) return value;
+            // If path is undefined or value not found in eventState
+            if (path && value === undefined) {
+                // Fall back to CSS variable (for values set outside this API)
+                const cssPath = convertPathToCssPath(path);
+                return cssState.getState(cssPath);
+            }
             
-            // Fall back to CSS variable (for values set outside this API)
-            const cssPath = path.replace(/\./g, "-");
-            return cssState.getState(cssPath);
+            return value;
         },
         
         // Set state with hierarchical path support
         setState(path, value) {
-            // Prevent recursive notifications
-            if (this._isNotifying) return value;
+            if (!path) return this;
+            
+            // Run before state change middlewares
+            let finalValue = value;
+            let shouldContinue = true;
+            
+            // Apply middlewares
+            for (const middleware of middlewares) {
+                const result = middleware(path, finalValue, this.getState.bind(this));
+                if (result === false) {
+                    shouldContinue = false;
+                    break;
+                } else if (result !== undefined) {
+                    finalValue = result;
+                }
+            }
+            
+            // Run lifecycle hooks
+            for (const hook of lifecycleHooks.beforeStateChange) {
+                hook(path, finalValue, this.getState.bind(this));
+            }
+            
+            if (!shouldContinue) return this;
+            
+            // Update event state (for JS access and pub/sub)
+            eventState.set(path, finalValue);
+            
+            // Update CSS state (for styling and DOM representation)
+            const cssPath = convertPathToCssPath(path);
+            cssState.setState(cssPath, finalValue);
+            
+            // Run after state change hooks
+            for (const hook of lifecycleHooks.afterStateChange) {
+                hook(path, finalValue, this.getState.bind(this));
+            }
+            
+            return this;
+        },
+        
+        // Plugin system methods
+        use(pluginName, plugin) {
+            if (plugins.has(pluginName)) {
+                console.warn(`Plugin '${pluginName}' is already registered. It will be replaced.`);
+            }
+            
+            // Register the plugin
+            plugins.set(pluginName, plugin);
+            
+            // Initialize the plugin
+            if (typeof plugin.init === 'function') {
+                // Pass the API to the plugin
+                plugin.init(this);
+            }
+            
+            // Register middlewares
+            if (Array.isArray(plugin.middlewares)) {
+                middlewares.push(...plugin.middlewares);
+            }
+            
+            // Register lifecycle hooks
+            if (plugin.hooks) {
+                Object.entries(plugin.hooks).forEach(([hookName, hookFn]) => {
+                    if (Array.isArray(lifecycleHooks[hookName])) {
+                        lifecycleHooks[hookName].push(hookFn);
+                    }
+                });
+            }
+            
+            // Add plugin methods to the API
+            if (plugin.methods) {
+                Object.entries(plugin.methods).forEach(([methodName, method]) => {
+                    if (typeof method === 'function') {
+                        this[methodName] = method.bind(plugin);
+                    }
+                });
+            }
+            
+            return this;
+        },
+        
+        getPlugin(pluginName) {
+            return plugins.get(pluginName);
+        },
+        
+        hasPlugin(pluginName) {
+            return plugins.has(pluginName);
+        },
+        
+        removePlugin(pluginName) {
+            const plugin = plugins.get(pluginName);
+            if (!plugin) return false;
+            
+            // Run cleanup if available
+            if (typeof plugin.destroy === 'function') {
+                plugin.destroy();
+            }
+            
+            // Remove plugin methods
+            if (plugin.methods) {
+                Object.keys(plugin.methods).forEach(methodName => {
+                    delete this[methodName];
+                });
+            }
+            
+            // Remove middlewares
+            if (Array.isArray(plugin.middlewares)) {
+                plugin.middlewares.forEach(middleware => {
+                    const index = middlewares.indexOf(middleware);
+                    if (index !== -1) {
+                        middlewares.splice(index, 1);
+                    }
+                });
+            }
             
-            this._isNotifying = true;
+            // Remove lifecycle hooks
+            if (plugin.hooks) {
+                Object.entries(plugin.hooks).forEach(([hookName, hookFn]) => {
+                    if (Array.isArray(lifecycleHooks[hookName])) {
+                        const index = lifecycleHooks[hookName].indexOf(hookFn);
+                        if (index !== -1) {
+                            lifecycleHooks[hookName].splice(index, 1);
+                        }
+                    }
+                });
+            }
             
-            try {
-                // Update event state
-                eventState.set(path, value);
-                
-                // Update CSS state (convert dots to dashes for CSS variables)
-                const cssPath = path.replace(/\./g, "-");
-                cssState.setState(cssPath, value);
-                
-                return value;
-            } finally {
-                this._isNotifying = false;
+            // Remove the plugin
+            plugins.delete(pluginName);
+            return true;
+        },
+        
+        // Add middleware
+        addMiddleware(middleware) {
+            if (typeof middleware === 'function') {
+                middlewares.push(middleware);
+                return true;
             }
+            return false;
+        },
+        
+        // Add lifecycle hook
+        addHook(hookName, hookFn) {
+            if (typeof hookFn === 'function' && Array.isArray(lifecycleHooks[hookName])) {
+                lifecycleHooks[hookName].push(hookFn);
+                return true;
+            }
+            return false;
         },
         
         // Subscribe to state changes with support for wildcards
@@ -67,8 +220,44 @@ const createUnifiedState = (initialState = {}) => {
             return cssState.observe(key, callback);
         },
         
+        // Configure serialization options
+        configureSerializer(config) {
+            cssState.configureSerializer(config);
+            return this;
+        },
+        
+        // Get current serializer configuration
+        getSerializerConfig() {
+            return cssState._serializer?.config || null;
+        },
+        
+        // Set serialization mode ('hybrid', 'json', or 'escape')
+        setSerializationMode(mode) {
+            return this.configureSerializer({ mode });
+        },
+        
         // Clean up resources
         destroy() {
+            // Run onDestroy hooks
+            for (const hook of lifecycleHooks.onDestroy) {
+                hook();
+            }
+            
+            // Destroy all plugins
+            for (const [pluginName, plugin] of plugins.entries()) {
+                if (typeof plugin.destroy === 'function') {
+                    plugin.destroy();
+                }
+            }
+            
+            // Clear plugins and middlewares
+            plugins.clear();
+            middlewares.length = 0;
+            Object.keys(lifecycleHooks).forEach(key => {
+                lifecycleHooks[key].length = 0;
+            });
+            
+            // Destroy core state management
             cssState.destroy();
             eventState.destroy();
         }
@@ -80,23 +269,75 @@ const createUnifiedState = (initialState = {}) => {
 // Create a singleton instance of the unified state
 const UnifiedState = createUnifiedState();
 
-// Create a template manager connected to the unified state
-const TemplateManager = createTemplateManager(UnifiedState);
+// Create a template manager plugin
+const templateManagerPlugin = {
+    name: 'templateManager',
+    instance: null,
+    
+    init(api) {
+        this.instance = createTemplateManager(api);
+        return this;
+    },
+    
+    destroy() {
+        // Any cleanup needed for the template manager
+    },
+    
+    // Plugin methods that will be added to the UIstate API
+    methods: {
+        onAction(action, handler) {
+            return this.instance.onAction(action, handler);
+        },
+        
+        registerActions(actionsMap) {
+            return this.instance.registerActions(actionsMap);
+        },
+        
+        attachDelegation(root = document.body) {
+            return this.instance.attachDelegation(root);
+        },
+        
+        mount(componentName, container) {
+            return this.instance.mount(componentName, container);
+        },
+        
+        renderTemplateFromCss(templateName, data) {
+            return this.instance.renderTemplateFromCss(templateName, data);
+        },
+        
+        createComponent(name, renderFn, stateKeys) {
+            return this.instance.createComponent(name, renderFn, stateKeys);
+        },
+        
+        applyClassesFromState(element, stateKey, options) {
+            return this.instance.applyClassesFromState(element, stateKey, options);
+        }
+    },
+    
+    // Expose handlers property
+    get handlers() {
+        return this.instance.handlers;
+    }
+};
 
-// Create a combined API for backward compatibility
+// Create a combined API with plugin support
 const UIstate = {
     ...UnifiedState,
     
-    // Add template manager methods
-    handlers: TemplateManager.handlers,
-    onAction: TemplateManager.onAction.bind(TemplateManager),
-    attachDelegation: TemplateManager.attachDelegation.bind(TemplateManager),
-    mount: TemplateManager.mount.bind(TemplateManager),
-    
-    // Initialize both systems
+    // Initialize the system with plugins
     init() {
+        // Register the template manager plugin
+        this.use('templateManager', templateManagerPlugin);
+        
+        // Run onInit hooks
+        for (const hook of this.getPlugin('templateManager').instance.lifecycleHooks?.onInit || []) {
+        // for (const hook of lifecycleHooks.onInit) {
+            hook();
+        }
+        
         // Attach event delegation to document body
         this.attachDelegation(document.body);
+        
         return this;
     }
 };
@@ -104,8 +345,9 @@ const UIstate = {
 export default UIstate;
 export { 
     createUnifiedState, 
-    UnifiedState,
+    createCssState, 
+    createEventState, 
     createTemplateManager,
-    TemplateManager,
-    UIstate 
+    convertPathToCssPath,
+    templateManagerPlugin
 };

package/src/stateInspector.js

@@ -0,0 +1,140 @@
+/**
+ * StateInspector - Real-time state inspection panel for UIstate
+ * 
+ * This module provides a configurable UI panel that displays and allows manipulation
+ * of CSS variables and state values in UIstate applications.
+ * 
+ * Features:
+ * - Toggle visibility with a dedicated button
+ * - Real-time updates of CSS variable values
+ * - Organized display of state by categories
+ * - Ability to filter state variables
+ * - Direct manipulation of state values
+ */
+
+/**
+ * Create a configured state inspector instance
+ * @param {Object} config - Configuration options
+ * @returns {Object} - StateInspector instance
+ */
+function createStateInspector(config = {}) {
+    // Default configuration
+    const defaultConfig = {
+        target: document.body,
+        initiallyVisible: false,
+        categories: ['app', 'ui', 'data'],
+        position: 'bottom-right',
+        maxHeight: '300px',
+        stateManager: null, // Optional reference to UIstate or CssState instance
+        theme: 'light'
+    };
+    
+    // Merge provided config with defaults
+    const options = { ...defaultConfig, ...config };
+    
+    // Private state
+    let isVisible = options.initiallyVisible;
+    let panel = null;
+    let toggleButton = null;
+    let filterInput = null;
+    let stateContainer = null;
+    let currentFilter = '';
+    
+    // StateInspector instance
+    const inspector = {
+        // Current configuration
+        config: options,
+        
+        /**
+         * Update configuration
+         * @param {Object} newConfig - New configuration options
+         */
+        configure(newConfig) {
+            Object.assign(this.config, newConfig);
+            this.refresh();
+        },
+        
+        /**
+         * Attach the inspector panel to the target element
+         * @param {Element} element - Target element to attach to (defaults to config.target)
+         * @returns {Object} - The inspector instance for chaining
+         */
+        attach(element = this.config.target) {
+            // Implementation will create and attach the panel
+            // For now, this is a placeholder
+            console.log('StateInspector: Panel would be attached to', element);
+            return this;
+        },
+        
+        /**
+         * Show the inspector panel
+         * @returns {Object} - The inspector instance for chaining
+         */
+        show() {
+            isVisible = true;
+            if (panel) panel.style.display = 'block';
+            return this;
+        },
+        
+        /**
+         * Hide the inspector panel
+         * @returns {Object} - The inspector instance for chaining
+         */
+        hide() {
+            isVisible = false;
+            if (panel) panel.style.display = 'none';
+            return this;
+        },
+        
+        /**
+         * Toggle the visibility of the inspector panel
+         * @returns {Object} - The inspector instance for chaining
+         */
+        toggle() {
+            return isVisible ? this.hide() : this.show();
+        },
+        
+        /**
+         * Refresh the state display
+         * @returns {Object} - The inspector instance for chaining
+         */
+        refresh() {
+            // Implementation will update the displayed state values
+            // For now, this is a placeholder
+            console.log('StateInspector: State display would be refreshed');
+            return this;
+        },
+        
+        /**
+         * Filter the displayed state variables
+         * @param {string} filterText - Text to filter by
+         * @returns {Object} - The inspector instance for chaining
+         */
+        filter(filterText) {
+            currentFilter = filterText;
+            // Implementation will filter the displayed variables
+            return this.refresh();
+        },
+        
+        /**
+         * Clean up resources used by the inspector
+         */
+        destroy() {
+            if (panel && panel.parentNode) {
+                panel.parentNode.removeChild(panel);
+            }
+            panel = null;
+            toggleButton = null;
+            filterInput = null;
+            stateContainer = null;
+        }
+    };
+    
+    return inspector;
+}
+
+// Create a default instance
+const StateInspector = createStateInspector();
+
+export default StateInspector;
+export { createStateInspector };