# Eds Block Development

> Guide for developing EDS blocks using vanilla JavaScript, Content Driven Development, and block decoration patterns. Covers block structure, decorate function, content extraction, DOM manipulation, and EDS best practices for Adobe Edge Delivery Services.

- Skill: `diegosouzapw/eds-block-development` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/eds-block-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/eds-block-development/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/eds-block-development

---


# EDS Block Development Guide

## ⚠️ CRITICAL WARNING: EDS Reserved Class Names

**BEFORE WRITING ANY CODE, READ THIS:**

EDS automatically adds these class names to your blocks:
- `.{blockname}-container` - Added to parent `<section>` element
- `.{blockname}-wrapper` - Added to block's parent `<div>` wrapper

**❌ NEVER use these suffixes in your CSS or JavaScript:**
```css
/* ❌ PRODUCTION BUG - Will break entire page */
.overlay-container { position: fixed; opacity: 0; }

/* ✅ SAFE - Use different suffix */
.overlay-backdrop { position: fixed; opacity: 0; }
```

**Safe suffixes:** `-backdrop`, `-panel`, `-inner`, `-grid`, `-list`, `-content`, `-dialog`, `-popup`

See [CSS Best Practices](#critical-avoid-eds-reserved-class-names) section below for full details.

---

## Purpose

Guide developers through creating and modifying Adobe Edge Delivery Services (EDS) blocks following vanilla JavaScript patterns, Content Driven Development principles, and EDS best practices.

## When to Use This Skill

Automatically activates when:
- Creating new blocks in `/blocks/`
- Modifying existing block JavaScript (`.js` files)
- Implementing block decoration patterns
- Working with EDS content structures
- Using keywords: "block", "decorate", "EDS block"

---

## Quick Start: Block Structure

### File Organization

Every EDS block follows this structure:

```
blocks/your-block/
├── your-block.js             # Decoration logic (REQUIRED)
├── your-block.css            # Block-specific styles (REQUIRED)
├── README.md                 # Usage documentation (REQUIRED)
├── EXAMPLE.md                # Google Docs example (REQUIRED)
├── test.html                 # Development test file (RECOMMENDED)
└── block-architecture.md     # Technical architecture (OPTIONAL - for complex blocks)
```

**Critical naming convention:** File names must match the block name exactly (kebab-case).

---

## Google Docs Table Structure (CRITICAL)

### How EDS Recognizes Blocks

**The first row of a table in Google Docs is the block name that drives everything:**

1. **First row (header row)** = Block name (e.g., "overlay", "cards", "hero")
   - EDS uses this name to load `/blocks/{name}/{name}.js`
   - EDS uses this name to load `/blocks/{name}/{name}.css`
   - This triggers the `decorate()` function
   - **WITHOUT THIS, YOUR BLOCK WILL NOT LOAD**

2. **Subsequent rows** = Block content (data rows)
   - Row 2, Row 3, etc. become `block.children[0]`, `block.children[1]`, etc.
   - Your `decorate()` function processes these rows

### Example: Google Docs Table

```
| overlay        | ← HEADER ROW (block name) - CRITICAL!
|----------------|
| Learn More     | ← Row 2 becomes block.children[0]
| Welcome! ...   | ← Row 3 becomes block.children[1]
```

**What EDS does:**
1. Sees header row "overlay"
2. Loads `/blocks/overlay/overlay.js`
3. Loads `/blocks/overlay/overlay.css`
4. Calls `decorate(blockElement)`
5. Your code processes rows 2 and 3

### Common Mistake

❌ **WRONG** - No header row:
```
| Learn More     |
| Welcome! ...   |
```
Result: Block not recognized, CSS/JS not loaded, no decoration happens

✅ **CORRECT** - Header row with block name:
```
| overlay        | ← Must match /blocks/overlay/
|----------------|
| Learn More     |
| Welcome! ...   |
```

---

## The Decorate Function Pattern

All EDS blocks export a default `decorate` function that receives the block element:

```javascript
export default function decorate(block) {
  // 1. Configuration (at the top)
  const config = {
    animationDuration: 300,
    maxItems: 10,
    errorMessage: 'Failed to load content'
  };

  // 2. Extract content from EDS structure
  const rows = Array.from(block.children);
  const content = rows.map(row => {
    const cells = Array.from(row.children);
    return cells.map(cell => cell.textContent.trim());
  });

  // 3. Create new DOM structure
  const container = document.createElement('div');
  container.className = 'your-block-wrapper';

  // 4. Build your component
  content.forEach(([title, description]) => {
    const item = document.createElement('div');
    item.className = 'your-block-item';
    item.innerHTML = `
      <h3>${title}</h3>
      <p>${description}</p>
    `;
    container.appendChild(item);
  });

  // 5. Setup event handlers
  container.querySelectorAll('.your-block-item').forEach(item => {
    item.addEventListener('click', () => {
      console.log('Item clicked');
    });
  });

  // 6. Replace block content
  block.textContent = '';
  block.appendChild(container);
}
```

---

## Configuration Object Architecture

### ⚠️ CRITICAL: Separation of Concerns

**Every block must distinguish between:**

1. **Global Constants** - Developer-facing messages and module-level state
2. **Runtime Configuration** - User-facing settings, durations, URLs, icons, text
3. **Metadata Overrides** - Notebook-specific configuration from `.ipynb` metadata

### Global Constants Pattern

**Place at the top of your JavaScript file (before all other code):**

```javascript
// ============================================================================
// GLOBAL CONSTANTS - Developer-facing error messages (easily searchable)
// ============================================================================
const BLOCKNAME_ERRORS = {
  CONFIG_MISSING: 'Incomplete code: Configuration object missing. Block cannot initialize.',
  INVALID_DATA: 'Invalid data format. Expected array of objects.',
  FETCH_FAILED: 'Failed to fetch remote data.',
};

// ============================================================================
// MODULE-LEVEL CONSTANTS
// ============================================================================
// Module-level cache (persists across block instances)
const BLOCKNAME_CACHE = new Map();
```

**Why this matters:**

- Error messages are **developer-facing** - they help developers debug issues
- Placing them at the top makes them **easily searchable** with Ctrl+F
- Separates concerns: developers modify global constants, users/metadata configure runtime behavior
- **Never put error messages in the config object** - they're not runtime configuration

### Runtime Configuration Object

**Define inside `decorate()` function:**

```javascript
export default function decorate(block) {
  // Configuration object - runtime settings
  const config = {
    // Messages (user-facing)
    errorMessage: 'Failed to load content',
    loadingMessage: 'Loading...',

    // Timing
    animationDuration: 300,
    defaultTimeout: 5000,

    // Limits
    maxItems: 10,
    maxRetries: 3,

    // URLs and Paths
    apiEndpoint: '/api/data.json',
    fallbackUrl: 'https://example.com/fallback',

    // UI Icons (HTML entities)
    icons: {
      close: '&times;',
      arrow: '&#9654;',
      warning: '&#9888;',
    },

    // UI Text
    text: {
      submitButton: 'Submit',
      cancelButton: 'Cancel',
      confirmMessage: 'Are you sure?',
    },
  };

  // Extract metadata overrides
  const metadata = block.dataset;
  const timeout = metadata.timeout ? parseInt(metadata.timeout) : config.defaultTimeout;

  // Use config and metadata throughout
  // ...
}
```

**What belongs in config object:**

- ✅ Durations and timing values
- ✅ API endpoints and URLs
- ✅ UI text and icons
- ✅ Limits and thresholds
- ✅ User-facing messages
- ❌ Error messages (use global constants)
- ❌ Module-level caches (use module constants)

### Metadata Override Pattern

**For `.ipynb` notebooks:**

```javascript
export default function decorate(block) {
  const config = { /* ... */ };

  // Extract notebook metadata (if applicable)
  const notebookData = JSON.parse(block.textContent || '{}');
  const metadata = notebookData.metadata || {};

  // Override config with metadata (convert units if needed)
  const splashDuration = metadata['splash-duration']
    ? metadata['splash-duration'] * 1000  // Convert seconds to milliseconds
    : config.defaultSplashDuration;

  const autorun = metadata.autorun === true;  // Boolean from metadata

  // Use overridden values
  showSplashScreen(splashDuration);
}
```

**For EDS blocks with data attributes:**

```javascript
export default function decorate(block) {
  const config = { /* ... */ };

  // Override config with data attributes
  const layout = block.dataset.layout || 'grid';
  const columns = parseInt(block.dataset.columns) || config.defaultColumns;

  // Apply configuration
  block.classList.add(`layout-${layout}`);
  block.style.setProperty('--columns', columns);
}
```

### Dependency Injection for Config

**When config is needed in helper functions, use dependency injection:**

```javascript
// ❌ BAD - Global access (causes ReferenceError)
function createOverlay(data) {
  const icon = config.icons.close;  // ReferenceError: config is not defined
  // ...
}

// ✅ GOOD - Dependency injection
function createOverlay(data, config) {
  const icon = config.icons.close;  // Explicit parameter
  // ...
}

export default function decorate(block) {
  const config = { /* ... */ };

  // Pass config explicitly
  const overlay = createOverlay(data, config);
}
```

**For nested function calls:**

```javascript
function createOverlay(data, config) {
  // Config validation guard clause
  if (!config) {
    console.error('[BLOCK] CRITICAL: Config object missing in createOverlay');
    const errorDiv = document.createElement('div');
    errorDiv.className = 'block-error';
    errorDiv.textContent = BLOCKNAME_ERRORS.CONFIG_MISSING;
    return errorDiv;
  }

  // Pass config down the chain
  const content = renderContent(data, config);
  const footer = renderFooter(config);

  // ...
}

function renderContent(data, config) {
  // Config flows through entire call chain
  const icon = config.icons.arrow;
  // ...
}

export default function decorate(block) {
  const config = { /* ... */ };

  // Top-level call passes config
  const overlay = createOverlay(data, config);
}
```

### Config Validation Pattern

**CRITICAL: Never use hardcoded fallbacks with `||` operator:**

```javascript
// ❌ BAD - Hardcoded fallback bypasses config
function createOverlay(data, config = null) {
  const icon = config?.icons?.close || '&times;';  // Fallback defeats config purpose
  const timeout = config?.timeout || 5000;         // Hardcoded value
}

// ✅ GOOD - Guard clause with explicit error
function createOverlay(data, config = null) {
  // Fail explicitly if config missing
  if (!config) {
    console.error('[BLOCK] CRITICAL: Config object missing');
    const errorDiv = document.createElement('div');
    errorDiv.textContent = BLOCKNAME_ERRORS.CONFIG_MISSING;
    return errorDiv;
  }

  // Direct property access (no fallbacks)
  const icon = config.icons.close;
  const timeout = config.timeout;

  // Config is guaranteed to exist here
}
```

**Why this matters:**

- Fallbacks hide configuration issues
- Block should **fail explicitly** if config missing
- Makes bugs obvious during development
- Forces proper dependency injection

**Only acceptable use of fallback:**

```javascript
// ✅ Acceptable - Ternary for intentional default behavior
const layout = config ? config.layout : 'grid';

// ✅ Acceptable - Metadata override with config fallback
const duration = metadata['duration'] || config.defaultDuration;
```

### Refactoring Existing Blocks

**When reviewing or modifying existing blocks, check for:**

1. **Hardcoded values scattered throughout code**
   - Extract to config object at top of `decorate()`
   - Group by category (messages, timing, limits, etc.)

2. **Error messages in function bodies**
   - Move to `BLOCKNAME_ERRORS` global constant at file top
   - Update all usages to reference global constant

3. **Functions accessing config globally**
   - Add `config` parameter to function signature
   - Pass config explicitly from call sites
   - Add guard clause for config validation

4. **Hardcoded fallbacks using `||` operator**
   - Replace with guard clauses that fail explicitly
   - Use ternary only for intentional defaults

**Refactoring checklist:**

```javascript
// Before refactoring:
function helper() {
  const icon = '&times;';  // ❌ Hardcoded
  const timeout = 5000;    // ❌ Hardcoded
  if (error) {
    showError('Failed');   // ❌ Hardcoded message
  }
}

// After refactoring:
const BLOCK_ERRORS = {
  FETCH_FAILED: 'Failed to load data',  // ✅ Global constant
};

export default function decorate(block) {
  const config = {
    icons: { close: '&times;' },  // ✅ Config object
    timeout: 5000,                 // ✅ Config object
  };

  helper(config);  // ✅ Dependency injection
}

function helper(config) {
  if (!config) {  // ✅ Guard clause
    console.error(BLOCK_ERRORS.CONFIG_MISSING);
    return;
  }

  const icon = config.icons.close;  // ✅ Direct access
  const timeout = config.timeout;   // ✅ Direct access

  if (error) {
    showError(BLOCK_ERRORS.FETCH_FAILED);  // ✅ Global constant
  }
}
```

### Real-World Example: ipynb-viewer

**See `blocks/ipynb-viewer/ipynb-viewer.js` for comprehensive implementation:**

- **Global constants** (lines 14-24): Error messages and module cache
- **Config object** (lines 4073-4105): Runtime settings organized by category
- **Metadata overrides** (lines 4120-4125): Splash duration from notebook metadata
- **Dependency injection** (lines 2236, 3349): Config passed through function chain
- **Guard clauses** (lines 2238-2245, 3351-3362): Fail explicitly if config missing

**Key architectural decisions:**

1. Error messages promoted to global constants (easily searchable)
2. All hardcoded values moved to config object
3. Config passed explicitly through all function calls
4. No `||` fallbacks - functions fail with clear errors
5. Metadata overrides use ternary for intentional defaults

---

## Content Extraction Patterns

### Basic Two-Column Pattern

```javascript
export default function decorate(block) {
  const rows = Array.from(block.children);

  const items = rows.map(row => {
    const [titleCell, descriptionCell] = row.children;
    return {
      title: titleCell?.textContent?.trim() || '',
      description: descriptionCell?.textContent?.trim() || ''
    };
  });

  // Use the items...
}
```

### Picture Extraction Pattern

```javascript
function extractPicture(cell) {
  const picture = cell.querySelector('picture');
  if (!picture) return null;

  return {
    img: picture.querySelector('img'),
    sources: Array.from(picture.querySelectorAll('source'))
  };
}

export default function decorate(block) {
  const rows = Array.from(block.children);

  rows.forEach(row => {
    const [imageCell, contentCell] = row.children;
    const picture = extractPicture(imageCell);

    if (picture) {
      // Use the picture element
    }
  });
}
```

### Link Extraction Pattern

```javascript
function extractLink(cell) {
  const link = cell.querySelector('a');
  return link ? {
    href: link.href,
    text: link.textContent.trim(),
    target: link.target
  } : null;
}
```

---

## DOM Manipulation Best Practices

### 1. Clear the Block First

```javascript
export default function decorate(block) {
  // Extract data first
  const data = extractContent(block);

  // Clear the block
  block.textContent = '';

  // Add new content
  const container = createNewStructure(data);
  block.appendChild(container);
}
```

### 2. Use Document Fragments for Multiple Elements

```javascript
function createItems(data) {
  const fragment = document.createDocumentFragment();

  data.forEach(item => {
    const element = document.createElement('div');
    element.textContent = item;
    fragment.appendChild(element);
  });

  return fragment;
}

export default function decorate(block) {
  const data = extractContent(block);
  block.textContent = '';
  block.appendChild(createItems(data));
}
```

### 3. Minimize DOM Manipulation

```javascript
// ❌ BAD - Multiple reflows
data.forEach(item => {
  const element = document.createElement('div');
  element.textContent = item;
  block.appendChild(element); // Triggers reflow each time
});

// ✅ GOOD - Single reflow
const fragment = document.createDocumentFragment();
data.forEach(item => {
  const element = document.createElement('div');
  element.textContent = item;
  fragment.appendChild(element);
});
block.appendChild(fragment); // Single reflow
```

---

## Error Handling

### Basic Error Handling

```javascript
export default function decorate(block) {
  try {
    const config = { /* ... */ };
    const content = extractContent(block);

    if (!content || content.length === 0) {
      throw new Error('No content found');
    }

    const container = createStructure(content);
    block.textContent = '';
    block.appendChild(container);

  } catch (error) {
    console.error('Block decoration failed:', error);
    block.innerHTML = '<p class="error-message">Unable to load content</p>';
  }
}
```

### Async Operations

```javascript
export default async function decorate(block) {
  try {
    // Show loading state
    block.innerHTML = '<p class="loading">Loading...</p>';

    // Fetch data
    const response = await fetch('/api/data');
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    const data = await response.json();

    // Clear and render
    block.textContent = '';
    block.appendChild(createStructure(data));

  } catch (error) {
    console.error('Failed to load data:', error);
    block.innerHTML = '<p class="error-message">Failed to load content</p>';
  }
}
```

---

## CSS Best Practices

### Block-Specific Naming

```css
/* Namespace all classes with block name */
.your-block-wrapper {
  /* Container styles */
}

.your-block-item {
  /* Item styles */
}

.your-block-title {
  /* Title styles */
}

/* Use BEM naming for variants */
.your-block-item--featured {
  /* Featured variant */
}

.your-block-item__icon {
  /* Item element */
}
```

### ⚠️ CRITICAL: Avoid EDS Reserved Class Names

**EDS automatically adds these classes:**
- `.{blockname}-wrapper` - Added to the block's parent `<div>` wrapper
- `.{blockname}-container` - Added to the parent `<section>` element
- `.block` - Added to all block elements
- `.section` - Added to all section elements
- `.button-container` - Added to parent elements of buttons
- `.default-content-wrapper` - Added to default content wrappers

**DO NOT use these class names in your CSS or JavaScript:**

```css
/* ❌ BAD - Conflicts with EDS automatic naming */
.overlay-container {
  position: fixed;  /* Will be applied to the section, breaking layout */
}

.cards-wrapper {
  display: grid;  /* Will conflict with EDS's .cards-wrapper on block element */
}

/* ✅ GOOD - Use different suffixes */
.overlay-backdrop {
  position: fixed;  /* Safe - won't conflict */
}

.cards-grid {
  display: grid;  /* Safe - different name */
}

.overlay-modal-container {
  /* Safe - more specific name */
}
```

**Why this matters:**
- EDS's `decorateBlock()` adds `.{blockname}-wrapper` to block parent divs (line 682)
- EDS's `decorateBlock()` adds `.{blockname}-container` to parent sections (line 684)
- EDS's `decorateBlock()` adds `.block` to all block elements (line 677)
- EDS's `decorateSections()` adds `.section` to all sections (line 503)
- EDS's `decorateButtons()` adds `.button-container` to button parents (lines 430, 439, 448)
- If your CSS uses these same class names, styles will be applied to the wrong elements
- This can cause invisible pages, broken layouts, or unexpected behavior

**Additional conflicts to avoid:**
```css
/* ❌ Never style these EDS-generated classes with layout-breaking properties */
.block {
  position: fixed;  /* Will break ALL blocks on the page */
}

.section {
  display: none;  /* Will hide ALL sections */
}

.button-container {
  position: absolute;  /* Will break ALL button layouts */
}
```

**Safe naming patterns:**
- `.{blockname}-backdrop`
- `.{blockname}-modal`
- `.{blockname}-content`
- `.{blockname}-inner`
- `.{blockname}-grid`
- `.{blockname}-list`
- `.{blockname}-panel`
- `.{blockname}-overlay`

**Reference:** See `scripts/aem.js`:
- Lines 674-686: `decorateBlock()` - adds wrapper/container classes
- Lines 489-530: `decorateSections()` - adds section classes
- Lines 421-453: `decorateButtons()` - adds button-container classes

### Mobile-First Responsive Design

```css
/* Base styles (mobile) */
.your-block-item {
  padding: 1rem;
  margin-bottom: 1rem;
}

/* Tablet */
@media (min-width: 600px) {
  .your-block-item {
    padding: 1.5rem;
  }
}

/* Desktop */
@media (min-width: 900px) {
  .your-block-item {
    padding: 2rem;
  }
}
```

### Use CSS Variables

```css
.your-block {
  background-color: var(--background-color);
  color: var(--text-color);
  font-family: var(--body-font-family);
  padding: var(--spacing-m);
}
```

### ⚠️ CRITICAL: Verify HTML Structure Before Writing CSS

**NEVER assume what HTML elements exist** - always inspect the actual DOM structure first.

**Why this matters:**

- Different parsers generate different HTML structures
- CSS targeting non-existent elements wastes debugging time
- Assumptions about `<p>` tags, `<div>` wrappers, or structure can be wrong

**Real-world example (ipynb-viewer parseMarkdown):**

The `parseMarkdown()` function converts double newlines to `<br><br>` tags, NOT `<p>` tags:

```javascript
// parseMarkdown() implementation (line 397)
html = html.replace(/\n\n+/g, '<br><br>'); // Paragraph breaks use <br><br>
html = html.replace(/\n/g, ' '); // Single newlines become spaces
```

**Problem pattern:**

```css
/* ❌ WRONG - Assumes <p> tags exist */
.your-block p {
  margin: 0.15rem 0;  /* No effect if parseMarkdown uses <br><br> */
}

/* ✅ CORRECT - Targets actual structure */
.your-block br {
  margin: 0.15rem 0;
  line-height: 0.15rem;
}

/* Hide consecutive br tags for better spacing */
.your-block br + br {
  display: none;
}
```

**Best practices when writing CSS:**

1. **Always verify HTML structure** - Use DevTools to inspect actual DOM
2. **Don't assume** - Just because you expect `<p>` tags doesn't mean they exist
3. **Check the renderer** - Look at how content is generated (parseMarkdown, renderCell, etc.)
4. **Test in isolation** - Add a bright background color to verify selector matches
5. **Read the source** - 5 minutes reading code beats 1 hour of trial-and-error

**How to verify:**

1. Open browser DevTools (F12)
2. Inspect the content area element
3. Look at the actual HTML generated by your parser/renderer
4. Check what elements exist (br vs p vs div vs section)
5. Write CSS rules for the **actual** structure, not the **assumed** structure

**Impact:**

- **Before verification**: Wasted hours debugging "why isn't my CSS working?"
- **After verification**: Immediate fix by targeting correct elements
- **Root cause**: Assumptions about HTML structure without inspection

**Documentation:** See `LEARNINGS.md` section "ipynb-viewer: parseMarkdown() Uses <br> Tags, Not <p> Tags"

---

## Accessibility

### Semantic HTML

```javascript
export default function decorate(block) {
  const container = document.createElement('nav'); // Use semantic elements
  container.setAttribute('aria-label', 'Block navigation');

  const list = document.createElement('ul');

  items.forEach(item => {
    const li = document.createElement('li');
    const button = document.createElement('button');
    button.textContent = item.text;
    button.setAttribute('aria-label', `Open ${item.text}`);

    li.appendChild(button);
    list.appendChild(li);
  });

  container.appendChild(list);
  block.textContent = '';
  block.appendChild(container);
}
```

### Keyboard Navigation

```javascript
export default function decorate(block) {
  const items = block.querySelectorAll('.your-block-item');

  items.forEach((item, index) => {
    // Make items focusable
    item.setAttribute('tabindex', '0');

    // Handle keyboard events
    item.addEventListener('keydown', (e) => {
      if (e.key === 'Enter' || e.key === ' ') {
        e.preventDefault();
        item.click();
      }

      if (e.key === 'ArrowDown' && items[index + 1]) {
        items[index + 1].focus();
      }

      if (e.key === 'ArrowUp' && items[index - 1]) {
        items[index - 1].focus();
      }
    });
  });
}
```

---

## Performance Optimization

### 1. Lazy Loading Images

```javascript
export default function decorate(block) {
  const images = block.querySelectorAll('img');

  images.forEach(img => {
    img.setAttribute('loading', 'lazy');
  });
}
```

### 2. Debouncing Event Handlers

```javascript
function debounce(func, wait) {
  let timeout;
  return function executedFunction(...args) {
    clearTimeout(timeout);
    timeout = setTimeout(() => func.apply(this, args), wait);
  };
}

export default function decorate(block) {
  const handleResize = debounce(() => {
    // Resize logic
  }, 250);

  window.addEventListener('resize', handleResize);
}
```

### 3. Use requestIdleCallback for Non-Critical Work

```javascript
export default function decorate(block) {
  // Critical rendering
  const container = createStructure(data);
  block.appendChild(container);

  // Non-critical work
  if ('requestIdleCallback' in window) {
    requestIdleCallback(() => {
      // Analytics, non-critical enhancements, etc.
      trackBlockView(block);
    });
  } else {
    setTimeout(() => {
      trackBlockView(block);
    }, 1);
  }
}
```

---

## Testing Your Block

### Create test.html

**⚠️ CRITICAL: Correct EDS HTML Structure**

The HTML structure in test.html must EXACTLY match how EDS transforms Google Docs tables:

```
Block Element (has block name class)
└── Row(s) (direct children, one <div> per row)
    └── Cell(s) (children of row, one <div> per cell)
```

**Example - Two-column block with one row:**
```html
<div class="your-block">          <!-- Block element -->
    <div>                          <!-- Row 1 -->
        <div>Cell 1 content</div>  <!-- Cell 1 -->
        <div>Cell 2 content</div>  <!-- Cell 2 -->
    </div>
</div>
```

**Example - Two-column block with multiple rows:**
```html
<div class="your-block">           <!-- Block element -->
    <div>                           <!-- Row 1 -->
        <div>Row 1, Cell 1</div>    <!-- Cell 1 -->
        <div>Row 1, Cell 2</div>    <!-- Cell 2 -->
    </div>
    <div>                           <!-- Row 2 -->
        <div>Row 2, Cell 1</div>    <!-- Cell 1 -->
        <div>Row 2, Cell 2</div>    <!-- Cell 2 -->
    </div>
</div>
```

**❌ COMMON MISTAKE - Extra wrapper div:**
```html
<!-- ❌ WRONG - Do NOT add extra wrapper divs -->
<div class="your-block">
    <div>                    <!-- ❌ Extra wrapper -->
        <div>                <!-- Row -->
            <div>Cell 1</div>
            <div>Cell 2</div>
        </div>
    </div>
</div>
```

### Complete test.html Template

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Your Block Test</title>

    <!-- EDS Core Styles -->
    <link rel="stylesheet" href="/styles/styles.css">
    <!-- Block CSS is loaded automatically by loadBlock() -->

    <style>
        /* EDS pattern - ensure body appears */
        body.appear {
            display: block;
        }

        /* Optional: Test page styling */
        body {
            padding: 2rem;
            max-width: 1200px;
            margin: 0 auto;
        }

        .test-section {
            margin: 2rem 0;
            padding: 1.5rem;
            border: 2px solid #ccc;
            border-radius: 8px;
            background: #f9f9f9;
        }

        .test-section h2 {
            margin-top: 0;
        }
    </style>
</head>
<body>
    <h1>Your Block Test Page</h1>

    <!-- Test Case 1: Basic Usage -->
    <div class="test-section">
        <h2>Test Case 1: Basic Two-Column Block</h2>

        <div class="your-block">
            <div>
                <div>Title 1</div>
                <div>Description 1</div>
            </div>
            <div>
                <div>Title 2</div>
                <div>Description 2</div>
            </div>
        </div>
    </div>

    <!-- Test Case 2: With Images -->
    <div class="test-section">
        <h2>Test Case 2: With Images</h2>

        <div class="your-block">
            <div>
                <div>
                    <picture>
                        <img src="https://via.placeholder.com/300x200" alt="Test Image">
                    </picture>
                </div>
                <div>Content with image</div>
            </div>
        </div>
    </div>

    <!-- Test Case 3: Block Variant -->
    <div class="test-section">
        <h2>Test Case 3: Block Variant</h2>

        <div class="your-block variant-name">
            <div>
                <div>Variant content</div>
                <div>Testing variant styling</div>
            </div>
        </div>
    </div>

    <script type="module">
        import { loadBlock } from '/scripts/aem.js';

        // CRITICAL: Add body.appear class FIRST (before loadBlock)
        // This makes the page visible (EDS hides body by default)
        document.body.classList.add('appear');

        // Get all blocks to test
        const blocks = document.querySelectorAll('.your-block');

        console.log(`Testing ${blocks.length} block(s)...`);

        // Load each block
        for (const block of blocks) {
            try {
                // Add .block class to mimic EDS production behavior
                block.classList.add('block');

                // CRITICAL: Set blockName dataset (required by loadBlock)
                // In production, decorateBlock() gets this from classList[0]
                block.dataset.blockName = 'your-block';

                // Load the block (loads JS and CSS automatically)
                await loadBlock(block);

                console.log('✅ Block loaded:', block.className);
            } catch (error) {
                console.error('❌ Block failed:', block.className, error);
            }
        }

        console.log('All blocks loaded!');
    </script>
</body>
</html>
```

**Important Notes:**

1. **Block Structure**: Each block must have rows as direct children, and cells as children of rows
2. **`.block` class**: Added by script to mimic EDS production (where `decorateBlock()` adds it automatically)
3. **`block.dataset.blockName`**: **CRITICAL** - Must be set before calling `loadBlock()`, otherwise you'll get "undefined" errors
4. **`body.appear`**: REQUIRED - EDS hides body by default, this class makes it visible
5. **Block loading order**: Add `body.appear` class BEFORE calling `loadBlock()`
6. **Multiple blocks**: Use `querySelectorAll()` and loop to test multiple instances
7. **Console logging**: Add logs to track loading progress and catch errors
8. **Block wrappers**: If your block uses `document.querySelector('.{blockname}-wrapper')` (e.g., for expressions plugin), wrap each block in `<div class="{blockname}-wrapper">` in test.html

**Common Errors:**
- If you see `/blocks/undefined/undefined.js 404`, you forgot to set `block.dataset.blockName`!
- If you see `Cannot read properties of null (reading 'firstChild')` in expressions.js, you need to wrap blocks in `.{blockname}-wrapper` divs

### Common HTML Structure Mistakes

❌ **WRONG** - Extra nesting:
```html
<div class="your-block">
    <div><div><div>Content</div></div></div>  <!-- Too many divs! -->
</div>
```

❌ **WRONG** - Missing row wrapper:
```html
<div class="your-block">
    <div>Cell 1</div>  <!-- No row wrapper! -->
    <div>Cell 2</div>
</div>
```

✅ **CORRECT** - Proper structure:
```html
<div class="your-block">
    <div>               <!-- Row -->
        <div>Cell 1</div>  <!-- Cell -->
        <div>Cell 2</div>  <!-- Cell -->
    </div>
</div>
```

✅ **CORRECT** - With wrapper (when block uses `.{blockname}-wrapper` selector):
```html
<div class="your-block-wrapper">  <!-- Wrapper for global selectors -->
    <div class="your-block">
        <div>                      <!-- Row -->
            <div>Cell 1</div>      <!-- Cell -->
            <div>Cell 2</div>      <!-- Cell -->
        </div>
    </div>
</div>
```

**When to use wrappers in test.html:**
- Your block uses `document.querySelector('.{blockname}-wrapper')` in its JavaScript
- Your block depends on external plugins (like expressions) that expect wrappers
- In production, EDS automatically wraps blocks in `.{blockname}-wrapper` divs
- Without the wrapper, code that queries for it will get `null` and may error

### Debugging Tips for test.html

If your test.html doesn't work, check:

1. **Structure**: Use browser DevTools to inspect the DOM structure
   - Right-click block → Inspect Element
   - Verify: Block → Row(s) → Cell(s)

2. **Classes**: Check that `.block` class was added
   - Should see: `<div class="your-block block">`

3. **Console errors**: Open DevTools Console (F12)
   - Look for JavaScript errors
   - Check if `loadBlock()` succeeded

4. **Network tab**: Check if CSS/JS files loaded
   - Should see: `/blocks/your-block/your-block.css`
   - Should see: `/blocks/your-block/your-block.js`

5. **Block scoping**: Ensure your JS uses `block` parameter, not global selectors
   ```javascript
   // ✅ CORRECT
   const cells = block.querySelectorAll('div > div');

   // ❌ WRONG
   const cells = document.querySelectorAll('.your-block div > div');
   ```

### Test with Development Server

```bash
npm run debug
```

Access your test at: `http://localhost:3000/blocks/your-block/test.html`

---

## Block Variations

### ⚠️ CRITICAL: Single JavaScript File for All Variations

**MANDATORY RULE: Each block must have exactly ONE JavaScript file, regardless of how many variations it supports.**

EDS blocks should NEVER have multiple JavaScript files like:
- ❌ `blockname.js`, `blockname-variation1.js`, `blockname-variation2.js`
- ❌ `view-myblog.js`, `view-myblog-ai.js`

Instead, all variation logic must be handled within the single JavaScript file using class detection:

```javascript
export default async function decorate(block) {
  // Detect variation by checking for class
  const isVariationA = block.classList.contains('variation-a');
  const isVariationB = block.classList.contains('variation-b');

  // Apply variation-specific logic
  if (isVariationA) {
    // Handle variation A logic
    const data = await fetchAndFilterData();
    renderVariationA(block, data);
  } else if (isVariationB) {
    // Handle variation B logic
    renderVariationB(block);
  } else {
    // Handle default/standard variation
    renderStandard(block);
  }
}
```

### Why Single File Architecture

- **Maintainability**: All logic for a block is in one place
- **EDS Convention**: The system expects one JS file per block
- **Performance**: Avoids loading multiple files for the same block
- **Consistency**: Follows the same pattern as CSS variations
- **Simplicity**: Easier to understand and debug

### Real-World Example

A blog block with an AI filter variation:

✅ **CORRECT:**
```
blocks/view-myblog/
├── view-myblog.js    # Single file with both standard and AI filtering
├── view-myblog.css
└── README.md
```

❌ **INCORRECT:**
```
blocks/view-myblog/
├── view-myblog.js
├── view-myblog-ai.js  # DON'T DO THIS
├── view-myblog.css
└── README.md
```

**Implementation pattern:**
```javascript
export default async function decorate(block) {
  // Detect AI variation
  const isAIVariation = block.classList.contains('ai');

  // Fetch data
  const rawData = await fetchData();

  // Filter or transform data based on variation
  const processedData = isAIVariation ? filterAIContent(rawData) : rawData;

  // Render with variation-aware logic
  const title = isAIVariation ? 'Latest AI Posts' : 'Latest Posts';
  render(block, processedData, title);
}

// Helper function for AI filtering
function filterAIContent(data) {
  // Filter logic specific to AI variation
  return data.filter(post =>
    post.url.includes('/ai/') ||
    post.title.toLowerCase().includes('ai')
  );
}
```

### How Authors Use Variations

In Google Docs:
```
| view-myblog (ai) |
|------------------|
```

This creates:
```html
<div class="view-myblog ai block">
  <!-- Content -->
</div>
```

Your single JavaScript file detects the `ai` class and applies appropriate logic.

---

## Common Patterns

### Configuration Object

```javascript
export default function decorate(block) {
  // Configuration at the top
  const config = {
    autoplay: block.dataset.autoplay === 'true',
    delay: parseInt(block.dataset.delay) || 3000,
    animation: block.dataset.animation || 'fade'
  };

  // Use config throughout
}
```

### Data Attributes for Options

```javascript
export default function decorate(block) {
  // Read options from data attributes
  const layout = block.dataset.layout || 'grid';
  const columns = parseInt(block.dataset.columns) || 3;

  // Apply classes based on options
  block.classList.add(`layout-${layout}`);
  block.style.setProperty('--columns', columns);
}
```

### Helper Functions

```javascript
// Helper functions outside decorate
function createCard(data) {
  const card = document.createElement('div');
  card.className = 'card';
  card.innerHTML = `
    <h3>${data.title}</h3>
    <p>${data.description}</p>
  `;
  return card;
}

export default function decorate(block) {
  const data = extractContent(block);

  const container = document.createElement('div');
  data.forEach(item => {
    container.appendChild(createCard(item));
  });

  block.textContent = '';
  block.appendChild(container);
}
```

---

## Common Mistakes to Avoid

### ❌ CRITICAL: Don't Use EDS Reserved Class Names

```javascript
// ❌ BAD - Class name conflicts with EDS automatic naming
function createOverlay(content) {
  const backdrop = document.createElement('div');
  backdrop.className = 'overlay-container'; // EDS adds this to parent section!
  return backdrop;
}

// ✅ GOOD - Use different class name
function createOverlay(content) {
  const backdrop = document.createElement('div');
  backdrop.className = 'overlay-backdrop'; // Safe - won't conflict
  return backdrop;
}
```

**Never use these patterns in your code:**
- `.{blockname}-container` - Reserved by EDS for parent sections
- `.{blockname}-wrapper` - Reserved by EDS for block elements

**This mistake caused a production bug:** Using `.overlay-container` in CSS with `position: fixed; z-index: 999; opacity: 0;` made entire pages invisible because EDS added `overlay-container` class to the parent section, applying those styles to the wrong element.

### ⚠️ CRITICAL: When to Use and When to Avoid Global Selectors

**Understanding the distinction between block-scoped and document-level operations is essential for EDS block development.**

#### ❌ NEVER Use Global Selectors for Block-Scoped Operations

**This is the most common bug in EDS blocks!**

When decorating a block, NEVER query for the block itself or its children using global selectors. ALWAYS use the `block` parameter.

```javascript
// ❌ BAD - Uses global selectors instead of block parameter
export default function decorate(block) {
  const bioElement = document.querySelector('.bio');  // ❌ Gets FIRST block on page!

  if (!bioElement.classList.contains('hide-author')) {
    const imgElement = document.querySelector('.bio.block img');  // ❌ Global!
    const bioBlock = document.querySelector('.bio.block');        // ❌ Global!

    bioBlock.appendChild(authorElement);  // ❌ Always modifies first block!
  }
}
```

**Why this is wrong:**
- `document.querySelector('.bio')` always returns the FIRST matching element on the page
- If you have multiple bio blocks, they ALL use the first block's configuration
- The second, third, etc. blocks won't work correctly
- Image link conversion fails because it checks the wrong block

```javascript
// ✅ GOOD - Uses block parameter for proper scoping
export default function decorate(block) {
  // Check the CURRENT block, not a global selector
  if (!block.classList.contains('hide-author')) {
    // Find img wit

…(truncated)