@salesforce/afv-skills 1.22.0 → 1.24.0

package/skills/generating-lwc-components/references/lms-guide.md

@@ -1,860 +0,0 @@
-<!-- Parent: generating-lwc-components/SKILL.md -->
-# Lightning Message Service (LMS) Guide
-
-Complete guide to cross-DOM component communication using Lightning Message Service.
-
----
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [When to Use LMS](#when-to-use-lms)
-3. [Message Channel Setup](#message-channel-setup)
-4. [Publishing Messages](#publishing-messages)
-5. [Subscribing to Messages](#subscribing-to-messages)
-6. [Scopes](#scopes)
-7. [Advanced Patterns](#advanced-patterns)
-8. [Best Practices](#best-practices)
-9. [Troubleshooting](#troubleshooting)
-
----
-
-## Overview
-
-Lightning Message Service (LMS) enables communication between components across different DOM contexts:
-- Lightning Web Components (LWC)
-- Aura Components
-- Visualforce pages (in Lightning Experience)
-
-**Key Benefits**:
-- Cross-DOM communication (Shadow DOM boundaries)
-- Loosely coupled components
-- Publish-subscribe pattern
-- Type-safe messaging with message channels
-
----
-
-## When to Use LMS
-
-| Use Case | Recommended Pattern |
-|----------|---------------------|
-| Parent → Child | `@api` properties (simple, direct) |
-| Child → Parent | Custom Events (simple, direct) |
-| Sibling → Sibling (same hierarchy) | Parent mediator + Custom Events |
-| **Cross-DOM communication** | **Lightning Message Service** |
-| **App Builder page components** | **Lightning Message Service** |
-| **Aura ↔ LWC communication** | **Lightning Message Service** |
-| **Visualforce ↔ LWC (in LEX)** | **Lightning Message Service** |
-
-**Rule of Thumb**: Use LMS when components cannot directly reference each other or cross DOM boundaries.
-
----
-
-## Message Channel Setup
-
-### 1. Create Message Channel Metadata
-
-Lightning Message Channels are metadata files that define the message schema.
-
-**File**: `force-app/main/default/messageChannels/AccountSelected__c.messageChannel-meta.xml`
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<LightningMessageChannel xmlns="http://soap.sforce.com/2006/04/metadata">
-    <description>Message channel for account selection events</description>
-    <isExposed>true</isExposed>
-    <lightningMessageFields>
-        <description>Account ID</description>
-        <fieldName>accountId</fieldName>
-    </lightningMessageFields>
-    <lightningMessageFields>
-        <description>Account Name</description>
-        <fieldName>accountName</fieldName>
-    </lightningMessageFields>
-    <lightningMessageFields>
-        <description>Source component identifier</description>
-        <fieldName>source</fieldName>
-    </lightningMessageFields>
-    <masterLabel>Account Selected</masterLabel>
-</LightningMessageChannel>
-```
-
-### 2. Deploy Message Channel
-
-```bash
-sf project deploy start -m LightningMessageChannel:AccountSelected__c
-```
-
-### 3. Import Message Channel in Component
-
-```javascript
-import ACCOUNT_SELECTED_CHANNEL from '@salesforce/messageChannel/AccountSelected__c';
-```
-
----
-
-## Publishing Messages
-
-### Basic Publisher Pattern
-
-```javascript
-// accountPublisher.js
-import { LightningElement, wire } from 'lwc';
-import { publish, MessageContext } from 'lightning/messageService';
-import ACCOUNT_SELECTED_CHANNEL from '@salesforce/messageChannel/AccountSelected__c';
-
-export default class AccountPublisher extends LightningElement {
-    @wire(MessageContext)
-    messageContext;
-
-    handleAccountClick(event) {
-        const accountId = event.target.dataset.id;
-        const accountName = event.target.dataset.name;
-
-        // Create payload
-        const payload = {
-            accountId: accountId,
-            accountName: accountName,
-            source: 'accountPublisher'
-        };
-
-        // Publish message
-        publish(this.messageContext, ACCOUNT_SELECTED_CHANNEL, payload);
-    }
-}
-```
-
-```html
-<!-- accountPublisher.html -->
-<template>
-    <div class="slds-card">
-        <div class="slds-card__header">
-            <h2 class="slds-text-heading_medium">Account List</h2>
-        </div>
-        <div class="slds-card__body">
-            <template for:each={accounts} for:item="account">
-                <div key={account.Id}
-                     class="slds-box slds-m-around_small"
-                     data-id={account.Id}
-                     data-name={account.Name}
-                     onclick={handleAccountClick}>
-                    {account.Name}
-                </div>
-            </template>
-        </div>
-    </div>
-</template>
-```
-
-### Publisher with Conditional Logic
-
-```javascript
-handlePublish(accountData) {
-    // Validate before publishing
-    if (!this.messageContext) {
-        console.error('MessageContext not initialized');
-        return;
-    }
-
-    if (!accountData || !accountData.Id) {
-        console.error('Invalid account data');
-        return;
-    }
-
-    const payload = {
-        accountId: accountData.Id,
-        accountName: accountData.Name,
-        source: this.componentName,
-        timestamp: Date.now()
-    };
-
-    publish(this.messageContext, ACCOUNT_SELECTED_CHANNEL, payload);
-
-    // Optional: Show toast confirmation
-    this.dispatchEvent(new ShowToastEvent({
-        title: 'Selection Published',
-        message: `Account "${accountData.Name}" selected`,
-        variant: 'success'
-    }));
-}
-```
-
----
-
-## Subscribing to Messages
-
-### Basic Subscriber Pattern
-
-```javascript
-// accountSubscriber.js
-import { LightningElement, wire } from 'lwc';
-import { subscribe, unsubscribe, MessageContext, APPLICATION_SCOPE } from 'lightning/messageService';
-import ACCOUNT_SELECTED_CHANNEL from '@salesforce/messageChannel/AccountSelected__c';
-
-export default class AccountSubscriber extends LightningElement {
-    subscription = null;
-    selectedAccountId;
-    selectedAccountName;
-
-    @wire(MessageContext)
-    messageContext;
-
-    connectedCallback() {
-        this.subscribeToChannel();
-    }
-
-    disconnectedCallback() {
-        this.unsubscribeFromChannel();
-    }
-
-    subscribeToChannel() {
-        if (!this.subscription) {
-            this.subscription = subscribe(
-                this.messageContext,
-                ACCOUNT_SELECTED_CHANNEL,
-                (message) => this.handleMessage(message),
-                { scope: APPLICATION_SCOPE }
-            );
-        }
-    }
-
-    unsubscribeFromChannel() {
-        unsubscribe(this.subscription);
-        this.subscription = null;
-    }
-
-    handleMessage(message) {
-        this.selectedAccountId = message.accountId;
-        this.selectedAccountName = message.accountName;
-
-        console.log('Message received from:', message.source);
-        console.log('Account ID:', message.accountId);
-    }
-}
-```
-
-```html
-<!-- accountSubscriber.html -->
-<template>
-    <div class="slds-card">
-        <div class="slds-card__header">
-            <h2 class="slds-text-heading_medium">Selected Account</h2>
-        </div>
-        <div class="slds-card__body">
-            <template lwc:if={selectedAccountId}>
-                <dl class="slds-dl_horizontal">
-                    <dt class="slds-dl_horizontal__label">Account ID:</dt>
-                    <dd class="slds-dl_horizontal__detail">{selectedAccountId}</dd>
-                    <dt class="slds-dl_horizontal__label">Account Name:</dt>
-                    <dd class="slds-dl_horizontal__detail">{selectedAccountName}</dd>
-                </dl>
-            </template>
-            <template lwc:else>
-                <p class="slds-text-color_weak">No account selected</p>
-            </template>
-        </div>
-    </div>
-</template>
-```
-
-### Subscriber with Filtering
-
-```javascript
-handleMessage(message) {
-    // Ignore messages from this component (avoid self-updates)
-    if (message.source === this.componentName) {
-        return;
-    }
-
-    // Filter by specific conditions
-    if (message.accountId && message.accountId.startsWith('001')) {
-        this.selectedAccountId = message.accountId;
-        this.selectedAccountName = message.accountName;
-
-        // Fetch additional data if needed
-        this.loadAccountDetails(message.accountId);
-    }
-}
-
-async loadAccountDetails(accountId) {
-    try {
-        const data = await getAccountDetails({ accountId });
-        this.accountDetails = data;
-    } catch (error) {
-        this.handleError(error);
-    }
-}
-```
-
----
-
-## Scopes
-
-LMS supports two subscription scopes:
-
-| Scope | Behavior | Use Case |
-|-------|----------|----------|
-| `APPLICATION_SCOPE` | Receive messages from entire app | Cross-page communication, global state |
-| `undefined` (default) | Receive messages only within active tab | Tab-specific communication |
-
-### Application Scope Example
-
-```javascript
-import { APPLICATION_SCOPE } from 'lightning/messageService';
-
-subscribe(
-    this.messageContext,
-    ACCOUNT_SELECTED_CHANNEL,
-    (message) => this.handleMessage(message),
-    { scope: APPLICATION_SCOPE }
-);
-```
-
-### Tab Scope Example
-
-```javascript
-// No scope specified = tab scope only
-subscribe(
-    this.messageContext,
-    ACCOUNT_SELECTED_CHANNEL,
-    (message) => this.handleMessage(message)
-);
-```
-
----
-
-## Advanced Patterns
-
-### 1. Multiple Subscriptions
-
-```javascript
-export default class MultiSubscriber extends LightningElement {
-    accountSubscription = null;
-    contactSubscription = null;
-
-    @wire(MessageContext) messageContext;
-
-    connectedCallback() {
-        // Subscribe to account channel
-        this.accountSubscription = subscribe(
-            this.messageContext,
-            ACCOUNT_SELECTED_CHANNEL,
-            (message) => this.handleAccountMessage(message),
-            { scope: APPLICATION_SCOPE }
-        );
-
-        // Subscribe to contact channel
-        this.contactSubscription = subscribe(
-            this.messageContext,
-            CONTACT_SELECTED_CHANNEL,
-            (message) => this.handleContactMessage(message),
-            { scope: APPLICATION_SCOPE }
-        );
-    }
-
-    disconnectedCallback() {
-        unsubscribe(this.accountSubscription);
-        unsubscribe(this.contactSubscription);
-        this.accountSubscription = null;
-        this.contactSubscription = null;
-    }
-
-    handleAccountMessage(message) {
-        // Handle account-specific logic
-    }
-
-    handleContactMessage(message) {
-        // Handle contact-specific logic
-    }
-}
-```
-
-### 2. Publish-Subscribe in Same Component
-
-```javascript
-export default class PublisherSubscriber extends LightningElement {
-    subscription = null;
-    @wire(MessageContext) messageContext;
-
-    connectedCallback() {
-        // Subscribe to messages from OTHER components
-        this.subscription = subscribe(
-            this.messageContext,
-            ACCOUNT_SELECTED_CHANNEL,
-            (message) => this.handleMessage(message),
-            { scope: APPLICATION_SCOPE }
-        );
-    }
-
-    disconnectedCallback() {
-        unsubscribe(this.subscription);
-    }
-
-    handleMessage(message) {
-        // Filter out own messages
-        if (message.source === 'myComponent') {
-            return;
-        }
-        // Process external messages
-        this.selectedAccountId = message.accountId;
-    }
-
-    handleLocalSelection(event) {
-        const accountId = event.detail.id;
-
-        // Publish for other components
-        publish(this.messageContext, ACCOUNT_SELECTED_CHANNEL, {
-            accountId,
-            source: 'myComponent'
-        });
-
-        // Update own state directly (don't rely on subscription)
-        this.selectedAccountId = accountId;
-    }
-}
-```
-
-### 3. Conditional Subscription
-
-```javascript
-export default class ConditionalSubscriber extends LightningElement {
-    @api enableLiveUpdates = false;
-    subscription = null;
-    @wire(MessageContext) messageContext;
-
-    connectedCallback() {
-        if (this.enableLiveUpdates) {
-            this.subscribeToChannel();
-        }
-    }
-
-    @api
-    toggleLiveUpdates(enabled) {
-        this.enableLiveUpdates = enabled;
-        if (enabled) {
-            this.subscribeToChannel();
-        } else {
-            this.unsubscribeFromChannel();
-        }
-    }
-
-    subscribeToChannel() {
-        if (!this.subscription) {
-            this.subscription = subscribe(
-                this.messageContext,
-                ACCOUNT_SELECTED_CHANNEL,
-                (message) => this.handleMessage(message),
-                { scope: APPLICATION_SCOPE }
-            );
-        }
-    }
-
-    unsubscribeFromChannel() {
-        if (this.subscription) {
-            unsubscribe(this.subscription);
-            this.subscription = null;
-        }
-    }
-}
-```
-
-### 4. Message Buffering
-
-```javascript
-export default class MessageBuffer extends LightningElement {
-    messageQueue = [];
-    isProcessing = false;
-
-    handleMessage(message) {
-        this.messageQueue.push(message);
-        this.processQueue();
-    }
-
-    async processQueue() {
-        if (this.isProcessing || this.messageQueue.length === 0) {
-            return;
-        }
-
-        this.isProcessing = true;
-
-        while (this.messageQueue.length > 0) {
-            const message = this.messageQueue.shift();
-            await this.processMessage(message);
-        }
-
-        this.isProcessing = false;
-    }
-
-    async processMessage(message) {
-        // Simulate async processing
-        return new Promise(resolve => {
-            setTimeout(() => {
-                this.selectedAccountId = message.accountId;
-                resolve();
-            }, 100);
-        });
-    }
-}
-```
-
----
-
-## Best Practices
-
-### 1. Always Unsubscribe
-
-```javascript
-disconnectedCallback() {
-    // CRITICAL: Prevent memory leaks
-    if (this.subscription) {
-        unsubscribe(this.subscription);
-        this.subscription = null;
-    }
-}
-```
-
-### 2. Validate MessageContext
-
-```javascript
-handlePublish(data) {
-    if (!this.messageContext) {
-        console.warn('MessageContext not available');
-        return;
-    }
-    publish(this.messageContext, CHANNEL, data);
-}
-```
-
-### 3. Use Descriptive Payloads
-
-```javascript
-// BAD - Unclear payload
-publish(this.messageContext, CHANNEL, { id: '001xxx' });
-
-// GOOD - Clear, descriptive payload
-publish(this.messageContext, CHANNEL, {
-    accountId: '001xxx000003DGQ',
-    accountName: 'Acme Corp',
-    source: 'accountList',
-    timestamp: Date.now(),
-    metadata: {
-        action: 'selected',
-        view: 'list'
-    }
-});
-```
-
-### 4. Document Message Channels
-
-```javascript
-/**
- * Publishes account selection event to AccountSelected__c channel
- * @param {Object} payload
- * @param {String} payload.accountId - Salesforce Account ID
- * @param {String} payload.accountName - Account Name
- * @param {String} payload.source - Component identifier
- */
-publishAccountSelection(payload) {
-    publish(this.messageContext, ACCOUNT_SELECTED_CHANNEL, payload);
-}
-```
-
-### 5. Error Handling
-
-```javascript
-handleMessage(message) {
-    try {
-        if (!message || !message.accountId) {
-            throw new Error('Invalid message payload');
-        }
-
-        this.selectedAccountId = message.accountId;
-        this.loadAccountDetails(message.accountId);
-    } catch (error) {
-        console.error('Error processing message:', error);
-        this.dispatchEvent(new ShowToastEvent({
-            title: 'Error',
-            message: 'Failed to process message',
-            variant: 'error'
-        }));
-    }
-}
-```
-
----
-
-## Troubleshooting
-
-### Issue: Messages Not Received
-
-**Checklist**:
-1. Is `MessageContext` wired correctly?
-   ```javascript
-   @wire(MessageContext) messageContext;
-   ```
-
-2. Is subscription active?
-   ```javascript
-   console.log('Subscription:', this.subscription); // Should not be null
-   ```
-
-3. Is the message channel deployed?
-   ```bash
-   sf project deploy start -m LightningMessageChannel
-   ```
-
-4. Are publisher and subscriber using the same channel?
-   ```javascript
-   // Both should import the same channel
-   import CHANNEL from '@salesforce/messageChannel/AccountSelected__c';
-   ```
-
-5. Is the scope correct?
-   ```javascript
-   // For cross-page: APPLICATION_SCOPE
-   // For same page: no scope (default)
-   ```
-
-### Issue: Memory Leaks
-
-**Cause**: Not unsubscribing in `disconnectedCallback()`
-
-**Fix**:
-```javascript
-disconnectedCallback() {
-    unsubscribe(this.subscription);
-    this.subscription = null;
-}
-```
-
-### Issue: Self-Updates
-
-**Cause**: Component receives its own published messages
-
-**Fix**: Filter by source
-```javascript
-handleMessage(message) {
-    if (message.source === this.componentName) {
-        return; // Ignore own messages
-    }
-    // Process message
-}
-```
-
----
-
-## Testing LMS Components
-
-### Mock MessageContext
-
-```javascript
-// testUtils.js
-export const createMessageContextMock = () => {
-    return jest.fn();
-};
-
-export const mockPublish = jest.fn();
-export const mockSubscribe = jest.fn();
-export const mockUnsubscribe = jest.fn();
-
-jest.mock('lightning/messageService', () => ({
-    publish: mockPublish,
-    subscribe: mockSubscribe,
-    unsubscribe: mockUnsubscribe,
-    MessageContext: Symbol('MessageContext'),
-    APPLICATION_SCOPE: Symbol('APPLICATION_SCOPE')
-}), { virtual: true });
-```
-
-### Test Publisher
-
-```javascript
-import { createElement } from 'lwc';
-import AccountPublisher from 'c/accountPublisher';
-import { publish } from 'lightning/messageService';
-import ACCOUNT_SELECTED_CHANNEL from '@salesforce/messageChannel/AccountSelected__c';
-
-jest.mock('lightning/messageService');
-
-describe('c-account-publisher', () => {
-    afterEach(() => {
-        jest.clearAllMocks();
-    });
-
-    it('publishes account selection', () => {
-        const element = createElement('c-account-publisher', {
-            is: AccountPublisher
-        });
-        document.body.appendChild(element);
-
-        // Trigger selection
-        const accountCard = element.shadowRoot.querySelector('[data-id="001xxx"]');
-        accountCard.click();
-
-        // Assert publish was called
-        expect(publish).toHaveBeenCalledWith(
-            expect.anything(),
-            ACCOUNT_SELECTED_CHANNEL,
-            expect.objectContaining({
-                accountId: '001xxx'
-            })
-        );
-    });
-});
-```
-
-### Test Subscriber
-
-```javascript
-import { createElement } from 'lwc';
-import AccountSubscriber from 'c/accountSubscriber';
-import { subscribe } from 'lightning/messageService';
-
-jest.mock('lightning/messageService');
-
-describe('c-account-subscriber', () => {
-    let messageHandler;
-
-    beforeEach(() => {
-        subscribe.mockImplementation((context, channel, handler, options) => {
-            messageHandler = handler;
-            return { subscription: 'mock-subscription' };
-        });
-    });
-
-    it('subscribes on connected', () => {
-        const element = createElement('c-account-subscriber', {
-            is: AccountSubscriber
-        });
-        document.body.appendChild(element);
-
-        expect(subscribe).toHaveBeenCalled();
-    });
-
-    it('handles incoming message', async () => {
-        const element = createElement('c-account-subscriber', {
-            is: AccountSubscriber
-        });
-        document.body.appendChild(element);
-
-        // Simulate message
-        messageHandler({
-            accountId: '001xxx',
-            accountName: 'Acme Corp'
-        });
-
-        await Promise.resolve();
-
-        const accountName = element.shadowRoot.querySelector('.account-name');
-        expect(accountName.textContent).toBe('Acme Corp');
-    });
-});
-```
-
----
-
-## Complete Example: Account-Contact Sync
-
-### Message Channel
-
-```xml
-<!-- ContactSelected__c.messageChannel-meta.xml -->
-<?xml version="1.0" encoding="UTF-8"?>
-<LightningMessageChannel xmlns="http://soap.sforce.com/2006/04/metadata">
-    <description>Contact selection messaging</description>
-    <isExposed>true</isExposed>
-    <lightningMessageFields>
-        <fieldName>contactId</fieldName>
-    </lightningMessageFields>
-    <lightningMessageFields>
-        <fieldName>contactName</fieldName>
-    </lightningMessageFields>
-    <lightningMessageFields>
-        <fieldName>accountId</fieldName>
-    </lightningMessageFields>
-    <masterLabel>Contact Selected</masterLabel>
-</LightningMessageChannel>
-```
-
-### Publisher Component
-
-```javascript
-// contactList.js
-import { LightningElement, api, wire } from 'lwc';
-import { publish, MessageContext } from 'lightning/messageService';
-import CONTACT_SELECTED from '@salesforce/messageChannel/ContactSelected__c';
-import getContacts from '@salesforce/apex/ContactController.getContacts';
-
-export default class ContactList extends LightningElement {
-    @api accountId;
-    contacts;
-    @wire(MessageContext) messageContext;
-
-    @wire(getContacts, { accountId: '$accountId' })
-    wiredContacts({ data, error }) {
-        if (data) {
-            this.contacts = data;
-        }
-    }
-
-    handleContactSelect(event) {
-        const contactId = event.currentTarget.dataset.id;
-        const contact = this.contacts.find(c => c.Id === contactId);
-
-        publish(this.messageContext, CONTACT_SELECTED, {
-            contactId: contact.Id,
-            contactName: contact.Name,
-            accountId: this.accountId
-        });
-    }
-}
-```
-
-### Subscriber Component
-
-```javascript
-// contactDetails.js
-import { LightningElement, wire } from 'lwc';
-import { subscribe, MessageContext, APPLICATION_SCOPE } from 'lightning/messageService';
-import CONTACT_SELECTED from '@salesforce/messageChannel/ContactSelected__c';
-import getContactDetails from '@salesforce/apex/ContactController.getContactDetails';
-
-export default class ContactDetails extends LightningElement {
-    subscription = null;
-    contactId;
-    contactDetails;
-    @wire(MessageContext) messageContext;
-
-    connectedCallback() {
-        this.subscription = subscribe(
-            this.messageContext,
-            CONTACT_SELECTED,
-            (message) => this.handleContactSelected(message),
-            { scope: APPLICATION_SCOPE }
-        );
-    }
-
-    disconnectedCallback() {
-        unsubscribe(this.subscription);
-    }
-
-    async handleContactSelected(message) {
-        this.contactId = message.contactId;
-        try {
-            this.contactDetails = await getContactDetails({
-                contactId: message.contactId
-            });
-        } catch (error) {
-            console.error('Error loading contact details:', error);
-        }
-    }
-}
-```
-
----
-
-## Related Resources
-
-- [component-patterns.md](component-patterns.md) - Parent-child communication
-- [jest-testing.md](jest-testing.md) - Testing LMS components
-- [Official LMS Documentation](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.use_message_channel)