@uistate/css 1.0.0

package/README.md

@@ -0,0 +1,63 @@
+# @uistate/css
+
+Zero-build CSS-native state management using CSS custom properties and data attributes.
+
+## What is this?
+
+A state management library that uses **CSS custom properties** (`--var`) and **`data-*` attributes** as the state transport layer. No bundler, no framework — just drop a `<script>` tag and go.
+
+State is inspectable in DevTools (Elements → Computed → CSS variables), and CSS selectors can react to state changes (`[data-theme="dark"]`).
+
+## Install
+
+```bash
+npm install @uistate/css
+```
+
+## Usage
+
+```html
+<script type="module">
+  import { createCssState } from '@uistate/css';
+
+  const ui = createCssState({ theme: 'light', count: 0 });
+
+  // State lives in CSS variables and data attributes
+  ui.setState('theme', 'dark');
+  // → document.documentElement has --theme: dark and data-theme="dark"
+
+  // Observe changes
+  ui.observe('theme', (value) => {
+    console.log('Theme changed to:', value);
+  });
+</script>
+
+<!-- Declarative observers -->
+<span data-observe="count">0</span>
+
+<!-- Declarative actions -->
+<button data-state-action="theme" data-state-value="dark">Dark Mode</button>
+```
+
+## Modules
+
+### `createCssState(initialState)`
+Core CSS state management. Sets/gets state via CSS custom properties, supports observers, declarative DOM binding via `data-observe` and `data-state-action` attributes.
+
+### `createSerializer(config)`
+Configurable serialization between JavaScript values and CSS-compatible strings. Supports `'escape'`, `'json'`, and `'hybrid'` modes.
+
+### `createTemplateManager(stateManager)`
+Component mounting via `<template>` elements, event delegation via `data-action` attributes, and CSS-variable-based templating.
+
+## Ideal for
+
+- **WordPress** — reactive PHP templates without a build step
+- **Jekyll / Hugo / 11ty** — interactivity for static sites
+- **Shopify Liquid / Twig / Blade** — server-rendered templates with client-side state
+- **Web Components** — CSS custom properties pierce shadow DOM
+- **Progressive enhancement** — layer interactivity onto existing HTML
+
+## License
+
+MIT

package/cssState.js

@@ -0,0 +1,212 @@
+/**
+ * UIstate - CSS-based state management module with integrated serialization
+ * Part of the UIstate declarative state management system
+ * Uses CSS custom properties and data attributes for state representation
+ * Features modular extension capabilities for DOM binding and events
+ */
+import StateSerializer from './stateSerializer.js';
+
+const createCssState = (initialState = {}, serializer = StateSerializer) => {
+    const state = {
+        _sheet: null,
+        _observers: new Map(),
+        _serializer: serializer,
+        _specialHandlers: {},
+        _eventHandlers: new Map(), // Store custom event binding handlers
+
+        init(serializerConfig) {
+            if (!this._sheet) {
+                const style = document.createElement('style');
+                document.head.appendChild(style);
+                this._sheet = style.sheet;
+                this._addRule(':root {}');
+            }
+
+            // Configure serializer if options provided
+            if (serializerConfig && typeof serializerConfig === 'object') {
+                this._serializer.configure(serializerConfig);
+            }
+
+            // Initialize with any provided state
+            if (initialState && typeof initialState === 'object') {
+                Object.entries(initialState).forEach(([key, value]) => {
+                    this.setState(key, value);
+                });
+            }
+
+            return this;
+        },
+
+        setState(key, value) {
+            // Use serializer for CSS variables
+            const cssValue = this._serializer.serialize(key, value);
+            document.documentElement.style.setProperty(`--${key}`, cssValue);
+
+            // Use serializer to handle all attribute application consistently
+            this._serializer.applyToAttributes(key, value);
+
+            // Notify any registered observers of the state change
+            this._notifyObservers(key, value);
+            return value;
+        },
+
+        setStates(stateObject) {
+            Object.entries(stateObject).forEach(([key, value]) => {
+                this.setState(key, value);
+            });
+            return this;
+        },
+
+        getState(key) {
+            const value = getComputedStyle(document.documentElement).getPropertyValue(`--${key}`).trim();
+            if (!value) return '';
+
+            // Use serializer for deserialization
+            return this._serializer.deserialize(key, value);
+        },
+
+        observe(key, callback) {
+            if (!this._observers.has(key)) {
+                this._observers.set(key, new Set());
+            }
+            this._observers.get(key).add(callback);
+            return () => {
+                const observers = this._observers.get(key);
+                if (observers) {
+                    observers.delete(callback);
+                }
+            };
+        },
+
+        _notifyObservers(key, value) {
+            const observers = this._observers.get(key);
+            if (observers) {
+                observers.forEach(cb => cb(value));
+            }
+        },
+
+        registerSpecialHandler(stateKey, handlerFn) {
+            this._specialHandlers[stateKey] = handlerFn;
+            return this;
+        },
+
+        // New method for registering event bindings
+        registerEventBinding(eventType, handler) {
+            this._eventHandlers.set(eventType, handler);
+            return this;
+        },
+
+        setupObservers(container = document) {
+            container.querySelectorAll('[data-observe]:not([data-observing])').forEach(el => {
+                const stateKey = el.dataset.observe;
+
+                this.observe(stateKey, (value) => {
+                    // Special handlers should run first to set data-state
+                    if (this._specialHandlers[stateKey]?.observe) {
+                        this._specialHandlers[stateKey].observe(value, el);
+                    } else if (stateKey.endsWith('-state') && el.hasAttribute('data-state')) {
+                        // Only update data-state for elements that already have this attribute
+                        el.dataset.state = value;
+                    } else {
+                        // For normal state observers like theme, counter, etc.
+                        el.textContent = value;
+                    }
+                });
+
+                // Trigger initial state
+                const initialValue = this.getState(stateKey);
+                if (this._specialHandlers[stateKey]?.observe) {
+                    this._specialHandlers[stateKey].observe(initialValue, el);
+                } else if (stateKey.endsWith('-state') && el.hasAttribute('data-state')) {
+                    // Only set data-state for elements that should have this attribute
+                    el.dataset.state = initialValue;
+                } else {
+                    // For normal elements
+                    el.textContent = initialValue;
+                }
+
+                el.dataset.observing = 'true';
+            });
+
+            return this;
+        },
+
+        // Default event handlers available for implementations to use
+        defaultClickHandler(e) {
+            const target = e.target.closest('[data-state-action]');
+            if (!target) return;
+
+            const stateAction = target.dataset.stateAction;
+            if (!stateAction) return;
+
+            // Special handlers get first priority
+            if (this._specialHandlers[stateAction]?.action) {
+                this._specialHandlers[stateAction].action(target);
+                return;
+            }
+
+            // Handle direct value setting via data-state-value
+            if (target.dataset.stateValue !== undefined) {
+                const valueToSet = target.dataset.stateValue;
+                this.setState(stateAction, valueToSet);
+            }
+        },
+
+        defaultInputHandler(e) {
+            const target = e.target;
+            const stateAction = target.dataset.stateAction;
+
+            if (!stateAction) return;
+
+            // Special handlers should access any needed data directly from the target
+            if (this._specialHandlers[stateAction]?.action) {
+                this._specialHandlers[stateAction].action(target);
+            }
+        },
+
+        // Updated setupStateActions to use registered event handlers
+        setupStateActions(container = document) {
+            // Only bind the registered event types
+            this._eventHandlers.forEach((handler, eventType) => {
+                container.addEventListener(eventType, handler);
+            });
+
+            // If no event handlers registered, register the default ones
+            if (this._eventHandlers.size === 0) {
+                container.addEventListener('click', (e) => this.defaultClickHandler(e));
+                container.addEventListener('input', (e) => this.defaultInputHandler(e));
+            }
+
+            return this;
+        },
+
+        _addRule(rule) {
+            if (this._sheet) {
+                this._sheet.insertRule(rule, this._sheet.cssRules.length);
+            }
+        },
+
+        // Add serializer configuration method
+        configureSerializer(config) {
+            if (this._serializer.configure) {
+                this._serializer.configure(config);
+            }
+            return this;
+        },
+
+        // Clean up resources
+        destroy() {
+            this._observers.clear();
+            // The style element will remain in the DOM
+            // as removing it would affect the UI state
+        }
+    };
+
+    return state.init();
+};
+
+// Create a singleton instance for easy usage
+const UIstate = createCssState();
+
+export { createCssState };
+export default UIstate;

package/index.js

@@ -0,0 +1,15 @@
+/**
+ * @uistate/css - Zero-build CSS-native state management
+ *
+ * Uses CSS custom properties and data attributes as the state transport layer.
+ * Works in any HTML page — no bundler, no framework required.
+ */
+
+// Primary: CSS State
+export { createCssState } from './cssState.js';
+
+// Serialization: CSS ↔ JS value transformation
+export { default as stateSerializer, createSerializer, escapeCssValue, unescapeCssValue } from './stateSerializer.js';
+
+// Templating: Component mounting and event delegation
+export { createTemplateManager, TemplateManager } from './templateManager.js';

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@uistate/css",
+  "version": "1.0.0",
+  "description": "Zero-build CSS-native state management using CSS custom properties and data attributes",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./cssState": "./cssState.js",
+    "./stateSerializer": "./stateSerializer.js",
+    "./templateManager": "./templateManager.js"
+  },
+  "files": [
+    "index.js",
+    "cssState.js",
+    "stateSerializer.js",
+    "templateManager.js"
+  ],
+  "keywords": [
+    "css-state",
+    "css-custom-properties",
+    "css-variables",
+    "state-management",
+    "zero-build",
+    "no-framework",
+    "declarative",
+    "data-attributes",
+    "theming",
+    "wordpress",
+    "static-sites",
+    "progressive-enhancement"
+  ],
+  "author": "Ajdin Imsirovic",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ImsirovicAjdin/uistate-css"
+  }
+}

package/stateSerializer.js

@@ -0,0 +1,267 @@
+/**
+ * StateSerializer - Configurable serialization module for UIstate
+ * Handles transformation between JavaScript values and CSS-compatible string values
+ *
+ * Supports multiple serialization strategies:
+ * - 'escape': Uses custom escaping for all values (original UIstate approach)
+ * - 'json': Uses JSON.stringify for complex objects, direct values for primitives
+ * - 'hybrid': Automatically selects the best strategy based on value type
+ *
+ * Also handles serialization of values for data attributes and CSS variables
+ * with consistent rules and unified serialization behavior
+ */
+
+// Utility functions for CSS value escaping/unescaping
+function escapeCssValue(value) {
+    if (typeof value !== 'string') return value;
+    return value.replace(/[^\x20-\x7E]|[!;{}:()[\]/@,'"]/g, function(char) {
+        const hex = char.charCodeAt(0).toString(16);
+        return '\\' + hex + ' ';
+    });
+}
+
+function unescapeCssValue(value) {
+    if (typeof value !== 'string') return value;
+    // Only perform unescaping if there are escape sequences
+    if (!value.includes('\\')) return value;
+
+    return value.replace(/\\([0-9a-f]{1,6})\s?/gi, function(match, hex) {
+        return String.fromCharCode(parseInt(hex, 16));
+    });
+}
+
+/**
+ * Create a configured serializer instance
+ * @param {Object} config - Configuration options
+ * @returns {Object} - Serializer instance
+ */
+function createSerializer(config = {}) {
+    // Default configuration
+    const defaultConfig = {
+        mode: 'hybrid',        // 'escape', 'json', or 'hybrid'
+        debug: false,          // Enable debug logging
+        complexThreshold: 3,   // Object properties threshold for hybrid mode
+        preserveTypes: true    // Preserve type information in serialization
+    };
+
+    // Merge provided config with defaults
+    const options = { ...defaultConfig, ...config };
+
+    // Serializer instance
+    const serializer = {
+        // Current configuration
+        config: options,
+
+        /**
+         * Update configuration
+         * @param {Object} newConfig - New configuration options
+         */
+        configure(newConfig) {
+            Object.assign(this.config, newConfig);
+            if (this.config.debug) {
+                console.log('StateSerializer config updated:', this.config);
+            }
+        },
+
+        /**
+         * Serialize a value for storage in CSS variables
+         * @param {string} key - The state key (for context-aware serialization)
+         * @param {any} value - The value to serialize
+         * @returns {string} - Serialized value
+         */
+        serialize(key, value) {
+            // Handle null/undefined
+            if (value === null || value === undefined) {
+                return '';
+            }
+
+            const valueType = typeof value;
+            const isComplex = valueType === 'object' &&
+                             (Array.isArray(value) ||
+                              (Object.keys(value).length >= this.config.complexThreshold));
+
+            // Select serialization strategy based on configuration and value type
+            if (this.config.mode === 'escape' ||
+                (this.config.mode === 'hybrid' && !isComplex)) {
+                // Use escape strategy for primitives or when escape mode is forced
+                if (valueType === 'string') {
+                    return escapeCssValue(value);
+                } else if (valueType === 'object') {
+                    // For simple objects in escape mode, still use JSON but with escaping
+                    const jsonStr = JSON.stringify(value);
+                    return escapeCssValue(jsonStr);
+                } else {
+                    // For other primitives, convert to string
+                    return String(value);
+                }
+            } else {
+                // Use JSON strategy for complex objects or when JSON mode is forced
+                return JSON.stringify(value);
+            }
+        },
+
+        /**
+         * Deserialize a value from CSS variable storage
+         * @param {string} key - The state key (for context-aware deserialization)
+         * @param {string} value - The serialized value
+         * @returns {any} - Deserialized value
+         */
+        deserialize(key, value) {
+            // Handle empty values
+            if (!value) return '';
+
+            // Try JSON parse first for values that look like JSON
+            if (this.config.mode !== 'escape' &&
+                ((value.startsWith('{') && value.endsWith('}')) ||
+                 (value.startsWith('[') && value.endsWith(']')))) {
+                try {
+                    return JSON.parse(value);
+                } catch (e) {
+                    if (this.config.debug) {
+                        console.warn(`Failed to parse JSON for key "${key}":`, value);
+                    }
+                    // Fall through to unescaping if JSON parse fails
+                }
+            }
+
+            // For non-JSON or escape mode, try unescaping
+            const unescaped = unescapeCssValue(value);
+
+            // If unescaped looks like JSON (might have been double-escaped), try parsing it
+            if (this.config.mode !== 'escape' &&
+                ((unescaped.startsWith('{') && unescaped.endsWith('}')) ||
+                 (unescaped.startsWith('[') && unescaped.endsWith(']')))) {
+                try {
+                    return JSON.parse(unescaped);
+                } catch (e) {
+                    // Not valid JSON, return unescaped string
+                }
+            }
+
+            return unescaped;
+        },
+
+        /**
+         * Serialize a value for data-* attribute
+         * @param {string} key - The state key
+         * @param {any} value - The value to serialize for attribute
+         * @returns {string} - Serialized attribute value
+         */
+        serializeForAttribute(key, value) {
+            if (value === null || value === undefined) return null;
+
+            // For objects, use the standard serializer
+            if (typeof value === 'object') {
+                return this.serialize(key, value);
+            }
+
+            // For primitive values, use direct string conversion
+            return String(value);
+        },
+
+        /**
+         * Apply serialized state to HTML element attributes and properties
+         * @param {string} key - State key
+         * @param {any} value - Value to apply
+         * @param {HTMLElement} element - Target element (defaults to documentElement)
+         */
+        applyToAttributes(key, value, element = document.documentElement) {
+            // Skip null/undefined values
+            if (value === null || value === undefined) {
+                element.removeAttribute(`data-${key}`);
+                return;
+            }
+
+            // Handle objects specially
+            if (typeof value === 'object') {
+                // Set the main attribute with serialized value
+                element.setAttribute(`data-${key}`, this.serialize(key, value));
+
+                // For non-array objects, set individual property attributes
+                if (!Array.isArray(value)) {
+                    Object.entries(value).forEach(([propKey, propValue]) => {
+                        const attributeKey = `data-${key}-${propKey.toLowerCase()}`;
+                        if (propValue !== null && propValue !== undefined) {
+                            if (typeof propValue === 'object') {
+                                element.setAttribute(
+                                    attributeKey,
+                                    this.serialize(`${key}.${propKey}`, propValue)
+                                );
+                            } else {
+                                element.setAttribute(attributeKey, propValue);
+                            }
+                        } else {
+                            element.removeAttribute(attributeKey);
+                        }
+                    });
+                }
+            } else {
+                // For primitives, set directly
+                element.setAttribute(`data-${key}`, value);
+            }
+        },
+
+        /**
+         * Utility method to determine if a value needs complex serialization
+         * @param {any} value - Value to check
+         * @returns {boolean} - True if complex serialization is needed
+         */
+        needsComplexSerialization(value) {
+            return typeof value === 'object' && value !== null;
+        },
+
+        /**
+         * Set state with proper serialization for CSS variables
+         * @param {Object} uistate - UIstate instance
+         * @param {string} path - State path
+         * @param {any} value - Value to set
+         * @returns {any} - The set value
+         */
+        setStateWithCss(uistate, path, value) {
+            // Update UIstate
+            uistate.setState(path, value);
+
+            // Update CSS variable with properly serialized value
+            const cssPath = path.replace(/\./g, '-');
+            const serialized = this.serialize(path, value);
+            document.documentElement.style.setProperty(`--${cssPath}`, serialized);
+
+            // Update data attribute for root level state
+            const segments = path.split('.');
+            if (segments.length === 1) {
+                document.documentElement.dataset[path] = typeof value === 'object'
+                    ? JSON.stringify(value)
+                    : value;
+            }
+
+            return value;
+        },
+
+        /**
+         * Get state with fallback to CSS variables
+         * @param {Object} uistate - UIstate instance
+         * @param {string} path - State path
+         * @returns {any} - Retrieved value
+         */
+        getStateFromCss(uistate, path) {
+            // First try UIstate
+            const value = uistate.getState(path);
+            if (value !== undefined) return value;
+
+            // If not found, try CSS variable
+            const cssPath = path.replace(/\./g, '-');
+            const cssValue = getComputedStyle(document.documentElement)
+                .getPropertyValue(`--${cssPath}`).trim();
+
+            return cssValue ? this.deserialize(path, cssValue) : undefined;
+        }
+    };
+
+    return serializer;
+}
+
+// Create a default instance with hybrid mode
+const StateSerializer = createSerializer();
+
+export default StateSerializer;
+export { createSerializer, escapeCssValue, unescapeCssValue };

package/templateManager.js

@@ -0,0 +1,216 @@
+/**
+ * TemplateManager - Component mounting and event delegation
+ * Handles HTML templating, component mounting, and event delegation
+ */
+
+const createTemplateManager = (stateManager) => {
+    const manager = {
+        handlers: {},
+        
+        onAction(action, handler) {
+            this.handlers[action] = handler;
+            return this;
+        },
+        
+        /**
+         * Register multiple actions with their handlers in a declarative way
+         * @param {Object} actionsMap - Map of action names to handlers or handler configs
+         * @returns {Object} - The manager instance for chaining
+         * 
+         * Example usage:
+         * templateManager.registerActions({
+         *   'add-item': addItem,
+         *   'delete-item': { fn: deleteItem, extractId: true },
+         *   'toggle-state': toggleState
+         * });
+         */
+        registerActions(actionsMap) {
+            Object.entries(actionsMap).forEach(([action, handler]) => {
+                if (typeof handler === 'function') {
+                    // Simple function handler
+                    this.onAction(action, handler);
+                } else if (typeof handler === 'object' && handler !== null) {
+                    // Handler with configuration
+                    const { fn, extractId = true, idAttribute = 'id' } = handler;
+                    
+                    if (typeof fn !== 'function') {
+                        throw new Error(`Handler for action '${action}' must be a function`);
+                    }
+                    
+                    this.onAction(action, (e) => {
+                        if (extractId) {
+                            const target = e.target.closest('[data-action]');
+                            // Look for common ID attributes in order of preference
+                            const id = target.dataset[idAttribute] || 
+                                      target.dataset.actionId || 
+                                      target.dataset.cardId || 
+                                      target.dataset.itemId;
+                                      
+                            fn(id, e, target);
+                        } else {
+                            fn(e);
+                        }
+                    });
+                } else {
+                    throw new Error(`Invalid handler for action '${action}'`);
+                }
+            });
+            return this;
+        },
+        
+        attachDelegation(root = document.body) {
+            root.addEventListener('click', e => {
+                const target = e.target.closest('[data-action]');
+                if (!target) return;
+                
+                const action = target.dataset.action;
+                if (!action) return;
+                
+                const handler = this.handlers[action];
+                if (typeof handler === 'function') {
+                    handler(e);
+                } else if (target.dataset.value !== undefined && stateManager) {
+                    // If we have a state manager, use it to update state
+                    stateManager.setState(action, target.dataset.value);
+                }
+            });
+            return this;
+        },
+        
+        /**
+         * Render a template from a CSS variable
+         * @param {string} templateName - Name of the template (will be prefixed with --template-)
+         * @param {Object} data - Data to inject into the template
+         * @returns {HTMLElement} - The rendered element
+         */
+        renderTemplateFromCss(templateName, data = {}) {
+            const cssTemplate = getComputedStyle(document.documentElement)
+                .getPropertyValue(`--template-${templateName}`)
+                .trim()
+                .replace(/^['"]|['"]$/g, ''); // Remove surrounding quotes
+            
+            if (!cssTemplate) throw new Error(`Template not found in CSS: --template-${templateName}`);
+            
+            let html = cssTemplate;
+            
+            // Replace all placeholders with actual data
+            Object.entries(data).forEach(([key, value]) => {
+                const regex = new RegExp(`{{${key}}}`, 'g');
+                html = html.replace(regex, value);
+            });
+            
+            // Create a temporary container
+            const temp = document.createElement('div');
+            temp.innerHTML = html;
+            
+            // Return the first child (the rendered template)
+            return temp.firstElementChild;
+        },
+        
+        mount(componentName, container) {
+            const tpl = document.getElementById(`${componentName}-template`);
+            if (!tpl) throw new Error(`Template not found: ${componentName}-template`);
+            const clone = tpl.content.cloneNode(true);
+            
+            function resolvePlaceholders(fragment) {
+                Array.from(fragment.querySelectorAll('*')).forEach(el => {
+                    const tag = el.tagName.toLowerCase();
+                    if (tag.endsWith('-placeholder')) {
+                        const name = tag.replace('-placeholder','');
+                        const childTpl = document.getElementById(`${name}-template`);
+                        if (!childTpl) throw new Error(`Template not found: ${name}-template`);
+                        const childClone = childTpl.content.cloneNode(true);
+                        resolvePlaceholders(childClone);
+                        el.replaceWith(childClone);
+                    }
+                });
+            }
+            
+            resolvePlaceholders(clone);
+            container.appendChild(clone);
+            return clone.firstElementChild;
+        },
+        
+        // Helper to create a reactive component with automatic updates
+        createComponent(name, renderFn, stateKeys = []) {
+            if (!stateManager) {
+                throw new Error('State manager is required for reactive components');
+            }
+            
+            // Create template element if it doesn't exist
+            let tpl = document.getElementById(`${name}-template`);
+            if (!tpl) {
+                tpl = document.createElement('template');
+                tpl.id = `${name}-template`;
+                document.body.appendChild(tpl);
+            }
+            
+            // Initial render
+            tpl.innerHTML = renderFn(stateManager);
+            
+            // Set up observers for reactive updates
+            if (stateKeys.length > 0) {
+                stateKeys.forEach(key => {
+                    stateManager.observe(key, () => {
+                        tpl.innerHTML = renderFn(stateManager);
+                    });
+                });
+            }
+            
+            return {
+                mount: (container) => this.mount(name, container)
+            };
+        },
+        
+        /**
+         * Apply CSS classes to an element based on a state key stored in CSS variables
+         * @param {HTMLElement} element - Element to apply classes to
+         * @param {string} stateKey - State key to look up in CSS variables
+         * @param {Object} options - Options for class application
+         * @returns {HTMLElement} - The element for chaining
+         * 
+         * Example usage:
+         * // CSS: :root { --card-primary-classes: "bg-primary text-white"; }
+         * templateManager.applyClassesFromState(cardElement, 'card-primary');
+         */
+        applyClassesFromState(element, stateKey, options = {}) {
+            if (!element) return element;
+            
+            const { 
+                prefix = '',
+                clearExisting = false,
+                namespace = '' 
+            } = typeof options === 'string' ? { prefix: options } : options;
+            
+            const prefixPath = prefix ? `${prefix}-` : '';
+            const namespacePath = namespace ? `${namespace}-` : '';
+            
+            const classString = getComputedStyle(document.documentElement)
+                .getPropertyValue(`--${namespacePath}${stateKey}-classes`)
+                .trim()
+                .replace(/^['"]|['"]$/g, '');
+                
+            if (classString) {
+                // Clear existing classes if specified
+                if (clearExisting) {
+                    element.className = '';
+                }
+                
+                // Add new classes
+                classString.split(' ').forEach(cls => {
+                    if (cls) element.classList.add(cls);
+                });
+            }
+            
+            return element; // For chaining
+        }
+    };
+    
+    return manager;
+};
+
+// Create a standalone instance that doesn't depend on any state manager
+const TemplateManager = createTemplateManager();
+
+export default createTemplateManager;
+export { createTemplateManager, TemplateManager };