@dinoreic/fez 0.2.2 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinoreic/fez",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Runtime custom dom elements",
   "main": "dist/fez.js",
   "type": "module",
@@ -20,7 +20,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "fez": "./bin/fez"
+    "fez": "bin/fez"
   },
   "files": [
     "bin",
@@ -29,17 +29,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "bun build.js b",
-    "b": "bun run build",
-    "watch": "bun build.js w",
-    "server": "bun run lib/server.js",
-    "dev": "bunx concurrently --kill-others \"bun run server\" \"find src demo lib | entr -c sh -c 'bun run index && bun run b'\"",
-    "test": "bun test",
-    "prepublishOnly": "bun run build && bun run test",
-    "publish": "npm publish --access public",
-    "index": "ruby ./bin/fez-index 'demo/fez/*.fez' > demo/fez/index.json"
-  },
   "keywords": [
     "dom",
     "elements",
@@ -66,5 +55,16 @@
     "happy-dom": "^18.0.1",
     "jsdom": "^26.1.0",
     "mime": "^4.0.7"
+  },
+  "scripts": {
+    "build": "bun build.js b",
+    "b": "bun run build",
+    "watch": "bun build.js w",
+    "server": "bun run lib/server.js",
+    "dev": "bunx concurrently --kill-others \"bun run server\" \"find src demo lib | entr -cn sh -c 'bun run index && bun run b'\"",
+    "test": "bun test",
+    "prepublishOnly": "bun run build && bun run test",
+    "publish": "npm publish --access public",
+    "index": "ruby ./bin/fez-index 'demo/fez/*.fez' > demo/fez/index.json"
   }
 }

package/src/fez/connect.js

@@ -1,94 +1,122 @@
-// templating
 import createTemplate from './lib/template.js'
 import FezBase from './instance.js'
 
-// this function accepts custom tag name and class definition, creates and connects
-// Fez(name, klass)
-export default function(name, klass) {
+/**
+ * Registers a new custom element with Fez framework
+ * @param {string} name - Custom element name (must contain a dash)
+ * @param {Class|Object} klass - Component class or configuration object
+ * @example
+ * Fez('my-component', class {
+ *   HTML = '<div>Hello World</div>'
+ *   CSS = '.my-component { color: blue; }'
+ * })
+ */
+export default function connect(name, klass) {
   const Fez = globalThis.window?.Fez || globalThis.Fez;
   // Validate custom element name format (must contain a dash)
   if (!name.includes('-')) {
     console.error(`Fez: Invalid custom element name "${name}". Custom element names must contain a dash (e.g., 'my-element', 'ui-button').`)
   }
 
-  // to allow anonymous class and then re-attach (does not work)
-  // Fez('ui-todo', class { ... # instead Fez('ui-todo', class extends FezBase {
+  // Transform simple class definitions into Fez components
   if (!klass.fezHtmlRoot) {
     const klassObj = new klass()
     const newKlass = class extends FezBase {}
 
+    // Copy all properties and methods from the original class
     const props = Object.getOwnPropertyNames(klassObj)
       .concat(Object.getOwnPropertyNames(klass.prototype))
       .filter(el => !['constructor', 'prototype'].includes(el))
 
     props.forEach(prop => newKlass.prototype[prop] = klassObj[prop])
 
-    Fez.fastBindInfo ||= {fast: [], slow: []}
-
-    if (klassObj.GLOBAL) { newKlass.fezGlobal = klassObj.GLOBAL }
-    if (klassObj.CSS) { newKlass.css = klassObj.CSS }
-    if (klassObj.HTML) { newKlass.html = klassObj.HTML }
-    if (klassObj.NAME) { newKlass.nodeName = klassObj.NAME }
-    if (klassObj.FAST) {
-      newKlass.fastBind = klassObj.FAST
-      Fez.fastBindInfo.fast.push(typeof klassObj.FAST == 'function' ? `${name} (func)` : name)
-    } else {
-      Fez.fastBindInfo.slow.push(name)
+    // Map component configuration properties
+    if (klassObj.GLOBAL) { newKlass.fezGlobal = klassObj.GLOBAL }  // Global instance reference
+    if (klassObj.CSS) { newKlass.css = klassObj.CSS }              // Component styles
+    if (klassObj.HTML) {
+      newKlass.html = closeCustomTags(klassObj.HTML)               // Component template
     }
+    if (klassObj.NAME) { newKlass.nodeName = klassObj.NAME }       // Custom DOM node name
 
+    // Auto-mount global components to body
     if (klassObj.GLOBAL) {
-      const func = () => document.body.appendChild(document.createElement(name))
+      const mountGlobalComponent = () => document.body.appendChild(document.createElement(name))
 
       if (document.readyState === 'loading') {
-        document.addEventListener('DOMContentLoaded', func);
+        document.addEventListener('DOMContentLoaded', mountGlobalComponent);
       } else {
-        func()
+        mountGlobalComponent()
       }
     }
 
     klass = newKlass
 
-    let info = `${name} compiled`
-    if (klassObj.FAST) info += ' (fast bind)'
-    Fez.log(info)
+    Fez.log(`${name} compiled`)
+  } else if (klass.html) {
+    // If klass already has html property, process it
+    klass.html = closeCustomTags(klass.html)
   }
 
+  // Process component template
   if (klass.html) {
-    klass.html = closeCustomTags(klass.html)
-
-    // wrap slot to enable reactive re-renders. It will use existing .fez-slot if found
+    // Replace <slot /> with reactive slot containers
     klass.html = klass.html.replace(/<slot\s*\/>|<slot\s*>\s*<\/slot>/g, () => {
-      const name = klass.SLOT || 'div'
-      return `<${name} class="fez-slot" fez-keep="default-slot"></${name}>`
+      const slotTag = klass.SLOT || 'div'
+      return `<${slotTag} class="fez-slot" fez-keep="default-slot"></${slotTag}>`
     })
 
+    // Compile template function
     klass.fezHtmlFunc = createTemplate(klass.html)
   }
 
-  // we have to register global css on component init, because some other component can depend on it (it is global)
+  // Register component styles globally (available to all components)
   if (klass.css) {
     klass.css = Fez.globalCss(klass.css, {name: name})
   }
 
   Fez.classes[name] = klass
 
+  connectCustomElement(name, klass)
+}
+
+/**
+ * Registers the custom element with the browser
+ * Sets up batched rendering for optimal performance
+ */
+function connectCustomElement(name, klass) {
+  const Fez = globalThis.window?.Fez || globalThis.Fez;
+
   if (!customElements.get(name)) {
     customElements.define(name, class extends HTMLElement {
       connectedCallback() {
-        // if you want to force fast render (prevent page flickering), add static fastBind = true or FAST = true
-        // we can not fast load auto for all because that creates hard to debug problems in nested custom nodes
-        // problems with events and slots (I woke up at 2AM, now it is 5AM)
-        // this is usually safe for first order components, as page header or any components that do not have innerHTML or use slots
-        // Example: you can add FAST as a function - render fast nodes that have name attribute
-        //   FAST(node) { return !!node.getAttribute('name') }
-        // to inspect fast / slow components use Fez.info() in console
-        if (useFastRender(this, klass)) {
-          connectNode(name, this)
-        } else {
-          window.requestAnimationFrame(()=>{
-            if (this.parentNode) {
-              connectNode(name, this)
-            }
+        // Batch all renders using microtasks for consistent timing and DOM completeness
+        if (!Fez._pendingConnections) {
+          Fez._pendingConnections = []
+          Fez._batchScheduled = false
+        }
+
+        Fez._pendingConnections.push({ name, node: this })
+
+        if (!Fez._batchScheduled) {
+          Fez._batchScheduled = true
+          Promise.resolve().then(() => {
+            const connections = Fez._pendingConnections.slice()
+            // console.error(`Batch processing ${connections.length} components:`, connections.map(c => c.name))
+            Fez._pendingConnections = []
+            Fez._batchScheduled = false
+
+            // Sort by DOM order to ensure parent nodes are processed before children
+            connections.sort((a, b) => {
+              if (a.node.contains(b.node)) return -1
+              if (b.node.contains(a.node)) return 1
+              return 0
+            })
+
+            connections.forEach(({ name, node }) => {
+              if (node.isConnected && node.parentNode) {
+                connectNode(name, node)
+              }
+            })
           })
         }
       }
@@ -96,8 +124,10 @@ export default function(name, klass) {
   }
 }
 
-//
-
+/**
+ * Converts self-closing custom tags to full open/close format
+ * Required for proper HTML parsing of custom elements
+ */
 function closeCustomTags(html) {
   const selfClosingTags = new Set([
     'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr'
@@ -108,17 +138,11 @@ function closeCustomTags(html) {
   })
 }
 
-function useFastRender(n, klass) {
-  const fezFast = n.getAttribute('fez-fast')
-  var isFast = typeof klass.fastBind === 'function' ? klass.fastBind(n) : klass.fastBind
-
-  if (fezFast == 'false') {
-    return false
-  } else {
-    return fezFast || isFast
-  }
-}
 
+/**
+ * Initializes a Fez component instance from a DOM node
+ * Replaces the custom element with the component's rendered content
+ */
 function connectNode(name, node) {
   const klass = Fez.classes[name]
   const parentNode = node.parentNode
@@ -143,7 +167,7 @@ function connectNode(name, node) {
     fez.props = klass.getProps(node, newNode)
     fez.class = klass
 
-    // move child nodes, natively to preserve bound events
+    // Move child nodes to preserve DOM event listeners
     fez.slot(node, newNode)
 
     newNode.fez = fez
@@ -160,10 +184,17 @@ function connectNode(name, node) {
       newNode.setAttribute('id', fez.props.id)
     }
 
-    fez.fezRegister();
-    ;(fez.init || fez.created || fez.connect).bind(fez)(fez.props);
+    // Component lifecycle initialization
+    fez.fezRegister()
+
+    // Call initialization method (init, created, or connect)
+    ;(fez.init || fez.created || fez.connect).bind(fez)(fez.props)
+
+    // Initial render
     fez.render()
     fez.firstRender = true
+
+    // Trigger mount lifecycle hook
     fez.onMount(fez.props)
 
     if (fez.onSubmit) {
@@ -174,9 +205,11 @@ function connectNode(name, node) {
       }
     }
 
-    // if onPropsChange method defined, add observer and trigger call on all attributes once component is loaded
+    // Set up reactive attribute watching
     if (fez.onPropsChange) {
       observer.observe(newNode, {attributes:true})
+
+      // Trigger initial prop change callbacks
       for (const [key, value] of Object.entries(fez.props)) {
         fez.onPropsChange(key, value)
       }
@@ -184,8 +217,10 @@ function connectNode(name, node) {
   }
 }
 
-//
-
+/**
+ * Global mutation observer for reactive attribute changes
+ * Watches for attribute changes and triggers component updates
+ */
 const observer = new MutationObserver((mutationsList, _) => {
   for (const mutation of mutationsList) {
     if (mutation.type === 'attributes') {

package/src/fez/defaults.js

@@ -3,8 +3,6 @@ const loadDefaults = () => {
   // include fez component by name
   //<fez-component name="some-node" :props="fez.props"></fez-component>
   Fez('fez-component', class {
-    FAST = true
-
     init(props) {
       const tag = document.createElement(props.name)
       tag.props = props.props || props['data-props'] || props
@@ -21,8 +19,6 @@ const loadDefaults = () => {
   // include remote data from url
   // <fez-include src="./demo/fez/ui-slider.html"></fez-include>
   Fez('fez-include', class {
-    FAST = true
-
     init(props) {
       Fez.fetch(props.src, (data)=>{
         const dom = Fez.domRoot(data)
@@ -45,7 +41,6 @@ const loadDefaults = () => {
         const hash = Fez.fnv1(this.root.outerHTML)
         const nodeName = `inline-${hash}`
         Fez(nodeName, class {
-          FAST = true
           HTML = html
           init() {
             Object.assign(this.state, props.state || {})

package/src/fez/instance.js

@@ -81,11 +81,6 @@ export default class FezBase {
     return formObject
   }
 
-  static fastBind() {
-    // return true to bind without requestAnimationFrame
-    // you can do this if you are sure you are not expecting innerHTML data
-    return false
-  }
 
   static nodeName = 'div'
 
@@ -106,42 +101,11 @@ export default class FezBase {
     if (this.root?.isConnected) {
       return true
     } else {
-      this.fezRemoveSelf()
+      this.fezOnDestroy()
       return false
     }
   }
 
-  // clear all node references
-  fezRemoveSelf() {
-    this._setIntervalCache ||= {}
-    Object.keys(this._setIntervalCache).forEach((key)=> {
-      clearInterval(this._setIntervalCache[key])
-    })
-
-    if (this._eventHandlers) {
-      Object.entries(this._eventHandlers).forEach(([eventName, handler]) => {
-        window.removeEventListener(eventName, handler);
-      });
-      this._eventHandlers = {};
-    }
-
-    if (this._timeouts) {
-      Object.values(this._timeouts).forEach(timeoutId => {
-        clearTimeout(timeoutId);
-      });
-      this._timeouts = {};
-    }
-
-    this.onDestroy()
-    this.onDestroy = () => {}
-
-    if (this.root) {
-      this.root.fez = undefined
-    }
-
-    this.root = undefined
-  }
-
   // get single node property
   prop(name) {
     let v = this.oldRoot[name] || this.props[name]
@@ -178,80 +142,92 @@ export default class FezBase {
     }
   }
 
-  // Generic function to handle window events with automatic cleanup
-  // eventName: 'resize', 'scroll', etc.
-  // func: callback function to execute
-  // delay: throttle delay in ms (default: 100ms)
-  on(eventName, func, delay = 200) {
-    this._eventHandlers = this._eventHandlers || {};
-    this._timeouts = this._timeouts || {};
-
-    if (this._eventHandlers[eventName]) {
-      window.removeEventListener(eventName, this._eventHandlers[eventName]);
+  // clear all node references
+  // Centralized destroy logic
+  fezOnDestroy() {
+    // Execute all registered cleanup callbacks
+    if (this._onDestroyCallbacks) {
+      this._onDestroyCallbacks.forEach(callback => {
+        try {
+          callback();
+        } catch (e) {
+          console.error('Fez: Error in cleanup callback:', e);
+        }
+      });
+      this._onDestroyCallbacks = [];
     }
 
-    if (this._timeouts[eventName]) {
-      clearTimeout(this._timeouts[eventName]);
+    // Call user's onDestroy lifecycle hook
+    this.onDestroy()
+    this.onDestroy = () => {}
+
+    // Clean up root references
+    if (this.root) {
+      this.root.fez = undefined
     }
 
-    let lastRun = 0;
+    this.root = undefined
+  }
 
-    const doExecute = () => {
-      if (!this.isConnected) {
-        if (this._eventHandlers[eventName]) {
-          window.removeEventListener(eventName, this._eventHandlers[eventName]);
-          delete this._eventHandlers[eventName];
-        }
-        if (this._timeouts[eventName]) {
-          clearTimeout(this._timeouts[eventName]);
-          delete this._timeouts[eventName];
-        }
-        return false;
-      }
-      func.call(this);
-      return true;
-    };
+  // Add a cleanup callback to be executed on destroy
+  addOnDestroy(callback) {
+    this._onDestroyCallbacks = this._onDestroyCallbacks || [];
+    this._onDestroyCallbacks.push(callback);
+  }
 
-    const handleEvent = () => {
-      const now = Date.now();
+  // Generic function to handle window events with automatic cleanup
+  on(eventName, func, delay = 200) {
+    this._eventHandlers = this._eventHandlers || {};
 
-      if (now - lastRun >= delay) {
-        if (doExecute()) {
-          lastRun = now;
-        } else {
-          return;
-        }
-      }
+    if (this._eventHandlers[eventName]) {
+      window.removeEventListener(eventName, this._eventHandlers[eventName]);
+    }
 
-      // Clear previous timeout and set new one to ensure final event
-      if (this._timeouts[eventName]) {
-        clearTimeout(this._timeouts[eventName]);
+    const throttledFunc = Fez.throttle(() => {
+      if (this.isConnected) {
+        func.call(this);
       }
+    }, delay);
 
-      this._timeouts[eventName] = setTimeout(() => {
-        if (now > lastRun && doExecute()) {
-          lastRun = Date.now();
-        }
-        delete this._timeouts[eventName];
-      }, delay);
-    };
+    this._eventHandlers[eventName] = throttledFunc;
+    window.addEventListener(eventName, throttledFunc);
 
-    this._eventHandlers[eventName] = handleEvent;
-    window.addEventListener(eventName, handleEvent);
+    this.addOnDestroy(() => {
+      window.removeEventListener(eventName, throttledFunc);
+      delete this._eventHandlers[eventName];
+    });
   }
 
   // Helper function for resize events
-  onResize(func, delay) {
+  onWindowResize(func, delay) {
     this.on('resize', func, delay);
     func();
   }
 
   // Helper function for scroll events
-  onScroll(func, delay) {
+  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();
+    });
+  }
+
   // 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) {
@@ -359,7 +335,8 @@ export default class FezBase {
 
     this.beforeRender()
 
-    const newNode = document.createElement(this.class.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
     if (Array.isArray(template)) {
@@ -486,13 +463,21 @@ export default class FezBase {
     this._setIntervalCache ||= {}
     clearInterval(this._setIntervalCache[name])
 
-    this._setIntervalCache[name] = setInterval(() => {
+    const intervalID = setInterval(() => {
       if (this.isConnected) {
         func()
       }
     }, tick)
 
-    return this._setIntervalCache[name]
+    this._setIntervalCache[name] = intervalID
+
+    // Register cleanup callback
+    this.addOnDestroy(() => {
+      clearInterval(intervalID);
+      delete this._setIntervalCache[name];
+    });
+
+    return intervalID
   }
 
   find(selector) {