agent-docs 1.3.0 → 1.4.0

package/docs/LWCHTMLTEMPLATES.md

@@ -11,20 +11,23 @@
 ## Template Structure
 
 - **Root element:** `<template>` (renders as `<namespace-component-name>`)
-- **Nested `<template>` tags:** required for directives; only allowed attributes:
-  - `for:each`, `iterator:iteratorname`, `lwc:if`, `lwc:else`, `lwc:elseif`, `if:true|false`
-  - No other directives or HTML attributes (e.g., no `class` on nested `<template>`)
+- **Nested `<template>` tags:** required for directives; only allowed
+  attributes:
+    - `for:each`, `iterator:iteratorname`, `lwc:if`, `lwc:else`, `lwc:elseif`,
+      `if:true|false`
+    - No other directives or HTML attributes (e.g., no `class` on nested
+      `<template>`)
 - **No inline `<style>` or `<script>` tags** — use separate CSS/JS files
 - Follow Lightning Design System patterns and accessibility guidelines
 
 ## Data Binding & Expressions
 
-| Syntax | Usage |
-|--------|-------|
-| `{property}` | Bind data (no spaces around property) |
-| `{data.name}` | Dot notation supported |
-| `{!property}` | Two-way binding (form inputs) |
-| `{handlerMethod}` | Event handler binding |
+| Syntax            | Usage                                 |
+| ----------------- | ------------------------------------- |
+| `{property}`      | Bind data (no spaces around property) |
+| `{data.name}`     | Dot notation supported                |
+| `{!property}`     | Two-way binding (form inputs)         |
+| `{handlerMethod}` | Event handler binding                 |
 
 ### Allowed Expression Syntax
 
@@ -40,8 +43,7 @@ The `{expression}` binding syntax **only** supports:
 
 ```html
 <!-- ❌ Logical operators -->
-{isReadOnly || isLoading}
-{isActive && isVisible}
+{isReadOnly || isLoading} {isActive && isVisible}
 
 <!-- ❌ Negation operator -->
 {!isDisabled}
@@ -50,28 +52,22 @@ The `{expression}` binding syntax **only** supports:
 {isActive ? 'active' : 'inactive'}
 
 <!-- ❌ Arithmetic -->
-{count + 1}
-{price * quantity}
+{count + 1} {price * quantity}
 
 <!-- ❌ Array indexing -->
-{items[0].name}
-{person[2].name['John']}
+{items[0].name} {person[2].name['John']}
 
 <!-- ❌ Function calls in templates -->
-{formatDate(startDate)}
-{calculateTotal()}
+{formatDate(startDate)} {calculateTotal()}
 
 <!-- ❌ String concatenation -->
-{'Hello ' + name}
-{`Item: ${itemName}`}
+{'Hello ' + name} {`Item: ${itemName}`}
 
 <!-- ❌ Comparisons -->
-{count > 0}
-{status === 'active'}
+{count > 0} {status === 'active'}
 
 <!-- ❌ Nullish coalescing / optional chaining in binding -->
-{user?.name}
-{value ?? 'default'}
+{user?.name} {value ?? 'default'}
 ```
 
 ### ✅ The Solution: Use JavaScript Getters
@@ -79,75 +75,78 @@ The `{expression}` binding syntax **only** supports:
 All computed logic **must** be moved to getters in the JavaScript class:
 
 **JavaScript (myComponent.js):**
+
 ```javascript
 import { LightningElement, api, track } from 'lwc';
 
 export default class MyComponent extends LightningElement {
-    @api isReadOnly = false;
-    @api isLoading = false;
-    @track items = [];
-    
-    // ✅ Logical operators → getter
-    get isDisabled() {
-        return this.isReadOnly || this.isLoading;
-    }
-    
-    // ✅ Negation → getter
-    get isEnabled() {
-        return !this.isDisabled;
-    }
-    
-    // ✅ Ternary → getter
-    get buttonLabel() {
-        return this.isLoading ? 'Loading...' : 'Submit';
-    }
-    
-    // ✅ Arithmetic → getter
-    get itemCountPlusOne() {
-        return this.count + 1;
-    }
-    
-    // ✅ Array indexing → getter
-    get firstItemName() {
-        return this.items[0]?.name || '';
-    }
-    
-    // ✅ String formatting → getter
-    get formattedCount() {
-        return `${this.count} items`;
-    }
-    
-    // ✅ Comparisons for conditional rendering → getter
-    get hasItems() {
-        return this.items.length > 0;
-    }
-    
-    // ✅ Complex class computation → getter
-    get containerClass() {
-        return {
-            'slds-box': true,
-            'slds-theme_shade': this.isActive,
-            'slds-hide': !this.isVisible
-        };
-    }
+	@api isReadOnly = false;
+	@api isLoading = false;
+	@track items = [];
+
+	// ✅ Logical operators → getter
+	get isDisabled() {
+		return this.isReadOnly || this.isLoading;
+	}
+
+	// ✅ Negation → getter
+	get isEnabled() {
+		return !this.isDisabled;
+	}
+
+	// ✅ Ternary → getter
+	get buttonLabel() {
+		return this.isLoading ? 'Loading...' : 'Submit';
+	}
+
+	// ✅ Arithmetic → getter
+	get itemCountPlusOne() {
+		return this.count + 1;
+	}
+
+	// ✅ Array indexing → getter
+	get firstItemName() {
+		return this.items[0]?.name || '';
+	}
+
+	// ✅ String formatting → getter
+	get formattedCount() {
+		return `${this.count} items`;
+	}
+
+	// ✅ Comparisons for conditional rendering → getter
+	get hasItems() {
+		return this.items.length > 0;
+	}
+
+	// ✅ Complex class computation → getter
+	get containerClass() {
+		return {
+			'slds-box': true,
+			'slds-theme_shade': this.isActive,
+			'slds-hide': !this.isVisible,
+		};
+	}
 }
 ```
 
 **HTML (myComponent.html):**
+
 ```html
 <template>
-    <template lwc:if={hasItems}>
-        <div class={containerClass}>
-            <p>{formattedCount}</p>
-            <p>First item: {firstItemName}</p>
-        </div>
-    </template>
-    
-    <lightning-button 
-        label={buttonLabel} 
-        disabled={isDisabled}
-        onclick={handleClick}>
-    </lightning-button>
+	<template lwc:if="{hasItems}">
+		<div class="{containerClass}">
+			<p>{formattedCount}</p>
+			<p>First item: {firstItemName}</p>
+		</div>
+	</template>
+
+	<lightning-button
+		label="{buttonLabel}"
+		disabled="{isDisabled}"
+		onclick="{handleClick}"
+	>
+	</lightning-button>
 </template>
 ```
 
@@ -155,17 +154,20 @@ export default class MyComponent extends LightningElement {
 
 Salesforce made this intentional choice for:
 
-| Reason | Explanation |
-|--------|-------------|
-| **Performance** | Simple property lookups are fast; no runtime expression parsing/evaluation |
-| **Security** | No risk of template injection or expression-based exploits |
-| **Predictability** | Reactivity is straightforward—change a property, component re-renders |
-| **Testability** | All logic lives in unit-testable JavaScript, not scattered in templates |
-| **Debugging** | Stack traces point to JS files, not opaque template expressions |
+| Reason             | Explanation                                                                |
+| ------------------ | -------------------------------------------------------------------------- |
+| **Performance**    | Simple property lookups are fast; no runtime expression parsing/evaluation |
+| **Security**       | No risk of template injection or expression-based exploits                 |
+| **Predictability** | Reactivity is straightforward—change a property, component re-renders      |
+| **Testability**    | All logic lives in unit-testable JavaScript, not scattered in templates    |
+| **Debugging**      | Stack traces point to JS files, not opaque template expressions            |
 
 ### AI Agent Rule Summary
 
-> **LWC Template Expression Rule:** The `{...}` binding syntax accepts ONLY property names and dot-notation paths. Any logic requiring operators (`||`, `&&`, `?:`, `+`, `>`, `===`, etc.), function calls, array indexing, or string interpolation MUST be implemented as a getter in the JavaScript class.
+> **LWC Template Expression Rule:** The `{...}` binding syntax accepts ONLY
+> property names and dot-notation paths. Any logic requiring operators (`||`,
+> `&&`, `?:`, `+`, `>`, `===`, etc.), function calls, array indexing, or string
+> interpolation MUST be implemented as a getter in the JavaScript class.
 
 ```
 Template binding:  {propertyName} or {object.nested.property}
@@ -174,41 +176,49 @@ Computed logic:    get computedProperty() { return /* any JS expression */; }
 
 ## Conditional Rendering
 
-Use `lwc:if`, `lwc:elseif`, `lwc:else` directives (prefer over multiple templates for simple conditions):
+Use `lwc:if`, `lwc:elseif`, `lwc:else` directives (prefer over multiple
+templates for simple conditions):
 
 ```html
-<template lwc:if={condition}>...</template>
-<template lwc:elseif={otherCondition}>...</template>
+<template lwc:if="{condition}">...</template>
+<template lwc:elseif="{otherCondition}">...</template>
 <template lwc:else>...</template>
 ```
 
-**Note:** The condition must be a simple property reference or getter—not an expression:
+**Note:** The condition must be a simple property reference or getter—not an
+expression:
 
 ```html
 <!-- ❌ Invalid -->
-<template lwc:if={items.length > 0}>
+<template lwc:if="{items.length">
+	0}>
 
-<!-- ✅ Valid — use a getter -->
-<template lwc:if={hasItems}>
+	<!-- ✅ Valid — use a getter -->
+	<template lwc:if="{hasItems}"></template
+></template>
 ```
 
 ## List Rendering
 
 ### for:each
+
 ```html
-<template for:each={array} for:item="item">
-    <div key={item.uniqueId}>{item.property}</div>
+<template for:each="{array}" for:item="item">
+	<div key="{item.uniqueId}">{item.property}</div>
 </template>
 ```
+
 - `key` required: string/number, **not** index or object
 - Access current item via `for:item="itemName"` → `{itemName.property}`
 
 ### iterator
+
 ```html
-<template iterator:it={array}>
-    <div key={it.value.uniqueId}>{it.value.property}</div>
+<template iterator:it="{array}">
+	<div key="{it.value.uniqueId}">{it.value.property}</div>
 </template>
 ```
+
 - Iterator name must be lowercase
 - Properties: `{it.value.property}`, `{it.index}`, `{it.first}`, `{it.last}`
 - Combine with `lwc:if` for first/last styling: `lwc:if={it.first}`
@@ -219,21 +229,24 @@ Use `lwc:if`, `lwc:elseif`, `lwc:else` directives (prefer over multiple template
 - Override `render()` to return template based on state
 - CSS must match template filename: `templateTwo.html` → `templateTwo.css`
 - Default: `componentName.html` when no `render()` override
-- **Prefer `lwc:if` for simple variations; use multiple templates for significantly different layouts**
+- **Prefer `lwc:if` for simple variations; use multiple templates for
+  significantly different layouts**
 
 ## Class Object Binding (LWC API v62.0+)
 
 Bind dynamic classes using arrays or objects instead of string concatenation:
 
-| Input | Output |
-|-------|--------|
-| `["highlight", "yellow"]` | `class="highlight yellow"` |
-| `{highlight: true, hidden: false}` | `class="highlight"` |
+| Input                              | Output                     |
+| ---------------------------------- | -------------------------- |
+| `["highlight", "yellow"]`          | `class="highlight yellow"` |
+| `{highlight: true, hidden: false}` | `class="highlight"`        |
 
-- Booleans, numbers, functions render as empty string (use `String(value)` if needed)
+- Booleans, numbers, functions render as empty string (use `String(value)` if
+  needed)
 - Use getters to compute complex class combinations
 
 **Example with getter:**
+
 ```javascript
 get cardClasses() {
     return {
@@ -245,7 +258,7 @@ get cardClasses() {
 ```
 
 ```html
-<div class={cardClasses}>...</div>
+<div class="{cardClasses}">...</div>
 ```
 
 ## Inline Style Binding
@@ -253,9 +266,11 @@ get cardClasses() {
 - Syntax: `style={computedStyles}`
 - Getter returns semi-colon separated properties: `width: 50%; font-size: 20px`
 - Use kebab-case CSS properties (`font-size`, not `fontSize`)
-- **Prefer CSS classes over inline styles**; use inline for dynamic/computed values only
+- **Prefer CSS classes over inline styles**; use inline for dynamic/computed
+  values only
 
 **Example:**
+
 ```javascript
 get progressBarStyle() {
     return `width: ${this.progressPercent}%; background-color: ${this.barColor}`;
@@ -263,7 +278,7 @@ get progressBarStyle() {
 ```
 
 ```html
-<div class="progress-bar" style={progressBarStyle}></div>
+<div class="progress-bar" style="{progressBarStyle}"></div>
 ```
 
 ## Event Handling
@@ -275,10 +290,12 @@ get progressBarStyle() {
 
 ```html
 <!-- ❌ Invalid — no inline functions -->
-<button onclick={() => this.handleClick()}>
+<button onclick="{()" ="">
+	this.handleClick()}>
 
-<!-- ✅ Valid — method reference -->
-<button onclick={handleClick}>
+	<!-- ✅ Valid — method reference -->
+	<button onclick="{handleClick}"></button>
+</button>
 ```
 
 ## Accessibility
@@ -292,7 +309,8 @@ get progressBarStyle() {
 - Minimize DOM manipulation
 - Use lazy loading / pagination for large lists
 - Avoid unnecessary rerenders by optimizing data binding
-- Getters are re-evaluated on every render—keep them lightweight or cache expensive computations
+- Getters are re-evaluated on every render—keep them lightweight or cache
+  expensive computations
 
 ## Validation Checklist
 
@@ -303,11 +321,13 @@ get progressBarStyle() {
 - [ ] No inline `<style>` or `<script>` tags
 - [ ] No manual DOM manipulation in JS
 - [ ] Data binding: `{property}` syntax, no spaces
-- [ ] **No computed expressions in templates** (no operators, function calls, array indexing)
+- [ ] **No computed expressions in templates** (no operators, function calls,
+      array indexing)
 - [ ] **All computed logic implemented as getters in JS class**
 - [ ] `for:each`: has `for:item` and unique `key` (string/number)
 - [ ] `iterator`: lowercase name, unique `key={it.value.uniqueId}`
-- [ ] Multiple templates: proper imports, `render()` override, matching CSS filenames
+- [ ] Multiple templates: proper imports, `render()` override, matching CSS
+      filenames
 - [ ] Class binding follows v62.0+ semantics (arrays/objects via getters)
 - [ ] Inline styles: `style={getter}`, kebab-case properties
 - [ ] Valid HTML syntax (use Salesforce Extensions Pack for validation)