@salesforce/afv-skills 1.21.0 → 1.23.0

package/skills/generating-lwc-components/references/lwc-best-practices.md

@@ -1,1310 +0,0 @@
-<!-- Parent: generating-lwc-components/SKILL.md -->
-# Lightning Web Components Best Practices
-
-This guide provides comprehensive best practices for building production-ready LWC components, organized around the **PICKLES Framework** and incorporating advanced patterns from industry experts.
-
----
-
-## PICKLES Framework Overview
-
-The PICKLES Framework provides a structured approach to LWC architecture. Use it as a checklist during component design and implementation.
-
-```
-🥒 P - Prototype    → Validate ideas with wireframes & mock data
-🥒 I - Integrate    → Choose data source (LDS, Apex, GraphQL)
-🥒 C - Composition  → Structure component hierarchy & communication
-🥒 K - Kinetics     → Handle user interactions & event flow
-🥒 L - Libraries    → Leverage platform APIs & base components
-🥒 E - Execution    → Optimize performance & lifecycle hooks
-🥒 S - Security     → Enforce permissions & data protection
-```
-
-**Reference**: [PICKLES Framework](https://www.salesforceben.com/the-ideal-framework-for-architecting-salesforce-lightning-web-components/) — David Picksley, Third Eye Consulting
-
----
-
-## Component Design Principles
-
-### Single Responsibility (PICKLES: Composition)
-
-Each component should do one thing well.
-
-```
-✅ GOOD: accountCard, accountList, accountForm (separate components)
-❌ BAD: accountManager (does display, list, and form in one)
-```
-
-### Composition Over Inheritance
-
-Build complex UIs by composing simple components.
-
-```html
-<!-- Compose components -->
-<template>
-    <c-page-header title="Accounts"></c-page-header>
-    <c-account-filters onfilter={handleFilter}></c-account-filters>
-    <c-account-list accounts={filteredAccounts}></c-account-list>
-    <c-pagination total={totalCount} onpage={handlePage}></c-pagination>
-</template>
-```
-
-### Unidirectional Data Flow
-
-Data flows down (props), events bubble up.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    DATA FLOW PATTERN                             │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│   Parent Component                                               │
-│   ┌─────────────────────────────────────────────────────────┐   │
-│   │  state: accounts = [...]                                │   │
-│   │                                                          │   │
-│   │  ┌──────────┐     ┌──────────┐     ┌──────────┐        │   │
-│   │  │ Child A  │ ←── │ Child B  │ ←── │ Child C  │        │   │
-│   │  │          │     │          │     │          │        │   │
-│   │  │ @api     │     │ @api     │     │ @api     │        │   │
-│   │  │ accounts │     │ selected │     │ details  │        │   │
-│   │  └────┬─────┘     └────┬─────┘     └────┬─────┘        │   │
-│   │       │                │                │               │   │
-│   │       │   Events       │   Events       │   Events      │   │
-│   │       └────────────────┴────────────────┘               │   │
-│   │              ↑ bubbles to parent                        │   │
-│   └─────────────────────────────────────────────────────────┘   │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Naming & Decorator Conventions
-
-### Property & Attribute Naming
-
-| Context | Convention | Example |
-|---------|-----------|---------|
-| JavaScript properties | camelCase | `itemName`, `maxValue` |
-| HTML attributes | kebab-case, lowercase | `item-name`, `max-value` |
-| Dispatched event names | Lowercase, no `on` prefix | `'recordchange'`, `'save'` |
-| HTML event listeners | `on` + event name | `onrecordchange`, `onsave` |
-
-Reserved prefixes in JS property names: `on`, `aria`, `data`. Reserved words: `slot`, `part`, `is`.
-
-### @api Decorator Rules
-
-- Only one decorator per field/method — do not combine `@api` with `@track` or `@wire`
-- For getter/setter pairs: decorate only the getter, and always define both getter and setter
-- Never mutate `@api` properties internally — use a private reactive copy instead
-- Only use `@api` on properties/methods that are part of the component's public API
-
-```javascript
-// ✅ GOOD: getter/setter with @api on getter only
-_recordId;
-
-@api
-get recordId() { return this._recordId; }
-set recordId(value) {
-    this._recordId = value;
-    this.loadRecord();
-}
-```
-
-### @track Decorator Rules
-
-Since Spring '20, primitive properties are reactive by default. `@track` is only needed when **mutating nested properties** of objects or arrays.
-
-| Scenario | @track Needed? |
-|----------|----------------|
-| Primitive value (`string`, `number`, `boolean`) | No |
-| Object/array that is **reassigned** entirely | No |
-| Object with **nested property mutation** (`this.obj.nested.value++`) | Yes |
-
-```javascript
-// ❌ Unnecessary: primitives are reactive by default
-@track searchTerm = '';
-
-// ✅ Correct: remove @track for primitives
-searchTerm = '';
-
-// ✅ Correct: @track needed for nested mutation
-@track formData = { billing: { city: '' } };
-// later: this.formData.billing.city = 'San Francisco';
-```
-
----
-
-## Data Integration (PICKLES: Integrate)
-
-### Data Source Decision Tree
-
-| Scenario | Recommended Approach |
-|----------|---------------------|
-| Single record by ID | Lightning Data Service (`getRecord`) |
-| Simple record CRUD | `lightning-record-form` / `lightning-record-edit-form` |
-| Complex queries | Apex with `@AuraEnabled(cacheable=true)` |
-| Related records, filtering | GraphQL wire adapter |
-| Real-time updates | Platform Events / Streaming API |
-| External data | Named Credentials + Apex callout |
-
-### GraphQL vs Apex Decision
-
-| Use GraphQL When | Use Apex When |
-|------------------|---------------|
-| Fetching related objects | Complex business logic |
-| Client-side filtering | Aggregate queries (COUNT, SUM) |
-| Cursor-based pagination | Bulk DML operations |
-| Reducing over-fetching | Callouts to external systems |
-
-### Wire Service Best Practices
-
-```javascript
-// Store wire result for refreshApex
-wiredAccountsResult;
-
-@wire(getAccounts, { searchTerm: '$searchTerm' })
-wiredAccounts(result) {
-    this.wiredAccountsResult = result;  // Store for refresh
-    const { data, error } = result;
-    if (data) {
-        this.accounts = data;
-        this.error = undefined;
-    } else if (error) {
-        this.error = this.reduceErrors(error);
-        this.accounts = [];
-    }
-}
-
-// Refresh when needed
-async handleRefresh() {
-    await refreshApex(this.wiredAccountsResult);
-}
-```
-
-### Error Handling Pattern
-
-```javascript
-// Centralized error reducer
-reduceErrors(errors) {
-    if (!Array.isArray(errors)) {
-        errors = [errors];
-    }
-
-    return errors
-        .filter(error => !!error)
-        .map(error => {
-            // UI API errors
-            if (error.body?.message) return error.body.message;
-            // JS errors
-            if (error.message) return error.message;
-            // GraphQL errors
-            if (error.graphQLErrors) {
-                return error.graphQLErrors.map(e => e.message).join(', ');
-            }
-            return JSON.stringify(error);
-        })
-        .join('; ');
-}
-```
----
-
-## Event Patterns (PICKLES: Kinetics)
-
-### Custom Events
-
-```javascript
-// Child dispatches event
-this.dispatchEvent(new CustomEvent('select', {
-    detail: { recordId: this.recordId },
-    bubbles: true,    // Bubbles through DOM
-    composed: true    // Crosses shadow boundary
-}));
-
-// Parent handles event
-handleSelect(event) {
-    const recordId = event.detail.recordId;
-}
-```
-
-### Event Bubbling Configuration
-
-Choose the minimum propagation scope needed:
-
-| Configuration | Encapsulation | Use Case |
-|---------------|---------------|----------|
-| `{ bubbles: false, composed: false }` | **Maximum** (Preferred) | Direct parent-child communication |
-| `{ bubbles: true, composed: false }` | Acceptable | Internal shadow DOM communication |
-| `{ bubbles: false, composed: true }` | Acceptable | Cross shadow boundary without full bubbling |
-| `{ bubbles: true, composed: true }` | **Discouraged** | Only when grandparent+ must handle event |
-
-```javascript
-// ✅ Preferred: Maximum encapsulation
-this.dispatchEvent(new CustomEvent('select', {
-    detail: { recordId: this.recordId }
-    // bubbles and composed default to false
-}));
-
-// ⚠️ Use only when necessary
-this.dispatchEvent(new CustomEvent('globalnotify', {
-    detail: { message: 'Record saved' },
-    bubbles: true,
-    composed: true
-}));
-```
-
-### Event Data Passing
-
-```javascript
-// Primitives: pass directly in detail
-this.dispatchEvent(new CustomEvent('update', {
-    detail: this.recordId  // string — no wrapping needed
-}));
-
-// Non-primitives: always pass a copy to prevent mutation
-this.dispatchEvent(new CustomEvent('change', {
-    detail: { ...this.formData }  // shallow copy
-}));
-```
-
-### Event Naming Conventions
-
-```
-✅ GOOD                    ❌ BAD
-────────────────────────   ────────────────────────
-onselect                   onSelectItem
-onrecordchange             on-record-change
-onsave                     onSaveClicked
-onerror                    onErrorOccurred
-```
-
-### When to Use LMS vs Events
-
-| Scenario | Use |
-|----------|-----|
-| Parent-child communication | Custom events |
-| Sibling components (same parent) | Events via parent |
-| Components on different parts of page | Lightning Message Service |
-| LWC to Aura communication | LMS |
-| LWC to Visualforce | LMS |
-
-### Debouncing Pattern
-
-```javascript
-delayTimeout;
-
-handleSearch(event) {
-    const searchTerm = event.target.value;
-    clearTimeout(this.delayTimeout);
-
-    this.delayTimeout = setTimeout(() => {
-        this.searchTerm = searchTerm;
-    }, 300);  // 300ms debounce
-}
-```
-
----
-
-## Spread Patterns & Destructuring
-
-### lwc:spread Directive
-
-The `lwc:spread` directive dynamically spreads object properties as component attributes. Useful for reducing boilerplate and enabling dynamic attribute binding.
-
-**Reference**: [Saurabh Samir - lwc:spread Directive](https://medium.com/@saurabh.samirs)
-
-#### Basic Usage
-
-```html
-<!-- Without lwc:spread (verbose) -->
-<lightning-button
-    label={buttonLabel}
-    variant={buttonVariant}
-    disabled={isDisabled}
-    onclick={handleClick}>
-</lightning-button>
-
-<!-- With lwc:spread (dynamic) -->
-<lightning-button lwc:spread={buttonAttributes} onclick={handleClick}></lightning-button>
-```
-
-```javascript
-get buttonAttributes() {
-    return {
-        label: this.buttonLabel,
-        variant: this.isImportant ? 'brand' : 'neutral',
-        disabled: this.isProcessing
-    };
-}
-```
-
-#### lwc:spread vs @api Object Binding
-
-| Approach | Use When | Reactivity |
-|----------|----------|------------|
-| `lwc:spread={obj}` | Passing multiple attributes dynamically | Re-renders on object change |
-| `@api config` | Passing structured data to custom component | Must spread in child |
-| Individual `@api` props | Simple, known properties | Each prop triggers render |
-
-#### Conditional Attribute Spreading
-
-```javascript
-get inputAttributes() {
-    const attrs = {
-        label: 'Search',
-        type: 'text',
-        value: this.searchTerm
-    };
-
-    // Conditionally add attributes
-    if (this.isRequired) {
-        attrs.required = true;
-    }
-
-    if (this.maxLength) {
-        attrs['max-length'] = this.maxLength;
-    }
-
-    return attrs;
-}
-```
-
-```html
-<lightning-input lwc:spread={inputAttributes} onchange={handleChange}></lightning-input>
-```
-
-#### Event Handlers with lwc:spread
-
-**Important**: Event handlers must be bound separately, not spread:
-
-```html
-<!-- ✅ CORRECT: Event handler separate from spread -->
-<lightning-button lwc:spread={buttonProps} onclick={handleClick}></lightning-button>
-
-<!-- ❌ INCORRECT: onclick in spread object won't work -->
-<!-- buttonProps = { label: 'Save', onclick: this.handleClick } -->
-```
-
-### lwc:on Directive (Spring '26 - API 66.0)
-
-The `lwc:on` directive solves the limitation above by enabling **dynamic event binding** directly from JavaScript. It allows you to bind multiple event handlers at runtime.
-
-**Requires**: API 66.0+ (Spring '26)
-
-#### Basic Usage
-
-```javascript
-// component.js
-export default class DynamicEventComponent extends LightningElement {
-    // Define event handlers as object properties
-    eventHandlers = {
-        click: this.handleClick.bind(this),
-        mouseover: this.handleMouseOver.bind(this),
-        focus: this.handleFocus.bind(this)
-    };
-
-    handleClick() {
-        console.log('Element clicked!');
-    }
-
-    handleMouseOver() {
-        console.log('Mouse over!');
-    }
-
-    handleFocus() {
-        console.log('Element focused!');
-    }
-}
-```
-
-```html
-<!-- template.html -->
-<template>
-    <!-- Bind multiple event handlers dynamically -->
-    <button lwc:on={eventHandlers}>Click Me</button>
-</template>
-```
-
-#### Combining lwc:spread and lwc:on
-
-For fully dynamic components, combine both directives:
-
-```javascript
-// component.js
-export default class FullyDynamicButton extends LightningElement {
-    // Properties via lwc:spread
-    buttonAttributes = {
-        label: 'Save',
-        variant: 'brand',
-        disabled: false
-    };
-
-    // Events via lwc:on
-    buttonEvents = {
-        click: this.handleClick.bind(this),
-        focus: this.handleFocus.bind(this)
-    };
-
-    handleClick() {
-        this.dispatchEvent(new CustomEvent('save'));
-    }
-
-    handleFocus() {
-        console.log('Button focused');
-    }
-}
-```
-
-```html
-<!-- template.html -->
-<template>
-    <!-- Best of both worlds: dynamic props AND dynamic events -->
-    <lightning-button
-        lwc:spread={buttonAttributes}
-        lwc:on={buttonEvents}>
-    </lightning-button>
-</template>
-```
-
-#### Dynamic Event Handlers from @api
-
-Pass event handler configurations from parent components:
-
-```javascript
-// childComponent.js
-export default class ChildComponent extends LightningElement {
-    @api eventConfig; // { click: handler, change: handler }
-
-    get resolvedHandlers() {
-        // Ensure handlers are properly bound
-        const handlers = {};
-        if (this.eventConfig) {
-            Object.entries(this.eventConfig).forEach(([event, handler]) => {
-                handlers[event] = typeof handler === 'function' ? handler : () => {};
-            });
-        }
-        return handlers;
-    }
-}
-```
-
-```html
-<!-- childComponent.html -->
-<template>
-    <div lwc:on={resolvedHandlers}>
-        <slot></slot>
-    </div>
-</template>
-```
-
-#### Removing Event Listeners
-
-Remove specific event listeners by omitting them from the object:
-
-```javascript
-// Toggle mouseover handler on/off
-toggleHoverHandler() {
-    if (this._hoverEnabled) {
-        // Remove mouseover by omitting it
-        this.eventHandlers = {
-            click: this.handleClick.bind(this)
-        };
-    } else {
-        // Add mouseover back
-        this.eventHandlers = {
-            click: this.handleClick.bind(this),
-            mouseover: this.handleMouseOver.bind(this)
-        };
-    }
-    this._hoverEnabled = !this._hoverEnabled;
-}
-```
-
-#### lwc:spread vs lwc:on Comparison
-
-| Directive | Purpose | Use Case |
-|-----------|---------|----------|
-| `lwc:spread` | Dynamic **properties/attributes** | Pass label, variant, disabled dynamically |
-| `lwc:on` | Dynamic **event handlers** | Bind click, change, custom events dynamically |
-| Both together | Fully dynamic configuration | Reusable wrapper components, dynamic UIs |
-
-**Important Notes**:
-- Do NOT mutate the object passed to `lwc:on` - create a new object to update handlers
-- Event type names should be lowercase without the `on` prefix (use `click` not `onclick`)
-- Always use `.bind(this)` or arrow functions to preserve context
-
-### Object Spread & Destructuring
-
-Modern JavaScript patterns for cleaner data handling in LWC.
-
-#### Object Spread for Config Merging
-
-```javascript
-// Default + user config pattern
-const defaultConfig = {
-    pageSize: 10,
-    sortField: 'Name',
-    sortDirection: 'ASC'
-};
-
-get tableConfig() {
-    return {
-        ...defaultConfig,
-        ...this.userConfig  // User config overrides defaults
-    };
-}
-```
-
-#### Destructuring with Defaults
-
-```javascript
-// Extract values with fallbacks
-handleRecordLoad(record) {
-    const {
-        Name = 'Unknown',
-        Industry = 'Not Specified',
-        AnnualRevenue = 0
-    } = record.fields;
-
-    this.accountName = Name.value;
-    this.industry = Industry.value;
-    this.revenue = AnnualRevenue.value;
-}
-```
-
-#### Nested Destructuring
-
-```javascript
-// Deep extraction in single statement
-processResult(result) {
-    const {
-        data: {
-            record: {
-                fields: { Name, BillingCity }
-            }
-        },
-        error
-    } = result;
-
-    if (error) {
-        this.handleError(error);
-        return;
-    }
-
-    this.name = Name.value;
-    this.city = BillingCity.value;
-}
-```
-
-#### Array Spread Patterns
-
-```javascript
-// Immutable array updates (required for LWC reactivity)
-addItem(newItem) {
-    this.items = [...this.items, newItem];  // Append
-}
-
-removeItem(index) {
-    this.items = [
-        ...this.items.slice(0, index),
-        ...this.items.slice(index + 1)
-    ];  // Remove at index
-}
-
-updateItem(index, updates) {
-    this.items = this.items.map((item, i) =>
-        i === index ? { ...item, ...updates } : item
-    );  // Update at index
-}
-```
-
-#### Parameter Spreading in Apex Calls
-
-```javascript
-async handleSubmit() {
-    const result = await createRecord({
-        ...this.recordData,
-        CreatedBy__c: this.currentUserId,
-        Status__c: 'Pending'
-    });
-}
-```
-
-### When to Use Each Pattern
-
-| Pattern | Best For | Avoid When |
-|---------|----------|------------|
-| `lwc:spread` | Many dynamic attributes, base component wrappers | Need event binding, simple static props |
-| Object spread | Config merging, immutable updates | Deep objects (consider structuredClone) |
-| Destructuring | Extracting multiple values, API responses | Simple single-property access |
-| Array spread | Adding/removing items immutably | Large arrays (performance concern) |
-
----
-
-## Complex Template Expressions (Spring '26 Beta - API 66.0)
-
-Spring '26 introduces **complex template expressions**, enabling JavaScript expressions directly in templates. This was previously limited to simple property and getter bindings.
-
-> ⚠️ **Beta Feature**: Use getters in production until this becomes GA. Document any complex expressions for future migration.
-
-### Before vs After
-
-```html
-<!-- BEFORE Spring '26: Required getters for any logic -->
-<template>
-    <!-- Simple property binding only -->
-    <template lwc:if={isValid}>...</template>
-
-    <!-- Complex conditions needed a getter -->
-    <template lwc:if={showLoadingState}>...</template>
-</template>
-```
-
-```javascript
-// Required getter in JS
-get showLoadingState() {
-    return this.isLoading && this.items.length === 0;
-}
-```
-
-```html
-<!-- AFTER Spring '26 (Beta): Complex expressions in template -->
-<template>
-    <!-- Logical operators -->
-    <template lwc:if={!isLoading && items.length > 0}>
-        <c-item-list items={items}></c-item-list>
-    </template>
-
-    <!-- Optional chaining -->
-    <template lwc:if={user?.permissions?.canEdit}>
-        <lightning-button label="Edit"></lightning-button>
-    </template>
-
-    <!-- Arithmetic expressions -->
-    <span class="slds-text-body_small">
-        Total: ${total * taxRate}
-    </span>
-
-    <!-- Comparison operators -->
-    <template lwc:if={items.length >= minItems}>
-        <c-pagination></c-pagination>
-    </template>
-</template>
-```
-
-### Supported Expression Types
-
-| Expression Type | Example | Notes |
-|-----------------|---------|-------|
-| **Logical NOT** | `{!isLoading}` | Negation |
-| **Logical AND** | `{a && b}` | Short-circuit evaluation |
-| **Logical OR** | `{a \|\| b}` | Short-circuit evaluation |
-| **Comparison** | `{count > 0}`, `{status === 'active'}` | `==`, `===`, `!=`, `!==`, `<`, `>`, `<=`, `>=` |
-| **Arithmetic** | `{price * quantity}` | `+`, `-`, `*`, `/`, `%` |
-| **Optional Chaining** | `{user?.profile?.name}` | Safe property access |
-| **Nullish Coalescing** | `{value ?? 'default'}` | Default for null/undefined |
-| **Ternary** | `{isActive ? 'Yes' : 'No'}` | Conditional value |
-| **Array Access** | `{items[0]}` | Index-based access |
-| **String Concatenation** | `{firstName + ' ' + lastName}` | String joining |
-
-### Best Practices for Complex Expressions
-
-```html
-<!-- ✅ GOOD: Simple inline logic -->
-<template lwc:if={!isLoading && hasData}>
-    ...
-</template>
-
-<!-- ✅ GOOD: Optional chaining for safety -->
-<span>{account?.Owner?.Name}</span>
-
-<!-- ⚠️ CAUTION: Keep expressions readable -->
-<!-- If expression is long, consider a getter for maintainability -->
-<template lwc:if={isEditable && hasPermission && !isLocked && status === 'draft'}>
-    <!-- Consider: get canEdit() { return ...; } -->
-</template>
-
-<!-- ❌ AVOID: Side effects in expressions -->
-<!-- Don't call methods that modify state -->
-```
-
-### Migration Strategy
-
-1. **New code**: Use complex expressions for simple conditions
-2. **Existing code**: Keep getters that have unit tests
-3. **Complex logic**: Continue using getters for maintainability
-4. **Document**: Mark complex expressions in templates for review when GA
-
-### Limitations (Beta)
-
-- No function calls in expressions (use getters)
-- No template literals with `${}` interpolation
-- Cannot reference `this` directly
-- No destructuring in expressions
-
----
-
-## Template Directives
-
-### Conditional Rendering: Legacy → Modern
-
-Always use `lwc:if`, `lwc:elseif`, `lwc:else` instead of the deprecated `if:true` / `if:false` directives.
-
-```html
-<!-- ❌ Legacy (deprecated) -->
-<template if:true={isLoading}>
-    <lightning-spinner></lightning-spinner>
-</template>
-<template if:false={isLoading}>
-    <c-data-view data={records}></c-data-view>
-</template>
-
-<!-- ✅ Modern -->
-<template lwc:if={isLoading}>
-    <lightning-spinner></lightning-spinner>
-</template>
-<template lwc:elseif={error}>
-    <c-error-panel errors={error}></c-error-panel>
-</template>
-<template lwc:else>
-    <c-data-view data={records}></c-data-view>
-</template>
-```
-
-**Rules**: Conditional directives are valid on `<template>`, standard HTML tags, custom components, and base components. All elements in a conditional group must be siblings at the same DOM level.
-
-### List Rendering
-
-#### for:each
-
-Every `for:each` must be paired with `for:item`. The `key` attribute must use a stable unique identifier — always `key={item.id}`, never an index.
-
-```html
-<!-- ✅ GOOD -->
-<template for:each={accounts} for:item="account">
-    <c-account-card key={account.Id} account={account}></c-account-card>
-</template>
-
-<!-- ❌ BAD: key={index} or key={account.Name} -->
-```
-
-#### iterator Directive
-
-Use `iterator` when you need access to `.first` or `.last` metadata for conditional styling.
-
-```html
-<template iterator:it={contacts}>
-    <div key={it.value.Id}>
-        {it.value.Name}
-    </div>
-</template>
-```
-
-**Iterator name must be lowercase**. Access item data via `{iteratorname}.value.property` and metadata via `.index`, `.first`, `.last`.
-
-#### Nested Loop Rules
-
-Use distinct `for:item` or `iterator` names in nested loops to avoid variable shadowing:
-
-```html
-<!-- ✅ Distinct names -->
-<template for:each={departments} for:item="dept">
-    <div key={dept.Id}>
-        <template for:each={dept.Employees} for:item="emp">
-            <span key={emp.Id}>{emp.Name}</span>
-        </template>
-    </div>
-</template>
-```
-
-### Multiple Template Rendering
-
-When a component needs to switch between entirely different layouts, import multiple HTML templates and return the appropriate one from `render()`.
-
-```javascript
-import defaultTemplate from './myComponent.html';
-import editTemplate from './myComponentEdit.html';
-
-export default class MyComponent extends LightningElement {
-    isEditing = false;
-
-    render() {
-        return this.isEditing ? editTemplate : defaultTemplate;
-    }
-}
-```
-
----
-
-## Performance Optimization (PICKLES: Execution)
-
-### Lifecycle Hook Guidance
-
-| Hook | When to Use | Avoid |
-|------|-------------|-------|
-| `constructor()` | Initialize properties | DOM access (not ready) |
-| `connectedCallback()` | Subscribe to events, fetch data | Heavy processing |
-| `renderedCallback()` | DOM-dependent logic | Infinite loops, property changes |
-| `disconnectedCallback()` | Cleanup subscriptions/listeners | Async operations |
-
-### Lazy Loading
-
-```html
-<!-- Only render when needed -->
-<template lwc:if={showDetails}>
-    <c-expensive-component record-id={recordId}></c-expensive-component>
-</template>
-```
-
-### Efficient Rendering
-
-```javascript
-// Bad: Creates new array every render
-get filteredItems() {
-    return this.items.filter(item => item.active);
-}
-
-// Good: Cache the result
-_filteredItems;
-_itemsHash;
-
-get filteredItems() {
-    const currentHash = JSON.stringify(this.items);
-    if (currentHash !== this._itemsHash) {
-        this._filteredItems = this.items.filter(item => item.active);
-        this._itemsHash = currentHash;
-    }
-    return this._filteredItems;
-}
-```
-
-### Virtual Scrolling
-
-Use `lightning-datatable` with `enable-infinite-loading` for large datasets instead of rendering all items.
-
-**For comprehensive performance patterns** (DOM optimization, event delegation, memory management, bundle size): see `references/performance-guide.md`
-
----
-
-## Advanced Jest Testing Patterns
-
-Based on [James Simone's advanced testing patterns](https://www.jamessimone.net/blog/joys-of-apex/advanced-lwc-jest-testing/).
-
-### Render Cycle Helper
-
-LWC re-rendering is asynchronous. Use this helper to document and await render cycles:
-
-```javascript
-// testUtils.js
-export const runRenderingLifecycle = async (reasons = ['render']) => {
-    while (reasons.length > 0) {
-        await Promise.resolve(reasons.pop());
-    }
-};
-
-// Usage in tests
-it('updates after property change', async () => {
-    const element = createElement('c-example', { is: Example });
-    document.body.appendChild(element);
-
-    element.greeting = 'new value';
-    await runRenderingLifecycle(['property change', 'render']);
-
-    expect(element.shadowRoot.querySelector('div').textContent).toBe('new value');
-});
-```
-
-### Proxy Unboxing (Lightning Web Security)
-
-Lightning Web Security proxifies objects. Unbox them for assertions:
-
-```javascript
-// LWS proxifies complex objects - unbox for comparison
-const unboxedData = JSON.parse(JSON.stringify(component.data));
-expect(unboxedData).toEqual(expectedData);
-```
-
-### DOM Cleanup Pattern
-
-Clean up after each test to prevent state bleed:
-
-```javascript
-describe('c-my-component', () => {
-    afterEach(() => {
-        // Clean up DOM
-        while (document.body.firstChild) {
-            document.body.removeChild(document.body.firstChild);
-        }
-        jest.clearAllMocks();
-    });
-});
-```
-
-### ResizeObserver Polyfill
-
-Some components use ResizeObserver. Add polyfill in jest.setup.js:
-
-```javascript
-// jest.setup.js
-if (!window.ResizeObserver) {
-    window.ResizeObserver = class ResizeObserver {
-        constructor(callback) {
-            this.callback = callback;
-        }
-        observe() {}
-        unobserve() {}
-        disconnect() {}
-    };
-}
-```
-
-### Mocking Apex Methods
-
-```javascript
-jest.mock('@salesforce/apex/MyController.getData', () => ({
-    default: jest.fn()
-}), { virtual: true });
-
-// In test
-import getData from '@salesforce/apex/MyController.getData';
-
-it('displays data', async () => {
-    getData.mockResolvedValue(MOCK_DATA);
-    // ... test code
-});
-```
-
----
-
-## Security Best Practices (PICKLES: Security)
-
-### FLS Enforcement
-
-```apex
-// Always use SECURITY_ENFORCED or stripInaccessible
-@AuraEnabled(cacheable=true)
-public static List<Account> getAccounts() {
-    return [SELECT Id, Name FROM Account WITH SECURITY_ENFORCED];
-}
-
-// For DML operations
-SObjectAccessDecision decision = Security.stripInaccessible(
-    AccessType.CREATABLE,
-    records
-);
-insert decision.getRecords();
-```
-
-### Input Sanitization
-
-```apex
-// Apex should escape user input
-String searchKey = '%' + String.escapeSingleQuotes(searchTerm) + '%';
-```
-
-### XSS Prevention
-
-LWC automatically escapes content in templates. Never bypass this.
-
-```html
-<!-- Safe: LWC auto-escapes -->
-<p>{userInput}</p>
-```
-
-### Input Validation Patterns
-
-#### Lightning Base Component Validation Attributes
-
-Use built-in validation attributes on Lightning input components to enforce constraints declaratively:
-
-```html
-<lightning-input
-    label="Email"
-    type="email"
-    required
-    max-length="255"
-    message-when-value-missing="Email is required"
-    message-when-pattern-mismatch="Enter a valid email address"
-    onchange={handleEmailChange}>
-</lightning-input>
-```
-
-#### Form Submission Validation
-
-Always validate all inputs before processing a form submission:
-
-```javascript
-handleSubmit() {
-    const allValid = [...this.template.querySelectorAll('lightning-input')]
-        .reduce((valid, input) => {
-            input.reportValidity();
-            return valid && input.checkValidity();
-        }, true);
-
-    if (!allValid) {
-        return;  // Stop — validation errors displayed to user
-    }
-
-    this.saveRecord();
-}
-```
-
-#### Custom Validation with setCustomValidity
-
-```javascript
-handleBlur(event) {
-    const input = event.target;
-    if (input.value && !this.isUniqueName(input.value)) {
-        input.setCustomValidity('This name is already in use');
-    } else {
-        input.setCustomValidity('');  // Always clear when valid
-    }
-    input.reportValidity();
-}
-```
-
-### Scoped Module Imports
-
-Always use static `@salesforce/` scoped imports instead of legacy Global Value Providers (`$Label`, `$Resource`, etc.)
-
----
-
-## Accessibility (a11y)
-
-### Required Practices
-
-| Element | Requirement |
-|---------|-------------|
-| Buttons | `label` or `aria-label` |
-| Icons | `alternative-text` |
-| Form inputs | Associated `<label>` |
-| Dynamic content | `aria-live` region |
-| Loading states | `aria-busy="true"` |
-
-### Keyboard Navigation
-
-```javascript
-handleKeyDown(event) {
-    switch (event.key) {
-        case 'Enter':
-        case ' ':
-            this.handleSelect(event);
-            break;
-        case 'Escape':
-            this.handleClose();
-            break;
-        case 'ArrowDown':
-            this.focusNext();
-            event.preventDefault();
-            break;
-    }
-}
-```
-
-### Focus Trap Pattern (for Modals)
-
-Based on [James Simone's modal pattern](https://www.jamessimone.net/blog/joys-of-apex/lwc-composable-modal/):
-
-```javascript
-_focusableElements = [];
-
-_onOpen() {
-    // Collect focusable elements
-    this._focusableElements = [
-        ...this.querySelectorAll('.focusable'),
-        ...this.template.querySelectorAll('lightning-button, button, [tabindex="0"]')
-    ].filter(el => !el.disabled);
-
-    // Focus first element
-    this._focusableElements[0]?.focus();
-
-    // Add ESC handler
-    window.addEventListener('keyup', this._handleKeyUp);
-}
-
-_handleKeyUp = (event) => {
-    if (event.code === 'Escape') {
-        this.close();
-    }
-}
-
-disconnectedCallback() {
-    window.removeEventListener('keyup', this._handleKeyUp);
-}
-```
-
----
-
-## SLDS 2 & Dark Mode
-
-### Dark Mode Checklist
-
-- [ ] No hardcoded hex colors (`#FFFFFF`, `#333333`)
-- [ ] No hardcoded RGB/RGBA values
-- [ ] All colors use CSS variables (`var(--slds-g-color-*)`)
-- [ ] Fallback values provided for SLDS 1 compatibility
-- [ ] Icons use SLDS utility icons (auto-adjust for dark mode)
-
-### SLDS 1 → SLDS 2 Migration
-
-```css
-/* BEFORE (SLDS 1 - Deprecated) */
-.my-card {
-    background-color: #ffffff;
-    color: #333333;
-}
-
-/* AFTER (SLDS 2 - Dark Mode Ready) */
-.my-card {
-    background-color: var(--slds-g-color-surface-container-1, #ffffff);
-    color: var(--slds-g-color-on-surface, #181818);
-}
-```
-
-### Key Global Styling Hooks
-
-| Category | SLDS 2 Variable |
-|----------|-----------------|
-| Surface | `--slds-g-color-surface-1` to `-4` |
-| Text | `--slds-g-color-on-surface` |
-| Border | `--slds-g-color-border-1`, `-2` |
-| Spacing | `--slds-g-spacing-0` to `-12` |
-
-**Important**: `--slds-c-*` (component-level hooks) are NOT supported in SLDS 2 yet.
-
----
-
-## CSS Isolation & Scoping
-
-LWC uses Shadow DOM for style encapsulation. Follow these rules to prevent style leakage and collisions.
-
-### CSS Selector Rules
-
-| Pattern | Status | Reason |
-|---------|--------|--------|
-| `:host` | ✅ Use | Targets the component's root element |
-| `:host(.modifier)` | ✅ Use | Conditional styling based on host class |
-| `.my-class` | ✅ Use | Class selectors scoped automatically |
-| `*` (universal) | ❌ Avoid | Can leak outside component scope |
-| `#my-id` | ❌ Avoid | LWC transforms IDs to globally unique values |
-| `c-my-component` | ❌ Avoid | Use `:host` instead of component name |
-| `:host-context()` | ❌ Not supported | Use `:host` instead |
-| `lightning-button` | ❌ Avoid | Cannot override base component internals |
-| `.slds-button` | ❌ Avoid | Cannot replace or override SLDS classes |
-
-```css
-/* ❌ BAD: Universal selector leaks */
-* { font-family: Arial, sans-serif; }
-
-/* ✅ GOOD: Scoped universal */
-:host * { font-family: Arial, sans-serif; }
-
-/* ❌ BAD: Component name as selector */
-c-my-component { display: flex; }
-
-/* ✅ GOOD: :host for component-level styles */
-:host { display: flex; }
-
-/* ❌ BAD: Overriding base component or SLDS */
-lightning-button { background-color: red; }
-.slds-button { background-color: purple; }
-
-/* ✅ GOOD: Use styling hooks */
-:host {
-    --slds-c-button-brand-color-background: red;
-}
-```
-
-### Avoid `!important` Overuse
-
-Rely on proper specificity rather than `!important` declarations. Excessive `!important` interferes with parent component styling and makes future maintenance difficult.
-
-### Never Rely on Compiler-Generated Scope Tokens
-
-```css
-/* ❌ BAD: Brittle — token changes across builds */
-c-child[lwc-2j48dfhd928c-host] { padding: 1rem; }
-
-/* ✅ GOOD */
-:host { padding: 1rem; }
-```
-
----
-
-## Testing Checklist
-
-### Unit Test Coverage
-
-- [ ] Component renders without errors
-- [ ] Data displays correctly when loaded
-- [ ] Error state displays when fetch fails
-- [ ] Empty state displays when no data
-- [ ] Events dispatch with correct payload
-- [ ] User interactions work correctly
-- [ ] Loading states are shown/hidden appropriately
-
-### Manual Testing
-
-- [ ] Works in Lightning Experience
-- [ ] Works in Salesforce Mobile
-- [ ] Works in Experience Cloud (if targeted)
-- [ ] Works in Dark Mode (SLDS 2)
-- [ ] Keyboard navigation works
-- [ ] Screen reader announces properly
-- [ ] No console errors
-- [ ] Performance acceptable with real data
-
----
-
-## Common Mistakes
-
-### 1. Modifying @api Properties
-
-```javascript
-// ❌ BAD
-@api items;
-handleClick() {
-    this.items.push(newItem);  // Mutation!
-}
-
-// ✅ GOOD
-handleClick() {
-    this.items = [...this.items, newItem];
-}
-```
-
-### 2. Forgetting to Clean Up
-
-```javascript
-// ❌ BAD: Memory leak
-connectedCallback() {
-    this.subscription = subscribe(...);
-}
-
-// ✅ GOOD
-disconnectedCallback() {
-    unsubscribe(this.subscription);
-}
-```
-
-### 3. Wire with Non-Reactive Parameters
-
-```javascript
-// ❌ BAD
-let recordId = '001xxx';
-@wire(getRecord, { recordId: recordId })
-
-// ✅ GOOD
-@api recordId;
-@wire(getRecord, { recordId: '$recordId' })
-```
-
----
-
-## Resources
-
-- [PICKLES Framework](https://www.salesforceben.com/the-ideal-framework-for-architecting-salesforce-lightning-web-components/) — David Picksley, Third Eye Consulting
-- [LWC Recipes (GitHub)](https://github.com/trailheadapps/lwc-recipes)
-- [SLDS 2 Transition Guide](https://www.lightningdesignsystem.com/2e1ef8501/p/8184ad-transition-to-slds-2)
-- [James Simone - Advanced Jest Testing](https://www.jamessimone.net/blog/joys-of-apex/advanced-lwc-jest-testing/)
-- [James Simone - Composable Modal](https://www.jamessimone.net/blog/joys-of-apex/lwc-composable-modal/)
-- [SLDS Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties.html)