@zolomedia/bifrost-client 1.7.74

package/L2_Handling/display/outputs/header_renderer.js

@@ -0,0 +1,162 @@
+/**
+ * 
+ * Header Renderer - Semantic Headers (h1-h6)
+ * 
+ *
+ * Renders header events from zCLI backend. Converts indent levels
+ * to semantic HTML header tags (h1-h6) with optional colors.
+ *
+ * @module rendering/header_renderer
+ * @layer 3
+ * @pattern Strategy (single event type)
+ *
+ * Philosophy:
+ * - "Terminal first" - headers structure all zCLI output
+ * - Pure rendering (no WebSocket, no state, no side effects)
+ * - Semantic HTML (indent → h1-h6)
+ * - Uses Layer 2 utilities exclusively (no inline logic)
+ *
+ * Dependencies:
+ * - Layer 2: dom_utils.js, ztheme_utils.js
+ *
+ * Exports:
+ * - HeaderRenderer: Class for rendering header events
+ *
+ * Example:
+ * ```javascript
+ * import { HeaderRenderer } from './header_renderer.js';
+ *
+ * const renderer = new HeaderRenderer(logger);
+ * renderer.render({
+ *   label: 'Welcome to zCLI',
+ *   color: 'primary',
+ *   indent: 1  // h1
+ * }, 'zVaF');
+ * ```
+ */
+
+// ─────────────────────────────────────────────────────────────────
+// Imports
+// ─────────────────────────────────────────────────────────────────
+
+// Layer 2: Utilities
+import { createElement } from '../../../zSys/dom/dom_utils.js';
+import { getTextColorClass, indentToHeaderTag } from '../../../zSys/theme/ztheme_utils.js';
+import { withErrorBoundary } from '../../../zSys/validation/error_boundary.js';
+
+// 
+// Header Renderer Class
+// 
+
+/**
+ * HeaderRenderer - Renders semantic header events
+ *
+ * Handles the 'header' zDisplay event. Converts indent levels
+ * to semantic HTML header tags (h1-h6) for proper document structure.
+ *
+ * Indent Mapping:
+ * - indent 0: Reserved for special cases (flush/hero layouts) - NOT a header
+ * - indent 1 → h1 (main title)
+ * - indent 2 → h2 (section)
+ * - indent 3 → h3 (subsection)
+ * - indent 4 → h4
+ * - indent 5 → h5
+ * - indent 6 → h6
+ * - indent 7+ → h6 (capped at h6)
+ */
+export class HeaderRenderer {
+  /**
+   * Create a HeaderRenderer instance
+   * @param {Object} logger - Logger instance for debugging
+   */
+  constructor(logger) {
+    this.logger = logger || console;
+    this.logger.debug('[HeaderRenderer] Initialized');
+
+    // Wrap render method with error boundary
+    const originalRender = this.render.bind(this);
+    this.render = withErrorBoundary(originalRender, {
+      component: 'HeaderRenderer',
+      logger: this.logger
+    });
+  }
+
+  /**
+   * Render a header event
+   *
+   * @param {Object} data - Header event data
+   * @param {string} data.label - Header text (backend sends 'label' not 'content')
+   * @param {string} [data.color] - Header color (primary, secondary, info, success, warning, error)
+   * @param {number} [data.indent=1] - Indent level (1-6, where 1=h1, 6=h6)
+   *                                    Note: indent 0 is reserved for special cases
+   * @param {string} [data.class] - Custom CSS class (optional)
+   * @param {string} zone - Target DOM element ID
+   * @returns {HTMLElement|null} Created header element or null if failed
+   *
+   * @example
+   * renderer.render({ label: 'Main Title', indent: 1 }, 'zVaF');  // h1
+   * renderer.render({ label: 'Section', indent: 2, color: 'primary' }, 'zVaF');  // h2
+   * renderer.render({ label: 'Subsection', indent: 3 }, 'zVaF');  // h3
+   */
+  render(data, zone) {
+    // Backend sends 'label' for headers (not 'content')
+    const { label, color, indent = 1, class: customClass } = data;
+
+    // Validate required parameters
+    if (!label) {
+      this.logger.error('[HeaderRenderer] [ERROR] Missing required parameter: label');
+      return null;
+    }
+
+    // Handle indent 0 as special case (reserved for flush/hero layouts)
+    if (indent === 0) {
+      this.logger.warn('[HeaderRenderer] [WARN] indent=0 is reserved for special cases, treating as indent=1 (h1)');
+      // Could also skip rendering or return null, but treating as h1 is safer
+    }
+
+    // Get target container
+    const container = document.getElementById(zone);
+    if (!container) {
+      this.logger.error(`[HeaderRenderer] [ERROR] Zone not found: ${zone}`);
+      return null;
+    }
+
+    // Convert indent to header tag (h1-h6) using Layer 2 utility
+    // This automatically clamps indent between 1-6
+    const headerTag = indentToHeaderTag(indent);
+
+    // Build CSS classes array
+    const classes = [];
+
+    // Add custom class if provided (from YAML)
+    if (customClass) {
+      classes.push(customClass);
+    }
+
+    // Add color class if provided (uses Layer 2 utility)
+    if (color) {
+      const colorClass = getTextColorClass(color);
+      if (colorClass) {
+        classes.push(colorClass);
+      }
+    }
+
+    // Create header element (using Layer 2 utility)
+    const header = createElement(headerTag, classes);
+    header.textContent = label; // Use textContent for XSS safety
+
+    // Append to container
+    container.appendChild(header);
+
+    // Log success
+    this.logger.log(`[HeaderRenderer] Rendered ${headerTag} (${label.length} chars, indent: ${indent})`);
+
+    return header;
+  }
+}
+
+// 
+// Default Export
+// 
+export default HeaderRenderer;
+

package/L2_Handling/display/outputs/icon_renderer.js

@@ -0,0 +1,107 @@
+/**
+ * IconRenderer - Bootstrap Icons for Bifrost
+ *
+ * Renders Bootstrap Icons in web mode with support for:
+ * - Icon name (with or without 'bi-' prefix)
+ * - SSOT semantic color value (primary, warning, …) — resolved via getTextColorClass
+ * - Additional CSS classes (_zClass) — also the channel for sizing
+ *
+ * Features:
+ * - Clean HTML generation
+ * - Proper class composition
+ * - Graceful fallback for missing icons
+ * - Accessible by default: role="img" + aria-label derived from the icon name
+ *   (or an explicit alt_text / aria_label override)
+ *
+ * Author: zOS Framework
+ * Version: 1.0.0
+ * Date: 2026-03-24
+ */
+
+import { getTextColorClass } from '../../../zSys/theme/ztheme_utils.js';
+import { convertStyleToString } from '../../../zSys/dom/style_utils.js';
+
+export default class IconRenderer {
+  /**
+   * @param {Object} logger - Logger instance
+   */
+  constructor(logger) {
+    this.logger = logger;
+  }
+
+  /**
+   * Render Bootstrap Icon
+   * @param {Object} data - Icon configuration
+   * @param {string} data.name - Icon name (e.g., "tools", "bi-tools")
+   * @param {string} [data.color] - SSOT semantic color value (e.g., "primary", "warning")
+   * @param {string} [data._zClass] - Additional CSS classes (also sizing)
+   * @param {string|Object} [data._zStyle] - SSOT inline-style escape hatch
+   * @param {HTMLElement} [targetElement] - Optional parent to append into
+   * @returns {HTMLElement} The rendered node (bare <i>, or a styled <span> wrapper)
+   */
+  render(data, targetElement) {
+    if (!data || !data.name) {
+      this.logger.warn('[IconRenderer] Missing icon name');
+      return null;
+    }
+
+    // Strip 'bi-' prefix if present
+    const cleanName = data.name.replace(/^bi-/, '');
+
+    // Create icon element
+    const icon = document.createElement('i');
+    icon.className = `bi bi-${cleanName}`;
+
+    // Accessibility — a bare <i> is silent to screen readers. Honour the page's
+    // "accessible by default" promise: give every icon role="img" and a readable
+    // aria-label. An explicit alt_text/aria_label wins; otherwise humanize the
+    // bi-* name (bi-heart-fill → "heart fill"), mirroring the terminal's
+    // bracketed [description] fallback.
+    const ariaLabel = (data.alt_text || data.aria_label || cleanName.replace(/-/g, ' ')).trim();
+    if (ariaLabel) {
+      icon.setAttribute('role', 'img');
+      icon.setAttribute('aria-label', ariaLabel);
+    }
+
+    // Only wrap when the icon carries its OWN styling (colour / classes / inline
+    // style). A bare icon returns the raw <i> so the container-unwrapper can
+    // collapse any redundant parent frame instead of nesting a second box.
+    let node = icon;
+    if (data.color || data._zClass || data._zStyle) {
+      const wrapper = document.createElement('span');
+
+      // Build class list. color is an SSOT semantic value (primary, warning, …) —
+      // resolved through the same mapping zText/zH use, never a raw class.
+      const classes = [];
+      if (data.color) classes.push(getTextColorClass(data.color));
+      if (data._zClass) {
+        // Handle _zClass as string or array
+        if (Array.isArray(data._zClass)) {
+          classes.push(...data._zClass);
+        } else {
+          classes.push(...data._zClass.split(' ').filter(c => c));
+        }
+      }
+
+      if (classes.length > 0) {
+        wrapper.className = classes.join(' ');
+      }
+
+      // _zStyle — the SSOT escape hatch, same as every other event.
+      if (data._zStyle) {
+        const cssString = convertStyleToString(data._zStyle, this.logger);
+        if (cssString) {
+          wrapper.setAttribute('style', cssString);
+        }
+      }
+
+      wrapper.appendChild(icon);
+      node = wrapper;
+    }
+
+    if (targetElement) targetElement.appendChild(node);
+
+    this.logger.debug(`[IconRenderer] Rendered icon: %s`, `bi-${cleanName}`);
+    return node;
+  }
+}

package/L2_Handling/display/outputs/image_renderer.js

@@ -0,0 +1,145 @@
+/**
+ * 
+ * Image Renderer - Media Display Events
+ * 
+ *
+ * Terminal-First Design:
+ * - Backend sends src, alt_text, caption (works with URLs and local paths)
+ * - Terminal displays metadata + button to open
+ * - Bifrost renders <img> element with zTheme styling
+ *
+ * Renders image display events from zCLI backend. Creates image
+ * elements using primitives-first architecture.
+ *
+ * @module rendering/image_renderer
+ * @layer 3
+ * @pattern Primitives-First
+ *
+ * Dependencies:
+ * - None (uses native DOM API)
+ *
+ * Exports:
+ * - ImageRenderer: Class for rendering image events
+ *
+ * Example:
+ * ```javascript
+ * import ImageRenderer from './image_renderer.js';
+ *
+ * const renderer = new ImageRenderer(logger);
+ * const element = renderer.render({
+ *   src: 'https://picsum.photos/200/300',
+ *   alt_text: 'Random Image',
+ *   caption: 'A beautiful picture',
+ *   _zClass: 'zRounded-circle',
+ *   _id: 'profile-pic'
+ * });
+ * ```
+ */
+
+// ─────────────────────────────────────────────────────────────────
+// Imports
+// ─────────────────────────────────────────────────────────────────
+
+// Layer 2: Utilities
+import { withErrorBoundary } from '../../../zSys/validation/error_boundary.js';
+
+export class ImageRenderer {
+  constructor(logger) {
+    this.logger = logger;
+
+    // Wrap render method with error boundary
+    const originalRender = this.render.bind(this);
+    this.render = withErrorBoundary(originalRender, {
+      component: 'ImageRenderer',
+      logger: this.logger
+    });
+  }
+
+  /**
+   * Render image element from primitives
+   *
+   * Terminal-First Design:
+   * - src: Supports ANY URL (external) or path (local/relative)
+   * - alt_text: Accessibility text (terminal shows this as header)
+   * - caption: Optional caption (terminal shows below path)
+   * - _zClass: Bifrost-only styling (e.g., zRounded-circle)
+   * - _id: Bifrost-only DOM id for targeting
+   *
+   * @param {Object} eventData - Event data from backend
+   * @param {string} eventData.src - Image source (URL or path)
+   * @param {string} [eventData.alt_text] - Alternative text for accessibility
+   * @param {string} [eventData.caption] - Optional caption text
+   * @param {string} [eventData._zClass] - Custom classes for styling
+   * @param {string} [eventData._id] - Custom id for targeting
+   * @returns {HTMLElement} Image container element
+   */
+  render(eventData) {
+    const { src, alt_text, caption, _zClass, _id } = eventData;
+
+    if (!src) {
+      this.logger.error('[ImageRenderer] Missing src parameter');
+      return this._createErrorElement();
+    }
+
+    this.logger.debug(`[ImageRenderer] Rendering image: ${src}`);
+
+    // Create img element (THE primitive) - align with zTheme
+    const img = document.createElement('img');
+    img.src = src;  // Supports ANY URL (picsum, external, etc.) or local path
+
+    // Apply _zClass and _id directly to img (zTheme pattern)
+    if (_zClass) {
+      img.className = _zClass;
+    }
+    if (_id) {
+      img.setAttribute('id', _id);
+    }
+
+    // Add alt text for accessibility
+    if (alt_text) {
+      img.alt = alt_text;
+    } else {
+      img.alt = ''; // Empty alt for decorative images
+    }
+
+    // DON'T force inline styles - let zTheme/user control via classes
+    // If user wants object-fit, they can add "zObject-fit-cover" to _zClass
+
+    // Only wrap in <figure> if there's a caption (semantic HTML)
+    if (caption) {
+      const figure = document.createElement('figure');
+      figure.appendChild(img);
+
+      const figcaption = document.createElement('figcaption');
+      figcaption.textContent = caption;
+      figcaption.className = 'zText-muted zText-center zmt-2';
+      figure.appendChild(figcaption);
+
+      // _zClass/_zStyle already live on the inner <img> — tell the orchestrator's
+      // central metadata pass not to also stamp them onto this <figure> wrapper.
+      figure.__zMetaScoped = true;
+
+      this.logger.log('[ImageRenderer] Image with caption rendered');
+      return figure;
+    }
+
+    // No caption = return bare img (primitives-first + zTheme alignment!)
+    this.logger.debug('[ImageRenderer] Image rendered');
+    return img;
+  }
+
+  /**
+   * Create error element when src is missing
+   * @private
+   * @returns {HTMLElement}
+   */
+  _createErrorElement() {
+    const error = document.createElement('div');
+    error.className = 'zAlert zAlert-danger';
+    error.textContent = '[WARN] Image source missing';
+    return error;
+  }
+}
+
+export default ImageRenderer;
+

package/L2_Handling/display/outputs/list_renderer.js

@@ -0,0 +1,190 @@
+/**
+ * ListRenderer - Renders list elements (ul/ol) with zTheme styling
+ * Part of the modular bifrost rendering architecture
+ */
+
+// ─────────────────────────────────────────────────────────────────
+// Imports
+// ─────────────────────────────────────────────────────────────────
+
+// Layer 2: Utilities
+import { withErrorBoundary } from '../../../zSys/validation/error_boundary.js';
+
+export class ListRenderer {
+  constructor(logger, client) {
+    this.client = client;
+    this.logger = logger;
+
+    // Wrap render method with error boundary
+    const originalRender = this.render.bind(this);
+    this.render = withErrorBoundary(originalRender, {
+      component: 'ListRenderer',
+      logger: this.logger
+    });
+  }
+
+  /**
+   * Render a list element (bulleted or numbered)
+   * Supports plain text items, nested arrays, and nested zDisplay events
+   * NEW v1.7: Supports cascading styles for nested arrays!
+   * @param {Object} eventData - zDisplay event data with items array
+   * @param {number} level - Internal: current nesting level for cascading (default: 0)
+   * @returns {Promise<HTMLElement>} - Rendered list element (ul or ol)
+   */
+  async render(eventData, level = 0) {
+    this.logger.debug(`[ListRenderer] Rendering list: ${eventData.items?.length || 0} items`);
+
+    // Determine current style based on cascading
+    let currentStyle;
+    let cascadeStyles = null;
+    
+    if (Array.isArray(eventData.style)) {
+      // Cascading styles: cycle through array based on nesting level
+      cascadeStyles = eventData.style;
+      currentStyle = eventData.style[level % eventData.style.length];
+      this.logger.log(`[ListRenderer] Using cascading style: ${currentStyle} (level ${level})`);
+    } else {
+      // Single style: use for all levels
+      currentStyle = eventData.style || 'bullet';
+    }
+
+    // Determine list element type and CSS list-style-type
+    let listElement;
+    let listStyleType = null;
+    
+    if (currentStyle === 'number') {
+      listElement = document.createElement('ol');
+    } else if (currentStyle === 'letter') {
+      listElement = document.createElement('ol');
+      listStyleType = 'lower-alpha';  // a, b, c
+    } else if (currentStyle === 'roman') {
+      listElement = document.createElement('ol');
+      listStyleType = 'lower-roman';  // i, ii, iii
+    } else if (currentStyle === 'circle') {
+      listElement = document.createElement('ul');
+      listStyleType = 'circle';  // 
+    } else if (currentStyle === 'square') {
+      listElement = document.createElement('ul');
+      listStyleType = 'square';  // 
+    } else {
+      // bullet (default) or any other style
+      listElement = document.createElement('ul');
+    }
+
+    // Apply base zTheme class
+    listElement.className = 'zList';
+
+    // Apply list-style-type if specified
+    if (listStyleType) {
+      listElement.style.listStyleType = listStyleType;
+    }
+
+    // _zClass is applied centrally by the orchestrator (SSOT, append mode) on the
+    // returned listElement — we only read it below to detect inline layout.
+
+    // TODO: DEPRECATE - Remove `indent` property from list events
+    // Rationale: Conflicts with native HTML nesting, redundant with _zClass/_zStyle,
+    // only used in 2 places (markdown parser, traceback). Natural nesting is better.
+    // NOTE: Manual removal only - do not auto-fix with agents
+    // Apply indent using zms (margin-start) classes
+    if (eventData.indent && eventData.indent > 0) {
+      listElement.className += ` zms-${eventData.indent}`;
+    }
+
+    // Apply custom id if provided (_id parameter - ignored by terminal)
+    if (level === 0 && eventData._id) {
+      listElement.setAttribute('id', eventData._id);
+    }
+
+    // Check if this is an inline list (for horizontal layout)
+    const isInline = level === 0 && eventData._zClass && eventData._zClass.includes('zList-inline');
+
+    // Render list items (async to support nested zDisplay events)
+    const items = eventData.items || [];
+    let lastLi = null;  // Track last created <li> for appending nested lists
+    
+    for (const item of items) {
+      // NEW v1.7: Handle nested arrays naturally!
+      if (Array.isArray(item)) {
+        this.logger.debug('[ListRenderer] Rendering nested array');
+        
+        // Nested array should be appended to the PREVIOUS list item
+        if (lastLi) {
+          try {
+            const nestedEventData = {
+              items: item,
+              style: cascadeStyles || currentStyle,  // Pass cascading styles or current style
+              indent: 0  // Nested lists use native HTML indentation
+            };
+            const nestedList = await this.render(nestedEventData, level + 1);
+            lastLi.appendChild(nestedList);
+          } catch (error) {
+            this.logger.error('[ListRenderer] Error rendering nested array:', error);
+            lastLi.textContent += ` [Error: ${error.message}]`;
+          }
+        } else {
+          this.logger.warn('[ListRenderer] Nested array without previous list item - creating standalone');
+          // Fallback: create a new <li> if no previous item exists
+          const li = document.createElement('li');
+          try {
+            const nestedEventData = {
+              items: item,
+              style: cascadeStyles || currentStyle,
+              indent: 0
+            };
+            const nestedList = await this.render(nestedEventData, level + 1);
+            li.appendChild(nestedList);
+            listElement.appendChild(li);
+            lastLi = li;
+          } catch (error) {
+            this.logger.error('[ListRenderer] Error rendering nested array:', error);
+            li.textContent = `[Error: ${error.message}]`;
+            listElement.appendChild(li);
+            lastLi = li;
+          }
+        }
+        // Don't update lastLi - nested arrays attach to previous item
+        continue;
+      }
+
+      // Create new <li> for non-array items
+      const li = document.createElement('li');
+
+      // Apply zList-inline-item class if this is an inline list
+      if (isInline) {
+        li.className = 'zList-inline-item';
+      }
+
+      // Check if item contains a nested zDisplay event
+      if (item && typeof item === 'object' && item.zDisplay) {
+        this.logger.debug('[ListRenderer] Rendering nested zDisplay event');
+        
+        // Recursively render the nested zDisplay event
+        try {
+          const nestedElement = await this.client.zDisplayOrchestrator.renderZDisplayEvent(item.zDisplay);
+          if (nestedElement) {
+            li.appendChild(nestedElement);
+          } else {
+            this.logger.warn('[ListRenderer] Nested zDisplay returned null, using fallback');
+            li.textContent = JSON.stringify(item);
+          }
+        } catch (error) {
+          this.logger.error('[ListRenderer] Error rendering nested zDisplay:', error);
+          li.textContent = `[Error: ${error.message}]`;
+        }
+      } else {
+        // Plain text item (original behavior)
+        const content = typeof item === 'string' ? item : (item.content || '');
+        li.textContent = content;
+      }
+
+      listElement.appendChild(li);
+      lastLi = li;  // Track this as the last created <li>
+    }
+
+    this.logger.log(`[ListRenderer] Rendered ${currentStyle} list with ${items.length} items`);
+    return listElement;
+  }
+}
+
+export default ListRenderer;

package/L2_Handling/display/outputs/outputs.js

@@ -0,0 +1,19 @@
+/**
+ * Output Rendering Module Barrel Export
+ * 
+ * Data output components (tables, text, cards, alerts, images, DL, etc.).
+ * 
+ * @module rendering/outputs
+ * @layer 3 (Output Rendering)
+ */
+
+export * from './alert_renderer.js';
+export * from './card_renderer.js';
+export * from './dl_renderer.js';
+export * from './header_renderer.js';
+export * from './icon_renderer.js';
+export * from './image_renderer.js';
+export * from './list_renderer.js';
+export * from './table_renderer.js';
+export * from './text_renderer.js';
+export * from './typography_renderer.js';