@vanduo-oss/framework 1.3.8 → 1.4.0

package/js/utils/helpers.js

@@ -258,7 +258,7 @@ function escapeHtml(str) {
  * Keeps a small set of tags and strips disallowed tags and attributes. Safe for
  * simple rich text (use server-side or DOMPurify for stronger guarantees).
  * @param {string} input
- * @param {{ allowSvg?: boolean }} [options]
+ * @param {{ allowSvg?: boolean, allowStyle?: boolean }} [options]
  * @returns {string} sanitized HTML
  */
 function sanitizeHtml(input, options = {}) {
@@ -271,6 +271,7 @@ function sanitizeHtml(input, options = {}) {
     return escapeHtml(input);
   }
   const allowSvg = options && options.allowSvg === true;
+  const allowStyle = !options || options.allowStyle !== false;
   const baseAllowed = ['B', 'STRONG', 'I', 'EM', 'BR', 'A', 'SPAN', 'U', 'DIV', 'P', 'KBD', 'CODE', 'SMALL', 'MARK'];
   const svgAllowed = ['SVG', 'PATH', 'LINE', 'CIRCLE', 'POLYLINE', 'RECT', 'G'];
   const allowed = allowSvg ? baseAllowed.concat(svgAllowed) : baseAllowed;
@@ -310,8 +311,11 @@ function sanitizeHtml(input, options = {}) {
           }
         });
       } else {
-        // Keep class and style; strip everything else (no event handlers, no src, etc.)
-        const safeAttrs = new Set(['class', 'style']);
+        // Keep class and optionally inline style; strip everything else.
+        const safeAttrs = new Set(['class']);
+        if (allowStyle) {
+          safeAttrs.add('style');
+        }
         const otherAttrs = Array.from(child.attributes || []);
         otherAttrs.forEach(function (a) {
           if (!safeAttrs.has(a.name)) { child.removeAttribute(a.name); }
@@ -327,4 +331,3 @@ function sanitizeHtml(input, options = {}) {
 }
 
 
-

package/js/utils/lifecycle.js

@@ -1,135 +1,210 @@
 /**
  * Vanduo Framework - Lifecycle Manager
- * Central registry for component instances and cleanup
- * Prevents memory leaks in SPAs by tracking event listeners
+ * Central registry for scoped init/destroy, instance cleanup, and DOM queries.
  */
 
-(function() {
+(function () {
   'use strict';
 
-  /**
-   * Lifecycle Manager
-   * Simple registry that tracks component instances and their cleanup functions
-   */
+  function normalizeCallbacks(value) {
+    if (!value) return [];
+    if (Array.isArray(value)) {
+      return value.filter(function (fn) {
+        return typeof fn === 'function';
+      });
+    }
+    return typeof value === 'function' ? [value] : [];
+  }
+
+  function normalizeOptions(options) {
+    if (typeof options === 'function') {
+      return { onDestroy: [options] };
+    }
+    return options || {};
+  }
+
+  function callSafely(label, fn) {
+    try {
+      fn();
+    } catch (error) {
+      console.warn('[Vanduo Lifecycle] ' + label + ' error:', error);
+    }
+  }
+
   const Lifecycle = {
-    // Map of element -> { componentName, cleanupFunctions }
+    // Map<Element, Map<componentName, { cleanup, onDestroy, registeredAt }>>
     instances: new Map(),
 
-    /**
-     * Register a component instance
-     * @param {HTMLElement} element - The DOM element
-     * @param {string} componentName - Name of the component
-     * @param {Array<Function>} cleanupFns - Functions to call on destroy
-     */
-    register: function(element, componentName, cleanupFns = []) {
-      if (this.instances.has(element)) {
-        // Already registered, merge cleanup functions
-        const existing = this.instances.get(element);
-        existing.cleanup = existing.cleanup.concat(cleanupFns);
+    isRoot: function (root) {
+      return !!root && (root === document || root.nodeType === 1 || root.nodeType === 9 || root.nodeType === 11);
+    },
+
+    normalizeRoot: function (root) {
+      return this.isRoot(root) ? root : document;
+    },
+
+    isInRoot: function (root, element) {
+      const scope = this.normalizeRoot(root);
+      if (!(element instanceof Element)) return false;
+      if (scope === document) {
+        return document.documentElement ? document.documentElement.contains(element) : document.contains(element);
+      }
+      if (scope === element) return true;
+      return typeof scope.contains === 'function' && scope.contains(element);
+    },
+
+    queryAll: function (root, selector) {
+      const scope = this.normalizeRoot(root);
+      const matches = [];
+      if (scope instanceof Element && typeof scope.matches === 'function' && scope.matches(selector)) {
+        matches.push(scope);
+      }
+      if (typeof scope.querySelectorAll === 'function') {
+        const descendants = scope.querySelectorAll(selector);
+        for (let i = 0; i < descendants.length; i++) {
+          matches.push(descendants[i]);
+        }
+      }
+      return matches;
+    },
+
+    queryOne: function (root, selector) {
+      const matches = this.queryAll(root, selector);
+      return matches.length ? matches[0] : null;
+    },
+
+    runInRoot: function (root, fn) {
+      const scope = this.normalizeRoot(root);
+      return fn(scope);
+    },
+
+    register: function (element, componentName, cleanupFns, options) {
+      if (!(element instanceof Element) || !componentName) return;
+
+      const optionBag = normalizeOptions(options);
+      const cleanup = normalizeCallbacks(cleanupFns);
+      const onDestroy = normalizeCallbacks(optionBag.onDestroy);
+      const componentEntries = this.instances.get(element) || new Map();
+      const existing = componentEntries.get(componentName);
+
+      if (existing) {
+        existing.cleanup = existing.cleanup.concat(cleanup);
+        existing.onDestroy = existing.onDestroy.concat(onDestroy);
         return;
       }
 
-      this.instances.set(element, {
+      componentEntries.set(componentName, {
         component: componentName,
-        cleanup: cleanupFns,
+        cleanup: cleanup,
+        onDestroy: onDestroy,
         registeredAt: Date.now()
       });
+
+      this.instances.set(element, componentEntries);
     },
 
-    /**
-     * Unregister a single element and run its cleanup
-     * @param {HTMLElement} element - The element to unregister
-     */
-    unregister: function(element) {
-      const instance = this.instances.get(element);
-      if (!instance) return;
-
-      // Run all cleanup functions
-      instance.cleanup.forEach(function(fn) {
-        try {
-          fn();
-        } catch (e) {
-          console.warn('[Vanduo Lifecycle] Cleanup error:', e);
+    unregister: function (element, componentName) {
+      const componentEntries = this.instances.get(element);
+      if (!componentEntries) return;
+
+      if (componentName) {
+        const entry = componentEntries.get(componentName);
+        if (!entry) return;
+
+        componentEntries.delete(componentName);
+        if (!componentEntries.size) {
+          this.instances.delete(element);
         }
-      });
 
+        entry.cleanup.forEach(function (fn) {
+          callSafely('Cleanup', fn);
+        });
+        entry.onDestroy.forEach(function (fn) {
+          callSafely('Destroy', fn);
+        });
+        return;
+      }
+
+      const entries = Array.from(componentEntries.values());
       this.instances.delete(element);
+      entries.forEach(function (entry) {
+        entry.cleanup.forEach(function (fn) {
+          callSafely('Cleanup', fn);
+        });
+        entry.onDestroy.forEach(function (fn) {
+          callSafely('Destroy', fn);
+        });
+      });
     },
 
-    /**
-     * Destroy all instances of a specific component
-     * @param {string} componentName - Optional component name filter
-     */
-    destroyAll: function(componentName) {
+    destroyAll: function (componentName) {
       const toRemove = [];
+      this.instances.forEach(function (componentEntries, element) {
+        if (!componentName) {
+          toRemove.push([element, null]);
+          return;
+        }
 
-      this.instances.forEach(function(instance, element) {
-        if (!componentName || instance.component === componentName) {
-          toRemove.push(element);
+        if (componentEntries.has(componentName)) {
+          toRemove.push([element, componentName]);
         }
       });
 
-      toRemove.forEach(function(element) {
-        Lifecycle.unregister(element);
+      toRemove.forEach(function (entry) {
+        Lifecycle.unregister(entry[0], entry[1] || undefined);
       });
+
+      return toRemove.length;
     },
 
-    /**
-     * Destroy all instances within a specific container
-     * Useful for SPAs when navigating between pages
-     * @param {HTMLElement} container - Container element
-     */
-    destroyAllInContainer: function(container) {
+    destroyAllInContainer: function (container, componentName) {
+      const scope = this.normalizeRoot(container);
       const toRemove = [];
 
-      this.instances.forEach(function(instance, element) {
-        if (container.contains(element)) {
-          toRemove.push(element);
+      this.instances.forEach(function (componentEntries, element) {
+        if (!Lifecycle.isInRoot(scope, element)) return;
+
+        if (!componentName) {
+          toRemove.push([element, null]);
+          return;
+        }
+
+        if (componentEntries.has(componentName)) {
+          toRemove.push([element, componentName]);
         }
       });
 
-      toRemove.forEach(function(element) {
-        Lifecycle.unregister(element);
+      toRemove.forEach(function (entry) {
+        Lifecycle.unregister(entry[0], entry[1] || undefined);
       });
+
+      return toRemove.length;
     },
 
-    /**
-     * Get all registered instances (for debugging)
-     * @returns {Array} Array of instance info objects
-     */
-    getAll: function() {
+    getAll: function () {
       const result = [];
-      this.instances.forEach(function(instance, element) {
-        result.push({
-          element: element,
-          component: instance.component,
-          registeredAt: instance.registeredAt
+      this.instances.forEach(function (componentEntries, element) {
+        componentEntries.forEach(function (entry) {
+          result.push({
+            element: element,
+            component: entry.component,
+            registeredAt: entry.registeredAt
+          });
         });
       });
       return result;
     },
 
-    /**
-     * Check if an element is registered
-     * @param {HTMLElement} element - The element to check
-     * @returns {boolean}
-     */
-    has: function(element) {
-      return this.instances.has(element);
+    has: function (element, componentName) {
+      const componentEntries = this.instances.get(element);
+      if (!componentEntries) return false;
+      return componentName ? componentEntries.has(componentName) : componentEntries.size > 0;
     }
   };
 
-  // Auto-cleanup on page unload
-  window.addEventListener('beforeunload', function() {
+  window.addEventListener('beforeunload', function () {
     Lifecycle.destroyAll();
   });
 
-  // Expose globally
   window.VanduoLifecycle = Lifecycle;
-
-  // Register with Vanduo framework if available
-  if (typeof window.Vanduo !== 'undefined') {
-    window.Vanduo.register('lifecycle', Lifecycle);
-  }
-
 })();

package/js/vanduo.js

@@ -6,6 +6,7 @@
   'use strict';
 
   const VANDUO_VERSION = typeof __VANDUO_VERSION__ !== 'undefined' ? __VANDUO_VERSION__ : '0.0.0-dev';
+  const hasOwn = Object.prototype.hasOwnProperty;
 
   /**
    * Vanduo Framework Object
@@ -13,46 +14,193 @@
   const Vanduo = {
     version: VANDUO_VERSION,
     components: {},
+    aliases: {},
+    _decoratedComponents: new WeakSet(),
+
+    resolveComponentName: function (name) {
+      return this.aliases[name] || name;
+    },
+
+    _isRoot: function (root) {
+      if (typeof window.VanduoLifecycle !== 'undefined' && typeof window.VanduoLifecycle.isRoot === 'function') {
+        return window.VanduoLifecycle.isRoot(root);
+      }
+
+      return !!root && (root === document || root.nodeType === 1 || root.nodeType === 9 || root.nodeType === 11);
+    },
+
+    _normalizeRoot: function (root) {
+      return this._isRoot(root) ? root : document;
+    },
+
+    _queryAll: function (root, selector) {
+      const scope = this._normalizeRoot(root);
+      const matches = [];
+
+      if (scope instanceof Element && typeof scope.matches === 'function' && scope.matches(selector)) {
+        matches.push(scope);
+      }
+
+      if (typeof scope.querySelectorAll === 'function') {
+        const descendants = scope.querySelectorAll(selector);
+        for (let i = 0; i < descendants.length; i++) {
+          matches.push(descendants[i]);
+        }
+      }
+
+      return matches;
+    },
+
+    queryAll: function (root, selector) {
+      if (typeof selector === 'undefined') {
+        selector = root;
+        root = document;
+      }
+
+      return this._queryAll(root, selector);
+    },
+
+    queryOne: function (root, selector) {
+      const matches = this.queryAll(root, selector);
+      return matches.length ? matches[0] : null;
+    },
+
+    _isLifecycleManagedComponent: function (component) {
+      if (!component || typeof component !== 'object') return false;
+
+      for (const key in component) {
+        if (hasOwn.call(component, key) && component[key] instanceof Map) {
+          return true;
+        }
+      }
+
+      return false;
+    },
+
+    _syncComponentLifecycle: function (name, component, root) {
+      const lifecycle = window.VanduoLifecycle;
+      if (!lifecycle || !this._isLifecycleManagedComponent(component)) return;
+
+      const componentName = this.resolveComponentName(name);
+      const scope = this._normalizeRoot(root);
+
+      for (const key in component) {
+        if (!hasOwn.call(component, key) || !(component[key] instanceof Map)) {
+          continue;
+        }
+
+        component[key].forEach(function (instance, element) {
+          if (!(element instanceof Element) || !lifecycle.isInRoot(scope, element) || lifecycle.has(element, componentName)) {
+            return;
+          }
+
+          if (typeof component.destroy === 'function') {
+            lifecycle.register(element, componentName, [], function () {
+              component.destroy(element);
+            });
+            return;
+          }
+
+          const cleanup = instance && Array.isArray(instance.cleanup) ? instance.cleanup : [];
+          lifecycle.register(element, componentName, cleanup, function () {
+            component[key].delete(element);
+          });
+        });
+      }
+    },
+
+    _decorateComponent: function (name, component) {
+      const framework = this;
+      const lifecycle = window.VanduoLifecycle;
+      if (!component || typeof component !== 'object' || this._decoratedComponents.has(component)) {
+        return;
+      }
+
+      const originalInit = typeof component.init === 'function' ? component.init : null;
+      if (originalInit) {
+        component.init = function (...args) {
+          const scopedRoot = framework._isRoot(args[0]) ? args[0] : null;
+          const result = originalInit.apply(this, args);
+
+          if (window.Vanduo) {
+            const syncRoot = scopedRoot || document;
+            window.Vanduo._syncComponentLifecycle(name, this, syncRoot);
+          }
+
+          return result;
+        };
+      }
+
+      const originalDestroyAll = typeof component.destroyAll === 'function' ? component.destroyAll : null;
+      if (originalDestroyAll) {
+        component.destroyAll = function (...args) {
+          const scopedRoot = framework._isRoot(args[0]) ? args[0] : null;
+          const componentName = window.Vanduo ? window.Vanduo.resolveComponentName(name) : name;
+
+          if (lifecycle && window.Vanduo && window.Vanduo._isLifecycleManagedComponent(this)) {
+            if (scopedRoot && scopedRoot !== document) {
+              lifecycle.destroyAllInContainer(scopedRoot, componentName);
+              if (this.__vanduoScopedDestroyAll === true) {
+                return originalDestroyAll.apply(this, args);
+              }
+              return;
+            }
+
+            lifecycle.destroyAll(componentName);
+          }
+
+          return originalDestroyAll.apply(this, args);
+        };
+      }
+
+      this._decoratedComponents.add(component);
+    },
 
     /**
      * Initialize framework
      * Call this after DOM is ready and all components are loaded
      */
-    init: function () {
-      // Initialize components when DOM is ready
+    init: function (root) {
+      const scope = this._normalizeRoot(root);
+
+      if (scope !== document) {
+        this.initComponents(scope);
+        return;
+      }
+
       if (typeof ready !== 'undefined') {
         ready(() => {
-          this.initComponents();
+          this.initComponents(document);
         });
-      } else {
-        // Fallback if helpers.js is not loaded
-        if (document.readyState === 'loading') {
-          document.addEventListener('DOMContentLoaded', () => {
-            this.initComponents();
-          });
-        } else {
-          this.initComponents();
-        }
+        return;
       }
+
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', () => {
+          this.initComponents(document);
+        });
+        return;
+      }
+
+      this.initComponents(document);
     },
 
     /**
      * Initialize all components
      */
-    initComponents: function () {
-      // Initialize all registered components
+    initComponents: function (root) {
+      const scope = this._normalizeRoot(root);
+
       Object.keys(this.components).forEach((name) => {
         const component = this.components[name];
         if (component.init && typeof component.init === 'function') {
           try {
-            component.init();
+            component.init(scope);
           } catch (e) {
             console.warn('[Vanduo] Failed to initialize component "' + name + '":', e);
           }
         }
       });
-
-      console.log('Vanduo Framework v' + this.version + ' initialized');
     },
 
     /**
@@ -60,49 +208,69 @@
      * @param {string} name - Component name
      * @param {Object} component - Component object with init method
      */
-    register: function (name, component) {
+    register: function (name, component, options) {
+      const opts = options || {};
+      this._decorateComponent(name, component);
       this.components[name] = component;
-      // Note: Components are NOT auto-initialized on registration
-      // Call Vanduo.init() explicitly after all components are registered
+
+      if (Array.isArray(opts.aliases)) {
+        opts.aliases.forEach((alias) => {
+          this.aliases[alias] = name;
+        });
+      }
+    },
+
+    registerAlias: function (alias, name) {
+      const canonicalName = this.resolveComponentName(name);
+      if (this.components[canonicalName]) {
+        this.aliases[alias] = canonicalName;
+      }
     },
 
     /**
      * Re-initialize a component (useful after dynamic DOM changes)
      * @param {string} name - Component name
      */
-    reinit: function (name) {
-      const component = this.components[name];
+    reinit: function (name, root) {
+      const scope = this._normalizeRoot(root);
+      const componentName = this.resolveComponentName(name);
+      const component = this.components[componentName];
       if (component && component.init && typeof component.init === 'function') {
         try {
-          component.init();
+          if (component.destroyAll && typeof component.destroyAll === 'function') {
+            component.destroyAll(scope);
+          }
+          component.init(scope);
         } catch (e) {
-          console.warn('[Vanduo] Failed to reinitialize component "' + name + '":', e);
+          console.warn('[Vanduo] Failed to reinitialize component "' + componentName + '":', e);
         }
       }
     },
 
     /**
-     * Destroy all component instances and clean up event listeners
-     * Uses lifecycle manager for memory leak prevention
+     * Destroy component instances within the provided root.
      */
-    destroyAll: function () {
-      // First, destroy components that have their own destroyAll
+    destroy: function (root) {
+      const scope = this._normalizeRoot(root);
       const names = Object.keys(this.components);
+
       for (let i = 0; i < names.length; i++) {
         const component = this.components[names[i]];
         if (component && component.destroyAll && typeof component.destroyAll === 'function') {
           try {
-            component.destroyAll();
+            component.destroyAll(scope);
           } catch (e) {
             console.warn('[Vanduo] Failed to destroy component "' + names[i] + '":', e);
           }
         }
       }
+    },
 
-      // Then, cleanup any remaining registered elements via lifecycle manager
-      if (typeof window.VanduoLifecycle !== 'undefined') {
-        window.VanduoLifecycle.destroyAll();
-      }
+    /**
+     * Destroy all component instances and clean up event listeners.
+     */
+    destroyAll: function () {
+      this.destroy(document);
     },
 
     /**
@@ -111,7 +279,8 @@
      * @returns {Object|null}
      */
     getComponent: function (name) {
-      return this.components[name] || null;
+      const componentName = this.resolveComponentName(name);
+      return this.components[componentName] || null;
     }
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanduo-oss/framework",
-  "version": "1.3.8",
+  "version": "1.4.0",
   "description": "Zero-dependency CSS/JS framework built on Fibonacci/Golden Ratio design system with Open Color integration",
   "keywords": [
     "css",
@@ -45,7 +45,7 @@
     "eslint": "^10.3.0",
     "husky": "^9.1.7",
     "lightningcss": "^1.32.0",
-    "stylelint": "^17.10.0",
+    "stylelint": "^17.11.0",
     "stylelint-config-standard": "^40.0.0"
   },
   "engines": {
@@ -54,10 +54,9 @@
   },
   "scripts": {
     "build": "node scripts/build.js",
-    "build:hex-grid": "pnpm --filter @vanduo-oss/hex-grid build",
-    "build:packages": "pnpm -r --filter ./packages/* build",
     "build:min": "node scripts/build.js --minify",
     "dev": "node scripts/build.js --development",
+    "stats:css": "node scripts/stats-css.js",
     "check:versions": "node scripts/check-version-consistency.js",
     "release:assets": "node scripts/upload-release-assets.js",
     "lint": "pnpm run lint:css && pnpm run lint:js",