@dinoreic/fez 0.4.0 → 0.5.2

package/src/fez/instance.js

@@ -1,721 +1,880 @@
-// HTML node builder
-import parseNode from './lib/n.js'
-import createTemplate from './lib/template.js'
+/**
+ * FezBase - Base class for all Fez components
+ *
+ * Provides lifecycle hooks, reactive state, DOM utilities, and template rendering
+ */
+
+import parseNode from "./lib/n.js";
+import createTemplate from "./lib/template.js";
+import { componentSubscribe, componentPublish } from "./lib/pubsub.js";
 
 export default class FezBase {
-  // get node attributes as object
+  // ===========================================================================
+  // STATIC METHODS
+  // ===========================================================================
+
+  static nodeName = "div";
+
+  /**
+   * Extract props from a DOM node's attributes
+   * Handles :attr syntax for evaluated expressions and data-props JSON
+   */
   static getProps(node, newNode) {
-    let attrs = {}
+    let attrs = {};
 
-    // we can directly attach props to DOM node instance
+    // Direct props attachment
     if (node.props) {
-      return node.props
+      return node.props;
     }
 
-    // LOG(node.nodeName, node.attributes)
+    // Collect attributes
     for (const attr of node.attributes) {
-      attrs[attr.name] = attr.value
+      attrs[attr.name] = attr.value;
     }
 
+    // Evaluate :attr expressions
     for (const [key, val] of Object.entries(attrs)) {
-      if ([':'].includes(key[0])) {
-        // LOG([key, val])
-        delete attrs[key]
+      if ([":"].includes(key[0])) {
+        delete attrs[key];
         try {
-          const newVal = new Function(`return (${val})`).bind(newNode)()
-          attrs[key.replace(/[\:_]/, '')] = newVal
-
+          const newVal = new Function(`return (${val})`).bind(newNode)();
+          attrs[key.replace(/[\:_]/, "")] = newVal;
         } catch (e) {
-          console.error(`Fez: Error evaluating attribute ${key}="${val}" for ${node.tagName}: ${e.message}`)
+          Fez.onError(
+            "attr",
+            `<${node.tagName.toLowerCase()}> Error evaluating ${key}="${val}": ${e.message}`,
+          );
         }
       }
     }
 
-    if (attrs['data-props']) {
-      let data = attrs['data-props']
-
-      if (typeof data == 'object') {
-        return data
-      }
-      else {
-        if (data[0] != '{') {
-          data = decodeURIComponent(data)
+    // Handle data-props JSON
+    if (attrs["data-props"]) {
+      let data = attrs["data-props"];
+      if (typeof data == "object") {
+        return data;
+      } else {
+        if (data[0] != "{") {
+          data = decodeURIComponent(data);
         }
         try {
-          attrs = JSON.parse(data)
+          attrs = JSON.parse(data);
         } catch (e) {
-          console.error(`Fez: Invalid JSON in data-props for ${node.tagName}: ${e.message}`)
+          Fez.onError(
+            "props",
+            `<${node.tagName.toLowerCase()}> Invalid JSON in data-props: ${e.message}`,
+          );
         }
       }
     }
-
-    // pass props as json template
-    // <script type="text/template">{...}</script>
-    // <foo-bar data-json-template="true"></foo-bar>
-    else if (attrs['data-json-template']) {
-      const data = newNode.previousSibling?.textContent
+    // Handle JSON template
+    else if (attrs["data-json-template"]) {
+      const data = newNode.previousSibling?.textContent;
       if (data) {
         try {
-          attrs = JSON.parse(data)
-          newNode.previousSibling.remove()
+          attrs = JSON.parse(data);
+          newNode.previousSibling.remove();
         } catch (e) {
-          console.error(`Fez: Invalid JSON in template for ${node.tagName}: ${e.message}`)
+          Fez.onError(
+            "props",
+            `<${node.tagName.toLowerCase()}> Invalid JSON in template: ${e.message}`,
+          );
         }
       }
     }
 
-    return attrs
+    return attrs;
   }
 
+  /**
+   * Get form data from closest/child form
+   */
   static formData(node) {
-    const formNode = node.closest('form') || node.querySelector('form')
+    const formNode = node.closest("form") || node.querySelector("form");
     if (!formNode) {
-      Fez.log('No form found for formData()')
-      return {}
+      Fez.consoleLog("No form found for formData()");
+      return {};
     }
-    const formData = new FormData(formNode)
-    const formObject = {}
+    const formData = new FormData(formNode);
+    const formObject = {};
     formData.forEach((value, key) => {
-      formObject[key] = value
+      formObject[key] = value;
     });
-    return formObject
+    return formObject;
   }
 
-
-  static nodeName = 'div'
-
-  // instance methods
+  // ===========================================================================
+  // CONSTRUCTOR & CORE
+  // ===========================================================================
 
   constructor() {}
 
-  n = parseNode
-
-  // string selector for use in HTML nodes
+  n = parseNode;
+  fezBlocks = {};
+
+  // Store for passing values to child components (e.g., loop vars)
+  fezGlobals = {
+    _data: new Map(),
+    _counter: 0,
+    set(value) {
+      const key = this._counter++;
+      this._data.set(key, value);
+      return key;
+    },
+    delete(key) {
+      const value = this._data.get(key);
+      this._data.delete(key);
+      return value;
+    },
+  };
+
+  /**
+   * Report error with component name always included
+   * @param {string} kind - Error category
+   * @param {string} message - Error message
+   * @param {Object} [context] - Additional context
+   * @returns {string} Formatted error message
+   */
+  fezError(kind, message, context) {
+    const name = this.fezName || this.root?.tagName?.toLowerCase() || "unknown";
+    const enhancedContext = context ? { ...context, componentName: name } : { componentName: name };
+    return Fez.onError(kind, `<${name}> ${message}`, enhancedContext);
+  }
+
+  /**
+   * String selector for use in HTML nodes
+   */
   get fezHtmlRoot() {
-    return `Fez(${this.UID}).`
-    // return this.props.id ? `Fez.find("#${this.props.id}").` : `Fez.find(this, "${this.fezName}").`
+    return `Fez(${this.UID}).`;
   }
 
-  // checks if node is attached and clears all if not
+  /**
+   * Check if node is attached to DOM
+   */
   get isConnected() {
-    if (this.root?.isConnected) {
-      return true
-    } else {
-      this.fezOnDestroy()
-      return false
-    }
+    return !!this.root?.isConnected;
   }
 
-  // get single node property
+  /**
+   * Get single node property
+   */
   prop(name) {
-    let v = this.oldRoot[name] || this.props[name]
-    if (typeof v == 'function') {
-      // if this.prop('onclick'), we want "this" to point to this.root (dom node)
-      v = v.bind(this.root)
+    let v = this.oldRoot[name] || this.props[name];
+    if (typeof v == "function") {
+      v = v.bind(this.root);
     }
-    return v
+    return v;
   }
 
-  // copy attributes to root node
-  copy() {
-    for (const name of Array.from(arguments)) {
-      let value = this.props[name]
-
-      if (value !== undefined) {
-        if (name == 'class') {
-          const klass = this.root.getAttribute(name, value)
-
-          if (klass) {
-            value = [klass, value].join(' ')
-          }
-        }
+  // ===========================================================================
+  // LIFECYCLE HOOKS
+  // ===========================================================================
 
-        if (name == 'style' || !this.root[name]) {
-          if (typeof value == 'string') {
-            this.root.setAttribute(name, value)
-          }
-          else {
-            this.root[name] = value
-          }
-        }
-      }
-    }
-  }
+  connect() {}
+  onMount() {}
+  beforeRender() {}
+  afterRender() {}
+  onDestroy() {}
+  onStateChange() {}
+  onGlobalStateChange() {}
+  onPropsChange() {}
 
-  // clear all node references
-  // Centralized destroy logic
+  /**
+   * Centralized destroy logic - called by MutationObserver when element is removed
+   */
   fezOnDestroy() {
-    // Execute all registered cleanup callbacks
+    // Guard against double-cleanup
+    if (this._destroyed) return;
+    this._destroyed = true;
+
+    // Execute cleanup callbacks (intervals, observers, event listeners)
     if (this._onDestroyCallbacks) {
-      this._onDestroyCallbacks.forEach(callback => {
+      this._onDestroyCallbacks.forEach((callback) => {
         try {
           callback();
         } catch (e) {
-          console.error('Fez: Error in cleanup callback:', e);
+          this.fezError("destroy", "Error in cleanup callback", e);
         }
       });
       this._onDestroyCallbacks = [];
     }
 
-    // Call user's onDestroy lifecycle hook
-    this.onDestroy()
-    this.onDestroy = () => {}
+    // Call user's onDestroy hook
+    this.onDestroy();
+    this.onDestroy = () => {};
 
     // Clean up root references
     if (this.root) {
-      this.root.fez = undefined
+      this.root.fez = undefined;
     }
-
-    this.root = undefined
+    this.root = undefined;
   }
 
-  // Add a cleanup callback to be executed on destroy
+  /**
+   * Add a cleanup callback for destroy
+   */
   addOnDestroy(callback) {
     this._onDestroyCallbacks = this._onDestroyCallbacks || [];
     this._onDestroyCallbacks.push(callback);
   }
 
-  // Generic function to handle window events with automatic cleanup
-  on(eventName, func, delay = 200) {
-    this._eventHandlers = this._eventHandlers || {};
-
-    if (this._eventHandlers[eventName]) {
-      window.removeEventListener(eventName, this._eventHandlers[eventName]);
-    }
+  // ===========================================================================
+  // RENDERING
+  // ===========================================================================
 
-    const throttledFunc = Fez.throttle(() => {
-      if (this.isConnected) {
-        func.call(this);
-      }
-    }, delay);
-
-    this._eventHandlers[eventName] = throttledFunc;
-    window.addEventListener(eventName, throttledFunc);
-
-    this.addOnDestroy(() => {
-      window.removeEventListener(eventName, throttledFunc);
-      delete this._eventHandlers[eventName];
-    });
-  }
-
-  // Helper function for resize events
-  onWindowResize(func, delay) {
-    this.on('resize', func, delay);
-    func();
-  }
-
-  // Helper function for scroll events
-  onWindowScroll(func, delay) {
-    this.on('scroll', func, delay);
-    func();
-  }
-
-  // Helper function for element resize events using ResizeObserver
-  onElementResize(el, func, delay = 200) {
-    const throttledFunc = Fez.throttle(() => {
-      if (this.isConnected) {
-        func.call(this, el.getBoundingClientRect(), el);
-      }
-    }, delay);
-
-    const observer = new ResizeObserver(throttledFunc);
-    observer.observe(el);
-
-    func.call(this, el.getBoundingClientRect(), el);
-
-    this.addOnDestroy(() => {
-      observer.disconnect();
-    });
+  /**
+   * Parse HTML and replace fez. references
+   */
+  fezParseHtml(text) {
+    const base = this.fezHtmlRoot.replaceAll('"', "&quot;");
+    text = text
+      .replace(/([!'"\s;])fez\.(\w)/g, `$1${base}$2`)
+      .replace(/>\s+</g, "><");
+    return text.trim();
   }
 
-  // copy child nodes, natively to preserve bound events
-  // if node name is SLOT insert adjacent and remove SLOT, else as a child nodes
-  slot(source, target) {
-    target ||= document.createElement('template')
-    const isSlot = target.nodeName == 'SLOT'
-
-    while (source.firstChild) {
-      if (isSlot) {
-        target.parentNode.insertBefore(source.lastChild, target.nextSibling);
-      } else {
-        target.appendChild(source.firstChild)
-      }
-    }
-
-    if (isSlot) {
-      target.parentNode.removeChild(target)
+  /**
+   * Schedule work on next animation frame (debounced by name)
+   */
+  fezNextTick(func, name) {
+    if (name) {
+      this._nextTicks ||= {};
+      this._nextTicks[name] ||= window.requestAnimationFrame(() => {
+        func.bind(this)();
+        this._nextTicks[name] = null;
+      }, name);
     } else {
-      source.innerHTML = ''
+      window.requestAnimationFrame(func.bind(this));
     }
-
-    return target
   }
 
-  setStyle(key, value) {
-    this.root.style.setProperty(key, value);
-  }
-
-  connect() {}
-  onMount() {}
-  beforeRender() {}
-  afterRender() {}
-  onDestroy() {}
-  onStateChange() {}
-  onGlobalStateChange() {}
-
-  // component publish will search for parent component that subscribes by name
-  publish(channel, ...args) {
-    const handle_publish = (component) => {
-      if (Fez._subs && Fez._subs[channel]) {
-        const sub = Fez._subs[channel].find(([comp]) => comp === component)
-        if (sub) {
-          sub[1].bind(component)(...args)
-          return true
-        }
-      }
-      return false
-    }
-
-    // Check if current component has subscription
-    if (handle_publish(this)) {
-      return true
-    }
-
-    // Bubble up to parent components
-    let parent = this.root.parentElement
-    while (parent) {
-      if (parent.fez) {
-        if (handle_publish(parent.fez)) {
-          return true
-        }
-      }
-      parent = parent.parentElement
-    }
-
-    // If no parent handled it, fall back to global publish
-    // Fez.publish(channel, ...args)
-    return false
+  /**
+   * Force a re-render on next frame
+   */
+  fezRefresh() {
+    this.fezNextTick(() => this.fezRender(), "refresh");
   }
 
-  fezBlocks = {}
-
-  parseHtml(text) {
-    const base = this.fezHtmlRoot.replaceAll('"', '&quot;')
-
-    text = text
-      .replace(/([!'"\s;])fez\.(\w)/g, `$1${base}$2`)
-      .replace(/>\s+</g, '><')
-
-    return text.trim()
+  /**
+   * Alias for fezRefresh - can be overwritten
+   */
+  refresh() {
+    this.fezRefresh();
   }
 
+  /**
+   * Render the component template to DOM
+   * Uses component-aware DOM differ with hash-based skip
+   */
+  fezRender(template) {
+    // Check instance-level template first, then class-level
+    template ||= this.fezHtmlFunc || this?.class?.fezHtmlFunc;
 
-  // pass name to have only one tick of a kind
-  nextTick(func, name) {
-    if (name) {
-      this._nextTicks ||= {}
-      this._nextTicks[name] ||= window.requestAnimationFrame(() => {
-        func.bind(this)()
-        this._nextTicks[name] = null
-      }, name)
-    } else {
-      window.requestAnimationFrame(func.bind(this))
-    }
-  }
-
-  // inject htmlString as innerHTML and replace $$. with local pointer
-  // $$. will point to current fez instance
-  // <slot></slot> will be replaced with current root
-  // this.render('...loading')
-  // this.render('.images', '...loading')
-  render(template) {
-    template ||= this?.class?.fezHtmlFunc
+    if (!template || !this.root) return;
 
-    if (!template || !this.root) return
+    // Prevent re-render loops from state changes in beforeRender/afterRender
+    this._isRendering = true;
 
-    this.beforeRender()
+    this.beforeRender();
 
-    const nodeName = typeof this.class.nodeName == 'function' ? this.class.nodeName(this.root) : this.class.nodeName
-    const newNode = document.createElement(nodeName || 'div')
+    const nodeName =
+      typeof this.class.nodeName == "function"
+        ? this.class.nodeName(this.root)
+        : this.class.nodeName;
+    const newNode = document.createElement(nodeName || "div");
 
-    let renderedTpl
+    let renderedTpl;
     if (Array.isArray(template)) {
-      // array nodes this.n(...), look tabs example
       if (template[0] instanceof Node) {
-        template.forEach( n => newNode.appendChild(n) )
-      } else{
-        renderedTpl = template.join('')
+        template.forEach((n) => newNode.appendChild(n));
+      } else {
+        renderedTpl = template.join("");
       }
-    }
-    else if (typeof template == 'string') {
-      renderedTpl = createTemplate(template)(this)
-    }
-    else if (typeof template == 'function') {
-      renderedTpl = template(this)
+    } else if (typeof template == "string") {
+      const name = this.root?.tagName?.toLowerCase();
+      renderedTpl = createTemplate(template, { name })(this);
+    } else if (typeof template == "function") {
+      renderedTpl = template(this);
     }
 
     if (renderedTpl) {
-      renderedTpl = renderedTpl.replace(/\s\w+="undefined"/g, '')
-      newNode.innerHTML = this.parseHtml(renderedTpl)
+      if (
+        renderedTpl instanceof DocumentFragment ||
+        renderedTpl instanceof Node
+      ) {
+        newNode.appendChild(renderedTpl);
+      } else {
+        renderedTpl = renderedTpl.replace(/\s\w+="undefined"/g, "");
+        const parsedHtml = this.fezParseHtml(renderedTpl);
+
+        // Hash-skip: if template output is identical, skip the morph entirely
+        const newHash = Fez.fnv1(parsedHtml);
+        if (newHash === this._fezHash) {
+          this._isRendering = false;
+          return;
+        }
+        this._fezHash = newHash;
+
+        newNode.innerHTML = parsedHtml;
+      }
     }
 
-    // Handle fez-keep attributes
-    this.fezKeepNode(newNode)
+    this.fezKeepNode(newNode);
 
-    // Handle fez-memoize attributes
-    this.fezMemoization(newNode)
+    // Save input values for fez-this/fez-bind bound elements before morph
+    const savedInputValues = new Map();
+    this.root.querySelectorAll("input, textarea, select").forEach((el) => {
+      if (el._fezThisName) {
+        savedInputValues.set(el._fezThisName, {
+          value: el.value,
+          checked: el.checked,
+        });
+      }
+    });
+
+    Fez.morphdom(this.root, newNode);
 
-    Fez.morphdom(this.root, newNode)
+    // Restore input values after morph - find element by _fezThisName property
+    savedInputValues.forEach((saved, name) => {
+      let el = null;
+      this.root.querySelectorAll("input, textarea, select").forEach((input) => {
+        if (input._fezThisName === name) el = input;
+      });
+      if (el) {
+        el.value = saved.value;
+        if (saved.checked !== undefined) el.checked = saved.checked;
+      }
+    });
 
-    this.fezRenderPostProcess()
+    this.fezRenderPostProcess();
+    this.afterRender();
 
-    this.afterRender()
+    this._isRendering = false;
   }
 
+  /**
+   * Post-render processing for fez-* attributes
+   */
   fezRenderPostProcess() {
     const fetchAttr = (name, func) => {
-      this.root.querySelectorAll(`*[${name}]`).forEach((n)=>{
-        let value = n.getAttribute(name)
-        n.removeAttribute(name)
+      this.root.querySelectorAll(`*[${name}]`).forEach((n) => {
+        let value = n.getAttribute(name);
+        n.removeAttribute(name);
         if (value) {
-          func.bind(this)(value, n)
+          func.bind(this)(value, n);
         }
-      })
-    }
+      });
+    };
 
-    // <button fez-this="button" -> this.button = node
-    fetchAttr('fez-this', (value, n) => {
-      (new Function('n', `this.${value} = n`)).bind(this)(n)
-    })
+    // fez-this="button" -> this.button = node
+    fetchAttr("fez-this", (value, n) => {
+      new Function("n", `this.${value} = n`).bind(this)(n);
+      // Mark element for value preservation on re-render
+      n._fezThisName = value;
+    });
 
-    // <button fez-use="animate" -> this.animate(node]
-    fetchAttr('fez-use', (value, n) => {
-      if (value.includes('=>')) {
-        // fez-use="el => el.focus()"
-        Fez.getFunction(value)(n)
-      }
-      else {
-        if (value.includes('.')) {
-          // fez-use="this.focus()"
-          Fez.getFunction(value).bind(n)()
-        }
-        else {
-          // fez-use="animate"
-          const target = this[value]
-          if (typeof target == 'function') {
-            target(n)
+    // fez-use="animate" -> this.animate(node)
+    fetchAttr("fez-use", (value, n) => {
+      if (value.includes("=>")) {
+        Fez.getFunction(value)(n);
+      } else {
+        if (value.includes(".")) {
+          Fez.getFunction(value).bind(n)();
+        } else {
+          const target = this[value];
+          if (typeof target == "function") {
+            target(n);
           } else {
-            console.error(`Fez error: "${value}" is not a function in ${this.fezName}`)
+            this.fezError("fez-use", `"${value}" is not a function`);
           }
         }
       }
-    })
+    });
 
-    // <button fez-class="dialog animate" -> add class "animate" after node init to trigger animation
-    fetchAttr('fez-class', (value, n) => {
-      let classes = value.split(/\s+/)
-      let lastClass = classes.pop()
-      classes.forEach((c)=> n.classList.add(c) )
+    // fez-class="dialog animate" -> add class after init for animation
+    fetchAttr("fez-class", (value, n) => {
+      let classes = value.split(/\s+/);
+      let lastClass = classes.pop();
+      classes.forEach((c) => n.classList.add(c));
       if (lastClass) {
-        setTimeout(()=>{
-          n.classList.add(lastClass)
-        }, 1)
-      }
-    })
-
-    // <input fez-bind="state.inputNode" -> this.state.inputNode will be the value of input
-    fetchAttr('fez-bind', (text, n) => {
-      if (['INPUT', 'SELECT', 'TEXTAREA'].includes(n.nodeName)) {
-        const value = (new Function(`return this.${text}`)).bind(this)()
-        const isCb = n.type.toLowerCase() == 'checkbox'
-        const eventName = ['SELECT'].includes(n.nodeName) || isCb ? 'onchange' : 'onkeyup'
-        n.setAttribute(eventName, `${this.fezHtmlRoot}${text} = this.${isCb ? 'checked' : 'value'}`)
-        this.val(n, value)
-      } else {
-        console.error(`Cant fez-bind="${text}" to ${n.nodeName} (needs INPUT, SELECT or TEXTAREA. Want to use fez-this?).`)
+        setTimeout(() => {
+          n.classList.add(lastClass);
+        }, 1);
       }
-    })
+    });
 
-    this.root.querySelectorAll(`*[disabled]`).forEach((n)=>{
-      let value = n.getAttribute('disabled')
-      if (['false'].includes(value)) {
-        n.removeAttribute('disabled')
+    // fez-bind="state.inputNode" -> two-way binding
+    fetchAttr("fez-bind", (text, n) => {
+      if (["INPUT", "SELECT", "TEXTAREA"].includes(n.nodeName)) {
+        const value = new Function(`return this.${text}`).bind(this)();
+        const isCb = n.type.toLowerCase() == "checkbox";
+        const eventName =
+          ["SELECT"].includes(n.nodeName) || isCb ? "onchange" : "onkeyup";
+        n.setAttribute(
+          eventName,
+          `${this.fezHtmlRoot}${text} = this.${isCb ? "checked" : "value"}`,
+        );
+        this.val(n, value);
+        // Mark element for value preservation on re-render
+        n._fezThisName = text;
       } else {
-        n.setAttribute('disabled', 'true')
+        this.fezError(
+          "fez-bind",
+          `Can't bind "${text}" to ${n.nodeName} (needs INPUT, SELECT or TEXTAREA)`,
+        );
       }
-    })
-  }
+    });
 
-  fezKeepNode(newNode) {
-    newNode.querySelectorAll('[fez-keep]').forEach(newEl => {
-      const key = newEl.getAttribute('fez-keep')
-      const oldEl = this.root.querySelector(`[fez-keep="${key}"]`)
-
-      if (oldEl) {
-        // Keep the old element in place of the new one
-        newEl.parentNode.replaceChild(oldEl, newEl)
-      } else if (key === 'default-slot') {
-        if (newEl.getAttribute('hide')) {
-          // You cant use state any more
-          this.state = null
-
-          const parent = newEl.parentNode
-
-          // Insert all root children before the slot's next sibling
-          Array.from(this.root.childNodes).forEach(child => {
-            parent.insertBefore(child, newEl)
-          })
-
-          // Remove the slot element
-          newEl.remove()
-        }
-        else {
-          // First render - populate the slot with current root children
-          Array.from(this.root.childNodes).forEach(
-            child => {
-              newEl.appendChild(child)
-            }
-          )
+    // Normalize boolean attributes (checked, disabled, selected)
+    for (const attr of ["checked", "disabled", "selected"]) {
+      this.root.querySelectorAll(`*[${attr}]`).forEach((n) => {
+        let value = n.getAttribute(attr);
+        if (["false", "null", "undefined"].includes(value)) {
+          n.removeAttribute(attr);
+          n[attr] = false;
+        } else {
+          n.setAttribute(attr, attr);
         }
-      }
-    })
+      });
+    }
   }
 
-  fezMemoization(newNode) {
-    // Find the single memoize element in new DOM (excluding fez components)
-    const newMemoEl = newNode.querySelector('[fez-memoize]:not(.fez)')
-    if (!newMemoEl) return
+  /**
+   * Handle slot initialization on first render.
+   * Moves captured children from _fezSlotNodes into the .fez-slot container.
+   * fez-keep matching is handled natively by the differ (morph.js).
+   */
+  fezKeepNode(newNode) {
+    // First render only: move captured children into slot container.
+    // On subsequent renders the differ preserves the live .fez-slot via fez-keep.
+    if (this._fezSlotInitialized) return;
+
+    // Safe to use .querySelector - newNode is a fresh template with no nested components yet
+    const newSlot = newNode.querySelector(".fez-slot");
+    if (newSlot && this._fezSlotNodes) {
+      this._fezSlotInitialized = true;
+      this._fezSlotNodes.forEach((child) => {
+        newSlot.appendChild(child);
+      });
+    }
+  }
 
-    this.fezMemoStore ||= new Map()
+  // ===========================================================================
+  // REACTIVE STATE
+  // ===========================================================================
 
-    const newMemoElKey = newMemoEl.getAttribute('fez-memoize')
-    const storedNode = this.fezMemoStore.get(newMemoElKey)
+  /**
+   * Register component: setup CSS, state, and bind methods
+   */
+  fezRegister() {
+    if (this.css) {
+      this.css = Fez.globalCss(this.css, { name: this.fezName, wrap: true });
+    }
 
-    if (storedNode) {
-      Fez.log(`Memoize restore ${this.fezName}: ${newMemoElKey}`)
-      newMemoEl.parentNode.replaceChild(storedNode.cloneNode(true), newMemoEl)
-    } else {
-      const oldMemoEl = this.root.querySelector('[fez-memoize]:not(.fez)')
-      if (oldMemoEl) {
-        const oldMemoElKey = oldMemoEl.getAttribute('fez-memoize')
-        this.fezMemoStore.set(oldMemoElKey, oldMemoEl.cloneNode(true))
-      }
+    if (this.class.css) {
+      this.class.css = Fez.globalCss(this.class.css, { name: this.fezName });
     }
+
+    this.state ||= this.fezReactiveStore();
+    this.globalState = Fez.state.createProxy(this);
+    this.fezRegisterBindMethods();
   }
 
-  // refresh single node only
-  refresh(selector) {
-    alert('NEEDS FIX and remove htmlTemplate')
-    if (selector) {
-      const n = Fez.domRoot(this.class.htmlTemplate)
-      const tpl = n.querySelector(selector).innerHTML
-      this.render(selector, tpl)
-    } else {
-      this.render()
-    }
+  /**
+   * Bind all instance methods to this
+   */
+  fezRegisterBindMethods() {
+    const methods = Object.getOwnPropertyNames(
+      Object.getPrototypeOf(this),
+    ).filter(
+      (method) =>
+        method !== "constructor" && typeof this[method] === "function",
+    );
+    methods.forEach((method) => (this[method] = this[method].bind(this)));
   }
 
-  // run only if node is attached, clear otherwise
-  setInterval(func, tick, name) {
-    if (typeof func == 'number') {
-      [tick, func] = [func, tick]
-    }
+  /**
+   * Create a reactive store that triggers re-renders on changes
+   */
+  fezReactiveStore(obj, handler) {
+    obj ||= {};
 
-    name ||= Fez.fnv1(String(func))
+    handler ||= (o, k, v, oldValue) => {
+      if (v != oldValue) {
+        this.onStateChange(k, v, oldValue);
+        // Don't schedule re-render during init/mount or if already rendering
+        if (!this._isRendering && !this._isInitializing) {
+          this.fezNextTick(this.fezRender, "fezRender");
+        }
+      }
+    };
 
-    this._setIntervalCache ||= {}
-    clearInterval(this._setIntervalCache[name])
+    handler.bind(this);
 
-    const intervalID = setInterval(() => {
-      if (this.isConnected) {
-        func()
+    function shouldProxy(obj) {
+      return (
+        typeof obj === "object" &&
+        obj !== null &&
+        !(obj instanceof Promise) &&
+        !obj.nodeType
+      );
+    }
+
+    function createReactive(obj, handler) {
+      if (!shouldProxy(obj)) {
+        return obj;
       }
-    }, tick)
 
-    this._setIntervalCache[name] = intervalID
+      return new Proxy(obj, {
+        set(target, property, value, receiver) {
+          const currentValue = Reflect.get(target, property, receiver);
 
-    // Register cleanup callback
-    this.addOnDestroy(() => {
-      clearInterval(intervalID);
-      delete this._setIntervalCache[name];
-    });
+          if (currentValue !== value) {
+            if (shouldProxy(value)) {
+              value = createReactive(value, handler);
+            }
 
-    return intervalID
+            const result = Reflect.set(target, property, value, receiver);
+            handler(target, property, value, currentValue);
+            return result;
+          }
+
+          return true;
+        },
+        get(target, property, receiver) {
+          const value = Reflect.get(target, property, receiver);
+          if (shouldProxy(value)) {
+            return createReactive(value, handler);
+          }
+          return value;
+        },
+      });
+    }
+
+    return createReactive(obj, handler);
   }
 
+  // ===========================================================================
+  // DOM HELPERS
+  // ===========================================================================
+
+  /**
+   * Find element by selector
+   */
   find(selector) {
-    return typeof selector == 'string' ? this.root.querySelector(selector) : selector
+    return typeof selector == "string"
+      ? this.root.querySelector(selector)
+      : selector;
+  }
+
+  /**
+   * Add one or more classes (space-separated) to root or given node
+   */
+  addClass(names, node) {
+    (node || this.root).classList.add(...names.split(/\s+/).filter(Boolean));
   }
 
-  // get or set node value
+  /**
+   * Toggle a class on root or given node, with optional force boolean
+   */
+  toggleClass(name, force, node) {
+    (node || this.root).classList.toggle(name, force);
+  }
+
+  /**
+   * Get or set node value (input/textarea/select or innerHTML)
+   */
   val(selector, data) {
-    const node = this.find(selector)
+    const node = this.find(selector);
 
     if (node) {
-      if (['INPUT', 'TEXTAREA', 'SELECT'].includes(node.nodeName)) {
-        if (typeof data != 'undefined') {
-          if (node.type == 'checkbox') {
-            node.checked = !!data
+      if (["INPUT", "TEXTAREA", "SELECT"].includes(node.nodeName)) {
+        if (typeof data != "undefined") {
+          if (node.type == "checkbox") {
+            node.checked = !!data;
           } else {
-            node.value = data
+            node.value = data;
           }
         } else {
-          return node.value
+          return node.value;
         }
       } else {
-        if (typeof data != 'undefined') {
-          node.innerHTML = data
+        if (typeof data != "undefined") {
+          node.innerHTML = data;
         } else {
-          return node.innerHTML
+          return node.innerHTML;
         }
       }
     }
   }
 
+  /**
+   * Instance form data helper
+   */
   formData(node) {
-    return this.class.formData(node || this.root)
+    return this.class.formData(node || this.root);
   }
 
-  // get or set attribute
+  /**
+   * Get or set root attribute
+   */
   attr(name, value) {
-    if (typeof value === 'undefined') {
-      return this.root.getAttribute(name)
+    if (typeof value === "undefined") {
+      return this.root.getAttribute(name);
     } else {
-      this.root.setAttribute(name, value)
-      return value
+      this.root.setAttribute(name, value);
+      return value;
     }
   }
 
-  // get root node child nodes as array
+  /**
+   * Get root element children as array, optionally transform
+   * Returns only element nodes (nodeType === 1), text nodes are excluded.
+   * Pass true to convert children to objects with attrs as keys, innerHTML as .html, original node as .ROOT
+   */
   childNodes(func) {
-    let children = Array.from(this.root.children)
-
-    if (func) {
-      // Create temporary container to avoid ancestor-parent errors
-      const tmpContainer = document.createElement('div')
-      tmpContainer.style.display = 'none'
-      document.body.appendChild(tmpContainer)
-      children.forEach(child => tmpContainer.appendChild(child))
-
-      children = Array.from(tmpContainer.children).map(func)
-      document.body.removeChild(tmpContainer)
+    let children = this._fezChildNodes || Array.from(this.root.children);
+    if (func === true) {
+      children = children.map((node) => {
+        const obj = { html: node.innerHTML, ROOT: node };
+        for (const attr of node.attributes) {
+          obj[attr.name] = attr.value;
+        }
+        return obj;
+      });
+    } else if (func) {
+      children = children.map(func);
     }
-
-    return children
+    return children;
   }
 
-  subscribe(channel, func) {
-    Fez._subs ||= {}
-    Fez._subs[channel] ||= []
-    Fez._subs[channel] = Fez._subs[channel].filter((el) => el[0].isConnected)
-    Fez._subs[channel].push([this, func])
+  /**
+   * Set CSS properties on root
+   */
+  setStyle(key, value) {
+    if (key && typeof key == "object") {
+      Object.entries(key).forEach(([prop, val]) => {
+        this.root.style.setProperty(prop, val);
+      });
+    } else {
+      this.root.style.setProperty(key, value);
+    }
   }
 
-  // get and set root node ID
-  rootId() {
-    this.root.id ||= `fez_${this.UID}`
-    return this.root.id
-  }
+  /**
+   * Copy props as attributes to root
+   */
+  copy() {
+    for (const name of Array.from(arguments)) {
+      let value = this.props[name];
 
-  fezRegister() {
-    if (this.css) {
-      this.css = Fez.globalCss(this.css, {name: this.fezName, wrap: true})
-    }
+      if (value !== undefined) {
+        if (name == "class") {
+          const klass = this.root.getAttribute(name, value);
+          if (klass) {
+            value = [klass, value].join(" ");
+          }
+        }
 
-    if (this.class.css) {
-      this.class.css = Fez.globalCss(this.class.css, {name: this.fezName})
+        if (typeof value == "string") {
+          this.root.setAttribute(name, value);
+        } else {
+          this.root[name] = value;
+        }
+      }
     }
-
-    this.state ||= this.reactiveStore()
-    this.globalState = Fez.state.createProxy(this)
-    this.fezRegisterBindMethods()
   }
 
-  // bind all instance method to this, to avoid calling with .bind(this)
-  fezRegisterBindMethods() {
-    const methods = Object.getOwnPropertyNames(Object.getPrototypeOf(this))
-      .filter(method => method !== 'constructor' && typeof this[method] === 'function')
-
-    methods.forEach(method => this[method] = this[method].bind(this))
+  /**
+   * Get or set root ID
+   */
+  rootId() {
+    this.root.id ||= `fez_${this.UID}`;
+    return this.root.id;
   }
 
-  // dissolve into parent, if you want to promote first child or given node with this.root
+  /**
+   * Dissolve component into parent
+   */
   dissolve(inNode) {
     if (inNode) {
-      inNode.classList.add('fez')
-      inNode.classList.add(`fez-${this.fezName}`)
-      inNode.fez = this
-      if (this.attr('id')) inNode.setAttribute('id', this.attr('id'))
+      inNode.classList.add("fez");
+      inNode.classList.add(`fez-${this.fezName}`);
+      inNode.fez = this;
+      if (this.attr("id")) inNode.setAttribute("id", this.attr("id"));
 
-      this.root.innerHTML = ''
-      this.root.appendChild(inNode)
+      this.root.innerHTML = "";
+      this.root.appendChild(inNode);
     }
 
-    const node = this.root
-    const nodes = this.childNodes()
-    const parent = this.root.parentNode
+    const node = this.root;
+    const nodes = this.childNodes();
+    const parent = this.root.parentNode;
 
-    nodes.reverse().forEach(el => parent.insertBefore(el, node.nextSibling))
+    nodes.reverse().forEach((el) => parent.insertBefore(el, node.nextSibling));
 
-    this.root.remove()
-    this.root = undefined
+    this.root.remove();
+    this.root = undefined;
 
     if (inNode) {
-      this.root = inNode
+      this.root = inNode;
     }
 
-    return nodes
+    return nodes;
   }
 
-  reactiveStore(obj, handler) {
-    obj ||= {}
+  // ===========================================================================
+  // EVENTS
+  // ===========================================================================
 
-    handler ||= (o, k, v, oldValue) => {
-      this.onStateChange(k, v, oldValue)
-      this.nextTick(this.render, 'render')
+  /**
+   * Add window event listener with auto-cleanup
+   */
+  on(eventName, func, delay = 200) {
+    this._eventHandlers = this._eventHandlers || {};
+
+    if (this._eventHandlers[eventName]) {
+      window.removeEventListener(eventName, this._eventHandlers[eventName]);
     }
 
-    handler.bind(this)
+    const throttledFunc = Fez.throttle(() => {
+      if (this.isConnected) func.call(this);
+    }, delay);
 
-    // licence ? -> generated by ChatGPT 2024
-    function createReactive(obj, handler) {
-      if (typeof obj !== 'object' || obj === null) {
-        return obj;
-      }
+    this._eventHandlers[eventName] = throttledFunc;
+    window.addEventListener(eventName, throttledFunc);
 
-      return new Proxy(obj, {
-        set(target, property, value, receiver) {
-          // Get the current value of the property
-          const currentValue = Reflect.get(target, property, receiver);
+    this.addOnDestroy(() => {
+      window.removeEventListener(eventName, throttledFunc);
+      delete this._eventHandlers[eventName];
+    });
+  }
 
-          // Only proceed if the new value is different from the current value
-          if (currentValue !== value) {
-            if (typeof value === 'object' && value !== null) {
-              value = createReactive(value, handler); // Recursively make nested objects reactive
-            }
+  /**
+   * Window resize handler
+   */
+  onWindowResize(func, delay) {
+    this.on("resize", func, delay);
+    func();
+  }
 
-            // Set the new value
-            const result = Reflect.set(target, property, value, receiver);
+  /**
+   * Window scroll handler
+   */
+  onWindowScroll(func, delay) {
+    this.on("scroll", func, delay);
+    func();
+  }
 
-            // Call the handler only if the value has changed
-            handler(target, property, value, currentValue);
+  /**
+   * Element resize handler using ResizeObserver
+   */
+  onElementResize(el, func, delay = 200) {
+    const throttledFunc = Fez.throttle(() => {
+      if (this.isConnected) func.call(this, el.getBoundingClientRect(), el);
+    }, delay);
 
-            return result;
-          }
+    const observer = new ResizeObserver(throttledFunc);
+    observer.observe(el);
 
-          // If the value hasn't changed, return true (indicating success) without calling the handler
-          return true;
-        },
-        get(target, property, receiver) {
-          const value = Reflect.get(target, property, receiver);
-          if (typeof value === 'object' && value !== null) {
-            return createReactive(value, handler); // Recursively make nested objects reactive
-          }
-          return value;
-        }
-      });
+    func.call(this, el.getBoundingClientRect(), el);
+
+    this.addOnDestroy(() => {
+      observer.disconnect();
+    });
+  }
+
+  /**
+   * Timeout with auto-cleanup
+   */
+  setTimeout(func, delay) {
+    const timeoutID = setTimeout(() => {
+      if (this.isConnected) func();
+    }, delay);
+
+    this.addOnDestroy(() => clearTimeout(timeoutID));
+
+    return timeoutID;
+  }
+
+  /**
+   * Interval with auto-cleanup
+   */
+  setInterval(func, tick, name) {
+    if (typeof func == "number") {
+      [tick, func] = [func, tick];
     }
 
-    return createReactive(obj, handler);
+    name ||= Fez.fnv1(String(func));
+
+    this._setIntervalCache ||= {};
+    clearInterval(this._setIntervalCache[name]);
+
+    const intervalID = setInterval(() => {
+      if (this.isConnected) func();
+    }, tick);
+
+    this._setIntervalCache[name] = intervalID;
+
+    this.addOnDestroy(() => {
+      clearInterval(intervalID);
+      delete this._setIntervalCache[name];
+    });
+
+    return intervalID;
+  }
+
+  // ===========================================================================
+  // PUB/SUB
+  // ===========================================================================
+
+  /**
+   * Publish to parent components (bubbles up through DOM)
+   * @param {string} channel - Event name
+   * @param {...any} args - Arguments to pass
+   * @returns {boolean} True if a parent handled the event
+   */
+  publish(channel, ...args) {
+    return componentPublish(this, channel, ...args);
+  }
+
+  /**
+   * Subscribe to a channel (auto-cleanup on destroy)
+   * @param {string} channel - Event name
+   * @param {Function} func - Handler function
+   * @returns {Function} Unsubscribe function
+   */
+  subscribe(channel, func) {
+    const unsubscribe = componentSubscribe(this, channel, func);
+    this.addOnDestroy(unsubscribe);
+    return unsubscribe;
+  }
+
+  // ===========================================================================
+  // SLOTS
+  // ===========================================================================
+
+  /**
+   * Copy child nodes natively to preserve bound events
+   */
+  fezSlot(source, target) {
+    target ||= document.createElement("template");
+    const isSlot = target.nodeName == "SLOT";
+
+    while (source.firstChild) {
+      if (isSlot) {
+        target.parentNode.insertBefore(source.lastChild, target.nextSibling);
+      } else {
+        target.appendChild(source.firstChild);
+      }
+    }
+
+    if (isSlot) {
+      target.parentNode.removeChild(target);
+    } else {
+      source.innerHTML = "";
+    }
+
+    return target;
   }
 }