@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/generating-lwc-components/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: generating-lwc-components
+description: "Lightning Web Components with PICKLES methodology and 165-point scoring. Use this skill when the user creates or edits LWC components, builds wire service patterns, or writes Jest tests for LWC. TRIGGER when: user creates/edits LWC components, touches lwc/**/*.js, .html, .css, .js-meta.xml files, or asks about wire service, SLDS, or Jest LWC tests. DO NOT TRIGGER when: Apex classes (use generating-apex), Aura components, or Visualforce."
+license: MIT
+metadata:
+  version: "1.1"
+---
+
+# generating-lwc-components: Lightning Web Components Development
+
+Use this skill when the user needs **Lightning Web Components**: LWC bundles, wire patterns, Apex/GraphQL integration, SLDS 2 styling, accessibility, performance work, or Jest unit tests.
+
+## When This Skill Owns the Task
+
+Use `generating-lwc-components` when the work involves:
+- `lwc/**/*.js`, `.html`, `.css`, `.js-meta.xml`
+- component scaffolding and bundle design
+- wire service, Apex integration, GraphQL integration
+- SLDS 2, dark mode, and accessibility work
+- Jest unit tests for LWC
+
+Delegate elsewhere when the user is:
+- writing Apex controllers or business logic first → [generating-apex](../generating-apex/SKILL.md)
+- building Flow XML rather than an LWC screen component → [generating-flow](../generating-flow/SKILL.md)
+- deploying metadata → [deploying-metadata](../deploying-metadata/SKILL.md)
+
+---
+
+## Required Context to Gather First
+
+Ask for or infer:
+- component purpose and target surface
+- data source: LDS, Apex, GraphQL, LMS, or external system via Apex
+- whether the user needs tests
+- whether the component must run in Flow, App Builder, Experience Cloud, or dashboard contexts
+- accessibility and styling expectations
+
+---
+
+## Recommended Workflow
+
+### 1. Choose the right architecture
+Use the **PICKLES** mindset:
+- prototype
+- integrate the right data source
+- compose component boundaries
+- define interaction model
+- use platform libraries
+- optimize execution
+- enforce security
+
+### 2. Choose the right data access pattern
+| Need | Default pattern |
+|---|---|
+| single-record UI | LDS / `getRecord` |
+| simple CRUD form | base record form components |
+| complex server query | Apex `@AuraEnabled(cacheable=true)` |
+| related graph data | GraphQL wire adapter |
+| cross-DOM communication | Lightning Message Service |
+
+### 3. Start from an asset when useful
+Use provided assets for:
+- basic component bundles
+- datatables
+- modal patterns
+- Flow screen components
+- GraphQL components
+- LMS message channels
+- Jest tests
+- TypeScript-enabled components
+
+### 4. Validate for frontend quality
+Check:
+- accessibility
+- SLDS 2 / dark mode compliance
+- event contracts
+- performance / rerender safety
+- Jest coverage when required
+
+### 5. Hand off supporting backend or deploy work
+Use:
+- [generating-apex](../generating-apex/SKILL.md) for controllers / services
+- [deploying-metadata](../deploying-metadata/SKILL.md) for deployment
+- [running-apex-tests](../running-apex-tests/SKILL.md) only for Apex-side test loops, not Jest
+
+---
+
+## High-Signal Rules
+
+- prefer platform base components over reinventing controls
+- use `@wire` for reactive read-only use cases; imperative calls for explicit actions and DML paths
+- do not introduce inaccessible custom UI
+- avoid hardcoded colors; use SLDS 2-compatible styling hooks / variables
+- avoid rerender loops in `renderedCallback()`
+- keep component communication patterns explicit and minimal
+
+---
+
+## Output Format
+
+When finishing, report in this order:
+1. **Component(s) created or updated**
+2. **Data access pattern chosen**
+3. **Files changed**
+4. **Accessibility / styling / testing notes**
+5. **Next implementation or deploy step**
+
+Suggested shape:
+
+```text
+LWC work: <summary>
+Pattern: <wire / apex / graphql / lms / flow-screen>
+Files: <paths>
+Quality: <a11y, SLDS2, dark mode, Jest>
+Next step: <deploy, add controller, or run tests>
+```
+
+---
+
+## Local Development Server
+
+Preview LWC components locally with hot reload — no deployment needed. Run the commands in `scripts/local-dev-preview.sh` to start a local dev session for a component, app, or Experience Cloud site.
+
+Local Dev commands install just-in-time on first run. They are long-running processes that open a browser with live preview. Changes to `.js`, `.html`, and `.css` files auto-reload instantly. Requires an active org connection for data and Apex callouts.
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to | Reason |
+|---|---|---|
+| Apex controller or service | [generating-apex](../generating-apex/SKILL.md) | backend logic |
+| embed in Flow screens | [generating-flow](../generating-flow/SKILL.md) | declarative orchestration |
+| deploy component bundle | [deploying-metadata](../deploying-metadata/SKILL.md) | org rollout |
+| create supporting metadata (message channels, objects) | [deploying-metadata](../deploying-metadata/SKILL.md) | metadata deployment |
+
+---
+
+## Reference File Index
+
+### Start here
+- [references/component-patterns.md](references/component-patterns.md) — component architecture patterns and bundle design
+- [references/slds-design-guide.md](references/slds-design-guide.md) — SLDS 2 styling, dark mode, CSS hooks
+- [references/lwc-best-practices.md](references/lwc-best-practices.md) — high-signal rules and anti-patterns
+- [references/scoring-and-testing.md](references/scoring-and-testing.md) — 165-point scoring rubric across 8 categories
+- [references/jest-testing.md](references/jest-testing.md) — Jest unit test patterns and async rendering helpers
+- [references/slds-blueprints.json](references/slds-blueprints.json) — machine-readable SLDS component blueprints
+- [references/cli-commands.md](references/cli-commands.md) — SF CLI commands for LWC development
+
+### Accessibility / performance / state
+- [references/accessibility-guide.md](references/accessibility-guide.md) — WCAG, ARIA, keyboard navigation patterns
+- [references/performance-guide.md](references/performance-guide.md) — lazy loading, debouncing, rerender safety
+- [references/state-management.md](references/state-management.md) — reactive state patterns and LMS
+- [references/template-anti-patterns.md](references/template-anti-patterns.md) — common HTML template mistakes to avoid
+
+### Integration / advanced features
+- [references/lms-guide.md](references/lms-guide.md) — Lightning Message Service patterns
+- [references/flow-integration-guide.md](references/flow-integration-guide.md) — Flow screen component design
+- [references/advanced-features.md](references/advanced-features.md) — Spring '26 features: TypeScript, lwc:on, GraphQL mutations
+- [references/async-notification-patterns.md](references/async-notification-patterns.md) — toast, notifications, async flows
+- [references/triangle-pattern.md](references/triangle-pattern.md) — parent-child-sibling communication triangle
+
+### Asset templates
+- [assets/basic-component/basicComponent.js](assets/basic-component/basicComponent.js) — wire service, error/loading states, event dispatching
+- [assets/datatable-component/datatableComponent.js](assets/datatable-component/datatableComponent.js) — datatable with inline editing
+- [assets/flow-screen-component/flowScreenComponent.js](assets/flow-screen-component/flowScreenComponent.js) — Flow screen with input/output properties
+- [assets/form-component/formComponent.js](assets/form-component/formComponent.js) — form validation and DML patterns
+- [assets/graphql-component/graphqlComponent.js](assets/graphql-component/graphqlComponent.js) — GraphQL wire adapter with cursor-based pagination
+- [assets/jest-test/componentName.test.js.example](assets/jest-test/componentName.test.js.example) — Jest test template (copy and rename, remove `.example` suffix)
+- [assets/message-channel/lmsPublisher.js](assets/message-channel/lmsPublisher.js) — LMS publisher pattern
+- [assets/message-channel/lmsSubscriber.js](assets/message-channel/lmsSubscriber.js) — LMS subscriber pattern
+- [assets/modal-component/modalComponent.js](assets/modal-component/modalComponent.js) — modal with focus trap and ESC handling
+- [assets/record-picker/recordPicker.js](assets/record-picker/recordPicker.js) — record picker with search
+- [assets/state-store/store.js](assets/state-store/store.js) — reactive state store for cross-component state
+- [assets/typescript-component/typescriptComponent.ts](assets/typescript-component/typescriptComponent.ts) — TypeScript-enabled component (Spring '26)
+- [assets/workspace-api/workspaceComponent.js](assets/workspace-api/workspaceComponent.js) — workspace API for tab and focus management
+- [assets/apex-controller/LwcController.cls](assets/apex-controller/LwcController.cls) — Apex controller with `@AuraEnabled(cacheable=true)` patterns
+
+### Scripts
+- [scripts/local-dev-preview.sh](scripts/local-dev-preview.sh) — local dev server commands for component, app, and site preview
+
+---
+
+## Score Guide
+
+| Score | Meaning |
+|---|---|
+| 150+ | production-ready LWC bundle |
+| 125–149 | strong component with minor polish left |
+| 100–124 | functional but review recommended |
+| < 100 | needs significant improvement |

package/skills/generating-lwc-components/assets/apex-controller/LwcController.cls

@@ -0,0 +1,327 @@
+/**
+ * APEX CONTROLLER TEMPLATE FOR LWC
+ *
+ * This template demonstrates @AuraEnabled methods for LWC with:
+ * - Cacheable methods for wire service
+ * - Non-cacheable methods for data mutations
+ * - Proper error handling
+ * - Security enforcement
+ * - Bulk-safe patterns
+ *
+ * Replace: LwcController → YourControllerName
+ */
+public with sharing class LwcController {
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // CACHEABLE METHODS (For @wire service)
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * Get records for display in LWC
+     * Use with @wire decorator for automatic caching and refresh
+     *
+     * @param parentId - Parent record ID (optional filter)
+     * @param searchTerm - Search filter (optional)
+     * @param limitSize - Max records to return
+     * @return List of Account records
+     */
+    @AuraEnabled(cacheable=true)
+    public static List<Account> getAccounts(Id parentId, String searchTerm, Integer limitSize) {
+        try {
+            Integer recordLimit = limitSize != null ? limitSize : 50;
+            String searchKey = String.isNotBlank(searchTerm)
+                ? '%' + String.escapeSingleQuotes(searchTerm) + '%'
+                : '%';
+
+            return [
+                SELECT Id, Name, Industry, AnnualRevenue, Phone, CreatedDate
+                FROM Account
+                WHERE Name LIKE :searchKey
+                WITH SECURITY_ENFORCED
+                ORDER BY Name
+                LIMIT :recordLimit
+            ];
+        } catch (Exception e) {
+            throw new AuraHandledException(e.getMessage());
+        }
+    }
+
+    /**
+     * Get single record by ID
+     */
+    @AuraEnabled(cacheable=true)
+    public static Account getAccountById(Id accountId) {
+        try {
+            List<Account> accounts = [
+                SELECT Id, Name, Industry, AnnualRevenue, Phone, BillingAddress,
+                       (SELECT Id, FirstName, LastName, Email FROM Contacts LIMIT 5)
+                FROM Account
+                WHERE Id = :accountId
+                WITH SECURITY_ENFORCED
+                LIMIT 1
+            ];
+
+            if (accounts.isEmpty()) {
+                throw new AuraHandledException('Account not found');
+            }
+
+            return accounts[0];
+        } catch (Exception e) {
+            throw new AuraHandledException(e.getMessage());
+        }
+    }
+
+    /**
+     * Get picklist values for a field
+     */
+    @AuraEnabled(cacheable=true)
+    public static List<PicklistOption> getIndustryOptions() {
+        List<PicklistOption> options = new List<PicklistOption>();
+
+        Schema.DescribeFieldResult fieldResult = Account.Industry.getDescribe();
+        List<Schema.PicklistEntry> entries = fieldResult.getPicklistValues();
+
+        for (Schema.PicklistEntry entry : entries) {
+            if (entry.isActive()) {
+                options.add(new PicklistOption(entry.getLabel(), entry.getValue()));
+            }
+        }
+
+        return options;
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // NON-CACHEABLE METHODS (For data mutations)
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * Create a new account
+     *
+     * @param accountData - JSON string of account fields
+     * @return Created Account with Id
+     */
+    @AuraEnabled
+    public static Account createAccount(String accountData) {
+        try {
+            // Parse JSON to Map
+            Map<String, Object> fieldMap = (Map<String, Object>) JSON.deserializeUntyped(accountData);
+
+            // Create Account record
+            Account newAccount = new Account();
+            newAccount.Name = (String) fieldMap.get('Name');
+            newAccount.Industry = (String) fieldMap.get('Industry');
+            newAccount.Phone = (String) fieldMap.get('Phone');
+
+            // Validate required fields
+            if (String.isBlank(newAccount.Name)) {
+                throw new AuraHandledException('Account name is required');
+            }
+
+            // Insert with security check
+            SObjectAccessDecision decision = Security.stripInaccessible(
+                AccessType.CREATABLE,
+                new List<Account>{ newAccount }
+            );
+            insert decision.getRecords();
+
+            return (Account) decision.getRecords()[0];
+        } catch (DmlException e) {
+            throw new AuraHandledException(e.getDmlMessage(0));
+        } catch (Exception e) {
+            throw new AuraHandledException(e.getMessage());
+        }
+    }
+
+    /**
+     * Update an existing account
+     *
+     * @param accountId - Record ID to update
+     * @param accountData - JSON string of fields to update
+     * @return Updated Account
+     */
+    @AuraEnabled
+    public static Account updateAccount(Id accountId, String accountData) {
+        try {
+            // Verify record exists and user has access
+            List<Account> existing = [
+                SELECT Id FROM Account
+                WHERE Id = :accountId
+                WITH SECURITY_ENFORCED
+                LIMIT 1
+            ];
+
+            if (existing.isEmpty()) {
+                throw new AuraHandledException('Account not found or access denied');
+            }
+
+            // Parse and apply updates
+            Map<String, Object> fieldMap = (Map<String, Object>) JSON.deserializeUntyped(accountData);
+
+            Account accountToUpdate = new Account(Id = accountId);
+
+            if (fieldMap.containsKey('Name')) {
+                accountToUpdate.Name = (String) fieldMap.get('Name');
+            }
+            if (fieldMap.containsKey('Industry')) {
+                accountToUpdate.Industry = (String) fieldMap.get('Industry');
+            }
+            if (fieldMap.containsKey('Phone')) {
+                accountToUpdate.Phone = (String) fieldMap.get('Phone');
+            }
+
+            // Update with security check
+            SObjectAccessDecision decision = Security.stripInaccessible(
+                AccessType.UPDATABLE,
+                new List<Account>{ accountToUpdate }
+            );
+            update decision.getRecords();
+
+            // Return refreshed record
+            return getAccountById(accountId);
+        } catch (DmlException e) {
+            throw new AuraHandledException(e.getDmlMessage(0));
+        } catch (Exception e) {
+            throw new AuraHandledException(e.getMessage());
+        }
+    }
+
+    /**
+     * Delete records
+     *
+     * @param recordIds - List of record IDs to delete
+     */
+    @AuraEnabled
+    public static void deleteAccounts(List<Id> recordIds) {
+        try {
+            if (recordIds == null || recordIds.isEmpty()) {
+                throw new AuraHandledException('No records specified for deletion');
+            }
+
+            // Query records to verify access
+            List<Account> accountsToDelete = [
+                SELECT Id FROM Account
+                WHERE Id IN :recordIds
+                WITH SECURITY_ENFORCED
+            ];
+
+            if (accountsToDelete.size() != recordIds.size()) {
+                throw new AuraHandledException('Some records not found or access denied');
+            }
+
+            delete accountsToDelete;
+        } catch (DmlException e) {
+            throw new AuraHandledException(e.getDmlMessage(0));
+        } catch (Exception e) {
+            throw new AuraHandledException(e.getMessage());
+        }
+    }
+
+    /**
+     * Bulk update records (for datatable inline editing)
+     *
+     * @param records - List of records with Id and fields to update
+     */
+    @AuraEnabled
+    public static void updateRecords(List<Account> records) {
+        try {
+            if (records == null || records.isEmpty()) {
+                return;
+            }
+
+            // Security check
+            SObjectAccessDecision decision = Security.stripInaccessible(
+                AccessType.UPDATABLE,
+                records
+            );
+
+            update decision.getRecords();
+        } catch (DmlException e) {
+            throw new AuraHandledException(e.getDmlMessage(0));
+        } catch (Exception e) {
+            throw new AuraHandledException(e.getMessage());
+        }
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // PAGINATED QUERY (For infinite scrolling)
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * Get paginated records for infinite scrolling
+     *
+     * @param limitSize - Records per page
+     * @param offset - Starting position
+     * @param sortBy - Field to sort by
+     * @param sortDirection - ASC or DESC
+     * @return PagedResult with records and total count
+     */
+    @AuraEnabled(cacheable=true)
+    public static PagedResult getPagedAccounts(
+        Integer limitSize,
+        Integer offset,
+        String sortBy,
+        String sortDirection
+    ) {
+        try {
+            Integer recordLimit = limitSize != null ? limitSize : 50;
+            Integer recordOffset = offset != null ? offset : 0;
+            String sortField = String.isNotBlank(sortBy) ? sortBy : 'Name';
+            String sortDir = sortDirection == 'desc' ? 'DESC' : 'ASC';
+
+            // Whitelist allowed sort fields to prevent SOQL injection
+            Set<String> allowedSortFields = new Set<String>{
+                'Name', 'Industry', 'AnnualRevenue', 'CreatedDate', 'Phone'
+            };
+
+            if (!allowedSortFields.contains(sortField)) {
+                sortField = 'Name';
+            }
+
+            // Build dynamic query
+            String query = 'SELECT Id, Name, Industry, AnnualRevenue, Phone, CreatedDate ' +
+                          'FROM Account ' +
+                          'WITH SECURITY_ENFORCED ' +
+                          'ORDER BY ' + sortField + ' ' + sortDir + ' NULLS LAST ' +
+                          'LIMIT :recordLimit OFFSET :recordOffset';
+
+            List<Account> records = Database.query(query);
+
+            // Get total count
+            Integer totalCount = [SELECT COUNT() FROM Account WITH SECURITY_ENFORCED];
+
+            return new PagedResult(records, totalCount);
+        } catch (Exception e) {
+            throw new AuraHandledException(e.getMessage());
+        }
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // WRAPPER CLASSES
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /**
+     * Wrapper for picklist options
+     */
+    public class PicklistOption {
+        @AuraEnabled public String label;
+        @AuraEnabled public String value;
+
+        public PicklistOption(String label, String value) {
+            this.label = label;
+            this.value = value;
+        }
+    }
+
+    /**
+     * Wrapper for paginated results
+     */
+    public class PagedResult {
+        @AuraEnabled public List<Account> records;
+        @AuraEnabled public Integer totalCount;
+
+        public PagedResult(List<Account> records, Integer totalCount) {
+            this.records = records;
+            this.totalCount = totalCount;
+        }
+    }
+}

package/skills/generating-lwc-components/assets/basic-component/basicComponent.css

@@ -0,0 +1,72 @@
+/**
+ * BASIC LWC COMPONENT TEMPLATE - CSS
+ *
+ * CSS in LWC is automatically scoped to the component.
+ * Use SLDS (Salesforce Lightning Design System) classes when possible.
+ *
+ * CSS Custom Properties (variables) can be exposed for theming.
+ */
+
+/* Host element styling */
+:host {
+    display: block;
+}
+
+/* Custom properties for theming */
+:host {
+    --card-background: var(--lwc-colorBackground, #ffffff);
+    --card-border-radius: var(--lwc-borderRadiusMedium, 0.25rem);
+    --item-hover-background: var(--lwc-colorBackgroundRowHover, #f3f3f3);
+}
+
+/* List item hover effect */
+.slds-item:hover {
+    background-color: var(--item-hover-background);
+    cursor: pointer;
+}
+
+/* Smooth transitions */
+.slds-tile {
+    transition: background-color 0.2s ease;
+}
+
+/* Loading state fade */
+.slds-spinner {
+    opacity: 0.8;
+}
+
+/* Error state styling */
+.slds-alert_error {
+    border-radius: var(--card-border-radius);
+}
+
+/* Empty state styling */
+.empty-state {
+    padding: 2rem;
+    text-align: center;
+}
+
+/* Responsive adjustments */
+@media (max-width: 480px) {
+    .slds-tile__detail {
+        padding: 0.5rem;
+    }
+
+    .slds-text-heading_small {
+        font-size: 0.875rem;
+    }
+}
+
+/* Focus states for accessibility */
+a:focus {
+    outline: 2px solid var(--lwc-colorBorderBrand, #1589ee);
+    outline-offset: 2px;
+    border-radius: 0.25rem;
+}
+
+/* High contrast mode support */
+@media (prefers-contrast: high) {
+    .slds-item:hover {
+        background-color: highlight;
+    }
+}