@dinoreic/fez 0.4.1 → 0.5.2

package/src/fez/root.js

@@ -1,256 +1,326 @@
-// runtime scss
-import Gobber from './vendor/gobber.js'
-
-// morph dom from one state to another
-import { Idiomorph } from './vendor/idiomorph.js'
-
-import objectDump from './utils/dump.js'
-import highlightAll from './utils/highlight_all.js'
-import connect from './connect.js'
-import compile from './compile.js'
-import state from './lib/global-state.js'
-
-// Fez('ui-slider')                             # first slider
-// Fez('ui-slider', (n)=>alert(n))              # find all and execute
-// Fez(this, 'ui-slider')                       # first parent ui-slider
-// Fez('ui-slider', class { init() { ... }}) # create Fez dom node
+/**
+ * Fez - Main Framework Object
+ *
+ * This file contains:
+ * - Main Fez function (component registration and lookup)
+ * - Component registry
+ * - CSS utilities
+ * - Pub/Sub system
+ * - DOM morphing
+ * - Error handling
+ * - Temporary store
+ *
+ * For component instance methods, see instance.js
+ */
+
+// =============================================================================
+// IMPORTS
+// =============================================================================
+
+import Gobber from "./vendor/gobber.js";
+import { fezMorph } from "./morph.js";
+import objectDump from "./utils/dump.js";
+import highlightAll from "./utils/highlight_all.js";
+import connect from "./connect.js";
+import compile from "./compile.js";
+import state from "./lib/global-state.js";
+import createTemplate from "./lib/template.js";
+import { subscribe, publish } from "./lib/pubsub.js";
+import fezLocalStorage from "./lib/localstorage.js";
+import fezAwait from "./lib/await-helper.js";
+import index from "./lib/index.js";
+
+// =============================================================================
+// MAIN FEZ FUNCTION
+// =============================================================================
+
+/**
+ * Main Fez function - register or find components
+ *
+ * @example
+ * Fez('ui-foo', class { ... })  // Register component
+ * Fez('ui-foo')                  // Find first instance
+ * Fez(123)                       // Find by UID
+ * Fez(domNode)                   // Find from DOM node
+ * Fez('ui-foo', fn)              // Find all & execute callback
+ *
+ * @param {string|number|Node} name - Component name, UID, or DOM node
+ * @param {Class|Function} [klass] - Component class or callback
+ * @returns {FezBase|Array|void}
+ */
 const Fez = (name, klass) => {
-  if(typeof name === 'number') {
-    const fez = Fez.instances.get(name)
-    if (fez) {
-      return fez
-    } else {
-      Fez.error(`Instance with UID "${name}" not found.`)
-    }
+  // Find by UID
+  if (typeof name === "number") {
+    const fez = Fez.instances.get(name);
+    if (fez) return fez;
+    Fez.onError("lookup", `Instance with UID "${name}" not found. Component may have been destroyed or never created.`, { uid: name });
+    return;
   }
-  else if (name) {
-    if (klass) {
-      const isPureFn = typeof klass === 'function' && !/^\s*class/.test(klass.toString()) && !/\b(this|new)\b/.test(klass.toString())
-
-      if (isPureFn) {
-        const list = Array
-          .from(document.querySelectorAll(`.fez.fez-${name}`))
-          .filter( n => n.fez )
-
-        list.forEach( el => klass(el.fez) )
-        return list
-      } else if (typeof klass != 'function') {
-        return Fez.find(name, klass)
-      } else {
-        return connect(name, klass)
-      }
-    } else {
-      const node = name.nodeName ? name.closest('.fez') : (
-        document.querySelector( name.includes('#') ? name : `.fez.fez-${name}` )
-      )
-      if (node) {
-        if (node.fez) {
-          return node.fez
-        } else {
-          Fez.error(`node "${name}" has no Fez attached.`)
-        }
-      } else {
-        Fez.error(`node "${name}" not found.`)
-      }
-    }
-  } else {
-    Fez.error('Fez() ?')
+
+  if (!name) {
+    Fez.onError("lookup", "Fez() called without arguments. Expected component name, UID, or DOM node.");
+    return;
   }
-}
 
-Fez.classes = {}
-Fez.instanceCount = 0
-Fez.instances = new Map()
+  // With second argument
+  if (klass) {
+    const isPureFn =
+      typeof klass === "function" &&
+      !/^\s*class/.test(klass.toString()) &&
+      !/\b(this|new)\b/.test(klass.toString());
+
+    // Fez('name', callback) - find all & execute
+    if (isPureFn) {
+      const list = Array.from(
+        document.querySelectorAll(`.fez.fez-${name}`),
+      ).filter((n) => n.fez);
+      list.forEach((el) => klass(el.fez));
+      return list;
+    }
 
-Fez.find = (onode, name) => {
-  let node = onode
+    // Fez('name', selector) - find with context
+    if (typeof klass !== "function") {
+      return Fez.find(name, klass);
+    }
 
-  if (typeof node == 'string') {
-    node = document.body.querySelector(node)
+    // Fez('name', class) - register component
+    return connect(name, klass);
   }
 
-  if (typeof node.val == 'function') {
-    node = node[0]
-  }
+  // Find instance by name or node
+  const node = name.nodeName
+    ? name.closest(".fez")
+    : document.querySelector(name.includes("#") ? name : `.fez.fez-${name}`);
 
-  const klass = name ? `.fez.fez-${name}` : '.fez'
+  if (!node) {
+    Fez.onError("lookup", `Component "${name}" not found in DOM. Ensure the component is defined and rendered.`, { componentName: name });
+    return;
+  }
 
-  const closestNode = node.closest(klass)
-  if (closestNode && closestNode.fez) {
-    return closestNode.fez
-  } else {
-    console.error('Fez node connector not found', onode, node)
+  if (!node.fez) {
+    Fez.onError("lookup", `DOM node "${name}" exists but has no Fez instance attached. Component may not be initialized yet.`, { node, tagName: name });
+    return;
   }
-}
 
-Fez.cssClass = (text) => {
-  return Gobber.css(text)
-}
+  return node.fez;
+};
 
-Fez.globalCss = (cssClass, opts = {}) => {
-  if (typeof cssClass === 'function') {
-    cssClass = cssClass()
-  }
+// =============================================================================
+// COMPONENT REGISTRY
+// =============================================================================
 
-  if (cssClass.includes(':')) {
-    let text = cssClass
-      .split("\n")
-      .filter(line => !(/^\s*\/\//.test(line)))
-      .join("\n")
+/** Unified component index - Fez.index['name'] = { class, meta, demo, info, source } */
+Fez.index = index;
 
-    if (opts.wrap) {
-      text = `:fez { ${text} }`
-    }
+/** Counter for unique instance IDs */
+Fez.instanceCount = 0;
 
-    text = text.replace(/\:fez|\:host/, `.fez.fez-${opts.name}`)
+/** Active component instances by UID */
+Fez.instances = new Map();
 
-    cssClass = Fez.cssClass(text)
-  }
+/**
+ * Find a component instance from a DOM node
+ * @param {Node|string} onode - DOM node or selector
+ * @param {string} [name] - Optional component name filter
+ * @returns {FezBase|undefined}
+ */
+Fez.find = (onode, name) => {
+  let node =
+    typeof onode === "string" ? document.body.querySelector(onode) : onode;
 
-  Fez.onReady(() => {
-    document.body.parentElement.classList.add(cssClass)
-  })
+  // jQuery compatibility
+  if (typeof node.val === "function") node = node[0];
 
-  return cssClass
-}
+  const selector = name ? `.fez.fez-${name}` : ".fez";
+  const closestNode = node.closest(selector);
 
-Fez.info = () => {
-  console.log('Fez components:', Object.keys(Fez.classes || {}))
-}
+  if (closestNode?.fez) return closestNode.fez;
 
-Fez.morphdom = (target, newNode, opts = {}) => {
-  Array.from(target.attributes).forEach(attr => {
-    newNode.setAttribute(attr.name, attr.value)
-  })
+  Fez.onError("find", `Node connector not found. Selector: "${selector}", node: ${onode}`, {
+    original: onode,
+    resolved: node,
+    selector,
+  });
+};
 
-  Idiomorph.morph(target, newNode, {
-    morphStyle: 'outerHTML'
-  })
+// =============================================================================
+// CSS UTILITIES
+// =============================================================================
 
-  // remove whitespace on next node, if exists (you never want this)
-  const nextSibling = target.nextSibling
-  if (nextSibling?.nodeType === Node.TEXT_NODE && nextSibling.textContent.trim() === '') {
-    nextSibling.remove();
-  }
-}
-
-Fez._globalSubs ||= new Map()
-
-Fez.publish = (channel, ...args) => {
-  Fez._subs ||= {}
-  Fez._subs[channel] ||= []
-  Fez._subs[channel].forEach((el) => {
-    el[1].bind(el[0])(...args)
-  })
-
-  // Trigger global subscriptions
-  const subs = Fez._globalSubs.get(channel)
-  if (subs) {
-    subs.forEach((sub) => {
-      if (sub.node.isConnected) {
-        sub.callback.call(sub.node, ...args)
-      } else {
-        // Remove disconnected nodes from subscriptions
-        subs.delete(sub)
-      }
-    })
-  }
-}
-
-Fez.subscribe = (node, eventName, callback) => {
-  // If second arg is function, shift arguments
-  if (typeof eventName === 'function') {
-    callback = eventName
-    eventName = node
-    node = document.body
+/**
+ * Generate unique CSS class from CSS text (via Goober)
+ * @param {string} text - CSS rules
+ * @returns {string} Generated class name
+ */
+Fez.cssClass = (text) => {
+  // In test environments without proper DOM, goober may fail
+  // Return a placeholder class name based on hash
+  try {
+    return Gobber.css(text);
+  } catch {
+    // Fallback: generate simple hash-based class name
+    let hash = 0;
+    for (let i = 0; i < text.length; i++) {
+      hash = ((hash << 5) - hash + text.charCodeAt(i)) | 0;
+    }
+    return "fez-" + Math.abs(hash).toString(36);
   }
+};
 
-  // Handle string selectors
-  if (typeof node === 'string') {
-    node = document.querySelector(node)
-  }
+/**
+ * Register global CSS styles
+ * @param {string|Function} cssClass - CSS text or function
+ * @param {Object} opts - { name, wrap }
+ * @returns {string} Generated class name
+ */
+Fez.globalCss = (cssClass, opts = {}) => {
+  if (typeof cssClass === "function") cssClass = cssClass();
 
-  if (!Fez._globalSubs.has(eventName)) {
-    Fez._globalSubs.set(eventName, new Set())
+  if (cssClass.includes(":")) {
+    let text = cssClass
+      .split("\n")
+      .filter((line) => !/^\s*\/\//.test(line))
+      .join("\n");
+
+    if (opts.wrap) text = `:fez { ${text} }`;
+    text = text.replace(/\:fez|\:host/, `.fez.fez-${opts.name}`);
+    cssClass = Fez.cssClass(text);
   }
 
-  const subs = Fez._globalSubs.get(eventName)
+  Fez.onReady(() => document.body.parentElement.classList.add(cssClass));
+  return cssClass;
+};
+
+// =============================================================================
+// DOM MORPHING
+// =============================================================================
+
+/**
+ * Morph DOM node to new state (via fez-morph)
+ * Child fez components are automatically preserved (skipped from morphing)
+ * Use fez-keep attribute for explicit element preservation
+ * @param {Element} target - Element to morph
+ * @param {Element} newNode - New state
+ */
+Fez.morphdom = (target, newNode) => {
+  fezMorph(target, newNode, {
+    // Preserve child fez components - skip morphing them entirely
+    skipNode: (oldNode) => {
+      if (
+        oldNode.classList?.contains("fez") &&
+        oldNode.fez &&
+        !oldNode.fez._destroyed
+      ) {
+        if (Fez.LOG) {
+          console.log(
+            `Fez: preserved child component ${oldNode.fez.fezName} (UID ${oldNode.fez.UID})`,
+          );
+        }
+        return true;
+      }
+      return false;
+    },
 
-  // Remove existing subscription for same node and callback
-  subs.forEach(sub => {
-    if (sub.node === node && sub.callback === callback) {
-      subs.delete(sub)
-    }
-  })
+    // Cleanup destroyed fez components
+    beforeRemove: (node) => {
+      if (node.classList?.contains("fez") && node.fez) {
+        node.fez.fezOnDestroy();
+      }
+    },
+  });
+};
 
-  const subscription = { node, callback }
-  subs.add(subscription)
+// =============================================================================
+// PUB/SUB SYSTEM (see lib/pubsub.js)
+// =============================================================================
 
-  // Return unsubscribe function
-  return () => {
-    subs.delete(subscription)
-  }
-}
+Fez.subscribe = subscribe;
+Fez.publish = publish;
 
-Fez.error = (text, show) => {
-  text = `Fez: ${text}`
-  console.error(text)
+// =============================================================================
+// LOCAL STORAGE (see lib/localstorage.js)
+// =============================================================================
+
+Fez.localStorage = fezLocalStorage;
+
+// =============================================================================
+// ASYNC AWAIT HELPER (see lib/await-helper.js)
+// =============================================================================
+
+Fez.fezAwait = fezAwait;
+
+// =============================================================================
+// ERROR HANDLING & LOGGING
+// =============================================================================
+
+Fez.consoleError = (text, show) => {
+  text = `Fez: ${text}`;
+  console.error(text);
   if (show) {
-    return `<span style="border: 1px solid red; font-size: 14px; padding: 3px 7px; background: #fee; border-radius: 4px;">${text}</span>`
+    return `<span style="border: 1px solid red; font-size: 14px; padding: 3px 7px; background: #fee; border-radius: 4px;">${text}</span>`;
   }
-}
+};
 
-Fez.log = (text) => {
-  if (Fez.LOG === true) {
-    text = String(text).substring(0, 180)
-    console.log(`Fez: ${text}`)
+Fez.consoleLog = (text) => {
+  if (Fez.LOG) {
+    console.log(`Fez: ${String(text).substring(0, 180)}`);
   }
-}
+};
 
-Fez.onError = (kind, message) => {
-  // Ensure kind is always a string
-  if (typeof kind !== 'string') {
-    throw new Error('Fez.onError: kind must be a string');
+/**
+ * Enhanced error handler with component context
+ * @param {string} kind - Error category (e.g., 'template', 'lifecycle', 'morph')
+ * @param {string|Error} message - Error message or Error object
+ * @param {Object} [context] - Additional context (component name, props, etc.)
+ * @returns {string} Formatted error message
+ */
+Fez.onError = (kind, message, context) => {
+  // Extract component name from context or message
+  let componentName = context?.componentName || context?.name;
+
+  // Try to extract component name from message if not in context
+  if (!componentName && typeof message === "string") {
+    const match = message.match(/<([^>]+)>/);
+    if (match) componentName = match[1];
   }
 
-  console.error(`${kind}: ${message.toString()}`);
-}
+  // Format the error message with component context
+  const prefix = componentName ? ` [${componentName}]` : "";
+  const errorMsg =
+    typeof message === "string" ? message : message?.message || String(message);
+  const fullMessage = `Fez ${kind}:${prefix} ${errorMsg}`;
 
-// work with tmp store
-Fez.store = {
-  store: new Map(),
-  counter: 0,
-
-  set(value) {
-    const key = this.counter++;
-    this.store.set(key, value);
-    return key;
-  },
-
-  get(key) {
-    return this.store.get(key);
-  },
+  // Log with context if available
+  if (context && Fez.LOG) {
+    console.error(fullMessage, context);
+  } else {
+    console.error(fullMessage);
+  }
 
-  delete(key) {
-    const value = this.store.get(key);
-    this.store.delete(key)
-    return value;
+  // Include stack trace for Error objects
+  if (message instanceof Error && message.stack && Fez.LOG) {
+    console.error(message.stack);
   }
+
+  return fullMessage;
 };
 
-// Load utility functions
-import addUtilities from './utility.js'
-import cssMixin from './utils/css_mixin.js'
-addUtilities(Fez)
-cssMixin(Fez)
+// =============================================================================
+// LOAD UTILITIES & EXPORTS
+// =============================================================================
+
+import addUtilities from "./utility.js";
+import cssMixin from "./utils/css_mixin.js";
+
+addUtilities(Fez);
+cssMixin(Fez);
 
-Fez.compile = compile
-Fez.state = state
-Fez.dump = objectDump
-Fez.highlightAll = highlightAll
+Fez.compile = compile;
+Fez.createTemplate = createTemplate;
+Fez.state = state;
+Fez.log = objectDump;
+Fez.highlightAll = highlightAll;
 
-Fez.onReady(() => {
-  Fez.log('Fez.LOG === true, logging enabled.')
-})
+Fez.onReady(() => Fez.consoleLog("Fez.LOG === true, logging enabled."));
 
-export default Fez
+export default Fez;