@zolomedia/bifrost-client 1.7.74

package/L3_Abstraction/orchestrator/metadata_processor.js

@@ -0,0 +1,249 @@
+/**
+ * L3_Abstraction/orchestrator/metadata_processor.js
+ * 
+ * Metadata Processing for Declarative Rendering
+ * 
+ * Handles extraction and application of metadata from YAML data:
+ * - _zClass: CSS classes
+ * - _zStyle: Inline styles
+ * - _zHTML: Element type (div, section, article, etc.)
+ * - _zId / zId: Element ID
+ * - _zGroup: Grouped rendering context
+ * - _zGroupLabel: Label for input groups
+ * - _zScripts: Client-side scripts
+ * 
+ * Extracted from zdisplay_orchestrator.js (Phase 4.4a)
+ *
+ * ════════════════════════════════════════════════════════════════════════════
+ *  _zClass / _zStyle CONTRACT — SINGLE SOURCE OF TRUTH (do not re-implement)
+ * ════════════════════════════════════════════════════════════════════════════
+ *  applyMetadata() is the ONE place _zClass/_zStyle are read and applied across
+ *  all three tiers. Renderers must NOT hand-roll className/style parsing.
+ *
+ *  THREE TIERS, ONE FUNCTION:
+ *   • zBlock — renderBlock / renderChunkProgressive call applyMetadata (overwrite).
+ *   • zKey   — createContainer calls applyMetadata (overwrite).
+ *   • zEvent — renderZDisplayEvent runs a single APPEND-mode applyMetadata pass on
+ *              the returned element AFTER the switch. Leaf renderers own only their
+ *              CONTEXTUAL class (color → zText- / zBtn- / zSignal- variants); they
+ *              do NOT touch _zClass or _zStyle.
+ *
+ *  CLASS MODES:
+ *   • overwrite (default): _zClass OWNS className — for freshly-created wrappers.
+ *   • append (options.append): _zClass LAYERS via classList.add — for event nodes
+ *     that already carry intrinsic classes (zText, bi-*, zTable…). Dedupes.
+ *
+ *  _zStyle: MERGES onto any existing inline style (indent margin, media max-width),
+ *  never clobbers it. It is an additive escape hatch.
+ *
+ *  COMPOSITE OPT-OUT (`element.__zMetaScoped = true`):
+ *   A renderer that returns a WRAPPER but places _zClass on an INNER node sets
+ *   __zMetaScoped on the wrapper so the central event pass skips it (no mis-target,
+ *   no double-apply). Current composites: media-with-caption (<figure> → inner
+ *   <img>/<video>/<audio>) and zTable (.zTable-container → inner <table>).
+ *   Cases that return null (zDash, in-place table replace) skip the pass entirely
+ *   and therefore keep their own _zClass handling.
+ * ════════════════════════════════════════════════════════════════════════════
+ */
+
+// Layer 0: Primitives
+import { createSemanticElement } from '../../L2_Handling/display/primitives/semantic_element_primitive.js';
+import { convertStyleToString } from '../../zSys/dom/style_utils.js';
+
+/**
+ * MetadataProcessor - Extracts and applies metadata to DOM elements
+ */
+export class MetadataProcessor {
+  constructor(logger) {
+    this.logger = logger;
+    
+    // Define metadata keys that should be skipped during iteration
+    this.METADATA_KEYS = [
+      '_zClass',
+      '_zStyle',
+      '_zHTML',
+      '_zId',
+      'zScripts',
+      '_zScripts',
+      '_zGroup',
+      '_zGroupLabel',
+      'zId'
+    ];
+  }
+
+  /**
+   * Extract metadata from data object (underscore-prefixed keys)
+   * @param {Object} data - YAML data object
+   * @returns {Object} Metadata object with extracted keys
+   */
+  extractMetadata(data) {
+    const metadata = {};
+    
+    if (!data || typeof data !== 'object') {
+      return metadata;
+    }
+
+    for (const [key, value] of Object.entries(data)) {
+      if (key.startsWith('_') || key === 'zId') {
+        metadata[key] = value;
+      }
+    }
+
+    return metadata;
+  }
+
+  /**
+   * Check if a key is a metadata key (should be skipped during iteration)
+   * @param {string} key - Key to check
+   * @returns {boolean} True if key is metadata
+   */
+  isMetadataKey(key) {
+    return this.METADATA_KEYS.includes(key) || key.startsWith('~');
+  }
+
+  /**
+   * Create a container element with metadata applied
+   * @param {string} zKey - Key for data-zkey attribute
+   * @param {Object} metadata - Metadata object
+   * @param {Object} logger - Logger instance
+   * @returns {HTMLElement} Container element with metadata applied
+   */
+  createContainer(zKey, metadata, logger = this.logger) {
+    // Use centralized semantic element primitive (SSOT for _zHTML)
+    const elementType = metadata._zHTML || 'div';
+    const container = createSemanticElement(elementType, {}, logger);
+
+    // Apply metadata
+    this.applyMetadata(container, metadata, zKey, logger);
+
+    // Add form submit logging for debugging
+    if (container.tagName.toLowerCase() === 'form') {
+      container.addEventListener('submit', (event) => {
+        logger.log(`[MetadataProcessor] Form submitted: ${zKey}`);
+        logger.log('[MetadataProcessor] Form data:', new FormData(container));
+        logger.log('[MetadataProcessor] Form validity:', container.checkValidity());
+      });
+    }
+
+    return container;
+  }
+
+  /**
+   * Normalize a _zClass value (string with comma/space separators, or array)
+   * into a clean array of class tokens. SSOT for the "how do I read _zClass"
+   * question that every tier (block / key / event) used to answer differently.
+   * @param {string|Array} zClass
+   * @returns {string[]}
+   */
+  normalizeClasses(zClass) {
+    if (!zClass) return [];
+    const parts = Array.isArray(zClass)
+      ? zClass
+      : (zClass.includes(',') ? zClass.split(',') : zClass.split(' '));
+    return parts.map(c => String(c).trim()).filter(Boolean);
+  }
+
+  /**
+   * Apply metadata to an existing element.
+   *
+   * Two class modes:
+   *  - overwrite (default): _zClass OWNS className — used by zBlock/zKey wrappers
+   *    that are freshly created and have no intrinsic classes.
+   *  - append (options.append): _zClass LAYERS on top via classList.add — used by
+   *    zEvent elements that already carry renderer-intrinsic classes (zText,
+   *    bi-*, zTable …) which must survive. Empty/absent _zClass is a no-op.
+   *
+   * @param {HTMLElement} element - Element to apply metadata to
+   * @param {Object} metadata - Metadata object (_zClass, _zStyle, zId)
+   * @param {string} [zKey] - Optional key for data-zkey attribute
+   * @param {Object} [logger] - Optional logger instance
+   * @param {Object} [options] - { append?: boolean }
+   */
+  applyMetadata(element, metadata, zKey = null, logger = this.logger, options = {}) {
+    const append = options.append === true;
+
+    // Apply custom classes
+    if (append) {
+      // Event tier: layer on top of intrinsic classes, never clear.
+      const extra = this.normalizeClasses(metadata._zClass);
+      if (extra.length) element.classList.add(...extra);
+    } else if (metadata._zClass !== undefined) {
+      if (metadata._zClass === '' || metadata._zClass === null) {
+        // Empty string or null = no container classes
+        element.className = '';
+      } else {
+        element.className = this.normalizeClasses(metadata._zClass).join(' ');
+      }
+    } else if (!element.className) {
+      // Default: NO classes (bare element, following HTML/CSS convention)
+      element.className = '';
+    }
+
+    // Apply inline styles if provided (supports string or nested object).
+    // MERGE onto any existing inline style (e.g. a renderer's indent margin or a
+    // media element's max-width) instead of clobbering it — _zStyle is an additive
+    // escape hatch, not a replacement for intrinsic layout styles.
+    if (metadata._zStyle !== undefined && metadata._zStyle !== '' && metadata._zStyle !== null) {
+      const cssString = convertStyleToString(metadata._zStyle, logger);
+      if (cssString) {
+        const existing = (element.getAttribute('style') || '').trim();
+        if (existing) {
+          const sep = existing.endsWith(';') ? ' ' : '; ';
+          element.setAttribute('style', existing + sep + cssString);
+        } else {
+          element.setAttribute('style', cssString);
+        }
+      }
+    }
+
+    // Apply custom ID if provided (no underscore = passed to both Bifrost & Terminal)
+    if (metadata.zId !== undefined && metadata.zId !== '' && metadata.zId !== null) {
+      element.setAttribute('id', metadata.zId);
+    }
+
+    // Add data attribute for debugging/testing
+    if (zKey) {
+      element.setAttribute('data-zkey', zKey);
+    }
+  }
+
+  /**
+   * Apply classes to an element (helper for adding classes without replacing)
+   * @param {HTMLElement} element - Element to add classes to
+   * @param {string|Array} classes - Classes to add (string or array)
+   */
+  applyClasses(element, classes) {
+    if (!classes) return;
+
+    if (Array.isArray(classes)) {
+      element.classList.add(...classes.filter(c => c.trim()));
+    } else if (typeof classes === 'string') {
+      const classList = classes.includes(',')
+        ? classes.split(',').map(c => c.trim())
+        : classes.split(' ').filter(c => c.trim());
+      element.classList.add(...classList);
+    }
+  }
+
+  /**
+   * Check if data has block-level metadata
+   * @param {Object} data - Data object to check
+   * @returns {boolean} True if data has metadata keys
+   */
+  hasBlockMetadata(data) {
+    if (!data || typeof data !== 'object') {
+      return false;
+    }
+    return Object.keys(data).some(k => k.startsWith('_'));
+  }
+
+  /**
+   * Detect if metadata indicates input-group context
+   * @param {Object} metadata - Metadata object
+   * @returns {boolean} True if input-group context
+   */
+  isInputGroupContext(metadata) {
+    return metadata._zGroup === 'input-group' ||
+           (metadata._zClass && metadata._zClass.includes('zInputGroup'));
+  }
+}

package/L3_Abstraction/orchestrator/navbar_builder.js

@@ -0,0 +1,201 @@
+/**
+ * L3_Abstraction/orchestrator/navbar_builder.js
+ * 
+ * NavBar Building and Rendering
+ * 
+ * Handles navigation bar construction for both:
+ * - Meta NavBar (from zSession config, rendered in <zNavBar> element)
+ * - Content NavBar (from ~zNavBar* metadata in YAML content)
+ * 
+ * Delegates actual rendering to NavigationRenderer (L2).
+ * 
+ * Extracted from zdisplay_orchestrator.js (Phase 4.3)
+ */
+
+/**
+ * NavBarBuilder - Constructs and renders navigation bars
+ */
+export class NavBarBuilder {
+  constructor(client, logger) {
+    this.client = client;
+    this.logger = logger;
+  }
+
+  /**
+   * 3A: Wire event delegation onto a server-built navbar element.
+   *
+   * Python emits data-nav-action="navigate|dropdown-toggle|hamburger" so the
+   * client needs zero construction logic — only generic interaction handling.
+   *
+   * @param {HTMLElement} navEl - The <nav> element injected from nav_html
+   * @param {Object} client    - BifrostClient (for navigationManager access)
+   * @param {Object} logger    - Logger instance
+   */
+  static wireNavBarEvents(navEl, client, logger) {
+    if (!navEl) return;
+
+    // ── Hamburger (mobile toggle) ────────────────────────────────────
+    const toggler = navEl.querySelector('[data-nav-action="hamburger"]');
+    if (toggler) {
+      const targetId = toggler.dataset.navTarget;
+      const collapse = navEl.querySelector(`#${targetId}`);
+      toggler.addEventListener('click', (e) => {
+        e.preventDefault();
+        const expanded = toggler.getAttribute('aria-expanded') === 'true';
+        toggler.setAttribute('aria-expanded', String(!expanded));
+        collapse?.classList.toggle('show', !expanded);
+        collapse?.classList.toggle('zShow', !expanded);
+      });
+    }
+
+    // ── Dropdown toggles ─────────────────────────────────────────────
+    navEl.querySelectorAll('[data-nav-action="dropdown-toggle"]').forEach(toggle => {
+      const menu = toggle.nextElementSibling;
+      toggle.addEventListener('click', (e) => {
+        e.preventDefault();
+        const isOpen = menu?.classList.contains('zShow');
+
+        // Second click on an already-open dropdown → navigate to the parent page
+        if (isOpen) {
+          const href = toggle.getAttribute('href') || toggle.dataset.navHref;
+          if (href && href !== '#') {
+            menu.classList.remove('zShow');
+            toggle.setAttribute('aria-expanded', 'false');
+            if (client?.navigationManager) {
+              // navbar:true → server RESETs the crumb trail (SSOT with zCLI:
+              // a navbar pick becomes the new root). Browser Back/popstate does
+              // NOT pass this, so it still pops the stack normally.
+              client.navigationManager.navigateToRoute(href, { navbar: true });
+            } else {
+              window.location.href = href;
+            }
+          }
+          return;
+        }
+
+        // Close all sibling dropdowns
+        navEl.querySelectorAll('.zDropdown-menu.zShow').forEach(m => {
+          if (m !== menu) {
+            m.classList.remove('zShow');
+            m.previousElementSibling?.setAttribute('aria-expanded', 'false');
+          }
+        });
+        menu?.classList.toggle('zShow', !isOpen);
+        toggle.setAttribute('aria-expanded', String(!isOpen));
+      });
+    });
+
+    // ── Navigation links ─────────────────────────────────────────────
+    navEl.querySelectorAll('[data-nav-action="navigate"]').forEach(link => {
+      link.addEventListener('click', (e) => {
+        e.preventDefault();
+        const href = link.dataset.navHref || link.getAttribute('href');
+        // Close enclosing dropdown (if any)
+        const menu = link.closest('.zDropdown-menu');
+        if (menu) {
+          menu.classList.remove('zShow');
+          menu.previousElementSibling?.setAttribute('aria-expanded', 'false');
+        }
+        if (client?.navigationManager) {
+          // navbar:true → server RESETs the crumb trail (SSOT with zCLI navbar).
+          client.navigationManager.navigateToRoute(href, { navbar: true });
+        } else {
+          window.location.href = href;
+        }
+      });
+    });
+
+    // ── Close dropdowns on outside click ─────────────────────────────
+    setTimeout(() => {
+      document.addEventListener('click', (e) => {
+        if (!navEl.contains(e.target)) {
+          navEl.querySelectorAll('.zDropdown-menu.zShow').forEach(menu => {
+            menu.classList.remove('zShow');
+            menu.previousElementSibling?.setAttribute('aria-expanded', 'false');
+          });
+        }
+      });
+    }, 100);
+
+    if (logger) logger.debug('[NavBarBuilder] wireNavBarEvents attached');
+  }
+
+  /**
+   * Render navbar DOM element (v1.6.1: Returns DOM element to preserve event listeners)
+   * Used for meta navbar (from zSession config) rendered in <zNavBar> element
+   * @param {Array} items - Navbar items (e.g., ['zVaF', 'zAbout', '^zLogin'])
+   * @param {Object} options - Client options (for title/brand)
+   * @returns {Promise<HTMLElement|null>} Navbar DOM element
+   */
+  async renderMetaNavBarHTML(items, options) {
+    this.logger.debug('[NavBarBuilder] renderMetaNavBarHTML called:', items.length);
+
+    if (!Array.isArray(items) || items.length === 0) {
+      this.logger.warn('[NavBarBuilder] [WARN] No navbar items provided');
+      return null;
+    }
+
+    try {
+      // Load navigation renderer
+      const navRenderer = await this.client._ensureNavigationRenderer();
+
+      // Render navbar element
+      const navElement = navRenderer.renderNavBar(items, {
+        className: 'zcli-navbar-meta',
+        theme: 'light',
+        href: (item) => {
+          // Strip modifiers (^ for bounce-back, ~ for anchor) from URL
+          const cleanItem = item.replace(/^[\^~]+/, '');
+          return `/${cleanItem}`;
+        },
+        brand: options.brand || options.title  // Use dedicated brand field (always zSpark)
+      });
+
+      // FIX v1.6.1: Return DOM element directly (NOT outerHTML!)
+      // This preserves event listeners attached by link_primitives.js
+      // The caller (zvaf_manager.js) will append the element instead of setting innerHTML
+      this.logger.log('[NavBarBuilder] Returning navbar DOM element (preserves event listeners)');
+      return navElement;
+    } catch (error) {
+      this.logger.error('[NavBarBuilder] Failed to render navbar element:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Render navigation bar from metadata (~zNavBar* in content)
+   * Used for content-embedded navbars in YAML
+   * @param {Array} items - Navbar items
+   * @param {HTMLElement} parentElement - Parent element to append to
+   */
+  async renderNavBar(items, parentElement) {
+    if (!Array.isArray(items) || items.length === 0) {
+      this.logger.warn('[NavBarBuilder] ~zNavBar* has no items or is not an array');
+      return;
+    }
+
+    try {
+      // Load navigation renderer
+      const navRenderer = await this.client._ensureNavigationRenderer();
+
+      // Render navbar with zTheme zNavbar component
+      const navElement = navRenderer.renderNavBar(items, {
+        theme: 'light'
+      });
+
+      if (navElement) {
+        parentElement.appendChild(navElement);
+
+        // Re-initialize zTheme collapse now that navbar is in DOM
+        if (window.zTheme && typeof window.zTheme.initCollapse === 'function') {
+          window.zTheme.initCollapse();
+          this.logger.log('[NavBarBuilder] Re-initialized zTheme collapse for navbar');
+        }
+
+        this.logger.log('[NavBarBuilder] Rendered navigation bar with items:', items);
+      }
+    } catch (error) {
+      this.logger.error('[NavBarBuilder] Failed to render navigation bar:', error);
+    }
+  }
+}

package/L3_Abstraction/orchestrator/orchestrator.js

@@ -0,0 +1,13 @@
+/**
+ * L3_Abstraction/orchestrator - Display Orchestration Components
+ * 
+ * High-level orchestration for declarative rendering pipeline.
+ * Coordinates L2 display handlers and manages rendering flow.
+ */
+
+export { WizardGateHandler } from './wizard_gate_handler.js';
+export { NavBarBuilder } from './navbar_builder.js';
+export { MetadataProcessor } from './metadata_processor.js';
+export { GroupRenderer } from './group_renderer.js';
+export { ContainerUnwrapper } from './container_unwrapper.js';
+export { InputEventHandler } from './input_event_handler.js';