fe-lwc-skill 1.0.0

package/skill/rules/template-dom-querying.md

@@ -0,0 +1,202 @@
+# template-dom-querying
+
+**Impact: HIGH**
+
+DOM querying in LWC is scoped to `this.template`. You cannot reach into a child component's DOM from a parent — attempting to do so always returns `null`.
+
+> **Rule:**
+>
+> - Always use `data-id` attributes as query selectors — never class names or tag names.
+> - `this.template.querySelector` is safe inside event handlers and `renderedCallback` — **not** in `connectedCallback`.
+> - Never query DOM across component boundaries. Expose `@api` methods on children instead.
+
+---
+
+## Case 1: Querying across component boundaries
+
+**Incorrect — parent queries into child's shadow DOM (always returns null):**
+
+```typescript
+// patientOnboarding.ts
+import { LightningElement } from "lwc";
+
+// @ts-ignore
+export default class PatientOnboarding extends LightningElement {
+  currentStep: number = 1;
+
+  public handleNext(): void {
+    // ❌ Always returns null — shadow DOM blocks cross-component queries
+    const input = this.template.querySelector("c-patient-onboarding-step1 lightning-input");
+    if (!input) return;
+    this.currentStep = 2;
+  }
+}
+```
+
+**Correct — parent calls `@api` method on child, child validates its own DOM:**
+
+```typescript
+// patientOnboardingStep1.ts
+import { LightningElement, api } from "lwc";
+
+// @ts-ignore
+export default class PatientOnboardingStep1 extends LightningElement {
+  // @ts-ignore
+  @api
+  public validate(): boolean {
+    const inputs = this.template.querySelectorAll<HTMLInputElement>("lightning-input");
+    return [...inputs].reduce((isValid, input) => {
+      input.reportValidity();
+      return isValid && input.checkValidity();
+    }, true);
+  }
+}
+```
+
+```typescript
+// patientOnboarding.ts
+import { LightningElement } from "lwc";
+
+interface StepComponent extends HTMLElement {
+  validate(): boolean;
+}
+
+// @ts-ignore
+export default class PatientOnboarding extends LightningElement {
+  currentStep: number = 1;
+
+  public get isStep1(): boolean {
+    return this.currentStep === 1;
+  }
+  public get isStep2(): boolean {
+    return this.currentStep === 2;
+  }
+
+  public handleNext(): void {
+    const stepComponent = this.template.querySelector<StepComponent>('[data-id="current-step"]');
+    if (!stepComponent) return;
+
+    // ✅ Child validates itself — parent only asks for the result
+    if (!stepComponent.validate()) return;
+
+    this.currentStep += 1;
+  }
+
+  public handlePrev(): void {
+    this.currentStep -= 1;
+  }
+}
+```
+
+```html
+<!-- patientOnboarding.html -->
+<template>
+  <template lwc:if="{isStep1}">
+    <c-patient-onboarding-step1 data-id="current-step"></c-patient-onboarding-step1>
+  </template>
+  <template lwc:if="{isStep2}">
+    <c-patient-onboarding-step2 data-id="current-step"></c-patient-onboarding-step2>
+  </template>
+  <div>
+    <lightning-button label="Back" onclick="{handlePrev}"></lightning-button>
+    <lightning-button variant="brand" label="Next" onclick="{handleNext}"></lightning-button>
+  </div>
+</template>
+```
+
+> `data-id="current-step"` stays the same across all steps — parent always queries the same selector.
+
+---
+
+## Case 2: Class/tag selectors instead of `data-id`
+
+**Incorrect — fragile selectors tied to implementation details:**
+
+```typescript
+// bookingForm.ts
+handleSubmit(event: Event): void {
+    event.preventDefault();
+    // ❌ Breaks if class name changes or element type is swapped
+    const input = this.template.querySelector<HTMLInputElement>('.date-input');
+}
+```
+
+**Correct — stable `data-id` selectors:**
+
+```typescript
+// bookingForm.ts
+import { LightningElement } from "lwc";
+
+// @ts-ignore
+export default class BookingForm extends LightningElement {
+  public handleSubmit(event: Event): void {
+    event.preventDefault();
+
+    const dateInput = this.template.querySelector<HTMLInputElement>('[data-id="date-input"]');
+    const timeInput = this.template.querySelector<HTMLInputElement>('[data-id="time-input"]');
+
+    if (!dateInput || !timeInput) return;
+
+    if (!dateInput.checkValidity() || !timeInput.checkValidity()) {
+      dateInput.reportValidity();
+      timeInput.reportValidity();
+      return;
+    }
+
+    this.submitBooking();
+  }
+
+  private submitBooking(): void {
+    // submit logic
+  }
+}
+```
+
+```html
+<!-- bookingForm.html -->
+<template>
+  <form onsubmit="{handleSubmit}">
+    <lightning-input data-id="date-input" name="date" type="date" label="Appointment Date" required></lightning-input>
+    <lightning-input data-id="time-input" name="time" type="time" label="Appointment Time" required></lightning-input>
+    <lightning-button type="submit" variant="brand" label="Book"></lightning-button>
+  </form>
+</template>
+```
+
+---
+
+## Case 3: Querying multiple elements with `querySelectorAll`
+
+```typescript
+// patientOnboardingStep2.ts
+import { LightningElement, api } from "lwc";
+
+// @ts-ignore
+export default class PatientOnboardingStep2 extends LightningElement {
+  // @ts-ignore
+  @api
+  public validate(): boolean {
+    const allInputs = this.template.querySelectorAll<HTMLInputElement>("lightning-input, lightning-textarea");
+    return [...allInputs].reduce((isValid, input) => {
+      input.reportValidity();
+      return isValid && input.checkValidity();
+    }, true);
+  }
+}
+```
+
+---
+
+## Quick Decision Guide
+
+| Situation                              | Pattern                                                      |
+| -------------------------------------- | ------------------------------------------------------------ |
+| Query element in the same component    | `this.template.querySelector<T>('[data-id="x"]')`            |
+| Safe timing for querySelector          | Event handlers, `renderedCallback` — not `connectedCallback` |
+| Trigger behavior in a child            | Expose `@api` method on child, call from parent              |
+| Validate all inputs in a form          | `querySelectorAll('lightning-input')` + `reduce`             |
+| Query child's internal DOM from parent | ❌ Not possible — Shadow DOM blocks it                       |
+
+---
+
+**Reference:** [Access Elements the Component Owns — Salesforce LWC Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.html)

package/skill/rules/template-form-pattern.md

@@ -0,0 +1,285 @@
+# template-form-pattern
+
+**Impact: HIGH**
+
+LWC provides `lightning-record-edit-form` for standard CRUD forms. Only build a custom form when the UX requirement goes beyond what the base component supports.
+
+> **Rule:**
+>
+> - Use `lightning-record-edit-form` for simple create/edit of a single record.
+> - In custom forms, use a single `handleChange` keyed on `event.target.name` — never per-field handlers.
+> - Keep all form state in one typed interface.
+> - In multi-step wizards, the parent owns state and submits once at the final step. Each step exposes `validate()` and `getFormData()` as `@api` methods.
+
+---
+
+## When to use `lightning-record-edit-form`
+
+```html
+<!-- appointmentEditForm.html — no JS needed -->
+<template>
+  <lightning-record-edit-form record-id="{recordId}" object-api-name="Appointment__c">
+    <lightning-messages></lightning-messages>
+    <lightning-input-field field-name="Name"></lightning-input-field>
+    <lightning-input-field field-name="Date__c"></lightning-input-field>
+    <lightning-input-field field-name="Status__c"></lightning-input-field>
+    <lightning-button type="submit" variant="brand" label="Save"></lightning-button>
+  </lightning-record-edit-form>
+</template>
+```
+
+---
+
+## When to use a custom form
+
+| Situation                            | Reason                                         |
+| ------------------------------------ | ---------------------------------------------- |
+| Multi-step wizard                    | `lightning-record-edit-form` cannot span steps |
+| Conditional fields                   | Requires reactive state control                |
+| Data from multiple objects           | LDS handles one object at a time               |
+| Custom validation beyond field-level | Needs manual `checkValidity`                   |
+
+---
+
+## Case 1: Conditional fields — single `handleChange`, centralized state
+
+**Incorrect — per-field handlers, scattered booleans:**
+
+```typescript
+// referralForm.ts
+import { LightningElement } from "lwc";
+
+// @ts-ignore
+export default class ReferralForm extends LightningElement {
+  referralType: string = "";
+  specialistName: string = "";
+  clinicName: string = "";
+  showSpecialistFields: boolean = false;
+
+  // ❌ Grows linearly with form size
+  public handleTypeChange(event: Event): void {
+    this.referralType = (event.target as HTMLInputElement).value;
+    this.showSpecialistFields = this.referralType === "specialist";
+  }
+
+  public handleSpecialistChange(event: Event): void {
+    this.specialistName = (event.target as HTMLInputElement).value;
+  }
+}
+```
+
+**Correct — single `handleChange`, derived conditional from state:**
+
+```typescript
+// referralForm.ts
+import { LightningElement } from "lwc";
+
+interface ReferralFormState {
+  referralType: string;
+  specialistName: string;
+  clinicName: string;
+  notes: string;
+}
+
+// @ts-ignore
+export default class ReferralForm extends LightningElement {
+  formState: ReferralFormState = {
+    referralType: "",
+    specialistName: "",
+    clinicName: "",
+    notes: "",
+  };
+
+  // ✅ One handler for all fields
+  public handleChange(event: Event): void {
+    const target = event.target as HTMLInputElement;
+    this.formState = { ...this.formState, [target.name]: target.value };
+  }
+
+  // ✅ Derived from state — no extra boolean needed
+  public get showSpecialistFields(): boolean {
+    return this.formState.referralType === "specialist";
+  }
+
+  public handleSubmit(event: Event): void {
+    event.preventDefault();
+    const allInputs = this.template.querySelectorAll<HTMLInputElement>("lightning-input, lightning-combobox");
+    const isValid = [...allInputs].reduce((valid, input) => {
+      input.reportValidity();
+      return valid && input.checkValidity();
+    }, true);
+
+    if (!isValid) return;
+    this.submitForm();
+  }
+
+  private submitForm(): void {
+    // submit logic
+  }
+}
+```
+
+---
+
+## Case 2: Multi-step wizard — parent owns state, submits once at final step
+
+**Step component — renders fields, exposes `validate()` and `getFormData()`:**
+
+```typescript
+// onboardingStep1.ts
+import { LightningElement, api } from "lwc";
+
+interface Step1FormState {
+  firstName: string;
+  lastName: string;
+  email: string;
+}
+
+// @ts-ignore
+export default class OnboardingStep1 extends LightningElement {
+  formState: Step1FormState = {
+    firstName: "",
+    lastName: "",
+    email: "",
+  };
+
+  public handleChange(event: Event): void {
+    const target = event.target as HTMLInputElement;
+    this.formState = { ...this.formState, [target.name]: target.value };
+  }
+
+  // @ts-ignore
+  @api
+  public validate(): boolean {
+    const inputs = this.template.querySelectorAll<HTMLInputElement>("lightning-input");
+    return [...inputs].reduce((valid, input) => {
+      input.reportValidity();
+      return valid && input.checkValidity();
+    }, true);
+  }
+
+  // @ts-ignore
+  @api
+  public getFormData(): Step1FormState {
+    return { ...this.formState };
+  }
+}
+```
+
+**Parent — accumulates state, submits once at final step:**
+
+```typescript
+// onboardingWizard.ts
+import { LightningElement } from "lwc";
+import { createRecord } from "lightning/uiRecordApi";
+import { ShowToastEvent } from "lightning/platformShowToastEvent";
+import { reduceErrors } from "c/utils";
+import CONTACT_OBJECT from "@salesforce/schema/Contact";
+
+interface StepComponent extends HTMLElement {
+  validate(): boolean;
+  getFormData(): Record<string, string>;
+}
+
+// @ts-ignore
+export default class OnboardingWizard extends LightningElement {
+  currentStep: number = 1;
+  totalSteps: number = 3;
+  formData: Record<string, string> = {};
+
+  public get isLastStep(): boolean {
+    return this.currentStep === this.totalSteps;
+  }
+
+  public get isStep1(): boolean {
+    return this.currentStep === 1;
+  }
+  public get isStep2(): boolean {
+    return this.currentStep === 2;
+  }
+  public get isStep3(): boolean {
+    return this.currentStep === 3;
+  }
+  public get showPrev(): boolean {
+    return this.currentStep > 1;
+  }
+  public get nextLabel(): string {
+    return this.isLastStep ? "Submit" : "Next";
+  }
+
+  public async handleNext(): Promise<void> {
+    const stepComponent = this.template.querySelector<StepComponent>('[data-id="current-step"]');
+    if (!stepComponent) return;
+
+    if (!stepComponent.validate()) return;
+
+    this.formData = { ...this.formData, ...stepComponent.getFormData() };
+
+    if (this.isLastStep) {
+      await this.submitAll();
+      return;
+    }
+
+    this.currentStep += 1;
+  }
+
+  public handlePrev(): void {
+    this.currentStep -= 1;
+  }
+
+  private async submitAll(): Promise<void> {
+    try {
+      await createRecord({
+        apiName: CONTACT_OBJECT.objectApiName,
+        fields: this.formData,
+      });
+      this.dispatchEvent(new ShowToastEvent({ title: "Success", message: "Onboarding complete.", variant: "success" }));
+    } catch (error) {
+      this.dispatchEvent(
+        new ShowToastEvent({
+          title: "Submission failed",
+          message: reduceErrors(error).join(", "),
+          variant: "error",
+        }),
+      );
+    }
+  }
+}
+```
+
+```html
+<!-- onboardingWizard.html -->
+<template>
+  <template lwc:if="{isStep1}">
+    <c-onboarding-step1 data-id="current-step"></c-onboarding-step1>
+  </template>
+  <template lwc:if="{isStep2}">
+    <c-onboarding-step2 data-id="current-step"></c-onboarding-step2>
+  </template>
+  <template lwc:if="{isStep3}">
+    <c-onboarding-step3 data-id="current-step"></c-onboarding-step3>
+  </template>
+
+  <div>
+    <template lwc:if="{showPrev}">
+      <lightning-button label="Back" onclick="{handlePrev}"></lightning-button>
+    </template>
+    <lightning-button variant="brand" label="{nextLabel}" onclick="{handleNext}"></lightning-button>
+  </div>
+</template>
+```
+
+---
+
+## Quick Decision Guide
+
+| Situation                        | Pattern                                                             |
+| -------------------------------- | ------------------------------------------------------------------- |
+| Simple create/edit single record | `lightning-record-edit-form`                                        |
+| Conditional fields               | Custom form + `get` derived from `formState`                        |
+| Multi-step wizard                | Parent owns `formData`; step exposes `validate()` + `getFormData()` |
+| Per-field change handlers        | ❌ Use single `handleChange` keyed on `name`                        |
+
+---
+
+**Reference:** [Build Custom UI to Create and Edit Records — Salesforce LWC Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/data-salesforce-write.html)

package/skill/rules/template-track-immutable.md

@@ -0,0 +1,206 @@
+# template-track-immutable
+
+**Impact: MEDIUM**
+
+`@track` was required in early LWC to make object/array properties reactive. Since Spring '20, all properties are tracked deeply by default. The correct way to trigger reactivity is through immutable updates.
+
+> **Rule:**
+>
+> - Do not use `@track` — it is no longer needed.
+> - Trigger reactivity on objects: `this.obj = { ...this.obj, key: value }`.
+> - Trigger reactivity on arrays: `[...arr, newItem]`, `arr.filter(...)`, `arr.map(...)`.
+> - Never mutate an object or array in place and expect the template to re-render.
+
+---
+
+## Case 1: Unnecessary `@track`, in-place mutation
+
+**Incorrect:**
+
+```typescript
+// appointmentForm.ts
+import { LightningElement, track } from "lwc";
+
+interface AppointmentFormState {
+  date: string;
+  time: string;
+  notes: string;
+}
+
+// @ts-ignore
+export default class AppointmentForm extends LightningElement {
+  // @ts-ignore
+  @track isLoading: boolean = false; // ❌ unnecessary
+  // @ts-ignore
+  @track errorMessage: string = ""; // ❌ unnecessary
+  // @ts-ignore
+  @track formState: AppointmentFormState = { date: "", time: "", notes: "" };
+
+  public handleChange(event: Event): void {
+    const target = event.target as HTMLInputElement;
+    // ❌ Mutates in place — template may not re-render reliably
+    (this.formState as Record<string, string>)[target.name] = target.value;
+  }
+}
+```
+
+**Correct — no `@track`, immutable update:**
+
+```typescript
+// appointmentForm.ts
+import { LightningElement } from "lwc";
+
+interface AppointmentFormState {
+  date: string;
+  time: string;
+  notes: string;
+}
+
+// @ts-ignore
+export default class AppointmentForm extends LightningElement {
+  isLoading: boolean = false;
+  errorMessage: string = "";
+  formState: AppointmentFormState = { date: "", time: "", notes: "" };
+
+  public handleChange(event: Event): void {
+    const target = event.target as HTMLInputElement;
+    // ✅ New object reference — LWC detects the change and re-renders
+    this.formState = { ...this.formState, [target.name]: target.value };
+  }
+}
+```
+
+---
+
+## Case 2: Mutating an array in place
+
+**Incorrect — push/splice mutates the existing reference, no re-render:**
+
+```typescript
+// appointmentList.ts
+import { LightningElement } from "lwc";
+
+interface AppointmentRecord {
+  Id: string;
+  Name: string;
+}
+
+// @ts-ignore
+export default class AppointmentList extends LightningElement {
+  appointments: AppointmentRecord[] = [];
+
+  public handleAdd(newAppointment: AppointmentRecord): void {
+    this.appointments.push(newAppointment); // ❌ mutates in place
+  }
+
+  public handleRemove(appointmentId: string): void {
+    const index = this.appointments.findIndex((a) => a.Id === appointmentId);
+    this.appointments.splice(index, 1); // ❌ mutates in place
+  }
+}
+```
+
+**Correct — new array reference:**
+
+```typescript
+// appointmentList.ts
+import { LightningElement } from "lwc";
+
+interface AppointmentRecord {
+  Id: string;
+  Name: string;
+}
+
+// @ts-ignore
+export default class AppointmentList extends LightningElement {
+  appointments: AppointmentRecord[] = [];
+
+  public handleAdd(newAppointment: AppointmentRecord): void {
+    this.appointments = [...this.appointments, newAppointment]; // ✅
+  }
+
+  public handleRemove(appointmentId: string): void {
+    this.appointments = this.appointments.filter((a) => a.Id !== appointmentId); // ✅
+  }
+
+  public handleUpdate(updatedAppointment: AppointmentRecord): void {
+    this.appointments = this.appointments.map((a) =>
+      a.Id === updatedAppointment.Id ? { ...a, ...updatedAppointment } : a,
+    ); // ✅
+  }
+
+  public handleRemoveClick(event: Event): void {
+    const target = event.target as HTMLElement;
+    this.handleRemove(target.dataset.id ?? "");
+  }
+}
+```
+
+---
+
+## Case 3: Updating a nested object property
+
+**Incorrect — mutating nested property:**
+
+```typescript
+// profileForm.ts
+public handleAddressChange(event: Event): void {
+    const target = event.target as HTMLInputElement;
+    // ❌ Mutates nested object — no re-render
+    this.formState.address.city = target.value;
+}
+```
+
+**Correct — spread at every changed level:**
+
+```typescript
+// profileForm.ts
+import { LightningElement } from "lwc";
+
+interface Address {
+  city: string;
+  street: string;
+}
+
+interface ProfileFormState {
+  name: string;
+  address: Address;
+}
+
+// @ts-ignore
+export default class ProfileForm extends LightningElement {
+  formState: ProfileFormState = {
+    name: "",
+    address: { city: "", street: "" },
+  };
+
+  public handleAddressChange(event: Event): void {
+    const target = event.target as HTMLInputElement;
+    this.formState = {
+      ...this.formState,
+      address: {
+        ...this.formState.address,
+        [target.name]: target.value,
+      },
+    };
+  }
+}
+```
+
+---
+
+## Quick Decision Guide
+
+| Situation                     | Pattern                                    |
+| ----------------------------- | ------------------------------------------ |
+| Update a primitive property   | Direct assignment: `this.value = newValue` |
+| Update one field in an object | `this.obj = { ...this.obj, field: value }` |
+| Add item to array             | `this.arr = [...this.arr, newItem]`        |
+| Remove item from array        | `this.arr = this.arr.filter(...)`          |
+| Update item in array          | `this.arr = this.arr.map(...)`             |
+| Update nested object          | Spread at every changed level              |
+| Should I use `@track`?        | No                                         |
+
+---
+
+**Reference:** [Reactivity — Salesforce LWC Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reactivity.html)