vanillaforge 1.9.0

package/src/core/component-manager.js

@@ -0,0 +1,306 @@
+/**
+ * Component Manager
+ * 
+ * Manages component registration, loading, rendering, and lifecycle.
+ * Handles component registration, instantiation, and lifecycle management.
+ * 
+ * @author VanillaForge Team
+ * @version 1.0.0
+ * @since 2025-06-15
+ */
+
+import { Logger } from '../utils/logger.js';
+import { ErrorHandler } from '../utils/error-handler.js';
+
+export class ComponentManager {
+  constructor(eventBus, logger, errorHandler, options = {}) {
+    this.eventBus = eventBus;
+    this.logger = logger || new Logger('ComponentManager');
+    this.errorHandler = errorHandler || new ErrorHandler();
+
+    // Default container id route components are mounted into. Configurable so
+    // apps and examples aren't locked to a single magic element id.
+    this.mountId = options.mountId || 'main-content';
+
+    this.components = new Map();
+    this.activeComponents = new Map();
+    this.isInitialized = false;
+
+    this.logger.debug('ComponentManager instance created');
+  }
+  /**
+   * Initialize the component manager
+   * 
+   * @returns {Promise<void>}
+   */
+  async init() {
+    try {
+      this.logger.info('Initializing component manager...');
+      
+      // Register built-in components
+      this.registerBuiltInComponents();
+      
+      // Set up event listeners
+      this.setupEventListeners();
+      
+      this.isInitialized = true;
+      this.logger.info('Component manager initialized successfully');
+      
+    } catch (error) {
+      this.logger.error('Failed to initialize component manager', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Alias for init() to maintain compatibility with FrameworkApp
+   */
+  async initialize() {
+    return this.init();
+  }  /**
+   * Register built-in components
+   * 
+   * @private
+   */    
+  registerBuiltInComponents() {
+    this.logger.debug('Registering built-in components...');
+    
+    // Built-in components will be registered externally via app.initialize()
+    // to avoid circular import dependencies
+    
+    this.logger.debug(`Built-in components ready for external registration`);
+  }
+
+  /**
+   * Register a component
+   * 
+   * @param {string} name - Component name
+   * @param {Class} ComponentClass - Component class
+   */
+  registerComponent(name, ComponentClass) {
+    if (this.components.has(name)) {
+      this.logger.warn(`Component ${name} already registered, overwriting`);
+    }
+    
+    this.components.set(name, ComponentClass);
+    this.logger.debug(`Component registered: ${name}`);
+  }  /**
+   * Load and render a component
+   * 
+   * @param {string} componentName - Name of component to load
+   * @param {Object} props - Props to pass to component
+   * @param {string} containerId - ID of container element
+   * @returns {Promise<Object>} Component instance
+   */
+  async loadComponent(componentName, props = {}, containerId = this.mountId) {
+    const ComponentClass = this.components.get(componentName);
+    if (!ComponentClass) {
+      const error = new Error(`Component not registered: ${componentName}`);
+      this.errorHandler.handleError(error);
+      throw error;
+    }
+    return this.loadComponentClass(ComponentClass, props, containerId);
+  }
+
+  /**
+   * Load a component by class directly (for router use)
+   * 
+   * @param {Function} ComponentClass - Component class constructor
+   * @param {Object} props - Component props
+   * @param {string} containerId - Target container ID
+   * @returns {Promise<Object>} Component instance
+   */
+  async loadComponentClass(ComponentClass, props = {}, containerId = this.mountId) {
+    try {
+      const container = document.getElementById(containerId);
+      if (!container) {
+        throw new Error(`Container not found: ${containerId}`);
+      }
+
+      // Unload any component currently mounted in this container so the new
+      // route owns it cleanly (single render path, no leftover listeners).
+      await this.unloadComponentsInContainer(container);
+
+      const instance = new ComponentClass(this.eventBus, props);
+      instance.container = container;
+
+      // Give the instance a reference to the app (for plugin service access)
+      // and a resolver so child() calls can look up components by name.
+      if (this.app) {
+        instance.app = this.app;
+      }
+      instance._resolveComponent = (name) => this.components.get(name);
+
+      // init() performs the single render (auto-render is on by default) and
+      // binds delegated DOM listeners on the component's stable wrapper.
+      await instance.init();
+
+      if (typeof instance.getLifecycle === 'function') {
+        const lifecycle = instance.getLifecycle();
+        if (lifecycle && typeof lifecycle.onMount === 'function') {
+          await lifecycle.onMount.call(instance);
+        }
+      }
+
+      const instanceId = `${instance.name}-${Date.now()}`;
+      this.activeComponents.set(instanceId, instance);
+
+      this.logger.info(`Component loaded successfully: ${instance.name}`);
+      return instance;
+    } catch (error) {
+      this.errorHandler.handleError(error, {
+        componentName: ComponentClass.name,
+        containerId
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Unload every active component currently mounted inside a container.
+   *
+   * @param {HTMLElement} container - Target container element
+   * @private
+   */
+  async unloadComponentsInContainer(container) {
+    for (const [id, instance] of this.activeComponents) {
+      if (instance.container === container) {
+        await this.unloadComponent(id);
+      }
+    }
+  }
+
+  /**
+   * Unload a component
+   * 
+   * @param {string} componentId - Component instance ID
+   * @returns {Promise<boolean>} Success status
+   */
+  async unloadComponent(componentId) {
+    try {
+      const instance = this.activeComponents.get(componentId);
+      
+      if (!instance) {
+        this.logger.warn(`Component instance not found: ${componentId}`);
+        return false;
+      }      // Call lifecycle onUnmount
+      if (instance.getLifecycle && typeof instance.getLifecycle === 'function') {
+        const lifecycle = instance.getLifecycle();
+        if (lifecycle.onUnmount && typeof lifecycle.onUnmount === 'function') {
+          await lifecycle.onUnmount.call(instance);
+        }
+      }
+
+      // Component's own destroy() removes delegated/manual listeners and clears
+      // its container (single source of teardown).
+      if (typeof instance.destroy === 'function') {
+        instance.destroy();
+      }
+
+      // Remove the wrapper element from the DOM
+      if (instance.element) {
+        instance.element.remove();
+      }
+
+      // Remove from active components
+      this.activeComponents.delete(componentId);
+      
+      this.logger.debug(`Component unloaded: ${instance.name}`);
+      return true;
+      
+    } catch (error) {
+      this.logger.error(`Failed to unload component: ${componentId}`, error);
+      return false;
+    }
+  }
+
+
+  /**
+   * Set up event listeners
+   * 
+   * @private
+   */  setupEventListeners() {
+    // Listen for component load requests
+    this.eventBus.on('component:load', async ({ name, props, containerId }) => {
+      try {
+        await this.loadComponent(name, props, containerId);
+      } catch (error) {
+        this.logger.error('Failed to load requested component', error);
+        this.eventBus.emit('component:error', { error, componentName: name });
+      }
+    });    // Listen for router component load requests
+    this.eventBus.on('router:load-component', async ({ component, route, loaderData }) => {
+      try {
+        const props = loaderData !== undefined
+          ? { route, data: loaderData }
+          : { route };
+        if (typeof component === 'string') {
+          // Component name - load by name
+          await this.loadComponent(component, props, this.mountId);
+        } else if (typeof component === 'function') {
+          // Component class - load directly
+          await this.loadComponentClass(component, props, this.mountId);
+        } else {
+          throw new Error(`Invalid component type: ${typeof component}`);
+        }
+        
+        this.logger.info(`Component loaded successfully: ${component.name || component}`);
+      } catch (error) {
+        this.logger.error('Failed to load router component', error);
+        this.eventBus.emit('component:error', { error, componentName: component });
+      }
+    });
+    
+    // Listen for component unload requests
+    this.eventBus.on('component:unload', async ({ componentId }) => {
+      await this.unloadComponent(componentId);
+    });
+  }
+
+  /**
+   * Get active components
+   * 
+   * @returns {Map} Active components
+   */
+  getActiveComponents() {
+    return new Map(this.activeComponents);
+  }
+
+  /**
+   * Get registered components
+   * 
+   * @returns {Array} Component names
+   */
+  getRegisteredComponents() {
+    return Array.from(this.components.keys());
+  }
+
+  /**
+   * Clean up component manager
+   * 
+   * @returns {Promise<void>}
+   */
+  async cleanup() {
+    try {
+      this.logger.info('Cleaning up component manager');
+      
+      // Unload all active components
+      const componentIds = Array.from(this.activeComponents.keys());
+      for (const componentId of componentIds) {
+        await this.unloadComponent(componentId);
+      }
+      
+      // Clear registrations
+      this.components.clear();
+      this.activeComponents.clear();
+      
+      // Reset state
+      this.isInitialized = false;
+      
+      this.logger.info('Component manager cleanup complete');
+      
+    } catch (error) {
+      this.logger.error('Error during component manager cleanup', error);
+    }
+  }
+}

package/src/core/dom-morph.js

@@ -0,0 +1,234 @@
+/**
+ * DOM Morph
+ *
+ * A small, zero-dependency DOM-diffing utility. Given a live element and a new
+ * HTML string, it patches only the parts of the DOM that actually changed
+ * instead of replacing `innerHTML` wholesale. This is what makes VanillaForge
+ * components "reactive" without a virtual DOM:
+ *
+ *  - Unchanged nodes are left untouched (no flicker, no lost scroll position).
+ *  - Focused form fields keep their focus, value, and selection/cursor range.
+ *  - Lists annotated with `data-key` are reconciled by key, so reordering or
+ *    removing an item does not rebuild the whole list.
+ *
+ * Roadmap: fine-grained reactivity (signals) would remove the need to re-render
+ * a component's full template on every change. See README "Roadmap".
+ */
+
+// Elements whose user-facing value lives in DOM properties, not attributes.
+const FORM_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT', 'OPTION']);
+
+// Attributes handled explicitly via syncFormState (never copied blindly).
+const FORM_STATE_ATTRS = new Set(['value', 'checked', 'selected']);
+
+/**
+ * Morph the children of `fromEl` to match `toHtml`.
+ *
+ * `fromEl` itself (the stable wrapper) is preserved — only its contents change.
+ *
+ * @param {HTMLElement} fromEl - Live element to patch in place.
+ * @param {string} toHtml - New HTML for the element's contents.
+ */
+export function morph(fromEl, toHtml) {
+  const template = document.createElement('template');
+  template.innerHTML = typeof toHtml === 'string' ? toHtml : '';
+  morphChildren(fromEl, template.content);
+}
+
+/**
+ * Return a stable key for a node, or null if it has none.
+ * @private
+ */
+function nodeKey(node) {
+  if (node.nodeType === Node.ELEMENT_NODE && node.hasAttribute('data-key')) {
+    return node.getAttribute('data-key');
+  }
+  return null;
+}
+
+/**
+ * Whether two nodes are "the same" for morphing purposes (can be patched in
+ * place rather than replaced).
+ * @private
+ */
+function isSameNode(a, b) {
+  if (a.nodeType !== b.nodeType) return false;
+  if (a.nodeType === Node.ELEMENT_NODE) {
+    return a.tagName === b.tagName && nodeKey(a) === nodeKey(b);
+  }
+  return true; // text / comment nodes
+}
+
+/**
+ * Reconcile the child nodes of `oldParent` to match `newParent`.
+ * Handles keyed reuse (and moves) plus positional matching for unkeyed nodes.
+ * @private
+ */
+function morphChildren(oldParent, newParent) {
+  const newNodes = Array.from(newParent.childNodes);
+  const oldNodes = Array.from(oldParent.childNodes);
+
+  // Index keyed old nodes so they can be reused even if they moved.
+  const keyedOld = new Map();
+  for (const node of oldNodes) {
+    const key = nodeKey(node);
+    if (key != null) keyedOld.set(key, node);
+  }
+
+  const used = new Set();
+  let cursor = 0; // pointer into oldNodes for positional (unkeyed) matching
+
+  for (let i = 0; i < newNodes.length; i++) {
+    const newNode = newNodes[i];
+    const key = nodeKey(newNode);
+    let reuse = null;
+
+    if (key != null && keyedOld.has(key)) {
+      // Keyed reuse: same logical item, possibly moved.
+      reuse = keyedOld.get(key);
+      keyedOld.delete(key);
+      used.add(reuse);
+    } else {
+      // Positional reuse: first compatible, unused, unkeyed old node.
+      while (cursor < oldNodes.length) {
+        const candidate = oldNodes[cursor++];
+        if (used.has(candidate)) continue;
+        if (nodeKey(candidate) != null) continue; // keyed nodes only reused by key
+        if (isSameNode(candidate, newNode)) {
+          reuse = candidate;
+          used.add(candidate);
+        }
+        break;
+      }
+    }
+
+    const slot = oldParent.childNodes[i] || null;
+    if (reuse) {
+      morphNode(reuse, newNode);
+      if (slot !== reuse) oldParent.insertBefore(reuse, slot);
+    } else {
+      oldParent.insertBefore(newNode.cloneNode(true), slot);
+    }
+  }
+
+  // Drop any leftover old nodes that were pushed past the new length.
+  while (oldParent.childNodes.length > newNodes.length) {
+    oldParent.removeChild(oldParent.lastChild);
+  }
+}
+
+/**
+ * Patch a single node (and recurse into element children).
+ * @private
+ */
+function morphNode(oldNode, newNode) {
+  if (oldNode.nodeType === Node.TEXT_NODE || oldNode.nodeType === Node.COMMENT_NODE) {
+    if (oldNode.nodeValue !== newNode.nodeValue) {
+      oldNode.nodeValue = newNode.nodeValue;
+    }
+    return;
+  }
+
+  if (oldNode.nodeType !== Node.ELEMENT_NODE) return;
+
+  morphAttributes(oldNode, newNode);
+
+  // Child-component host elements are opaque boundaries: the mounted child owns
+  // its inner DOM. We update the host's own attributes (including data-key so
+  // identity is tracked) but never recurse into its children. The composition
+  // system in BaseComponent.reconcileChildren() takes care of updates.
+  if (oldNode.hasAttribute('data-vf-host')) return;
+
+  if (FORM_TAGS.has(oldNode.tagName)) {
+    syncFormState(oldNode, newNode);
+  }
+
+  // A textarea's value is its text content; syncFormState already handled it,
+  // so don't let morphChildren clobber the live value while the user types.
+  if (oldNode.tagName !== 'TEXTAREA') {
+    morphChildren(oldNode, newNode);
+  }
+}
+
+/**
+ * Copy attributes from `newEl` onto `oldEl`, adding/updating/removing as needed.
+ * Form-state attributes are skipped here and owned by syncFormState.
+ * @private
+ */
+function morphAttributes(oldEl, newEl) {
+  const isForm = FORM_TAGS.has(oldEl.tagName);
+
+  for (const attr of Array.from(newEl.attributes)) {
+    if (isForm && FORM_STATE_ATTRS.has(attr.name)) continue;
+    if (oldEl.getAttribute(attr.name) !== attr.value) {
+      oldEl.setAttribute(attr.name, attr.value);
+    }
+  }
+
+  for (const attr of Array.from(oldEl.attributes)) {
+    if (isForm && FORM_STATE_ATTRS.has(attr.name)) continue;
+    if (!newEl.hasAttribute(attr.name)) {
+      oldEl.removeAttribute(attr.name);
+    }
+  }
+}
+
+/**
+ * Synchronise a form field's live value/checked state with the new template,
+ * preserving the caret/selection of a focused text field so typing is not
+ * interrupted by a re-render.
+ * @private
+ */
+function syncFormState(oldEl, newEl) {
+  const isActive = oldEl.ownerDocument.activeElement === oldEl;
+
+  switch (oldEl.tagName) {
+    case 'INPUT': {
+      const type = (newEl.getAttribute('type') || 'text').toLowerCase();
+      if (type === 'checkbox' || type === 'radio') {
+        const next = newEl.hasAttribute('checked');
+        if (oldEl.checked !== next) oldEl.checked = next;
+      } else {
+        setValuePreservingCaret(oldEl, newEl.getAttribute('value') ?? '', isActive);
+      }
+      break;
+    }
+    case 'TEXTAREA': {
+      setValuePreservingCaret(oldEl, newEl.textContent ?? '', isActive);
+      break;
+    }
+    case 'SELECT': {
+      // Option `selected` attributes are reconciled by morphChildren; mirror the
+      // resulting value onto the live property.
+      const next = newEl.value;
+      if (next != null && oldEl.value !== next) oldEl.value = next;
+      break;
+    }
+    case 'OPTION': {
+      const next = newEl.hasAttribute('selected');
+      if (oldEl.selected !== next) oldEl.selected = next;
+      break;
+    }
+  }
+}
+
+/**
+ * Set an input/textarea value, restoring the selection range when the element
+ * is focused so the user's caret position survives the update.
+ * @private
+ */
+function setValuePreservingCaret(el, value, isActive) {
+  if (el.value === value) return;
+  if (isActive && typeof el.selectionStart === 'number') {
+    const start = el.selectionStart;
+    const end = el.selectionEnd;
+    el.value = value;
+    try {
+      el.setSelectionRange(Math.min(start, value.length), Math.min(end, value.length));
+    } catch {
+      /* selection not supported for this input type */
+    }
+  } else {
+    el.value = value;
+  }
+}