` containing child `

` elements for each row, each of which contains `

` elements for each column. The block's `decorate(block)` function receives this wrapper and can restructure, add classes, attach event listeners, or inject new elements. ### Common Block Defects The most frequent block bugs are: (1) **unscoped CSS** that leaks styles into surrounding content or other blocks, (2) **missing null checks** when author content is optional or cells are empty, (3) **no mobile layout** because the developer only tested at desktop width, (4) **DOM thrashing** from interleaved reads and writes causing synchronous layout recalculations, (5) **inaccessible interactive elements** lacking ARIA attributes or keyboard handlers, and (6) **broken image handling** from not using `createOptimizedPicture`. ### EDS Loading Phases Block CSS and JS are loaded lazily by default — only when the block scrolls into view (or is in the first section). This means a block's CSS can cause a flash of unstyled content if the decoration is heavy. The `decorate()` function should minimize visible layout shifts by working with the existing DOM structure rather than replacing it entirely. ## Step 0: Create Todo List Before starting, create a todo list to track progress through these steps: - [ ] Read and inventory the block source files - [ ] Static analysis of JavaScript - [ ] CSS scope and quality check - [ ] Accessibility audit of generated markup - [ ] Performance review - [ ] Mobile responsiveness check - [ ] Generate test plan with scenarios - [ ] Produce findings report ## Step 1: Read and Inventory Block Files Locate and read the block source code: 1. **Identify the block directory.** The user should provide the block name or path. Expected location: `blocks/{block-name}/`. 2. **Read the JS file:** `blocks/{block-name}/{block-name}.js`. If this file does not exist, the block is CSS-only (valid but unusual). Note this. 3. **Read the CSS file:** `blocks/{block-name}/{block-name}.css`. If missing, the block relies on default styles or inherits from a parent. Flag as a potential issue. 4. **Check for additional files.** Some blocks include helper files, SVG icons, or sub-modules. List everything in the directory. 5. **Identify the block type:** simple (one item per row), compound (multiple columns per row), or container (wraps other content). This affects which tests apply. 6. **Note the line count** for both JS and CSS. Blocks over 80 lines in either file may be doing too much. ## Step 2: Static Analysis of JavaScript Analyze the JavaScript file for common defects: ### Function Structure - **Default export:** The file must export a default function named `decorate` (or use `export default function decorate(block)`). A named export or missing export prevents the block from loading. - **Function signature:** Must accept a single `block` parameter. Additional parameters are ignored by the EDS loader. - **Async handling:** If the function is `async`, verify all `await` calls have error handling. An unhandled promise rejection in `decorate()` silently breaks the block. ### Null Safety - **Empty cell guards:** For every `querySelector` or `children` access, check that the code handles `null` results. Search for patterns like `row.children[0].textContent` without a preceding null check — this throws when the cell is empty. - **Optional chaining:** Prefer `el?.querySelector('img')` over `el.querySelector('img')` for optional content. - **Array bounds:** If the code accesses `children[N]` by index, verify `N` is within bounds. Authors can add fewer or more rows than expected. ### DOM Manipulation - **Avoid `innerHTML` assignment.** Setting `innerHTML` destroys event listeners and is an XSS vector if content contains user input. Use `createElement` and `append` instead. - **Batch DOM writes.** Multiple sequential `element.style.x = ...` or `element.classList.add(...)` calls interleaved with reads (`offsetHeight`, `getBoundingClientRect`) cause synchronous layout. Flag any pattern where a read follows a write in a loop. - **Fragment usage:** When adding many elements, use `DocumentFragment` to batch insertions. ### Imports - **`createOptimizedPicture`:** If the block handles images, it should import `createOptimizedPicture` from `../../scripts/aem.js`. Raw `` tags miss EDS image optimization. - **No external CDN imports.** Blocks should not import from external CDNs (unpkg, cdnjs, jsdelivr). Dependencies must be bundled locally or loaded via `delayed.js`. - **Relative paths:** Imports should use relative paths (`../../scripts/...`), not absolute paths. ### Event Listeners - **Cleanup:** If the block adds `window` or `document` event listeners, verify they are cleaned up or use `{ once: true }` where appropriate. Blocks can be decorated multiple times on a single page. - **Delegation:** Prefer `block.addEventListener('click', handler)` over adding listeners to individual children. Delegation handles dynamic content and reduces memory. - **Passive listeners:** Scroll and touch event listeners should use `{ passive: true }` to avoid blocking the main thread. ## Step 3: CSS Scope and Quality Check Analyze the CSS file for scoping and quality issues: ### Scoping - **Every rule must be scoped.** Search for any selector that does not start with `.{block-name}`. Bare selectors like `p { }`, `img { }`, or `.button { }` will leak outside the block. This is a P0 defect. - **No `!important` declarations.** These are almost always a sign of a specificity problem. Flag each instance. - **No ID selectors.** EDS blocks should never use `#id` selectors — IDs are not stable across page renders. ### Custom Properties - **Use project variables.** Check for hardcoded color values (`#fff`, `rgb(...)`, `hsl(...)`). These should reference CSS custom properties from `styles/styles.css`. - **Block-specific variables.** If the block defines its own custom properties, they should be namespaced: `--cards-gap` not `--gap`. ### Responsive Design - **Mobile-first structure.** Base styles should be mobile layout. Desktop overrides go inside `@media (min-width: 900px)`. The 900px breakpoint is the EDS standard. - **Missing breakpoint.** If the CSS has no `@media` query at all, flag this — the block likely has not been tested on mobile. - **Touch targets.** Interactive elements must be at least 44x44px on mobile. Check `min-height` and `min-width` on clickable elements. ### Performance - **No expensive selectors.** Avoid deep descendant chains (`.block > div > div > div > p span`), universal selectors (`*`), or attribute selectors in hot paths. - **Animation performance.** Animations should only use `transform` and `opacity` — other properties trigger layout or paint. Check `transition` and `@keyframes` declarations. - **Font loading.** Blocks should not import fonts via `@import` or `@font-face`. Fonts are a project-level concern managed in `styles/styles.css`. ## Step 4: Accessibility Audit of Generated Markup Analyze the JavaScript to determine what DOM the block produces, then audit for accessibility: ### Semantic Structure - **Heading levels.** If the block generates or restructures headings, verify the levels are logical in context. A block should not force all headings to H2 — it should respect the author's heading level. - **List markup.** If the block displays a collection of items (cards, features, links), the generated DOM should use `

` or another semantic list structure, not bare `
` elements. - **Button vs. link.** If the block creates clickable elements, verify links (``) are used for navigation and buttons (`