scc-universal 1.1.0

package/.cursor/skills/sf-lwc-development/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: sf-lwc-development
+description: >-
+  LWC development — components, reactive properties, wire service, Apex integration, events, lifecycle hooks. Use when building LWC components or debugging wire/reactivity. Do NOT use for Aura, Visualforce, or Flow.
+---
+
+# LWC Development
+
+Lightning Web Components (LWC) is Salesforce's modern component model based on web standards — Custom Elements, Shadow DOM, and ES modules.
+
+## When to Use
+
+- When building new Lightning Web Components from scratch
+- When migrating Aura components to LWC
+- When debugging reactive property or wire service issues
+- When implementing parent-child communication with events or @api
+- When adding LWC components to record pages, app pages, or Experience Cloud sites
+
+@../_reference/LWC_PATTERNS.md
+
+---
+
+## Component Creation Procedure
+
+Every LWC component is a folder with at minimum an HTML template and a JavaScript class.
+
+```
+force-app/main/default/lwc/
+  accountList/
+    accountList.html          <- Template
+    accountList.js            <- Component class
+    accountList.css           <- Component-scoped styles (optional)
+    accountList.js-meta.xml   <- Metadata (targets, properties)
+```
+
+### Step 1 — HTML Template
+
+```html
+<template>
+    <lightning-card title="Accounts" icon-name="standard:account">
+        <template lwc:if={isLoading}>
+            <lightning-spinner alternative-text="Loading" size="small"></lightning-spinner>
+        </template>
+        <template lwc:elseif={hasError}>
+            <p class="slds-text-color_error">{errorMessage}</p>
+        </template>
+        <template lwc:else>
+            <template for:each={accounts} for:item="account">
+                <div key={account.Id} class="account-row">
+                    <span>{account.Name}</span>
+                    <lightning-button label="View" data-id={account.Id}
+                        onclick={handleViewAccount}></lightning-button>
+                </div>
+            </template>
+        </template>
+    </lightning-card>
+</template>
+```
+
+### Step 2 — JavaScript Class
+
+```javascript
+import { LightningElement, api, wire } from 'lwc';
+import { ShowToastEvent } from 'lightning/platformShowToastEvent';
+import { NavigationMixin } from 'lightning/navigation';
+import getAccounts from '@salesforce/apex/AccountsController.getAccounts';
+
+export default class AccountList extends NavigationMixin(LightningElement) {
+    @api recordId;
+    @api maxRecords = 10;
+
+    accounts = [];
+    isLoading = false;
+    error;
+
+    get hasError() { return this.error !== undefined; }
+    get isEmpty() { return !this.isLoading && this.accounts.length === 0; }
+    get errorMessage() {
+        return this.error?.body?.message ?? this.error?.message ?? 'An unknown error occurred.';
+    }
+
+    connectedCallback() { this.loadAccounts(); }
+
+    handleViewAccount(event) {
+        this[NavigationMixin.Navigate]({
+            type: 'standard__recordPage',
+            attributes: { recordId: event.currentTarget.dataset.id,
+                          objectApiName: 'Account', actionName: 'view' }
+        });
+    }
+
+    async loadAccounts() {
+        this.isLoading = true;
+        this.error = undefined;
+        try {
+            this.accounts = await getAccounts({
+                searchTerm: this.searchTerm, maxRecords: this.maxRecords
+            });
+        } catch (error) {
+            this.error = error;
+        } finally {
+            this.isLoading = false;
+        }
+    }
+}
+```
+
+### Step 3 — Meta XML
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>66.0</apiVersion>
+    <isExposed>true</isExposed>
+    <targets>
+        <target>lightning__RecordPage</target>
+        <target>lightning__AppPage</target>
+        <target>lightning__HomePage</target>
+    </targets>
+    <targetConfigs>
+        <targetConfig targets="lightning__RecordPage">
+            <property name="maxRecords" type="Integer" default="10"
+                      label="Maximum Records to Display" />
+        </targetConfig>
+    </targetConfigs>
+</LightningComponentBundle>
+```
+
+---
+
+## Wire Service Usage
+
+The wire service declaratively connects components to Salesforce data and re-runs when reactive parameters change.
+
+### Wire with Apex
+
+```javascript
+import { LightningElement, wire, api } from 'lwc';
+import { refreshApex } from '@salesforce/apex';
+import getAccountDetails from '@salesforce/apex/AccountsController.getAccountDetails';
+
+export default class AccountDetails extends LightningElement {
+    @api recordId;
+    _wiredResult;
+
+    @wire(getAccountDetails, { accountId: '$recordId' })
+    wiredAccount(result) {
+        this._wiredResult = result;
+        if (result.data) {
+            this.account = result.data;
+            this.error = undefined;
+        } else if (result.error) {
+            this.error = result.error;
+            this.account = undefined;
+        }
+    }
+
+    async handleSave(event) {
+        await updateAccount({ accountId: this.recordId, fields: event.detail.fields });
+        await refreshApex(this._wiredResult);
+    }
+}
+```
+
+### Wire with Lightning Data Service
+
+```javascript
+import { LightningElement, api, wire } from 'lwc';
+import { getRecord, getFieldValue, updateRecord } from 'lightning/uiRecordApi';
+import ACCOUNT_NAME from '@salesforce/schema/Account.Name';
+import ACCOUNT_INDUSTRY from '@salesforce/schema/Account.Industry';
+
+export default class AccountHeader extends LightningElement {
+    @api recordId;
+
+    @wire(getRecord, { recordId: '$recordId', fields: [ACCOUNT_NAME, ACCOUNT_INDUSTRY] })
+    account;
+
+    get name() { return getFieldValue(this.account.data, ACCOUNT_NAME); }
+    get industry() { return getFieldValue(this.account.data, ACCOUNT_INDUSTRY); }
+}
+```
+
+---
+
+## Event Handling — Component Communication
+
+### Child to Parent: Custom Events
+
+```javascript
+// child: opportunityCard.js
+handleSelect() {
+    this.dispatchEvent(new CustomEvent('opportunityselect', {
+        detail: { opportunityId: this.opportunity.Id },
+        bubbles: false, composed: false
+    }));
+}
+```
+
+```html
+<!-- parent template -->
+<c-opportunity-card opportunity={opp}
+    onopportunityselect={handleOpportunitySelect}></c-opportunity-card>
+```
+
+### Cross-Component: Lightning Message Service
+
+```javascript
+import { publish, subscribe, unsubscribe, MessageContext, APPLICATION_SCOPE }
+    from 'lightning/messageService';
+import CHANNEL from '@salesforce/messageChannel/OpportunitySelected__c';
+
+// Publisher
+@wire(MessageContext) messageContext;
+handleSelect(event) {
+    publish(this.messageContext, CHANNEL, { opportunityId: event.target.dataset.id });
+}
+
+// Subscriber
+connectedCallback() {
+    this.subscription = subscribe(this.messageContext, CHANNEL,
+        (msg) => this.handleMessage(msg), { scope: APPLICATION_SCOPE });
+}
+disconnectedCallback() { unsubscribe(this.subscription); }
+```
+
+---
+
+## Slots — Composition Patterns
+
+```html
+<!-- child: modalWrapper.html -->
+<template>
+    <div class="modal-header"><slot name="header"><h2>Default Header</h2></slot></div>
+    <div class="modal-body"><slot></slot></div>
+    <div class="modal-footer"><slot name="footer"></slot></div>
+</template>
+
+<!-- parent usage -->
+<c-modal-wrapper>
+    <span slot="header">Edit Account</span>
+    <lightning-record-edit-form record-id={recordId} object-api-name="Account">
+        <lightning-input-field field-name="Name"></lightning-input-field>
+    </lightning-record-edit-form>
+    <div slot="footer">
+        <lightning-button label="Save" variant="brand" onclick={handleSave}></lightning-button>
+    </div>
+</c-modal-wrapper>
+```
+
+---
+
+## Light DOM
+
+Renders component markup directly into the parent DOM (no shadow boundary).
+
+```javascript
+export default class ThemedComponent extends LightningElement {
+    static renderMode = 'light';
+}
+```
+
+Use for: global CSS theming, third-party library integration, Experience Cloud sites, simple leaf components. Query with `this.querySelector()` instead of `this.template.querySelector()`.
+
+---
+
+## Spring '26 Features
+
+### SLDS 2.0
+
+Use `--slds-c-*` styling hooks (replaces `--lwc-*` design tokens). Run `npx slds-lint` to check compliance.
+
+### TypeScript Support
+
+```bash
+npm install --save-dev @salesforce/lightning-types
+```
+
+### Complex Template Expressions (Beta)
+
+```html
+<p>{account.Name ?? 'Unknown Account'}</p>
+<p>{formatRevenue(account.AnnualRevenue)}</p>
+```
+
+Use getters for production code until this reaches GA.
+
+### LWC in Screen Flows
+
+Expose components as Flow screen actions via `lightning__FlowScreen` target. Implement `@api validate()` for Flow navigation validation.
+
+---
+
+## Related
+
+### Guardrails
+
+- **sf-lwc-constraints** — Enforced rules for LWC naming, reactivity, security, and accessibility
+
+### Agents
+
+- **sf-lwc-agent** — For interactive, in-depth LWC review guidance

package/.cursor/skills/sf-lwc-testing/SKILL.md

@@ -0,0 +1,387 @@
+---
+name: sf-lwc-testing
+description: >-
+  LWC Jest testing — component mounting, wire/Apex mocking, user interaction simulation, toast/navigation verification. Use when writing or debugging LWC Jest tests. Do NOT use for Apex or Flow testing.
+---
+
+# LWC Testing with Jest
+
+LWC uses Jest as its test runner. Salesforce provides `@salesforce/sfdx-lwc-jest` to handle Salesforce-specific imports. Tests run in Node.js — no browser, no Salesforce org.
+
+## When to Use
+
+- When writing Jest unit tests for Lightning Web Components
+- When mocking Wire adapters, Apex imperative calls, or navigation in LWC tests
+- When debugging flaky or async LWC tests
+- When setting up LWC test infrastructure for a new project
+
+@../_reference/LWC_PATTERNS.md
+@../_reference/TESTING_STANDARDS.md
+
+---
+
+## Setup Procedure
+
+### Step 1 — Install
+
+```bash
+npm install --save-dev @salesforce/sfdx-lwc-jest
+```
+
+### Step 2 — jest.config.js
+
+```javascript
+const { jestConfig } = require('@salesforce/sfdx-lwc-jest/config');
+module.exports = {
+    ...jestConfig,
+    modulePathIgnorePatterns: ['<rootDir>/.localdevserver'],
+    testEnvironment: 'jsdom',
+    testMatch: ['**/__tests__/**/*.test.js'],
+    setupFiles: ['<rootDir>/jest.setup.js']
+};
+```
+
+### Step 3 — jest.setup.js
+
+```javascript
+global.ResizeObserver = jest.fn().mockImplementation(() => ({
+    observe: jest.fn(), unobserve: jest.fn(), disconnect: jest.fn()
+}));
+```
+
+### Step 4 — Test File Location
+
+```
+lwc/accountSearch/
+    accountSearch.html
+    accountSearch.js
+    __tests__/
+        accountSearch.test.js
+```
+
+---
+
+## Basic Component Rendering
+
+```javascript
+import { createElement } from 'lwc';
+import AccountSearch from 'c/accountSearch';
+
+describe('c-account-search', () => {
+    afterEach(() => {
+        while (document.body.firstChild) {
+            document.body.removeChild(document.body.firstChild);
+        }
+        jest.clearAllMocks();
+    });
+
+    it('renders the search input', () => {
+        const element = createElement('c-account-search', { is: AccountSearch });
+        document.body.appendChild(element);
+
+        const input = element.shadowRoot.querySelector('lightning-input[type="search"]');
+        expect(input).not.toBeNull();
+        expect(input.label).toBe('Search Accounts');
+    });
+
+    it('renders with public @api property', () => {
+        const element = createElement('c-account-search', { is: AccountSearch });
+        element.maxRecords = 25;
+        document.body.appendChild(element);
+        expect(element.maxRecords).toBe(25);
+    });
+});
+```
+
+---
+
+## Wire Adapter Mocking (Modern Pattern)
+
+Use `jest.mock()` with the wire adapter directly. The deprecated `registerApexTestWireAdapter` pattern should not be used in new projects.
+
+```javascript
+import { createElement } from 'lwc';
+import AccountDetails from 'c/accountDetails';
+import getAccountDetails from '@salesforce/apex/AccountsController.getAccountDetails';
+
+jest.mock(
+    '@salesforce/apex/AccountsController.getAccountDetails',
+    () => ({ default: jest.fn() }),
+    { virtual: true }
+);
+
+describe('c-account-details wire', () => {
+    afterEach(() => {
+        while (document.body.firstChild) {
+            document.body.removeChild(document.body.firstChild);
+        }
+        jest.clearAllMocks();
+    });
+
+    it('displays account name when wire returns data', async () => {
+        getAccountDetails.mockResolvedValue({
+            Id: '001000000000001AAA', Name: 'Acme Corporation'
+        });
+        const element = createElement('c-account-details', { is: AccountDetails });
+        element.recordId = '001000000000001AAA';
+        document.body.appendChild(element);
+
+        await Promise.resolve();
+        await Promise.resolve();
+
+        expect(element.shadowRoot.querySelector('.account-name').textContent)
+            .toBe('Acme Corporation');
+    });
+
+    it('displays error state when wire returns error', async () => {
+        getAccountDetails.mockRejectedValue({
+            body: { message: 'Record not found' }, status: 404
+        });
+        const element = createElement('c-account-details', { is: AccountDetails });
+        element.recordId = '001000000000001AAA';
+        document.body.appendChild(element);
+
+        await Promise.resolve();
+        await Promise.resolve();
+
+        expect(element.shadowRoot.querySelector('.error-container')).not.toBeNull();
+    });
+});
+```
+
+---
+
+## Apex Imperative Call Mocking
+
+```javascript
+jest.mock(
+    '@salesforce/apex/AccountSearchController.searchAccounts',
+    () => jest.fn(),         // imperative: module IS the function
+    { virtual: true }
+);
+
+import searchAccounts from '@salesforce/apex/AccountSearchController.searchAccounts';
+
+it('calls Apex on search and displays results', async () => {
+    searchAccounts.mockResolvedValue([
+        { Id: '001000000000001AAA', Name: 'Acme Corp' }
+    ]);
+    const element = createElement('c-account-search', { is: AccountSearch });
+    document.body.appendChild(element);
+
+    // Trigger search
+    const input = element.shadowRoot.querySelector('lightning-input');
+    input.dispatchEvent(new CustomEvent('change', { detail: { value: 'Acme' } }));
+    element.shadowRoot.querySelector('lightning-button[label="Search"]').click();
+
+    await flushPromises();
+
+    expect(searchAccounts).toHaveBeenCalledWith({ searchTerm: 'Acme' });
+    const rows = element.shadowRoot.querySelectorAll('.account-row');
+    expect(rows).toHaveLength(1);
+});
+```
+
+Key distinction: for imperative Apex, mock as `() => jest.fn()`. For wired Apex, mock as `() => ({ default: jest.fn() })`.
+
+---
+
+## Async Testing — flushPromises
+
+LWC re-renders are asynchronous. Use `flushPromises` instead of chaining multiple `Promise.resolve()` calls.
+
+```javascript
+function flushPromises() {
+    return new Promise(resolve => setTimeout(resolve, 0));
+}
+```
+
+---
+
+## User Interaction Simulation
+
+### Click Events and Custom Event Assertions
+
+```javascript
+it('dispatches select event when button clicked', () => {
+    const element = createElement('c-account-card', { is: AccountCard });
+    element.account = { Id: '001000000000001AAA', Name: 'Test Corp' };
+    document.body.appendChild(element);
+
+    const handler = jest.fn();
+    element.addEventListener('accountselect', handler);
+
+    element.shadowRoot.querySelector('[data-id="view-btn"]').click();
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler.mock.calls[0][0].detail).toEqual({
+        accountId: '001000000000001AAA', accountName: 'Test Corp'
+    });
+});
+```
+
+### Input Value Changes
+
+```javascript
+const input = element.shadowRoot.querySelector('lightning-input[type="search"]');
+input.dispatchEvent(new CustomEvent('change', { detail: { value: 'Acme' } }));
+await Promise.resolve();
+```
+
+---
+
+## Toast Notification Testing
+
+```javascript
+import { ShowToastEventName } from 'lightning/platformShowToastEvent';
+
+it('shows success toast after save', async () => {
+    const toastHandler = jest.fn();
+    element.addEventListener(ShowToastEventName, toastHandler);
+
+    element.shadowRoot.querySelector('[data-id="save-btn"]').click();
+    await flushPromises();
+
+    expect(toastHandler).toHaveBeenCalledTimes(1);
+    expect(toastHandler.mock.calls[0][0].detail.variant).toBe('success');
+});
+```
+
+---
+
+## Navigation Mocking
+
+```javascript
+it('navigates to record page on view', () => {
+    const { navigate } = require('lightning/navigation');
+    const element = createElement('c-account-card', { is: AccountCard });
+    element.account = { Id: '001000000000001AAA' };
+    document.body.appendChild(element);
+
+    element.shadowRoot.querySelector('[data-id="view"]').click();
+
+    expect(navigate).toHaveBeenCalledWith(
+        expect.objectContaining({
+            type: 'standard__recordPage',
+            attributes: expect.objectContaining({ recordId: '001000000000001AAA' })
+        })
+    );
+});
+```
+
+---
+
+## What to Test vs What Not to Test
+
+### Test These
+
+- Business logic in computed properties and event handlers
+- Correct Apex method called with correct arguments
+- Component response to wire data and errors
+- User interactions and their effects on component state
+- Edge cases: empty arrays, null values, error states
+
+### Do Not Test These
+
+- LWC framework behavior (that `for:each` renders items)
+- Base component rendering (that `lightning-button` shows text)
+- CSS styling or implementation details (internal variable names)
+
+---
+
+## Spring '26: Local Component Testing
+
+Test LWC components in isolation without deploying to a scratch org.
+
+```bash
+npm install --save-dev @lwc/jest-preset
+npx lwc-jest --watchAll=false
+```
+
+---
+
+## TypeScript LWC Testing (Spring '26 Experimental)
+
+Spring '26 introduces experimental TypeScript support for LWC. Test `.ts` component files with these adjustments.
+
+### Jest Configuration
+
+```javascript
+// jest.config.js — add ts transform
+const { jestConfig } = require('@salesforce/sfdx-lwc-jest/config');
+module.exports = {
+    ...jestConfig,
+    transform: {
+        ...jestConfig.transform,
+        '^.+\\.ts$': ['@swc/jest']  // or 'ts-jest'
+    },
+    moduleFileExtensions: ['ts', 'js', 'html'],
+    testMatch: ['**/__tests__/**/*.test.(js|ts)']
+};
+```
+
+Install: `npm install --save-dev @swc/jest @swc/core` (faster) or `npm install --save-dev ts-jest typescript`.
+
+### Typed Wire Adapter Mocking
+
+```typescript
+import { createElement } from 'lwc';
+import AccountList from 'c/accountList';
+import getAccounts from '@salesforce/apex/AccountController.getAccounts';
+
+jest.mock('@salesforce/apex/AccountController.getAccounts',
+    () => ({ default: jest.fn() }), { virtual: true });
+
+const mockGetAccounts = getAccounts as jest.MockedFunction<typeof getAccounts>;
+
+describe('c-account-list (TypeScript)', () => {
+    afterEach(() => {
+        while (document.body.firstChild) document.body.removeChild(document.body.firstChild);
+        jest.clearAllMocks();
+    });
+
+    it('renders typed account data', async () => {
+        mockGetAccounts.mockResolvedValue([
+            { Id: '001xx0001', Name: 'Typed Corp', Industry: 'Technology' }
+        ]);
+        const element = createElement('c-account-list', { is: AccountList });
+        document.body.appendChild(element);
+
+        await Promise.resolve();
+        await Promise.resolve();
+
+        const rows = element.shadowRoot.querySelectorAll('.account-row');
+        expect(rows).toHaveLength(1);
+    });
+});
+```
+
+### Typed Event Detail Assertions
+
+```typescript
+it('dispatches typed custom event', () => {
+    const element = createElement('c-account-card', { is: AccountCard });
+    document.body.appendChild(element);
+
+    const handler = jest.fn();
+    element.addEventListener('select', handler);
+    element.shadowRoot.querySelector('[data-id="select-btn"]').click();
+
+    const detail = handler.mock.calls[0][0].detail as { accountId: string };
+    expect(detail.accountId).toBeDefined();
+});
+```
+
+> **Note:** TypeScript LWC support is experimental in Spring '26. Type definitions and tooling may change in future releases. Pin `@salesforce/sfdx-lwc-jest` to a known-good version.
+
+---
+
+## Related
+
+### Guardrails
+
+- **sf-testing-constraints** — Enforced rules for test coverage, assertions, and test data patterns
+
+### Agents
+
+- **sf-lwc-agent** — For interactive, in-depth LWC review guidance