dom-manipulation-best-practices

DOM Manipulation Performance Rules - Three-Phase Strategy

APPLY: EVERY QUERY - CRITICAL PERFORMANCE RULE

AEM Performance Principles (REQUIRED)

Based on AEM's performance guidelines:

• Phase E (Eager): Minimal DOM creation for LCP elements only
• Phase L (Lazy): Progressive enhancement of below-fold content
• Phase D (Delayed): Third-party DOM modifications after 3+ second delay

Phase E - LCP Critical DOM Operations (REQUIRED)

Immediate DOM insertion for LCP elements, minimal complexity

// ✅ REQUIRED - Phase E: Simple DOM structure for LCP
const createLCPElement = (content) => {
  const isFirstSection = true; // Determining logic for first section
  
  if (isFirstSection) {
    // Phase E: Keep DOM structure minimal for LCP
    const el = createTag('div', { class: 'hero-content' });
    el.textContent = content; // Simple text content first
    
    // Return immediately for LCP
    return el;
  }
};

// ✅ REQUIRED - Progressive enhancement pattern
const enhanceLCPElement = (element, enhancementData) => {
  // Phase L: Add enhancements after LCP
  setTimeout(() => {
    const enhancedContent = createTag('div', { class: 'enhanced-content' });
    enhancedContent.innerHTML = enhancementData;
    element.appendChild(enhancedContent);
  }, 0);
};

createElement Pattern (REQUIRED)

Always use the standardized createTag pattern from utils.js:

// ✅ CORRECT - Preserves events and performance (all phases)
const el = createTag('div', { class: 'my-class' }, content);
parent.append(el);

// ❌ WRONG - Breaks event listeners and re-parses DOM  
parent.innerHTML = '<div class="my-class">content</div>';

Phase-Aware DOM Construction (REQUIRED)

// ✅ REQUIRED - Build DOM progressively by phase
class ComponentBuilder {
  constructor(element) {
    this.element = element;
    this.isFirstSection = element.closest('.section') === document.querySelector('.section');
  }
  
  init() {
    if (this.isFirstSection) {
      // Phase E: Critical structure only
      this.buildCriticalDOM();
    } else {
      // Phase L: Build with intersection observer
      this.buildWithLazyLoading();
    }
  }
  
  buildCriticalDOM() {
    // Phase E: Minimal DOM for LCP
    const basicStructure = this.createBasicStructure();
    this.element.appendChild(basicStructure);
    
    // Queue enhancements for Phase L
    this.queueEnhancements();
  }
  
  buildWithLazyLoading() {
    // Phase L: Full DOM construction with intersection observer
    const observer = new IntersectionObserver((entries) => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          this.buildFullDOM();
          observer.unobserve(entry.target);
        }
      });
    }, { rootMargin: '200px' });
    
    observer.observe(this.element);
  }
  
  createBasicStructure() {
    // Simple DOM for LCP - no nested complexity
    return createTag('div', { class: 'basic-content' }, this.getBasicContent());
  }
  
  buildFullDOM() {
    // Phase L: Rich DOM structure
    const fullStructure = this.createEnhancedStructure();
    this.element.appendChild(fullStructure);
  }
}