@zolomedia/bifrost-client 1.7.74

package/zSys/dom/container_utils.js

@@ -0,0 +1,370 @@
+/**
+ * 
+ * Container Utilities - Layout Primitives
+ * 
+ *
+ * Pure functions for creating and managing layout containers.
+ * These are the TRUE primitives - before text, before headers, before anything.
+ *
+ * @module rendering/container_utils
+ * @layer 0 (Foundation - below Layer 2 utilities)
+ * @pattern Pure Functions (no state, no side effects)
+ *
+ * Philosophy:
+ * - "Container first" - Everything needs a home
+ * - Pure functions (input → output, no side effects)
+ * - Uses zTheme exclusively (no custom CSS)
+ * - Composable (containers can nest)
+ *
+ * Dependencies:
+ * - Layer 2: dom_utils.js
+ *
+ * Exports:
+ * - createContainer()
+ * - createSection()
+ * - createWrapper()
+ * - applyContainerStyles()
+ *
+ * Example:
+ * ```javascript
+ * import { createContainer, createWrapper } from './container_utils.js';
+ *
+ * const container = createContainer(['zContainer', 'zMy-4']);
+ * const flexWrapper = createWrapper(['zD-flex', 'zGap-3']);
+ * ```
+ */
+
+// ─────────────────────────────────────────────────────────────────
+// Imports
+// ─────────────────────────────────────────────────────────────────
+
+// Layer 2: Utilities
+import { createElement, setAttributes } from './dom_utils.js';
+
+// 
+// Container Creation Functions
+// 
+
+/**
+ * Create a main content container (zTheme: zContainer)
+ *
+ * A container is the primary layout element that provides:
+ * - Max width constraints
+ * - Horizontal centering
+ * - Responsive padding
+ *
+ * @param {Array<string>} [classes=[]] - Additional CSS classes to apply
+ * @param {Object} [attributes={}] - HTML attributes (id, data-*, etc.)
+ * @returns {HTMLElement} Div element with zContainer class
+ *
+ * @example
+ * // Basic centered container
+ * const container = createContainer();
+ *
+ * @example
+ * // Container with vertical margin
+ * const container = createContainer(['zMy-4']);
+ *
+ * @example
+ * // Fluid container (full width)
+ * const fluidContainer = createContainer(['zContainer-fluid']);
+ */
+export function createContainer(classes = [], attributes = {}) {
+  const containerClasses = ['zContainer', ...classes];
+  const container = createElement('div', containerClasses);
+
+  if (Object.keys(attributes).length > 0) {
+    setAttributes(container, attributes);
+  }
+
+  return container;
+}
+
+/**
+ * Create a semantic section element
+ *
+ * Sections are semantic HTML5 elements for content grouping.
+ * Use for major page sections (hero, features, footer, etc.)
+ *
+ * @param {Array<string>} [classes=[]] - CSS classes to apply
+ * @param {Object} [attributes={}] - HTML attributes
+ * @returns {HTMLElement} Section element
+ *
+ * @example
+ * // Hero section with background
+ * const hero = createSection(['zBg-primary', 'zText-white', 'zPy-5']);
+ *
+ * @example
+ * // Feature section with ID
+ * const features = createSection(['zPy-4'], { id: 'features' });
+ */
+export function createSection(classes = [], attributes = {}) {
+  const section = createElement('section', classes);
+
+  if (Object.keys(attributes).length > 0) {
+    setAttributes(section, attributes);
+  }
+
+  return section;
+}
+
+/**
+ * Create a generic wrapper div (for grouping/layout)
+ *
+ * Wrappers are flexible divs for:
+ * - Grouping related elements
+ * - Applying flex/grid layouts
+ * - Creating visual boundaries
+ *
+ * @param {Array<string>} [classes=[]] - CSS classes to apply
+ * @param {Object} [attributes={}] - HTML attributes
+ * @returns {HTMLElement} Div element (no default classes)
+ *
+ * @example
+ * // Flex row wrapper
+ * const row = createWrapper(['zD-flex', 'zGap-3', 'zFlex-items-center']);
+ *
+ * @example
+ * // Grid wrapper
+ * const grid = createWrapper(['zD-grid', 'zGap-4'], { style: 'grid-template-columns: repeat(3, 1fr);' });
+ *
+ * @example
+ * // Card body wrapper
+ * const cardBody = createWrapper(['zCard-body', 'zP-3']);
+ */
+export function createWrapper(classes = [], attributes = {}) {
+  const wrapper = createElement('div', classes);
+
+  if (Object.keys(attributes).length > 0) {
+    setAttributes(wrapper, attributes);
+  }
+
+  return wrapper;
+}
+
+// 
+// Container Styling Functions
+// 
+
+/**
+ * Apply container-specific styles via config object
+ *
+ * This is a higher-level function for applying multiple style concerns at once.
+ * Useful when you need to apply layout, display, and alignment in one call.
+ *
+ * @param {HTMLElement} element - Element to style
+ * @param {Object} config - Style configuration
+ * @param {string} [config.display] - Display mode (flex, grid, block, inline-block)
+ * @param {string} [config.direction] - Flex direction (row, column)
+ * @param {string} [config.align] - Alignment (start, center, end, stretch)
+ * @param {string} [config.justify] - Justification (start, center, end, between, around)
+ * @param {number} [config.gap] - Gap size (0-5)
+ * @param {boolean} [config.wrap] - Enable flex wrap
+ * @returns {HTMLElement} Element with styles applied
+ *
+ * @example
+ * // Create a flex container with centering
+ * const wrapper = createWrapper();
+ * applyContainerStyles(wrapper, {
+ *   display: 'flex',
+ *   direction: 'row',
+ *   align: 'center',
+ *   justify: 'between',
+ *   gap: 3
+ * });
+ *
+ * @example
+ * // Create a grid container
+ * const grid = createWrapper();
+ * applyContainerStyles(grid, {
+ *   display: 'grid',
+ *   gap: 4
+ * });
+ */
+export function applyContainerStyles(element, config = {}) {
+  const classes = [];
+
+  // Display mode
+  if (config.display) {
+    const displayMap = {
+      'flex': 'zD-flex',
+      'grid': 'zD-grid',
+      'block': 'zD-block',
+      'inline-block': 'zD-inline-block',
+      'none': 'zD-none'
+    };
+    const displayClass = displayMap[config.display];
+    if (displayClass) {
+      classes.push(displayClass);
+    }
+  }
+
+  // Flex direction (only applies if display is flex)
+  if (config.direction && config.display === 'flex') {
+    const directionMap = {
+      'row': 'zFlex-row',
+      'column': 'zFlex-column',
+      'row-reverse': 'zFlex-row-reverse',
+      'column-reverse': 'zFlex-column-reverse'
+    };
+    const directionClass = directionMap[config.direction];
+    if (directionClass) {
+      classes.push(directionClass);
+    }
+  }
+
+  // Alignment (align-items - vertical alignment in row, horizontal in column)
+  if (config.align) {
+    const alignMap = {
+      'start': 'zFlex-items-start',
+      'center': 'zFlex-items-center',
+      'end': 'zFlex-items-end',
+      'stretch': 'zFlex-items-stretch',
+      'baseline': 'zFlex-items-baseline'
+    };
+    const alignClass = alignMap[config.align];
+    if (alignClass) {
+      classes.push(alignClass);
+    }
+  }
+
+  // Justification (justify-content - horizontal alignment in row, vertical in column)
+  if (config.justify) {
+    const justifyMap = {
+      'start': 'zFlex-start',
+      'center': 'zFlex-center',
+      'end': 'zFlex-end',
+      'between': 'zFlex-between',
+      'around': 'zFlex-around',
+      'evenly': 'zFlex-evenly'
+    };
+    const justifyClass = justifyMap[config.justify];
+    if (justifyClass) {
+      classes.push(justifyClass);
+    }
+  }
+
+  // Gap
+  if (typeof config.gap === 'number' && config.gap >= 0 && config.gap <= 5) {
+    classes.push(`zGap-${config.gap}`);
+  }
+
+  // Flex wrap
+  if (config.wrap) {
+    classes.push('zFlex-wrap');
+  }
+
+  // Apply all classes at once
+  if (classes.length > 0) {
+    element.classList.add(...classes);
+  }
+
+  return element;
+}
+
+// 
+// Flex Utility Functions (for programmatic class generation)
+// 
+
+/**
+ * Get zTheme flex justify-content class (horizontal alignment)
+ * @param {string} justify - Justify: 'start', 'center', 'end', 'between', 'around', 'evenly'
+ * @returns {string} zTheme justify class
+ */
+export function getFlexJustifyClass(justify = 'start') {
+  const justifyMap = {
+    start: 'zFlex-start',
+    center: 'zFlex-center',
+    end: 'zFlex-end',
+    between: 'zFlex-between',
+    around: 'zFlex-around',
+    evenly: 'zFlex-evenly'
+  };
+
+  return justifyMap[justify] || 'zFlex-start';
+}
+
+/**
+ * Get zTheme flex align-items class (vertical alignment)
+ * @param {string} align - Align: 'start', 'center', 'end', 'stretch', 'baseline'
+ * @returns {string} zTheme align class
+ */
+export function getFlexAlignClass(align = 'stretch') {
+  const alignMap = {
+    start: 'zFlex-items-start',
+    center: 'zFlex-items-center',
+    end: 'zFlex-items-end',
+    stretch: 'zFlex-items-stretch',
+    baseline: 'zFlex-items-baseline'
+  };
+
+  return alignMap[align] || 'zFlex-items-stretch';
+}
+
+/**
+ * Get zTheme flex direction class
+ * @param {string} direction - Direction: 'row', 'column', 'row-reverse', 'column-reverse'
+ * @returns {string} zTheme flex direction class
+ */
+export function getFlexDirectionClass(direction = 'row') {
+  const directionMap = {
+    row: 'zFlex-row',
+    column: 'zFlex-column',
+    'row-reverse': 'zFlex-row-reverse',
+    'column-reverse': 'zFlex-column-reverse'
+  };
+
+  return directionMap[direction] || 'zFlex-row';
+}
+
+/**
+ * Create a container element for a zKey with metadata support
+ * @param {string} zKey - The zKey identifier
+ * @param {Object} metadata - Metadata object (may contain _zClass, _zHTML)
+ * @returns {Promise<HTMLElement>} Container element (div by default, or semantic element if _zHTML is specified)
+ */
+export async function createZKeyContainer(zKey, metadata = {}) {
+  // Use centralized semantic element primitive (SSOT for _zHTML)
+  const { createSemanticElement } = await import('../../L2_Handling/display/primitives/semantic_element_primitive.js');
+  const elementType = metadata._zHTML || 'div';
+  const container = createSemanticElement(elementType);
+
+  // Check for custom classes in metadata
+  if (metadata._zClass !== undefined) {
+    if (metadata._zClass === '' || metadata._zClass === null) {
+      // Empty string or null = no container classes (opt-out)
+      container.className = '';
+    } else {
+      // Apply custom classes
+      const classes = Array.isArray(metadata._zClass)
+        ? metadata._zClass
+        : metadata._zClass.split(',').map(c => c.trim());
+      container.className = classes.join(' ');
+    }
+  } else {
+    // Default: responsive zTheme container
+    container.className = 'zContainer-fluid zp-2';
+  }
+
+  // Set data attribute for debugging
+  container.setAttribute('data-zkey', zKey);
+  // Set id for DevTools navigation and CSS targeting
+  container.setAttribute('id', zKey);
+
+  return container;
+}
+
+// 
+// Default Export (for convenience)
+// 
+export default {
+  createContainer,
+  createSection,
+  createWrapper,
+  applyContainerStyles,
+  getFlexJustifyClass,
+  getFlexAlignClass,
+  getFlexDirectionClass,
+  createZKeyContainer
+};
+

package/zSys/dom/dom.js

@@ -0,0 +1,13 @@
+/**
+ * zSys/dom - DOM Utilities Barrel
+ * 
+ * DOM manipulation utilities (element creation, containers, blocks, encoding).
+ * 
+ * @module zSys/dom
+ * @layer zSys (System Utilities)
+ */
+
+export * from './block_utils.js';
+export * from './container_utils.js';
+export * from './dom_utils.js';
+export * from './encoding_utils.js';

package/zSys/dom/dom_utils.js

@@ -0,0 +1,328 @@
+/**
+ * 
+ * DOM Utilities - Pure DOM Manipulation Functions
+ * 
+ *
+ * Pure functions for DOM manipulation. Zero dependencies, zero state,
+ * zero side effects (except the DOM operations themselves).
+ *
+ * @module utils/dom_utils
+ * @layer 2
+ * @pattern Pure Functions
+ *
+ * Dependencies:
+ * - Layer 0: Browser DOM APIs only
+ *
+ * Exports:
+ * - createElement: Create element with classes and attributes
+ * - safeQuery: Safe querySelector (returns null instead of throwing)
+ * - safeQueryAll: Safe querySelectorAll (returns array instead of NodeList)
+ * - clearElement: Clear element content safely
+ * - appendChildren: Append multiple children at once
+ * - removeElement: Remove element safely (checks parent exists)
+ * - replaceElement: Replace element with another
+ * - setAttributes: Set multiple attributes at once
+ * - toggleClasses: Toggle multiple classes at once
+ * - createTextNode: Create text node (safe alternative to textContent)
+ *
+ * Example:
+ * ```javascript
+ * import { createElement, appendChildren } from './dom_utils.js';
+ *
+ * const button = createElement('button', ['zBtn', 'zBtnPrimary'], { type: 'button' });
+ * const icon = createElement('i', ['bi', 'bi-check']);
+ * appendChildren(button, [icon, createTextNode('Submit')]);
+ * ```
+ */
+
+// 
+// DOM Creation & Manipulation
+// 
+
+/**
+ * Create an HTML element with classes and attributes
+ *
+ * @param {string} tag - HTML tag name (e.g., 'div', 'button', 'input')
+ * @param {string[]} [classNames=[]] - Array of CSS class names to add
+ * @param {Object} [attributes={}] - HTML attributes to set {id, type, disabled, etc}
+ * @returns {HTMLElement} Created element
+ *
+ * @example
+ * const button = createElement('button', ['zBtn', 'zBtnPrimary'], {
+ *   type: 'button',
+ *   id: 'submit-btn',
+ *   disabled: false
+ * });
+ *
+ * @throws {Error} If tag is empty or invalid
+ */
+export function createElement(tag, classNames = [], attributes = {}) {
+  if (!tag || typeof tag !== 'string') {
+    throw new Error('[createElement] tag must be a non-empty string');
+  }
+
+  const element = document.createElement(tag);
+
+  // Add classes
+  if (classNames && classNames.length > 0) {
+    element.classList.add(...classNames);
+  }
+
+  // Set attributes
+  if (attributes && typeof attributes === 'object') {
+    setAttributes(element, attributes);
+  }
+
+  return element;
+}
+
+/**
+ * Create a text node (safe alternative to textContent)
+ *
+ * @param {string} text - Text content
+ * @returns {Text} Text node
+ *
+ * @example
+ * const textNode = createTextNode('Hello, World!');
+ * element.appendChild(textNode);
+ */
+export function createTextNode(text) {
+  return document.createTextNode(text || '');
+}
+
+// 
+// DOM Querying
+// 
+
+/**
+ * Safe querySelector (returns null instead of throwing)
+ *
+ * @param {string} selector - CSS selector
+ * @param {Element|Document} [context=document] - Search context
+ * @returns {Element|null} Found element or null
+ *
+ * @example
+ * const element = safeQuery('#my-element');
+ * if (element) {
+ *   element.classList.add('active');
+ * }
+ */
+export function safeQuery(selector, context = document) {
+  try {
+    return context.querySelector(selector);
+  } catch (error) {
+    this.logger.warn(`[safeQuery] Invalid selector: ${selector}`, error);
+    return null;
+  }
+}
+
+/**
+ * Safe querySelectorAll (returns array instead of NodeList)
+ *
+ * @param {string} selector - CSS selector
+ * @param {Element|Document} [context=document] - Search context
+ * @returns {Element[]} Array of found elements (empty if none found)
+ *
+ * @example
+ * const buttons = safeQueryAll('.zBtn');
+ * buttons.forEach(btn => btn.disabled = true);
+ */
+export function safeQueryAll(selector, context = document) {
+  try {
+    return Array.from(context.querySelectorAll(selector));
+  } catch (error) {
+    this.logger.warn(`[safeQueryAll] Invalid selector: ${selector}`, error);
+    return [];
+  }
+}
+
+// 
+// DOM Modification
+// 
+
+/**
+ * Clear element content safely
+ *
+ * @param {Element} element - Element to clear
+ *
+ * @example
+ * const container = document.getElementById('content');
+ * clearElement(container);
+ */
+export function clearElement(element) {
+  if (!element) {
+    return;
+  }
+
+  // Remove all children
+  while (element.firstChild) {
+    element.removeChild(element.firstChild);
+  }
+}
+
+/**
+ * Append multiple children to a parent element at once
+ *
+ * @param {Element} parent - Parent element
+ * @param {(Element|Text)[]} [children=[]] - Array of child elements or text nodes
+ *
+ * @example
+ * const container = createElement('div');
+ * const header = createElement('h1');
+ * const paragraph = createElement('p');
+ * appendChildren(container, [header, paragraph]);
+ */
+export function appendChildren(parent, children = []) {
+  if (!parent || !Array.isArray(children)) {
+    return;
+  }
+
+  children.forEach(child => {
+    if (child) {
+      parent.appendChild(child);
+    }
+  });
+}
+
+/**
+ * Remove element from DOM safely (checks if parent exists)
+ *
+ * @param {Element} element - Element to remove
+ *
+ * @example
+ * const button = document.getElementById('old-button');
+ * removeElement(button);
+ */
+export function removeElement(element) {
+  if (element && element.parentNode) {
+    element.parentNode.removeChild(element);
+  }
+}
+
+/**
+ * Replace element with another element
+ *
+ * @param {Element} oldElement - Element to replace
+ * @param {Element} newElement - Replacement element
+ *
+ * @example
+ * const oldButton = document.getElementById('old-btn');
+ * const newButton = createElement('button', ['zBtn', 'zBtnSuccess']);
+ * replaceElement(oldButton, newButton);
+ */
+export function replaceElement(oldElement, newElement) {
+  if (!oldElement || !newElement || !oldElement.parentNode) {
+    return;
+  }
+
+  oldElement.parentNode.replaceChild(newElement, oldElement);
+}
+
+// 
+// Attributes & Classes
+// 
+
+/**
+ * Set multiple attributes on an element at once
+ *
+ * @param {Element} element - Target element
+ * @param {Object} attributes - Attributes to set {name: value}
+ *
+ * @example
+ * const input = createElement('input');
+ * setAttributes(input, {
+ *   type: 'text',
+ *   id: 'username',
+ *   placeholder: 'Enter username',
+ *   required: true
+ * });
+ */
+export function setAttributes(element, attributes = {}) {
+  if (!element || !attributes) {
+    return;
+  }
+
+  Object.entries(attributes).forEach(([key, value]) => {
+    if (value === null || value === undefined) {
+      element.removeAttribute(key);
+    } else if (typeof value === 'boolean') {
+      // Handle boolean attributes (disabled, required, etc)
+      if (value) {
+        element.setAttribute(key, '');
+      } else {
+        element.removeAttribute(key);
+      }
+    } else {
+      element.setAttribute(key, value);
+    }
+  });
+}
+
+/**
+ * Toggle multiple classes on an element at once
+ *
+ * @param {Element} element - Target element
+ * @param {string[]} classes - Array of class names to toggle
+ * @param {boolean|null} [force=null] - Force add (true) or remove (false), or toggle (null)
+ *
+ * @example
+ * // Toggle classes
+ * toggleClasses(button, ['active', 'highlighted']);
+ *
+ * // Force add classes
+ * toggleClasses(button, ['disabled', 'inactive'], true);
+ *
+ * // Force remove classes
+ * toggleClasses(button, ['active', 'highlighted'], false);
+ */
+export function toggleClasses(element, classes = [], force = null) {
+  if (!element || !Array.isArray(classes)) {
+    return;
+  }
+
+  classes.forEach(className => {
+    if (className) {
+      if (force === null) {
+        element.classList.toggle(className);
+      } else {
+        element.classList.toggle(className, force);
+      }
+    }
+  });
+}
+
+// 
+// Container Helpers (Layer 2 - Pure Utilities)
+// 
+
+/**
+ * Create a div element with optional attributes
+ *
+ * Utility function to create a div with attributes in one call.
+ * This is a Layer 2 (Utilities) function - pure, no business logic.
+ *
+ * @param {Object} [attributes={}] - Attributes to set on the div
+ * @returns {HTMLDivElement} The created div element
+ *
+ * @example
+ * // Simple div
+ * const container = createDiv();
+ *
+ * // Div with classes
+ * const card = createDiv({ class: 'zCard zCard-primary' });
+ *
+ * // Div with multiple attributes
+ * const item = createDiv({ 'data-item-id': '123', 'data-type': 'product' });
+ *
+ * // Div with ARIA attributes for accessibility
+ * const alert = createDiv({ role: 'alert', 'aria-live': 'polite' });
+ */
+export function createDiv(attributes = {}) {
+  const div = createElement('div');
+
+  if (Object.keys(attributes).length > 0) {
+    setAttributes(div, attributes);
+  }
+
+  return div;
+}