@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/generating-lwc-components/references/triangle-pattern.md

@@ -0,0 +1,365 @@
+<!-- Parent: generating-lwc-components/SKILL.md -->
+# Flow-LWC-Apex Triangle: LWC Perspective
+
+The **Triangle Architecture** is a foundational Salesforce pattern where Flow, LWC, and Apex work together. This guide focuses on the **LWC role** in this architecture.
+
+---
+
+## Architecture Overview
+
+```
+                         ┌─────────────────────────────────────┐
+                         │              FLOW                   │
+                         │         (Orchestrator)              │
+                         └───────────────┬─────────────────────┘
+                                         │
+              ┌──────────────────────────┼──────────────────────────┐
+              │                          │                          │
+              │ screens                  │ actionCalls              │
+              │ <componentInstance>      │ actionType="apex"        │
+              │                          │                          │
+              ▼                          ▼                          ▲
+┌─────────────────────────┐    ┌─────────────────────────┐         │
+│          LWC            │    │         APEX            │         │
+│     (UI Component)      │───▶│   (Business Logic)      │─────────┘
+│                         │    │                         │
+│ • Rich UI/UX        ◀── YOU ARE HERE                   │
+│ • User Interaction      │    │ • @InvocableMethod      │
+│ • FlowAttribute         │    │ • @AuraEnabled          │
+│   ChangeEvent           │    │ • Complex Logic         │
+│ • FlowNavigation        │    │ • DML Operations        │
+│   FinishEvent           │    │                         │
+└─────────────────────────┘    └─────────────────────────┘
+              │                          ▲
+              │      @AuraEnabled        │
+              │      wire / imperative   │
+              └──────────────────────────┘
+```
+
+---
+
+## LWC's Role in the Triangle
+
+| Communication Path | Mechanism | Direction |
+|-------------------|-----------|-----------|
+| Flow → LWC | `inputParameters` → `@api` | One-way input |
+| LWC → Flow | `FlowAttributeChangeEvent` | Event-based output |
+| LWC → Flow Nav | `FlowNavigationFinishEvent` | Navigation command |
+| LWC → Apex | `@wire` or `imperative` | Async call |
+| Apex → LWC | Return value / wire refresh | Response |
+
+---
+
+## Pattern 1: Flow Screen Component
+
+**Use Case**: Custom UI component for user selection within a guided Flow.
+
+```
+┌─────────┐     @api (in)      ┌─────────┐
+│  FLOW   │ ────────────────▶  │   LWC   │
+│ Screen  │                    │  Screen │
+│         │ ◀────────────────  │Component│
+│         │  FlowAttribute     │         │
+└─────────┘   ChangeEvent      └─────────┘
+```
+
+### LWC JavaScript
+
+```javascript
+import { LightningElement, api } from 'lwc';
+import { FlowAttributeChangeEvent, FlowNavigationFinishEvent } from 'lightning/flowSupport';
+
+export default class RecordSelector extends LightningElement {
+    // Input from Flow (read-only in component)
+    @api recordId;
+    @api availableActions = [];
+
+    // Output to Flow (must dispatch event to update)
+    @api selectedRecordId;
+
+    handleSelect(event) {
+        // Update local property
+        this.selectedRecordId = event.detail.id;
+
+        // CRITICAL: Dispatch event to update Flow variable
+        this.dispatchEvent(new FlowAttributeChangeEvent(
+            'selectedRecordId',  // Must match @api property name
+            this.selectedRecordId
+        ));
+    }
+
+    handleFinish() {
+        // Navigate Flow to next screen
+        if (this.availableActions.find(action => action === 'NEXT')) {
+            this.dispatchEvent(new FlowNavigationFinishEvent('NEXT'));
+        }
+    }
+}
+```
+
+### LWC meta.xml (Flow Target)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>66.0</apiVersion>
+    <isExposed>true</isExposed>
+    <masterLabel>Record Selector</masterLabel>
+    <description>Custom record selection component for Flow screens</description>
+    <targets>
+        <target>lightning__FlowScreen</target>
+    </targets>
+    <targetConfigs>
+        <targetConfig targets="lightning__FlowScreen">
+            <property name="recordId" type="String" label="Record ID" description="Parent record ID"/>
+            <property name="selectedRecordId" type="String" label="Selected Record ID" role="outputOnly"/>
+        </targetConfig>
+    </targetConfigs>
+</LightningComponentBundle>
+```
+
+### Property Roles
+
+| Role | Description | Flow Behavior |
+|------|-------------|---------------|
+| (none) | Input/Output | Editable in Flow builder |
+| `role="inputOnly"` | Input only | Cannot be used as output |
+| `role="outputOnly"` | Output only | Read-only in Flow builder |
+
+---
+
+## Pattern 2: LWC Calling Apex
+
+**Use Case**: LWC needs data or operations beyond Flow context.
+
+### Wire Pattern (Reactive, Cached)
+
+```javascript
+import { LightningElement, api, wire } from 'lwc';
+import getRecords from '@salesforce/apex/RecordController.getRecords';
+
+export default class RecordList extends LightningElement {
+    @api recordId;
+    records;
+    error;
+
+    @wire(getRecords, { parentId: '$recordId' })
+    wiredRecords({ error, data }) {
+        if (data) {
+            this.records = data;
+            this.error = undefined;
+        } else if (error) {
+            this.error = error;
+            this.records = undefined;
+        }
+    }
+}
+```
+
+### Imperative Pattern (On-Demand, Fresh)
+
+```javascript
+import { LightningElement, api } from 'lwc';
+import { FlowNavigationFinishEvent } from 'lightning/flowSupport';
+import processRecord from '@salesforce/apex/RecordController.processRecord';
+
+export default class RecordProcessor extends LightningElement {
+    @api recordId;
+    @api availableActions = [];
+    isProcessing = false;
+
+    async handleSubmit() {
+        this.isProcessing = true;
+        try {
+            const result = await processRecord({ recordId: this.recordId });
+            if (result.isSuccess) {
+                // Navigate Flow forward
+                this.dispatchEvent(new FlowNavigationFinishEvent('NEXT'));
+            }
+        } catch (error) {
+            // Handle error (show toast, etc.)
+            console.error('Processing failed:', error.body.message);
+        } finally {
+            this.isProcessing = false;
+        }
+    }
+}
+```
+
+### When to Use Each Pattern
+
+| Pattern | Use When | Caching |
+|---------|----------|---------|
+| `@wire` | Data should refresh when inputs change | Yes (cacheable=true) |
+| Imperative | User-triggered action, DML needed | No |
+
+---
+
+## Pattern 3: Full Triangle Integration
+
+**Use Case**: LWC in Flow screen that calls Apex for complex operations.
+
+```javascript
+import { LightningElement, api, wire } from 'lwc';
+import { FlowAttributeChangeEvent, FlowNavigationFinishEvent } from 'lightning/flowSupport';
+import getProducts from '@salesforce/apex/ProductController.getProducts';
+import calculatePricing from '@salesforce/apex/PricingService.calculate';
+
+export default class ProductSelector extends LightningElement {
+    @api accountId;           // Input from Flow
+    @api selectedProducts;    // Output to Flow
+    @api totalPrice;          // Output to Flow
+    @api availableActions = [];
+
+    products;
+    selectedIds = new Set();
+
+    // Wire: Fetch products reactively
+    @wire(getProducts, { accountId: '$accountId' })
+    wiredProducts({ data, error }) {
+        if (data) this.products = data;
+    }
+
+    handleProductSelect(event) {
+        const productId = event.target.dataset.id;
+        if (this.selectedIds.has(productId)) {
+            this.selectedIds.delete(productId);
+        } else {
+            this.selectedIds.add(productId);
+        }
+        this.updateFlowOutputs();
+    }
+
+    async updateFlowOutputs() {
+        // Update selected products output
+        this.selectedProducts = Array.from(this.selectedIds);
+        this.dispatchEvent(new FlowAttributeChangeEvent(
+            'selectedProducts',
+            this.selectedProducts
+        ));
+
+        // Imperative: Calculate pricing
+        const result = await calculatePricing({
+            productIds: this.selectedProducts
+        });
+        this.totalPrice = result.total;
+        this.dispatchEvent(new FlowAttributeChangeEvent(
+            'totalPrice',
+            this.totalPrice
+        ));
+    }
+
+    handleNext() {
+        this.dispatchEvent(new FlowNavigationFinishEvent('NEXT'));
+    }
+}
+```
+
+---
+
+## Jest Testing (Flow Integration)
+
+```javascript
+import { createElement } from 'lwc';
+import RecordSelector from 'c/recordSelector';
+import { FlowAttributeChangeEvent, FlowNavigationFinishEvent } from 'lightning/flowSupport';
+
+// Mock lightning/flowSupport
+jest.mock('lightning/flowSupport', () => ({
+    FlowAttributeChangeEvent: jest.fn(),
+    FlowNavigationFinishEvent: jest.fn()
+}), { virtual: true });
+
+describe('c-record-selector', () => {
+    afterEach(() => {
+        while (document.body.firstChild) {
+            document.body.removeChild(document.body.firstChild);
+        }
+        jest.clearAllMocks();
+    });
+
+    it('dispatches FlowAttributeChangeEvent on selection', async () => {
+        const element = createElement('c-record-selector', {
+            is: RecordSelector
+        });
+        element.recordId = '001xx000003GYHAA2';
+        document.body.appendChild(element);
+
+        // Simulate user selection
+        const handler = jest.fn();
+        element.addEventListener('flowattributechange', handler);
+
+        const tile = element.shadowRoot.querySelector('[data-id]');
+        tile.click();
+
+        // Verify FlowAttributeChangeEvent was constructed
+        expect(FlowAttributeChangeEvent).toHaveBeenCalledWith(
+            'selectedRecordId',
+            expect.any(String)
+        );
+    });
+
+    it('dispatches FlowNavigationFinishEvent on finish', async () => {
+        const element = createElement('c-record-selector', {
+            is: RecordSelector
+        });
+        element.availableActions = ['NEXT', 'FINISH'];
+        document.body.appendChild(element);
+
+        const finishButton = element.shadowRoot.querySelector('.finish-button');
+        finishButton.click();
+
+        expect(FlowNavigationFinishEvent).toHaveBeenCalledWith('NEXT');
+    });
+});
+```
+
+---
+
+## Deployment Order
+
+When deploying integrated triangle solutions:
+
+```
+1. APEX CLASSES
+   └── @AuraEnabled controllers (LWC depends on these)
+
+2. LWC COMPONENTS      ← Deploy SECOND
+   └── meta.xml with lightning__FlowScreen target
+   └── JavaScript with Flow imports
+
+3. FLOWS
+   └── Reference deployed LWC components
+```
+
+---
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| Missing FlowAttributeChangeEvent | Output never updates in Flow | Always dispatch event when output changes |
+| Direct @api property mutation for outputs | Flow doesn't see changes | Use FlowAttributeChangeEvent |
+| Mixing @wire and imperative for same data | Cache/freshness conflicts | Choose one pattern per data need |
+| Calling Apex for Flow-available data | Unnecessary callouts | Pass via inputParameters |
+| Hardcoded navigation actions | Breaks in different contexts | Check availableActions first |
+
+---
+
+## Flow Events Reference
+
+| Event | Purpose | Parameters |
+|-------|---------|------------|
+| `FlowAttributeChangeEvent` | Update output property | (propertyName, value) |
+| `FlowNavigationFinishEvent` | Navigate Flow | 'NEXT', 'BACK', 'PAUSE', 'FINISH' |
+
+---
+
+## Related Documentation
+
+| Topic | Location |
+|-------|----------|
+| Flow screen component template | `generating-lwc-components/assets/flow-screen-component/` |
+| LWC best practices | `generating-lwc-components/references/lwc-best-practices.md` |
+| Apex triangle perspective | `sf-apex/references/triangle-pattern.md` |
+| Flow triangle perspective | `sf-flow/references/triangle-pattern.md` |

package/skills/generating-lwc-components/scripts/local-dev-preview.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Local Development Server — preview LWC components with hot reload (no deployment needed).
+# Requires an active org connection. Commands install just-in-time on first run and open
+# a browser with live preview. Changes to .js, .html, and .css files auto-reload instantly.
+#
+# Usage: Pass --target-org <alias> and choose the mode that matches your use case.
+
+TARGET_ORG="${1:-}"
+
+if [ -z "$TARGET_ORG" ]; then
+    echo "Usage: $0 <org-alias> [component|app|site]"
+    echo "  component  Preview a single LWC component in isolation (default)"
+    echo "  app        Preview a Lightning Experience app locally"
+    echo "  site       Preview an Experience Cloud site locally"
+    exit 1
+fi
+
+MODE="${2:-component}"
+
+case "$MODE" in
+    component)
+        sf lightning dev component --target-org "$TARGET_ORG"
+        ;;
+    app)
+        sf lightning dev app --target-org "$TARGET_ORG"
+        ;;
+    site)
+        sf lightning dev site --target-org "$TARGET_ORG"
+        ;;
+    *)
+        echo "Unknown mode: $MODE. Choose one of: component, app, site"
+        exit 1
+        ;;
+esac

package/skills/generating-mermaid-diagrams/CREDITS.md

@@ -0,0 +1,46 @@
+# Credits & Acknowledgments
+
+This skill was built upon established patterns in technical diagramming and Salesforce data modeling. The following concepts and conventions shaped its design.
+
+---
+
+## Diagramming Concepts
+
+### Text-Based Diagramming
+The skill uses Mermaid as its primary diagramming syntax, covering Entity Relationship Diagrams, sequence diagrams, and flowcharts. Key capabilities include:
+
+- Entity Relationship Diagram syntax
+- Sequence diagram patterns
+- Flowchart and state diagram support
+- Live rendering through Mermaid-capable renderers
+
+An alternative syntax, PlantUML, informed the UML diagram patterns used in sequence and class diagrams.
+
+---
+
+## Salesforce Domain Patterns
+
+### Data Modeling Conventions
+The ERD conventions follow standard Salesforce object relationship patterns, including Master-Detail, Lookup, and External relationships as documented in the Salesforce platform's object model.
+
+### Integration Architecture
+Integration sequence diagrams draw on widely-adopted API documentation patterns adapted for Salesforce's authentication and integration architecture.
+
+### Schema Reference
+Object and field relationship information reflects standard Salesforce object reference conventions and relationship type definitions.
+
+---
+
+## Key Concepts
+
+### ERD Notation
+The Entity Relationship Diagram conventions follow standard database modeling patterns adapted for Salesforce relationships (Master-Detail, Lookup, External).
+
+### Sequence Diagram Patterns
+OAuth flow and integration sequence diagrams follow UML 2.0 standards with Salesforce-specific adaptations.
+
+### Mermaid in Documentation
+The approach of using Mermaid for inline diagrams in Markdown documentation is a widely-adopted pattern in technical documentation that enables version-controlled diagrams alongside code.
+
+### Color Accessibility
+The color palette follows accessibility guidelines for color-blind-friendly design, using a pastel fill with high-contrast stroke approach.

package/skills/generating-mermaid-diagrams/README.md

@@ -0,0 +1,114 @@
+# generating-mermaid-diagrams
+
+> Salesforce architecture diagram generation using Mermaid syntax with ASCII fallback
+
+## Overview
+
+`generating-mermaid-diagrams` is a Salesforce architecture diagram skill that generates professional diagrams using Mermaid syntax with ASCII art fallback for terminal compatibility.
+
+## Features
+
+- **OAuth Flows** - Authorization Code, PKCE, JWT Bearer, Client Credentials, Device Flow
+- **Data Models** - ERD diagrams with generating-custom-object integration
+- **Integrations** - Sequence diagrams for API patterns
+- **Architecture** - System landscape overviews
+- **Role Hierarchies** - Security model visualization
+- **Agentforce** - Agent topic and action flows
+- **Accessible** - Color-blind friendly palette
+- **Terminal Friendly** - ASCII fallback for all diagrams
+
+## Quick Start
+
+```
+# Generate an OAuth diagram
+"Create a JWT Bearer OAuth flow diagram"
+
+# Generate a data model
+"Create an ERD for Account, Contact, and Opportunity"
+
+# Generate an integration diagram
+"Diagram our Salesforce to SAP sync flow"
+```
+
+## Diagram Types
+
+| Type | Template | Use Case |
+|------|----------|----------|
+| Authorization Code | `oauth/authorization-code.md` | Web apps with backends |
+| PKCE Flow | `oauth/authorization-code-pkce.md` | Mobile/SPA apps |
+| JWT Bearer | `oauth/jwt-bearer.md` | Server-to-server, CI/CD |
+| Client Credentials | `oauth/client-credentials.md` | Service accounts |
+| Device Flow | `oauth/device-authorization.md` | CLI tools, IoT |
+| Refresh Token | `oauth/refresh-token.md` | Token renewal |
+| Data Model | `datamodel/salesforce-erd.md` | Object relationships |
+| Integration | `integration/api-sequence.md` | API callout patterns |
+| Architecture | `architecture/system-landscape.md` | System overview |
+| Role Hierarchy | `role-hierarchy/user-hierarchy.md` | Security model |
+| Agentforce | `agentforce/agent-flow.md` | AI agent architecture |
+
+## Scoring System (80 Points)
+
+| Category | Points | Criteria |
+|----------|--------|----------|
+| Accuracy | 20 | Correct actors, flow steps, relationships |
+| Clarity | 20 | Readable labels, logical layout |
+| Completeness | 15 | All key elements included |
+| Styling | 15 | Color scheme, theming, annotations |
+| Best Practices | 10 | Proper notation, UML conventions |
+
+## Color Palette
+
+Tailwind-inspired pastel colors with dark borders (see [references/color-palette.md](references/color-palette.md)):
+
+| Component | Fill (200) | Stroke (700+) |
+|-----------|------------|---------------|
+| AI & Agents | `#fbcfe8` | `#be185d` |
+| Integration | `#fed7aa` | `#c2410c` |
+| Development | `#ddd6fe` | `#6d28d9` |
+| Metadata | `#a5f3fc` | `#0e7490` |
+| Data | `#fde68a` | `#b45309` |
+| Deploy | `#a7f3d0` | `#047857` |
+
+## Example Output
+
+### Mermaid Diagram
+```mermaid
+sequenceDiagram
+    autonumber
+    participant A as Server
+    participant SF as Salesforce
+
+    A->>A: Create JWT
+    A->>SF: POST /token (JWT)
+    SF->>SF: Validate Signature
+    SF->>A: Access Token
+```
+
+### ASCII Fallback
+```
+┌───────────────┐     ┌───────────────┐
+│    Server     │     │   Salesforce  │
+└───────┬───────┘     └───────┬───────┘
+        │  1. Create JWT      │
+        │  2. POST /token     │
+        │────────────────────>│
+        │                     │
+        │  3. Validate JWT    │
+        │                     │
+        │  4. Access Token    │
+        │<────────────────────│
+```
+
+## Cross-Skill Integration
+
+| Skill | Integration |
+|-------|-------------|
+| generating-custom-object / generating-custom-field | Auto-discover objects/fields for ERD |
+| configuring-connected-apps | Link OAuth flows to app setup |
+| developing-agentforce | Visualize agent architecture |
+
+## Documentation
+
+- [Color Palette](references/color-palette.md) - Styling guide
+- [Mermaid Reference](references/mermaid-reference.md) - Syntax quick reference
+- [Diagram Conventions](references/diagram-conventions.md) - Consistency rules