fe-lwc-skill 1.0.0

package/skill/rules/events-custom-event.md

@@ -0,0 +1,227 @@
+# events-custom-event
+
+**Impact: HIGH**
+
+Custom events are the standard mechanism for child-to-parent communication in LWC. Two boolean flags — `bubbles` and `composed` — control how far an event travels through the DOM.
+
+> **Rule:**
+>
+> - Always declare `bubbles` and `composed` explicitly.
+> - Prefer **kebab-case** event names (`step-completed`) — camelCase is valid but less portable across some platforms.
+> - The template handler attribute is always `on` + the full event name: `onstep-completed` or `onstepcompleted`.
+> - Pass data through `detail`, not as top-level properties on the event object.
+> - Keep `composed: true` only when the listener lives outside the component's shadow root.
+
+---
+
+## Decision Guide: `bubbles` and `composed`
+
+| Listener location                                          | `bubbles`           | `composed` |
+| ---------------------------------------------------------- | ------------------- | ---------- |
+| Direct parent only                                         | `false`             | `false`    |
+| Any ancestor in the same shadow tree                       | `true`              | `false`    |
+| Outside the shadow root (cross-shadow, App Builder region) | `true`              | `true`     |
+| Cross-region on Experience Cloud                           | Use **LMS** instead | —          |
+
+---
+
+## Case 1: Missing flags, data not in `detail`
+
+**Incorrect:**
+
+```typescript
+// appointmentCard.ts
+import { LightningElement, api } from "lwc";
+
+// @ts-ignore
+export default class AppointmentCard extends LightningElement {
+  // @ts-ignore
+  @api recordId: string;
+
+  public handleCancel(): void {
+    // ❌ No bubbles/composed, data not in detail
+    const event = new CustomEvent("appointmentCancelled", {
+      appointmentId: this.recordId,
+      reason: "User cancelled",
+    } as CustomEventInit);
+    this.dispatchEvent(event);
+  }
+}
+```
+
+**Correct — explicit flags, data in `detail`:**
+
+```typescript
+// appointmentCard.ts
+import { LightningElement, api } from "lwc";
+
+interface AppointmentCancelledDetail {
+  appointmentId: string;
+  reason: string;
+}
+
+// @ts-ignore
+export default class AppointmentCard extends LightningElement {
+  // @ts-ignore
+  @api recordId: string;
+
+  public handleCancel(): void {
+    this.dispatchEvent(
+      new CustomEvent<AppointmentCancelledDetail>("appointmentCancelled", {
+        bubbles: false, // ✅ explicit — direct parent is the listener
+        composed: false, // ✅ explicit — same shadow root
+        detail: {
+          appointmentId: this.recordId,
+          reason: "User cancelled",
+        },
+      }),
+    );
+  }
+}
+```
+
+```typescript
+// parentContainer.ts
+import { LightningElement } from "lwc";
+
+interface AppointmentCancelledDetail {
+  appointmentId: string;
+  reason: string;
+}
+
+// @ts-ignore
+export default class ParentContainer extends LightningElement {
+  public handleCancel(event: CustomEvent<AppointmentCancelledDetail>): void {
+    const { appointmentId, reason } = event.detail;
+    // handle cancellation...
+  }
+}
+```
+
+```html
+<!-- parentContainer.html -->
+<c-appointment-card onappointmentcancelled="{handleCancel}"></c-appointment-card>
+```
+
+---
+
+## Case 2: Event must bubble through multiple ancestors
+
+Scenario: `appointmentStep` → `appointmentWizard` → `appointmentModal`. The modal is the listener.
+
+**Incorrect — `bubbles: false` stops the event at the direct parent:**
+
+```typescript
+// appointmentStep.ts
+handleNext(): void {
+    this.dispatchEvent(
+        new CustomEvent('step-completed', {
+            bubbles: false,  // ❌ stops at appointmentWizard
+            composed: false,
+            detail: { stepIndex: this.currentStep },
+        })
+    );
+}
+```
+
+**Correct:**
+
+```typescript
+// appointmentStep.ts
+import { LightningElement } from "lwc";
+
+interface StepCompletedDetail {
+  stepIndex: number;
+}
+
+// @ts-ignore
+export default class AppointmentStep extends LightningElement {
+  currentStep: number = 0;
+
+  public handleNext(): void {
+    this.dispatchEvent(
+      new CustomEvent<StepCompletedDetail>("step-completed", {
+        bubbles: true, // ✅ travels up to appointmentModal
+        composed: false, // ✅ still within the same shadow root
+        detail: { stepIndex: this.currentStep },
+      }),
+    );
+  }
+}
+```
+
+```typescript
+// appointmentModal.ts
+import { LightningElement } from "lwc";
+
+// @ts-ignore
+export default class AppointmentModal extends LightningElement {
+  currentStep: number = 0;
+
+  public handleStepCompleted(event: CustomEvent<{ stepIndex: number }>): void {
+    this.currentStep = event.detail.stepIndex + 1;
+  }
+}
+```
+
+---
+
+## Case 3: `composed: true` when crossing shadow roots (slotted content)
+
+**Incorrect:**
+
+```typescript
+// slottedForm.ts
+handleSubmit(): void {
+    this.dispatchEvent(
+        new CustomEvent('form-submitted', {
+            bubbles: true,
+            composed: false, // ❌ cannot cross the shadow root boundary
+            detail: { formData: this.formState },
+        })
+    );
+}
+```
+
+**Correct:**
+
+```typescript
+// slottedForm.ts
+import { LightningElement } from "lwc";
+
+interface FormSubmittedDetail {
+  formData: Record<string, string>;
+}
+
+// @ts-ignore
+export default class SlottedForm extends LightningElement {
+  formState: Record<string, string> = {};
+
+  public handleSubmit(): void {
+    this.dispatchEvent(
+      new CustomEvent<FormSubmittedDetail>("form-submitted", {
+        bubbles: true,
+        composed: true, // ✅ crosses the shadow boundary to the slot host
+        detail: { formData: this.formState },
+      }),
+    );
+  }
+}
+```
+
+---
+
+## Quick Decision Guide
+
+| Situation                                          | Pattern                                                        |
+| -------------------------------------------------- | -------------------------------------------------------------- |
+| Child notifies direct parent                       | `bubbles: false`, `composed: false`                            |
+| Child notifies distant ancestor (same shadow tree) | `bubbles: true`, `composed: false`                             |
+| Slotted component notifies slot host               | `bubbles: true`, `composed: true`                              |
+| Cross-region on App Builder / Experience Cloud     | Use **LMS**                                                    |
+| Event name                                         | Prefer kebab-case; handler is `on` + name, all lowercase       |
+| Payload                                            | Always in **`detail`** — typed with a generic `CustomEvent<T>` |
+
+---
+
+**Reference:** [Create and Dispatch Events — Salesforce LWC Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/events-create-dispatch.html)

package/skill/rules/events-lms.md

@@ -0,0 +1,193 @@
+# events-lms
+
+**Impact: HIGH**
+
+Lightning Message Service (LMS) is the platform-native solution for communication between components that have no parent-child relationship, or that live in different shadow roots across App Builder regions and Experience Cloud portal slots.
+
+> **Rule:**
+>
+> - Use LMS when components have **no shared parent**, or live in **different App Builder regions / Experience Cloud slots**.
+> - Always **unsubscribe** in `disconnectedCallback` to prevent memory leaks.
+> - Define each message channel in a dedicated `.messageChannel` metadata file.
+
+> **Note for Jest tests:** `@salesforce/messageChannel` requires a mock in Jest. Add the mock in `jest.config.js`:
+>
+> ```javascript
+> moduleNameMapper: {
+>   '@salesforce/messageChannel/(.+)': '<rootDir>/path/to/__mocks__/messageChannel.js'
+> }
+> ```
+
+---
+
+## Decision Guide: LMS vs Custom Event
+
+| Scenario                                                  | Use                                                      |
+| --------------------------------------------------------- | -------------------------------------------------------- |
+| Child notifies direct parent                              | Custom event (`bubbles: false`)                          |
+| Child notifies distant ancestor (same shadow tree)        | Custom event (`bubbles: true`)                           |
+| Component in Experience Cloud header notifies main region | **LMS**                                                  |
+| Two sibling components with no shared parent              | **LMS**                                                  |
+| Cross-tab or cross-page communication                     | Not supported — use server-side state or Platform Events |
+
+---
+
+## Step 1: Define the MessageChannel metadata file
+
+```xml
+<!-- force-app/main/default/messageChannels/AppointmentSelected.messageChannel-meta.xml -->
+<?xml version="1.0" encoding="UTF-8"?>
+<LightningMessageChannel xmlns="http://soap.sforce.com/2006/04/metadata">
+    <masterLabel>AppointmentSelected</masterLabel>
+    <isExposed>true</isExposed>
+    <description>Notifies subscribers when a patient appointment is selected.</description>
+    <lightningMessageFields>
+        <fieldName>appointmentId</fieldName>
+        <description>Salesforce record Id of the selected appointment.</description>
+    </lightningMessageFields>
+    <lightningMessageFields>
+        <fieldName>patientName</fieldName>
+        <description>Display name of the patient.</description>
+    </lightningMessageFields>
+</LightningMessageChannel>
+```
+
+---
+
+## Step 2: Publisher
+
+**Incorrect — custom event cannot reach a component in a different region:**
+
+```typescript
+// appointmentList.ts
+handleAppointmentClick(event: Event): void {
+    const target = event.currentTarget as HTMLElement;
+    this.dispatchEvent(
+        new CustomEvent('appointmentselected', {
+            bubbles: true,
+            composed: true, // ❌ still won't reach a separate region/slot
+            detail: { appointmentId: target.dataset.id },
+        })
+    );
+}
+```
+
+**Correct — publish via LMS:**
+
+```typescript
+// appointmentList.ts
+import { LightningElement, wire } from "lwc";
+import { MessageContext, publish, MessageContextType } from "lightning/messageService";
+import APPOINTMENT_SELECTED from "@salesforce/messageChannel/AppointmentSelected__c";
+
+interface AppointmentSelectedPayload {
+  appointmentId: string;
+  patientName: string;
+}
+
+// @ts-ignore
+export default class AppointmentList extends LightningElement {
+  // @ts-ignore
+  @wire(MessageContext)
+  messageContext: MessageContextType;
+
+  public handleAppointmentClick(event: Event): void {
+    const target = event.currentTarget as HTMLElement;
+
+    const payload: AppointmentSelectedPayload = {
+      appointmentId: target.dataset.id ?? "",
+      patientName: target.dataset.patientName ?? "",
+    };
+
+    publish(this.messageContext, APPOINTMENT_SELECTED, payload);
+  }
+}
+```
+
+---
+
+## Step 3: Subscriber
+
+**Incorrect — subscribing without unsubscribing:**
+
+```typescript
+// appointmentDetail.ts
+import { LightningElement, wire } from "lwc";
+import { MessageContext, subscribe, MessageContextType } from "lightning/messageService";
+import APPOINTMENT_SELECTED from "@salesforce/messageChannel/AppointmentSelected__c";
+
+// @ts-ignore
+export default class AppointmentDetail extends LightningElement {
+  // @ts-ignore
+  @wire(MessageContext)
+  messageContext: MessageContextType;
+
+  public connectedCallback(): void {
+    subscribe(this.messageContext, APPOINTMENT_SELECTED, (message) => {
+      this.appointmentId = (message as { appointmentId: string }).appointmentId;
+    });
+    // ❌ return value discarded — cannot unsubscribe later
+  }
+}
+```
+
+**Correct — store the subscription handle and unsubscribe in `disconnectedCallback`:**
+
+```typescript
+// appointmentDetail.ts
+import { LightningElement, wire } from "lwc";
+import {
+  MessageContext,
+  subscribe,
+  unsubscribe,
+  MessageContextType,
+  MessageServiceSubscription,
+} from "lightning/messageService";
+import APPOINTMENT_SELECTED from "@salesforce/messageChannel/AppointmentSelected__c";
+
+interface AppointmentSelectedPayload {
+  appointmentId: string;
+  patientName: string;
+}
+
+// @ts-ignore
+export default class AppointmentDetail extends LightningElement {
+  // @ts-ignore
+  @wire(MessageContext)
+  messageContext: MessageContextType;
+
+  subscription: MessageServiceSubscription | null = null;
+  appointmentId: string | null = null;
+
+  public connectedCallback(): void {
+    this.subscription = subscribe(this.messageContext, APPOINTMENT_SELECTED, (message) =>
+      this.handleMessage(message as AppointmentSelectedPayload),
+    );
+  }
+
+  public disconnectedCallback(): void {
+    unsubscribe(this.subscription); // ✅ clean up when component leaves the DOM
+    this.subscription = null;
+  }
+
+  private handleMessage(message: AppointmentSelectedPayload): void {
+    this.appointmentId = message.appointmentId;
+  }
+}
+```
+
+---
+
+## Quick Decision Guide
+
+| Situation                                | Pattern                                               |
+| ---------------------------------------- | ----------------------------------------------------- |
+| Same shadow tree, parent-child           | Custom event                                          |
+| Different regions / unrelated components | LMS                                                   |
+| Payload type                             | Typed interface + cast on receive                     |
+| Unsubscribe                              | Always in `disconnectedCallback`                      |
+| Jest tests                               | Mock `@salesforce/messageChannel` in `jest.config.js` |
+
+---
+
+**Reference:** [Lightning Message Service — Salesforce LWC Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/use-message-service.html)

package/skill/rules/template-directives.md

@@ -0,0 +1,191 @@
+# template-directives
+
+**Impact: HIGH**
+
+LWC introduced modern template directives in API version 58.0. The old `if:true` / `if:false` directives are deprecated. Always use `lwc:if` / `lwc:elseif` / `lwc:else` for conditionals and `for:each` with a `key` for loops.
+
+> **Rule:**
+>
+> - Never use `if:true` or `if:false` — use `lwc:if` / `lwc:elseif` / `lwc:else`.
+> - `lwc:elseif` and `lwc:else` must be **direct siblings** of `lwc:if` — no elements between them.
+> - Always use `for:each` with a unique `key` on the **direct child element** — never on the `<template>` tag.
+> - Never use array index as `key` — use a stable unique ID from the data.
+
+---
+
+## Case 1: Conditional rendering
+
+**Incorrect — deprecated directives:**
+
+```html
+<template>
+  <template if:true="{isLoading}">
+    <lightning-spinner></lightning-spinner>
+  </template>
+  <template if:false="{isLoading}">
+    <template if:true="{hasData}">
+      <p>{appointment.Name}</p>
+    </template>
+  </template>
+</template>
+```
+
+**Correct — modern directives:**
+
+```html
+<template>
+  <template lwc:if="{isLoading}">
+    <lightning-spinner></lightning-spinner>
+  </template>
+
+  <template lwc:elseif="{hasData}">
+    <p>{appointment.Name}</p>
+  </template>
+
+  <template lwc:else>
+    <p>No appointment found.</p>
+  </template>
+</template>
+```
+
+> ⚠️ **Sibling rule:** `lwc:elseif` / `lwc:else` must immediately follow `lwc:if` with no elements in between, or the chain breaks silently.
+>
+> ```html
+> <!-- ❌ Breaks the chain — p element between if and elseif -->
+> <template lwc:if="{condA}">...</template>
+> <p>something</p>
+> <template lwc:elseif="{condB}">...</template>
+> ```
+
+```typescript
+// appointmentCard.ts
+import { LightningElement, api, wire } from "lwc";
+import { getRecord, getFieldValue } from "lightning/uiRecordApi";
+import NAME_FIELD from "@salesforce/schema/Appointment__c.Name";
+
+// @ts-ignore
+export default class AppointmentCard extends LightningElement {
+  // @ts-ignore
+  @api recordId: string;
+
+  isLoading: boolean = true;
+  appointment: Record<string, unknown> | null = null;
+
+  // @ts-ignore
+  @wire(getRecord, { recordId: "$recordId", fields: [NAME_FIELD] })
+  public handleRecord({ data, error }: { data?: Record<string, unknown>; error?: unknown }): void {
+    this.isLoading = false;
+    if (data) {
+      this.appointment = data;
+    }
+  }
+
+  public get hasData(): boolean {
+    return !!this.appointment;
+  }
+
+  public get appointmentName(): string | null {
+    return getFieldValue(this.appointment, NAME_FIELD) as string | null;
+  }
+}
+```
+
+---
+
+## Case 2: Rendering a list with `for:each`
+
+**Incorrect — `key` on `<template>` tag (ignored by LWC engine):**
+
+```html
+<!-- ❌ key on <template> is ignored -->
+<template for:each="{appointments}" for:item="appt" key="{appt.Id}">
+  <div>
+    <p>{appt.Name}</p>
+  </div>
+</template>
+```
+
+**Incorrect — array index as key:**
+
+```html
+<!-- ❌ causes incorrect DOM reuse on reorder/remove -->
+<template for:each="{appointments}" for:item="appt" for:index="idx">
+  <div key="{idx}">
+    <p>{appt.Name}</p>
+  </div>
+</template>
+```
+
+**Correct — `key` on the direct child element, using a stable record ID:**
+
+```html
+<template>
+  <template for:each="{appointments}" for:item="appt">
+    <div key="{appt.Id}">
+      <p>{appt.Name}</p>
+      <p>{appt.Status__c}</p>
+    </div>
+  </template>
+</template>
+```
+
+```typescript
+// appointmentList.ts
+import { LightningElement, api, wire } from "lwc";
+import getAppointments from "@salesforce/apex/AppointmentController.getAppointments";
+
+interface AppointmentRecord {
+  Id: string;
+  Name: string;
+  Status__c: string;
+  IsUrgent__c: boolean;
+}
+
+// @ts-ignore
+export default class AppointmentList extends LightningElement {
+  // @ts-ignore
+  @api recordId: string;
+
+  // @ts-ignore
+  @wire(getAppointments, { recordId: "$recordId" })
+  appointments: { data?: AppointmentRecord[]; error?: unknown };
+}
+```
+
+---
+
+## Case 3: Conditional rendering inside a loop
+
+```html
+<template>
+  <template for:each="{appointments.data}" for:item="appt">
+    <div key="{appt.Id}" class="slds-m-bottom_small">
+      <p>{appt.Name}</p>
+
+      <template lwc:if="{appt.IsUrgent__c}">
+        <lightning-badge label="Urgent" class="slds-theme_error"></lightning-badge>
+      </template>
+
+      <template lwc:else>
+        <lightning-badge label="Routine"></lightning-badge>
+      </template>
+    </div>
+  </template>
+</template>
+```
+
+---
+
+## Quick Decision Guide
+
+| Situation                       | Pattern                                                     |
+| ------------------------------- | ----------------------------------------------------------- |
+| Show/hide one block             | `lwc:if`                                                    |
+| if / else if / else             | `lwc:if` + `lwc:elseif` + `lwc:else` (direct siblings only) |
+| Render a list                   | `for:each` + `key` on direct child element                  |
+| Key value                       | Stable record ID — never array index                        |
+| Conditional content inside loop | `lwc:if` inside `for:each`                                  |
+
+---
+
+**Reference:** [Render Lists — Salesforce LWC Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-directives.html)