@dinoreic/fez 0.2.2 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinoreic/fez",
-  "version": "0.2.2",
+  "version": "0.3.2",
   "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 || {})
@@ -58,6 +53,41 @@ const loadDefaults = () => {
       }
     }
   })
+
+  // Memory store for memoization
+  const memoStore = new Map()
+
+  // memoize component content by key
+  // <fez-memoize key="unique-key">content to memoize</fez-memoize>
+  Fez('fez-memoize', class {
+    init(props) {
+      if (!props.key) {
+        Fez.error('fez-memoize: key prop is required')
+        return
+      }
+
+      if (memoStore.has(props.key)) {
+        // Restore from memory in init
+        const storedNode = memoStore.get(props.key)
+        Fez.log(`Memoize - key: "${props.key}" - restore`)
+        this.root.innerHTML = ''
+        this.root.appendChild(storedNode.cloneNode(true))
+      }
+    }
+
+    onMount(props) {
+      // Only store if not already in memory
+      if (!memoStore.has(props.key)) {
+        requestAnimationFrame(() => {
+          // Store current DOM content
+          const contentNode = document.createElement('div')
+          contentNode.innerHTML = this.root.innerHTML
+          Fez.log(`Memoize - key: "${props.key}" - set`)
+          memoStore.set(props.key, contentNode)
+        })
+      }
+    }
+  })
 }
 
 // Only load defaults if Fez is available
@@ -66,4 +96,4 @@ if (typeof Fez !== 'undefined' && Fez) {
 }
 
 // Export for use in tests
-export { loadDefaults }
+export { loadDefaults }