@dinoreic/fez 0.4.0 → 0.5.2

package/src/fez/connect.js

@@ -1,211 +1,318 @@
-import createTemplate from './lib/template.js'
-import FezBase from './instance.js'
-
 /**
- * Global mutation observer for reactive attribute changes
- * Watches for attribute changes and triggers component updates
+ * Fez Component Registration & Connection
+ *
+ * This file handles:
+ * - Registering components with customElements
+ * - Transforming plain classes to FezBase subclasses
+ * - Instantiating components when they appear in DOM
+ *
+ * Flow:
+ * 1. connect(name, class) - registers custom element
+ * 2. connectedCallback() - when element appears in DOM
+ * 3. connectNode() - creates instance, renders, calls lifecycle
  */
-const observer = new MutationObserver((mutationsList, _) => {
-  for (const mutation of mutationsList) {
-    if (mutation.type === 'attributes') {
-      const fez = mutation.target.fez
-      const name = mutation.attributeName
-      const value = mutation.target.getAttribute(name)
 
+import createTemplate from "./lib/template.js";
+import FezBase from "./instance.js";
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const SELF_CLOSING_TAGS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "source",
+  "track",
+  "wbr",
+]);
+
+// Attribute observer for reactive props
+const attrObserver = new MutationObserver((mutations) => {
+  for (const mutation of mutations) {
+    if (mutation.type === "attributes") {
+      const fez = mutation.target.fez;
       if (fez) {
-        fez.props[name] = value
-        fez.onPropsChange(name, value)
-        // console.log(`The [${name}] attribute was modified to [${value}].`);
+        const name = mutation.attributeName;
+        const value = mutation.target.getAttribute(name);
+        fez.props[name] = value;
+        fez.onPropsChange(name, value);
       }
     }
   }
 });
 
+// =============================================================================
+// MAIN CONNECT FUNCTION
+// =============================================================================
+
 /**
- * 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
+ * Register a Fez component
+ *
+ * @param {string} name - Custom element name (must contain dash)
+ * @param {Class} klass - Component class
+ *
  * @example
- * Fez('my-component', class {
- *   HTML = '<div>Hello World</div>'
- *   CSS = '.my-component { color: blue; }'
+ * Fez('ui-button', class {
+ *   HTML = '<button><slot /></button>'
+ *   CSS = 'button { color: blue; }'
+ *   init() { console.log('created') }
  * })
  */
 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').`)
+
+  // Validate name
+  if (!name.includes("-")) {
+    console.error(`Fez: Invalid name "${name}". Must contain a dash.`);
+    return;
   }
 
-  // Transform simple class definitions into Fez components
-  if (!klass.fezHtmlRoot) {
-    const klassObj = new klass()
-    const newKlass = class extends FezBase {}
+  // Transform to FezBase subclass
+  klass = ensureFezBase(Fez, name, klass);
+
+  // Process HTML template
+  if (klass.html) {
+    klass.html = klass.html
+      .replace(
+        /<slot(\s[^>]*)?>/,
+        `<div class="fez-slot" fez-keep="default-slot"$1>`,
+      )
+      .replace("</slot>", `</div>`);
 
-    // 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))
+    klass.fezHtmlFunc = createTemplate(klass.html, { name });
+  }
 
-    props.forEach(prop => newKlass.prototype[prop] = klassObj[prop])
+  // Register CSS
+  if (klass.css) {
+    klass.css = Fez.globalCss(klass.css, { name });
+  }
 
-    // Map component configuration properties
-    if (klassObj.FAST) { newKlass.FAST = klassObj.FAST }           // Global instance reference
-    if (klassObj.GLOBAL) { newKlass.GLOBAL = 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
+  // Store class in index
+  Fez.index.ensure(name).class = klass;
 
-    // Auto-mount global components to body
-    if (klassObj.GLOBAL) {
-      document.body.appendChild(document.createElement(name))
-    }
+  // Register custom element
+  if (!customElements.get(name)) {
+    customElements.define(
+      name,
+      class extends HTMLElement {
+        connectedCallback() {
+          if (shouldRenderFast(this, klass)) {
+            connectNode(name, this);
+          } else {
+            requestAnimationFrame(() => connectNode(name, this));
+          }
+        }
+      },
+    );
+  }
+}
 
-    klass = newKlass
+// =============================================================================
+// CLASS TRANSFORMATION
+// =============================================================================
 
-    Fez.log(`${name} compiled`)
-  } else if (klass.html) {
-    // If klass already has html property, process it
-    klass.html = closeCustomTags(klass.html)
+/**
+ * Transform plain class to FezBase subclass
+ * Maps uppercase config props (HTML, CSS, etc.)
+ */
+function ensureFezBase(Fez, name, klass) {
+  // Already a FezBase subclass
+  if (klass.prototype instanceof FezBase) {
+    if (klass.html) klass.html = closeCustomTags(klass.html);
+    return klass;
   }
 
-  // Process component template
-  if (klass.html) {
-    let slotTag = klass.SLOT || 'div'
+  // Create FezBase subclass
+  const instance = new klass();
+  const newKlass = class extends FezBase {};
 
-    klass.html = klass.html
-      .replace('<slot', `<${slotTag} class="fez-slot" fez-keep="default-slot"`)
-      .replace('</slot>', `</${slotTag}>`)
+  // Copy properties and methods
+  const props = [
+    ...Object.getOwnPropertyNames(instance),
+    ...Object.getOwnPropertyNames(klass.prototype),
+  ].filter((p) => p !== "constructor" && p !== "prototype");
 
-    // Compile template function
-    klass.fezHtmlFunc = createTemplate(klass.html)
+  for (const prop of props) {
+    newKlass.prototype[prop] = instance[prop];
   }
 
-  // Register component styles globally (available to all components)
-  if (klass.css) {
-    klass.css = Fez.globalCss(klass.css, {name: name})
+  // Map config properties
+  const configMap = {
+    FAST: "FAST",
+    GLOBAL: "GLOBAL",
+    NAME: "nodeName",
+  };
+  for (const [from, to] of Object.entries(configMap)) {
+    if (instance[from]) newKlass[to] = instance[from];
   }
 
-  Fez.classes[name] = klass
+  // Handle CSS (can be string or function)
+  if (instance.CSS) {
+    newKlass.css =
+      typeof instance.CSS === "function" ? instance.CSS() : instance.CSS;
+  }
 
-  if (!customElements.get(name)) {
-    customElements.define(name, class extends HTMLElement {
-      connectedCallback() {
-        // Fez.onReady(()=>{connectNode(name, this)})
-        // connectNode(name, this)
-        if (useFastRender(this, klass)) {
-          connectNode(name, this)
-        } else {
-          requestAnimationFrame(()=>{
-            connectNode(name, this)
-          })
-        }
-      }
-    })
+  // Handle HTML (can be string or function)
+  if (instance.HTML) {
+    const html =
+      typeof instance.HTML === "function" ? instance.HTML() : instance.HTML;
+    newKlass.html = closeCustomTags(html);
+  }
+
+  // Handle META (generic metadata object)
+  if (instance.META) {
+    newKlass.META = instance.META;
+    Fez.index.ensure(name).meta = instance.META;
   }
-}
 
-function useFastRender(node, klass) {
-  const fezFast = node.getAttribute('fez-fast')
-  var isFast = typeof klass.FAST === 'function' ? klass.FAST(node) : klass.FAST
-  if (fezFast == 'false') {
-    return false
-  } else {
-    return fezFast || isFast
+  // Auto-mount global components
+  if (instance.GLOBAL) {
+    Fez.onReady(() => document.body.appendChild(document.createElement(name)));
   }
+
+  Fez.consoleLog(`${name} compiled`);
+  return newKlass;
 }
 
 /**
- * Converts self-closing custom tags to full open/close format
- * Required for proper HTML parsing of custom elements
+ * Convert self-closing custom tags to full format
+ * <my-comp /> -> <my-comp></my-comp>
+ * Uses (?:[^>]|=>) to skip => (arrow functions) inside attributes
  */
 function closeCustomTags(html) {
-  const selfClosingTags = new Set([
-    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr'
-  ])
+  return html.replace(
+    /<([a-z][a-z-]*)\b((?:=>|[^>])*)>/g,
+    (match, tag, attrs) => {
+      if (!attrs.trimEnd().endsWith("/")) return match;
+      if (SELF_CLOSING_TAGS.has(tag)) return match;
+      return `<${tag}${attrs.replace(/\s*\/$/, "")}></${tag}>`;
+    },
+  );
+}
+
+/**
+ * Determine if component should render synchronously
+ */
+function shouldRenderFast(node, klass) {
+  const attr = node.getAttribute("fez-fast");
+  if (attr === "false") return false;
 
-  return html.replace(/<([a-z-]+)\b([^>]*)\/>/g, (match, tagName, attributes) => {
-    return selfClosingTags.has(tagName) ? match : `<${tagName}${attributes}></${tagName}>`
-  })
+  const klassFast =
+    typeof klass.FAST === "function" ? klass.FAST(node) : klass.FAST;
+  return !!(attr || klassFast || node.childNodes[0] || node.nextSibling);
 }
 
+// =============================================================================
+// NODE CONNECTION (Instantiation)
+// =============================================================================
+
 /**
- * Initializes a Fez component instance from a DOM node
- * Replaces the custom element with the component's rendered content
+ * Initialize component instance from DOM node
  */
 function connectNode(name, node) {
-  const klass = Fez.classes[name]
-  const parentNode = node.parentNode
+  if (!node.isConnected) return;
+  if (node.classList?.contains("fez")) return;
 
-  if (node.isConnected) {
-    const nodeName = typeof klass.nodeName == 'function' ? klass.nodeName(node) : klass.nodeName
-    const newNode = document.createElement(nodeName || 'div')
+  const klass = Fez.index[name]?.class;
+  const nodeName =
+    typeof klass.nodeName === "function"
+      ? klass.nodeName(node)
+      : klass.nodeName;
+  const newNode = document.createElement(nodeName || "div");
 
-    newNode.classList.add('fez')
-    newNode.classList.add(`fez-${name}`)
+  newNode.classList.add("fez", `fez-${name}`);
 
-    parentNode.replaceChild(newNode, node);
+  if (!node.parentNode) {
+    console.warn(`Fez: ${name} has no parent, skipping`);
+    return;
+  }
 
-    const fez = new klass()
+  // Replace custom element with component node
+  node.parentNode.replaceChild(newNode, node);
 
-    fez.UID = ++Fez.instanceCount
-    Fez.instances.set(fez.UID, fez)
+  // Create instance
+  const fez = new klass();
+  fez.UID = ++Fez.instanceCount;
+  Fez.instances.set(fez.UID, fez);
 
-    fez.oldRoot = node
-    fez.fezName = name
-    fez.root = newNode
-    fez.props = klass.getProps(node, newNode)
-    fez.class = klass
+  fez.oldRoot = node;
+  fez.fezName = name;
+  fez.root = newNode;
+  fez.props = klass.getProps(node, newNode);
+  fez.class = klass;
 
-    // Move child nodes to preserve DOM event listeners
-    fez.slot(node, newNode)
+  // Move children (slot content)
+  fez.fezSlot(node, newNode);
 
-    newNode.fez = fez
+  newNode.fez = fez;
 
-    if (klass.GLOBAL && klass.GLOBAL != true) {
-      window[klass.GLOBAL] = fez
-    }
+  // Global component reference
+  if (klass.GLOBAL && klass.GLOBAL !== true) {
+    window[klass.GLOBAL] ||= fez;
+  }
 
-    if (window.$) {
-      fez.$root = $(newNode)
-    }
+  // jQuery compatibility
+  if (window.$) fez.$root = $(newNode);
 
-    if (fez.props.id) {
-      newNode.setAttribute('id', fez.props.id)
-    }
+  // Copy ID
+  if (fez.props.id) newNode.setAttribute("id", fez.props.id);
+
+  // Copy fez-keep for DOM differ preservation
+  const fezKeep = node.getAttribute("fez-keep");
+  if (fezKeep) newNode.setAttribute("fez-keep", fezKeep);
+
+  // === LIFECYCLE ===
+
+  // Setup reactive state
+  fez.fezRegister();
+
+  // Capture children before rendering replaces them
+  if (fez.root.childNodes.length) {
+    fez._fezSlotNodes = Array.from(fez.root.childNodes);
+    fez._fezChildNodes = fez._fezSlotNodes.filter((n) => n.nodeType === 1);
+  }
+
+  // Prevent state changes during init/mount from scheduling extra renders
+  fez._isInitializing = true;
 
-    // Component lifecycle initialization
-    fez.fezRegister()
+  // Init (supports multiple naming conventions)
+  const initMethod = fez.onInit || fez.init || fez.created || fez.connect;
+  initMethod.call(fez, fez.props);
 
-    // Call initialization method (init, created, or connect)
-    ;(fez.init || fez.created || fez.connect).bind(fez)(fez.props)
+  // Render
+  fez.fezRender();
 
-    // Initial render
-    fez.render()
-    fez.firstRender = true
+  // Done initializing - state changes in onMount will now trigger renders
+  fez._isInitializing = false;
 
-    // Trigger mount lifecycle hook
-    fez.onMount(fez.props)
+  // Mount
+  fez.onMount(fez.props);
 
-    if (fez.onSubmit) {
-      const form = fez.root.nodeName == 'FORM' ? fez.root : fez.find('form')
+  // Form submit handling
+  if (fez.onSubmit) {
+    const form = fez.root.nodeName === "FORM" ? fez.root : fez.find("form");
+    if (form) {
       form.onsubmit = (e) => {
-        e.preventDefault()
-        fez.onSubmit(fez.formData())
-      }
+        e.preventDefault();
+        fez.onSubmit(fez.formData());
+      };
     }
+  }
 
-    // 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)
-      }
+  // Watch for attribute changes
+  if (fez.onPropsChange) {
+    attrObserver.observe(newNode, { attributes: true });
+    for (const [key, value] of Object.entries(fez.props)) {
+      fez.onPropsChange(key, value);
     }
   }
 }