@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/generating-lwc-components/assets/typescript-component/typescriptComponent.js-meta.xml

@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    TYPESCRIPT LWC COMPONENT TEMPLATE - METADATA
+
+    This template demonstrates TypeScript usage in LWC.
+
+    Requirements:
+    - API 66.0+ (Spring '26)
+    - @salesforce/lightning-types npm package
+    - TypeScript 5.4.5+
+
+    Note: TypeScript files must be compiled to JavaScript before deployment.
+    The Salesforce platform does not store TypeScript source code.
+-->
+<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>66.0</apiVersion>
+    <isExposed>true</isExposed>
+    <masterLabel>TypeScript Component</masterLabel>
+    <description>TypeScript-based LWC demonstrating type-safe patterns with @salesforce/lightning-types</description>
+
+    <targets>
+        <target>lightning__RecordPage</target>
+        <target>lightning__AppPage</target>
+        <target>lightning__HomePage</target>
+        <target>lightning__FlowScreen</target>
+    </targets>
+
+    <targetConfigs>
+        <targetConfig targets="lightning__RecordPage">
+            <objects>
+                <object>Account</object>
+            </objects>
+            <property
+                name="maxRecords"
+                type="Integer"
+                label="Maximum Records"
+                description="Maximum number of records to display"
+                default="10"
+                min="1"
+                max="100"/>
+        </targetConfig>
+
+        <targetConfig targets="lightning__AppPage,lightning__HomePage">
+            <property
+                name="maxRecords"
+                type="Integer"
+                label="Maximum Records"
+                default="10"
+                min="1"
+                max="100"/>
+        </targetConfig>
+
+        <targetConfig targets="lightning__FlowScreen">
+            <property
+                name="recordId"
+                type="String"
+                label="Record ID"
+                description="ID of the account record"
+                role="inputOnly"/>
+
+            <property
+                name="selectedAccountId"
+                type="String"
+                label="Selected Account ID"
+                role="outputOnly"/>
+
+            <property
+                name="maxRecords"
+                type="Integer"
+                label="Maximum Records"
+                default="10"
+                role="inputOnly"/>
+        </targetConfig>
+    </targetConfigs>
+</LightningComponentBundle>

package/skills/generating-lwc-components/assets/typescript-component/typescriptComponent.test.ts.example

@@ -0,0 +1,301 @@
+/**
+ * Jest Test File for TypeScript LWC Component
+ *
+ * Demonstrates typed testing patterns for LWC with:
+ * - Type-safe mock definitions
+ * - Typed event assertions
+ * - Interface-based test data
+ *
+ * This file ships with a .example suffix so Jest does not auto-discover it
+ * inside installed skill folders. Copy it into your project and rename it to:
+ * force-app/main/default/lwc/typescriptComponent/__tests__/typescriptComponent.test.ts
+ *
+ * Run after copying:
+ * sf force lightning lwc test run --spec force-app/main/default/lwc/typescriptComponent/__tests__/typescriptComponent.test.ts
+ */
+import { createElement, LightningElement } from 'lwc';
+import TypescriptComponent from 'c/typescriptComponent';
+import { getRecord } from 'lightning/uiRecordApi';
+import getAccounts from '@salesforce/apex/AccountController.getAccounts';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPE DEFINITIONS FOR TESTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+interface AccountRecord {
+    Id: string;
+    Name: string;
+    Industry?: string;
+    AnnualRevenue?: number;
+}
+
+interface MockWireAdapter {
+    emit: (data: unknown) => void;
+    error: (error: Error) => void;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MOCK SETUP
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Mock Apex controller
+jest.mock(
+    '@salesforce/apex/AccountController.getAccounts',
+    () => ({ default: jest.fn() }),
+    { virtual: true }
+);
+
+// Mock LDS getRecord
+jest.mock(
+    'lightning/uiRecordApi',
+    () => ({
+        getRecord: jest.fn(),
+        getFieldValue: jest.fn((data, field) => data?.fields?.[field.fieldApiName]?.value),
+        updateRecord: jest.fn()
+    }),
+    { virtual: true }
+);
+
+// Mock schema imports
+jest.mock('@salesforce/schema/Account.Name', () => ({ default: { fieldApiName: 'Name' } }), { virtual: true });
+jest.mock('@salesforce/schema/Account.Industry', () => ({ default: { fieldApiName: 'Industry' } }), { virtual: true });
+jest.mock('@salesforce/schema/Account.AnnualRevenue', () => ({ default: { fieldApiName: 'AnnualRevenue' } }), { virtual: true });
+jest.mock('@salesforce/schema/Account.Id', () => ({ default: { fieldApiName: 'Id' } }), { virtual: true });
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TEST DATA
+// ═══════════════════════════════════════════════════════════════════════════
+
+const MOCK_ACCOUNTS: AccountRecord[] = [
+    { Id: '001xx000003DGQAAA4', Name: 'Acme Corporation', Industry: 'Technology', AnnualRevenue: 5000000 },
+    { Id: '001xx000003DGQBAA4', Name: 'Global Industries', Industry: 'Manufacturing', AnnualRevenue: 12000000 },
+    { Id: '001xx000003DGQCAA4', Name: 'Pinnacle Solutions', Industry: 'Consulting', AnnualRevenue: 750000 }
+];
+
+const MOCK_RECORD = {
+    id: '001xx000003DGQAAA4',
+    fields: {
+        Name: { value: 'Acme Corporation' },
+        Industry: { value: 'Technology' },
+        AnnualRevenue: { value: 5000000 }
+    }
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TEST UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Flush microtask queue and wait for LWC rendering
+ */
+const flushPromises = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+/**
+ * Wait for specific number of render cycles
+ */
+const waitForRender = async (cycles: number = 1): Promise<void> => {
+    for (let i = 0; i < cycles; i++) {
+        await flushPromises();
+    }
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TESTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('c-typescript-component', () => {
+    let element: LightningElement & {
+        recordId?: string;
+        maxRecords?: number;
+    };
+
+    // Clean up after each test
+    afterEach(() => {
+        while (document.body.firstChild) {
+            document.body.removeChild(document.body.firstChild);
+        }
+        jest.clearAllMocks();
+    });
+
+    // ─────────────────────────────────────────────────────────────────────
+    // RENDERING TESTS
+    // ─────────────────────────────────────────────────────────────────────
+
+    describe('rendering', () => {
+        it('displays loading spinner initially', () => {
+            element = createElement('c-typescript-component', { is: TypescriptComponent });
+            document.body.appendChild(element);
+
+            const spinner = element.shadowRoot?.querySelector('lightning-spinner');
+            expect(spinner).not.toBeNull();
+        });
+
+        it('displays accounts after data loads', async () => {
+            // Arrange
+            (getAccounts as jest.Mock).mockResolvedValue(MOCK_ACCOUNTS);
+
+            // Act
+            element = createElement('c-typescript-component', { is: TypescriptComponent });
+            document.body.appendChild(element);
+
+            // Emit wire data
+            await waitForRender(2);
+
+            // Assert
+            const listItems = element.shadowRoot?.querySelectorAll('.slds-item');
+            expect(listItems?.length).toBe(MOCK_ACCOUNTS.length);
+        });
+
+        it('displays error message on failure', async () => {
+            // Arrange
+            const errorMessage = 'Failed to load accounts';
+            (getAccounts as jest.Mock).mockRejectedValue(new Error(errorMessage));
+
+            // Act
+            element = createElement('c-typescript-component', { is: TypescriptComponent });
+            document.body.appendChild(element);
+            await waitForRender(2);
+
+            // Assert
+            const errorAlert = element.shadowRoot?.querySelector('.slds-alert_error');
+            expect(errorAlert).not.toBeNull();
+        });
+
+        it('displays empty state when no accounts', async () => {
+            // Arrange
+            (getAccounts as jest.Mock).mockResolvedValue([]);
+
+            // Act
+            element = createElement('c-typescript-component', { is: TypescriptComponent });
+            document.body.appendChild(element);
+            await waitForRender(2);
+
+            // Assert
+            const emptyMessage = element.shadowRoot?.querySelector('.slds-text-color_weak');
+            expect(emptyMessage?.textContent).toContain('No accounts found');
+        });
+    });
+
+    // ─────────────────────────────────────────────────────────────────────
+    // EVENT HANDLING TESTS
+    // ─────────────────────────────────────────────────────────────────────
+
+    describe('event handling', () => {
+        it('dispatches accountselected event when account clicked', async () => {
+            // Arrange
+            (getAccounts as jest.Mock).mockResolvedValue(MOCK_ACCOUNTS);
+            const handler = jest.fn();
+
+            element = createElement('c-typescript-component', { is: TypescriptComponent });
+            element.addEventListener('accountselected', handler);
+            document.body.appendChild(element);
+            await waitForRender(2);
+
+            // Act
+            const accountLink = element.shadowRoot?.querySelector('a[data-id]') as HTMLAnchorElement;
+            accountLink?.click();
+            await waitForRender();
+
+            // Assert
+            expect(handler).toHaveBeenCalled();
+            const eventDetail = handler.mock.calls[0][0].detail;
+            expect(eventDetail.account).toBeDefined();
+            expect(eventDetail.account.Id).toBe(MOCK_ACCOUNTS[0].Id);
+        });
+
+        it('handles refresh button click', async () => {
+            // Arrange
+            (getAccounts as jest.Mock).mockResolvedValue(MOCK_ACCOUNTS);
+
+            element = createElement('c-typescript-component', { is: TypescriptComponent });
+            document.body.appendChild(element);
+            await waitForRender(2);
+
+            // Act
+            const refreshButton = element.shadowRoot?.querySelector('lightning-button[label="Refresh"]') as HTMLElement;
+            refreshButton?.click();
+            await waitForRender();
+
+            // Assert - refresh should trigger loading state
+            const spinner = element.shadowRoot?.querySelector('lightning-spinner');
+            expect(spinner).not.toBeNull();
+        });
+    });
+
+    // ─────────────────────────────────────────────────────────────────────
+    // API PROPERTY TESTS
+    // ─────────────────────────────────────────────────────────────────────
+
+    describe('@api properties', () => {
+        it('accepts maxRecords property', async () => {
+            // Arrange
+            (getAccounts as jest.Mock).mockResolvedValue(MOCK_ACCOUNTS);
+
+            // Act
+            element = createElement('c-typescript-component', { is: TypescriptComponent });
+            element.maxRecords = 5;
+            document.body.appendChild(element);
+            await waitForRender(2);
+
+            // Assert
+            expect((getAccounts as jest.Mock)).toHaveBeenCalledWith(
+                expect.objectContaining({ maxRecords: 5 })
+            );
+        });
+
+        it('accepts recordId property', () => {
+            // Act
+            element = createElement('c-typescript-component', { is: TypescriptComponent });
+            element.recordId = '001xx000003DGQAAA4';
+            document.body.appendChild(element);
+
+            // Assert
+            expect(element.recordId).toBe('001xx000003DGQAAA4');
+        });
+    });
+
+    // ─────────────────────────────────────────────────────────────────────
+    // TYPE SAFETY TESTS
+    // ─────────────────────────────────────────────────────────────────────
+
+    describe('type safety', () => {
+        it('handles undefined optional fields gracefully', async () => {
+            // Arrange - account without optional fields
+            const partialAccounts: AccountRecord[] = [
+                { Id: '001xx000003DGQAAA4', Name: 'Minimal Account' }
+            ];
+            (getAccounts as jest.Mock).mockResolvedValue(partialAccounts);
+
+            // Act
+            element = createElement('c-typescript-component', { is: TypescriptComponent });
+            document.body.appendChild(element);
+            await waitForRender(2);
+
+            // Assert - should render without errors
+            const listItems = element.shadowRoot?.querySelectorAll('.slds-item');
+            expect(listItems?.length).toBe(1);
+
+            // Industry span should not be rendered
+            const industrySpan = element.shadowRoot?.querySelector('.slds-text-body_small');
+            expect(industrySpan).toBeNull();
+        });
+
+        it('formats currency values correctly', async () => {
+            // Arrange
+            (getAccounts as jest.Mock).mockResolvedValue(MOCK_ACCOUNTS);
+
+            element = createElement('c-typescript-component', { is: TypescriptComponent });
+            document.body.appendChild(element);
+            await waitForRender(2);
+
+            // Act - select an account
+            const accountLink = element.shadowRoot?.querySelector('a[data-id]') as HTMLAnchorElement;
+            accountLink?.click();
+            await waitForRender();
+
+            // Assert - revenue should be formatted
+            const detailSection = element.shadowRoot?.querySelector('.slds-box');
+            expect(detailSection).not.toBeNull();
+        });
+    });
+});

package/skills/generating-lwc-components/assets/typescript-component/typescriptComponent.ts

@@ -0,0 +1,295 @@
+/**
+ * TypeScript LWC Component Template
+ *
+ * Demonstrates TypeScript usage in Lightning Web Components with:
+ * - Type definitions using @salesforce/lightning-types
+ * - Typed wire service patterns
+ * - Generic type parameters
+ * - Interface definitions
+ * - Strict null checking
+ *
+ * Requires: API 66.0+ (Spring '26)
+ * Setup: npm install @salesforce/lightning-types @salesforce/i18n lwc
+ *
+ * @see https://developer.salesforce.com/docs/platform/lwc/guide/ts.html
+ */
+import { LightningElement, api, wire, track } from 'lwc';
+import { getRecord, getFieldValue, updateRecord } from 'lightning/uiRecordApi';
+import { ShowToastEvent } from 'lightning/platformShowToastEvent';
+import { refreshApex } from '@salesforce/apex';
+
+// Import Apex controller with type definitions
+import getAccounts from '@salesforce/apex/AccountController.getAccounts';
+
+// Import schema for type safety
+import ACCOUNT_NAME_FIELD from '@salesforce/schema/Account.Name';
+import ACCOUNT_INDUSTRY_FIELD from '@salesforce/schema/Account.Industry';
+import ACCOUNT_REVENUE_FIELD from '@salesforce/schema/Account.AnnualRevenue';
+import ACCOUNT_ID_FIELD from '@salesforce/schema/Account.Id';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPE DEFINITIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Account record interface matching Salesforce object
+ */
+interface AccountRecord {
+    Id: string;
+    Name: string;
+    Industry?: string;
+    AnnualRevenue?: number;
+}
+
+/**
+ * Wire result type for Apex calls
+ */
+interface WireResult<T> {
+    data?: T;
+    error?: Error;
+}
+
+/**
+ * Apex wire result with refresh support
+ */
+interface ApexWireResult<T> extends WireResult<T> {
+    // Full result object for refreshApex
+}
+
+/**
+ * LDS Record result type
+ */
+interface RecordResult {
+    data?: {
+        id: string;
+        fields: Record<string, { value: unknown }>;
+    };
+    error?: Error;
+}
+
+/**
+ * Component configuration props
+ */
+interface ComponentConfig {
+    maxRecords: number;
+    sortField: keyof AccountRecord;
+    sortDirection: 'ASC' | 'DESC';
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+const DEFAULT_CONFIG: ComponentConfig = {
+    maxRecords: 10,
+    sortField: 'Name',
+    sortDirection: 'ASC'
+};
+
+const ACCOUNT_FIELDS = [
+    ACCOUNT_NAME_FIELD,
+    ACCOUNT_INDUSTRY_FIELD,
+    ACCOUNT_REVENUE_FIELD
+];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// COMPONENT CLASS
+// ═══════════════════════════════════════════════════════════════════════════
+
+export default class TypescriptComponent extends LightningElement {
+    // ─────────────────────────────────────────────────────────────────────
+    // Public API Properties (typed)
+    // ─────────────────────────────────────────────────────────────────────
+
+    @api recordId: string | undefined;
+
+    @api
+    get maxRecords(): number {
+        return this._config.maxRecords;
+    }
+    set maxRecords(value: number) {
+        this._config = { ...this._config, maxRecords: value };
+    }
+
+    // ─────────────────────────────────────────────────────────────────────
+    // Private Properties (tracked for reactivity)
+    // ─────────────────────────────────────────────────────────────────────
+
+    @track private _accounts: AccountRecord[] = [];
+    @track private _selectedAccount: AccountRecord | null = null;
+    @track private _error: string | null = null;
+    @track private _isLoading: boolean = true;
+
+    private _config: ComponentConfig = { ...DEFAULT_CONFIG };
+    private _wiredAccountsResult: ApexWireResult<AccountRecord[]> | undefined;
+
+    // ─────────────────────────────────────────────────────────────────────
+    // Wire Services (typed)
+    // ─────────────────────────────────────────────────────────────────────
+
+    /**
+     * Wire Apex method with typed result handling
+     */
+    @wire(getAccounts, { maxRecords: '$maxRecords' })
+    wiredAccounts(result: ApexWireResult<AccountRecord[]>): void {
+        this._wiredAccountsResult = result;
+        const { data, error } = result;
+
+        this._isLoading = false;
+
+        if (data) {
+            this._accounts = this.sortAccounts(data);
+            this._error = null;
+        } else if (error) {
+            this._error = this.reduceErrors(error);
+            this._accounts = [];
+        }
+    }
+
+    /**
+     * Wire LDS getRecord with typed result
+     */
+    @wire(getRecord, { recordId: '$recordId', fields: ACCOUNT_FIELDS })
+    wiredRecord(result: RecordResult): void {
+        if (result.data) {
+            this._selectedAccount = {
+                Id: result.data.id,
+                Name: getFieldValue(result.data, ACCOUNT_NAME_FIELD) as string,
+                Industry: getFieldValue(result.data, ACCOUNT_INDUSTRY_FIELD) as string | undefined,
+                AnnualRevenue: getFieldValue(result.data, ACCOUNT_REVENUE_FIELD) as number | undefined
+            };
+        } else if (result.error) {
+            this._error = this.reduceErrors(result.error);
+        }
+    }
+
+    // ─────────────────────────────────────────────────────────────────────
+    // Getters (computed properties)
+    // ─────────────────────────────────────────────────────────────────────
+
+    get accounts(): AccountRecord[] {
+        return this._accounts;
+    }
+
+    get hasAccounts(): boolean {
+        return this._accounts.length > 0;
+    }
+
+    get isLoading(): boolean {
+        return this._isLoading;
+    }
+
+    get errorMessage(): string | null {
+        return this._error;
+    }
+
+    get hasError(): boolean {
+        return this._error !== null;
+    }
+
+    get selectedAccountName(): string {
+        return this._selectedAccount?.Name ?? 'No account selected';
+    }
+
+    get formattedRevenue(): string {
+        const revenue = this._selectedAccount?.AnnualRevenue;
+        if (revenue === undefined || revenue === null) {
+            return 'N/A';
+        }
+        return new Intl.NumberFormat('en-US', {
+            style: 'currency',
+            currency: 'USD'
+        }).format(revenue);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────
+    // Event Handlers (typed parameters)
+    // ─────────────────────────────────────────────────────────────────────
+
+    handleAccountSelect(event: CustomEvent<{ accountId: string }>): void {
+        const { accountId } = event.detail;
+        const account = this._accounts.find(a => a.Id === accountId);
+
+        if (account) {
+            this._selectedAccount = account;
+            this.dispatchAccountSelected(account);
+        }
+    }
+
+    handleRefresh(): void {
+        this._isLoading = true;
+        if (this._wiredAccountsResult) {
+            refreshApex(this._wiredAccountsResult);
+        }
+    }
+
+    async handleUpdate(event: CustomEvent<{ field: keyof AccountRecord; value: string | number }>): Promise<void> {
+        const { field, value } = event.detail;
+
+        if (!this._selectedAccount?.Id) {
+            this.showToast('Error', 'No account selected', 'error');
+            return;
+        }
+
+        try {
+            const fields: Record<string, unknown> = {
+                [ACCOUNT_ID_FIELD.fieldApiName]: this._selectedAccount.Id,
+                [field]: value
+            };
+
+            await updateRecord({ fields });
+
+            this.showToast('Success', 'Account updated successfully', 'success');
+            this.handleRefresh();
+        } catch (error) {
+            this.showToast('Error', this.reduceErrors(error as Error), 'error');
+        }
+    }
+
+    // ─────────────────────────────────────────────────────────────────────
+    // Private Methods (typed)
+    // ─────────────────────────────────────────────────────────────────────
+
+    private sortAccounts(accounts: AccountRecord[]): AccountRecord[] {
+        const { sortField, sortDirection } = this._config;
+
+        return [...accounts].sort((a, b) => {
+            const aVal = a[sortField];
+            const bVal = b[sortField];
+
+            if (aVal === undefined || aVal === null) return 1;
+            if (bVal === undefined || bVal === null) return -1;
+
+            const comparison = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+            return sortDirection === 'ASC' ? comparison : -comparison;
+        });
+    }
+
+    private reduceErrors(error: Error | Error[]): string {
+        const errors = Array.isArray(error) ? error : [error];
+
+        return errors
+            .filter((e): e is Error => e !== null && e !== undefined)
+            .map(e => {
+                if (typeof e === 'string') return e;
+                if ('body' in e && typeof (e as { body?: { message?: string } }).body?.message === 'string') {
+                    return (e as { body: { message: string } }).body.message;
+                }
+                return e.message || 'Unknown error';
+            })
+            .join('; ');
+    }
+
+    private dispatchAccountSelected(account: AccountRecord): void {
+        const event = new CustomEvent<{ account: AccountRecord }>('accountselected', {
+            detail: { account },
+            bubbles: true,
+            composed: true
+        });
+        this.dispatchEvent(event);
+    }
+
+    private showToast(title: string, message: string, variant: 'success' | 'error' | 'warning' | 'info'): void {
+        this.dispatchEvent(new ShowToastEvent({ title, message, variant }));
+    }
+}