slashdev 1.1.0 → 1.2.0

package/claude-skills/salesforce-development/references/lwc-patterns.md

@@ -0,0 +1,374 @@
+# LWC Patterns — Reference
+
+Load this file when building or modifying Lightning Web Components.
+
+---
+
+## Parent-Child Communication
+
+### Parent to child — public properties and methods
+
+Expose properties with `@api` on the child. The parent sets them declaratively in the template.
+
+```javascript
+// childComponent.js
+import { LightningElement, api } from 'lwc';
+
+export default class ChildComponent extends LightningElement {
+    @api recordId;
+    @api variant = 'default';
+
+    // Public method — parent can call this imperatively
+    @api
+    reset() {
+        this.template.querySelectorAll('lightning-input').forEach(input => input.value = '');
+    }
+}
+```
+
+```html
+<!-- parentComponent.html -->
+<template>
+    <c-child-component record-id={selectedId} variant="compact"></c-child-component>
+</template>
+```
+
+Call a child's public method from the parent:
+
+```javascript
+// parentComponent.js
+handleReset() {
+    this.template.querySelector('c-child-component').reset();
+}
+```
+
+### Child to parent — CustomEvent dispatch
+
+Children communicate upward by dispatching `CustomEvent`. The parent listens with an
+`on<eventname>` handler in the template. Event names must be lowercase, no underscores.
+
+```javascript
+// childComponent.js
+handleSelect(event) {
+    const selectedId = event.target.dataset.id;
+    this.dispatchEvent(new CustomEvent('itemselect', {
+        detail: { recordId: selectedId },
+        bubbles: false,   // default — only the direct parent receives it
+        composed: false    // default — does not cross shadow DOM boundary
+    }));
+}
+```
+
+```html
+<!-- parentComponent.html -->
+<template>
+    <c-child-component onitemselect={handleItemSelect}></c-child-component>
+</template>
+```
+
+```javascript
+// parentComponent.js
+handleItemSelect(event) {
+    this.selectedRecordId = event.detail.recordId;
+}
+```
+
+---
+
+## Lightning Message Service (LMS)
+
+Use LMS for communication between **unrelated** components — components in different DOM
+trees, Aura and LWC, or even Visualforce pages on the same Lightning page.
+
+### 1. Create a message channel
+
+```xml
+<!-- force-app/main/default/messageChannels/RecordSelected.messageChannel-meta.xml -->
+<?xml version="1.0" encoding="UTF-8"?>
+<LightningMessageChannel xmlns="http://soap.sforce.com/2006/04/metadata">
+    <masterLabel>Record Selected</masterLabel>
+    <isExposed>true</isExposed>
+    <lightningMessageFields>
+        <fieldName>recordId</fieldName>
+    </lightningMessageFields>
+</LightningMessageChannel>
+```
+
+### 2. Publish
+
+```javascript
+import { LightningElement, wire } from 'lwc';
+import { publish, MessageContext } from 'lightning/messageService';
+import RECORD_SELECTED from '@salesforce/messageChannel/RecordSelected__c';
+
+export default class PublisherComponent extends LightningElement {
+    @wire(MessageContext) messageContext;
+
+    handleClick(event) {
+        publish(this.messageContext, RECORD_SELECTED, {
+            recordId: event.target.dataset.id
+        });
+    }
+}
+```
+
+### 3. Subscribe
+
+```javascript
+import { LightningElement, wire } from 'lwc';
+import { subscribe, unsubscribe, MessageContext } from 'lightning/messageService';
+import RECORD_SELECTED from '@salesforce/messageChannel/RecordSelected__c';
+
+export default class SubscriberComponent extends LightningElement {
+    @wire(MessageContext) messageContext;
+    subscription = null;
+    selectedRecordId;
+
+    connectedCallback() {
+        this.subscription = subscribe(this.messageContext, RECORD_SELECTED, (message) => {
+            this.selectedRecordId = message.recordId;
+        });
+    }
+
+    disconnectedCallback() {
+        unsubscribe(this.subscription);
+        this.subscription = null;
+    }
+}
+```
+
+---
+
+## @wire with Reactive Parameters and refreshApex
+
+### Reactive parameters
+
+Prefix a property with `$` in the `@wire` decorator to make the wire re-fire when the
+property changes.
+
+```javascript
+import { LightningElement, wire } from 'lwc';
+import getContacts from '@salesforce/apex/ContactController.getContacts';
+
+export default class ContactList extends LightningElement {
+    selectedAccountId;
+    
+    @wire(getContacts, { accountId: '$selectedAccountId' })
+    contacts;
+
+    handleAccountChange(event) {
+        this.selectedAccountId = event.detail.value;
+        // Wire automatically re-fires — no manual call needed
+    }
+}
+```
+
+### Refreshing cached wire data
+
+After a write operation, the wire cache is stale. Use `refreshApex` to force a re-fetch.
+
+```javascript
+import { refreshApex } from '@salesforce/apex';
+
+// Store the full wire result (not just .data)
+@wire(getContacts, { accountId: '$selectedAccountId' })
+wiredContactsResult;
+
+async handleSave() {
+    await saveContact({ contact: this.editedContact });
+    // Refresh the wire — pass the ENTIRE wire result, not .data
+    await refreshApex(this.wiredContactsResult);
+}
+```
+
+---
+
+## uiRecordApi vs Apex
+
+`lightning/uiRecordApi` provides client-side record CRUD without writing Apex. It respects
+FLS and sharing automatically. Use it for simple single-record operations.
+
+### When to use uiRecordApi
+
+- Reading/writing a **single record** with known fields
+- You want **automatic FLS enforcement** without extra code
+- No complex logic or cross-object queries needed
+
+### When to use Apex
+
+- Querying **multiple records** with filters, joins, or aggregations
+- Complex business logic before/after the DML
+- Bulk operations
+- Callouts or async processing
+
+### Examples
+
+```javascript
+import { getRecord, getFieldValue } from 'lightning/uiRecordApi';
+import { updateRecord } from 'lightning/uiRecordApi';
+import { createRecord } from 'lightning/uiRecordApi';
+import { deleteRecord } from 'lightning/uiRecordApi';
+import NAME_FIELD from '@salesforce/schema/Account.Name';
+import INDUSTRY_FIELD from '@salesforce/schema/Account.Industry';
+
+// Read
+@wire(getRecord, { recordId: '$recordId', fields: [NAME_FIELD, INDUSTRY_FIELD] })
+account;
+
+get accountName() {
+    return getFieldValue(this.account.data, NAME_FIELD);
+}
+
+// Update
+async handleUpdate() {
+    const fields = {};
+    fields.Id = this.recordId;
+    fields[INDUSTRY_FIELD.fieldApiName] = 'Technology';
+    await updateRecord({ fields });
+}
+
+// Create
+async handleCreate() {
+    const fields = {};
+    fields[NAME_FIELD.fieldApiName] = 'New Account';
+    const record = await createRecord({ apiName: 'Account', fields });
+    this.newRecordId = record.id;
+}
+
+// Delete
+async handleDelete() {
+    await deleteRecord(this.recordId);
+}
+```
+
+---
+
+## Error Handling — reduceErrors and ShowToastEvent
+
+### reduceErrors utility
+
+LWC errors come in multiple shapes (wire errors, imperative errors, UI API errors). This
+utility normalizes them into a string array.
+
+```javascript
+// utils/reduceErrors.js
+export function reduceErrors(errors) {
+    if (!Array.isArray(errors)) {
+        errors = [errors];
+    }
+
+    return errors
+        .filter((error) => !!error)
+        .map((error) => {
+            if (Array.isArray(error.body)) {
+                return error.body.map((e) => e.message);
+            }
+            if (typeof error.body?.message === 'string') {
+                return error.body.message;
+            }
+            if (typeof error.message === 'string') {
+                return error.message;
+            }
+            return error.statusText || 'Unknown error';
+        })
+        .flat();
+}
+```
+
+### ShowToastEvent for user-facing messages
+
+```javascript
+import { ShowToastEvent } from 'lightning/platformShowToastEvent';
+
+// Success
+this.dispatchEvent(new ShowToastEvent({
+    title: 'Success',
+    message: 'Record saved successfully',
+    variant: 'success'
+}));
+
+// Error with reduceErrors
+this.dispatchEvent(new ShowToastEvent({
+    title: 'Error',
+    message: reduceErrors(error).join(', '),
+    variant: 'error',
+    mode: 'sticky'  // stays until dismissed — use for errors
+}));
+```
+
+---
+
+## Navigation via NavigationMixin
+
+```javascript
+import { LightningElement } from 'lwc';
+import { NavigationMixin } from 'lightning/navigation';
+
+export default class NavigationExample extends NavigationMixin(LightningElement) {
+
+    // Navigate to a record page
+    navigateToRecord(recordId) {
+        this[NavigationMixin.Navigate]({
+            type: 'standard__recordPage',
+            attributes: {
+                recordId: recordId,
+                objectApiName: 'Account',
+                actionName: 'view'
+            }
+        });
+    }
+
+    // Navigate to a list view
+    navigateToListView() {
+        this[NavigationMixin.Navigate]({
+            type: 'standard__objectPage',
+            attributes: {
+                objectApiName: 'Account',
+                actionName: 'list'
+            },
+            state: {
+                filterName: 'Recent'
+            }
+        });
+    }
+
+    // Navigate to a custom tab / Lightning page
+    navigateToTab() {
+        this[NavigationMixin.Navigate]({
+            type: 'standard__navItemPage',
+            attributes: {
+                apiName: 'MyCustomTab'
+            }
+        });
+    }
+
+    // Generate a URL without navigating
+    async getRecordUrl(recordId) {
+        return this[NavigationMixin.GenerateUrl]({
+            type: 'standard__recordPage',
+            attributes: {
+                recordId: recordId,
+                actionName: 'view'
+            }
+        });
+    }
+}
+```
+
+---
+
+## @salesforce/* Scoped Imports
+
+These are compile-time imports resolved by the Lightning platform. They cannot be mocked
+in standard Jest tests without `@salesforce/sfdx-lwc-jest` shims.
+
+| Import | Purpose | Example |
+|--------|---------|---------|
+| `@salesforce/apex/ClassName.methodName` | Call an Apex method | `import getAccounts from '@salesforce/apex/AccountCtrl.getAccounts'` |
+| `@salesforce/schema/Object.Field` | Reference a field (compile-time validated) | `import NAME from '@salesforce/schema/Account.Name'` |
+| `@salesforce/user/Id` | Current user's ID | `import userId from '@salesforce/user/Id'` |
+| `@salesforce/label/c.MyLabel` | Custom label | `import greeting from '@salesforce/label/c.WelcomeMessage'` |
+| `@salesforce/resourceUrl/MyResource` | Static resource URL | `import LOGO from '@salesforce/resourceUrl/CompanyLogo'` |
+| `@salesforce/i18n/lang` | User's language/locale | `import LANG from '@salesforce/i18n/lang'` |
+| `@salesforce/messageChannel/ChannelName__c` | Message channel for LMS | See LMS section above |
+| `@salesforce/customPermission/PermName` | Check custom permission | `import hasPerm from '@salesforce/customPermission/ManageAccounts'` |