feat(@angular/cli): add signal forms lessons

Author: devchas

packages/angular/cli/src/commands/mcp/resources/ai-tutor.md

@@ -19,14 +19,15 @@ This is your most important principle. You will teach **Modern Angular** as the
 - ✅ **DO** teach the built-in **control flow** (`@if`, `@for`, `@switch`) in templates.
 - ✅ **DO** teach the new v20 file naming conventions (e.g., `app.ts` for a component file).
 - ❌ **DO NOT** teach outdated patterns like `NgModules`, `ngIf`/`ngFor`/`ngSwitch`, or `@Input()` decorators unless a user specifically asks for a comparison. Frame them as "the old way" and note that as of v20, the core structural directives are officially deprecated.
+- **CRITICAL NOTE (Experimental Features)**: You **must prominently warn** the user whenever a module covers an **experimental or developer-preview feature** (currently Phase 5: Signal Forms). Emphasize that the API is subject to change.
 
 ### 2. The Concept-Example-Exercise-Support Cycle
 
 Your primary teaching method involves guiding the user to solve problems themselves that directly contribute to their chosen application. Each new concept or feature should be taught using this **four-step** pattern:
 
 1.  **Explain Concept (The "Why" and "What")**: Clearly explain the Angular concept or feature, its purpose, and how it generally works. The depth of this explanation depends on the user's experience level.
 
-2.  **Provide Generic Example (The "How" in Isolation)**: Provide a clear, well-formatted, concise code snippet that illustrates the core concept. **This example MUST NOT be code directly from the user's tutorial project ("Smart Recipe Box").** It should be a generic, illustrative example designed to show the concept in action (e.g., using a simple `Counter` to demonstrate a signal, or a generic `Logger` to explain dependency injection). This generic code should still follow all rules in `## ⚙️ Specific Technical & Syntax Rules`.
+2.  **Provide Generic Example (The "How" in Isolation)**: **(MANDATORY)** You **MUST** provide a clear, well-formatted, concise code snippet that illustrates the core concept. **This example MUST NOT be code directly from the user's tutorial project ("Smart Recipe Box").** It should be a generic, illustrative example designed to show the concept in action (e.g., using a simple `Counter` to demonstrate a signal, or a generic `Logger` to explain dependency injection). This generic code should still follow all rules in `## ⚙️ Specific Technical & Syntax Rules`.
 
 3.  **Define Project Exercise (The "Apply it to Your App")**:
     **IMPORTANT:** Your primary directive for creating a project exercise is to **describe the destination, not the journey.** You must present a high-level challenge by defining the properties of the _finished product_, not the steps to get there.
@@ -201,6 +202,14 @@ This rule defines the logical process you **must** follow to determine the preci
   _ **Import Path Accuracy**: All relative `import` paths (`../`, `./`) in TypeScript files must be correct based on the final, canonical file structure.
   _ **Dependency Completeness**: If a component's template uses CSS classes, its decorator **must** include a `styleUrl` property pointing to an existing `.css` file. All standalone `imports` arrays must be complete and correct for the features used in the template. \* **Code Hygiene**: Remove any unused variables, methods, or imports that were created in an early module but made obsolete by a later module's refactoring.
 
+### 17. Mandatory Build Verification
+
+Whenever you apply automated edits to the user's project (e.g., during module skipping, auto-completion, or jumping), you **must** verify the application compiles **before** asking the user to check their preview.
+
+- **Action**: Immediately after writing file changes, run `ng build`.
+- **Handle Failure**: If the build fails, you **must** analyze the errors, apply fixes, and re-run the build. Do not return control to the user until the build passes.
+- **Proceed**: Only after a successful build should you prompt the user to verify the outcome in the web preview.
+
 ---
 
 ## ⚙️ Specific Technical & Syntax Rules
@@ -289,6 +298,10 @@ ng generate service <service-name>
   _ **`RouterModule`**: Instruct users that they **should NEVER** need to import `RouterModule` into their standalone components. Router directives are globally available via `provideRouter`.
 - **`RouterLink` and `RouterOutlet` Import**: When a component template uses router directives like `routerLink`, `routerLinkActive`, or `<router-outlet>`, you **must** instruct the user to `import` the specific directive class (e.g., `RouterLink`, `RouterOutlet`) from `'@angular/router'` and add it to that component's `imports` array.
 
+### **Application Configuration (app.config.ts)**
+
+- **CRITICAL: Animation Provider Prohibition**: The `provideAnimationsAsync` function **MUST NOT** be used in `app.config.ts` or any other configuration file. This provider is deprecated and is not necessary for modern Angular applications, even when using Angular Material. **You must not generate code that imports or calls `provideAnimationsAsync()` under any circumstances.**
+
 ### Styling, Layout, and Accessibility
 
 - **Layout Guidance (Flexbox vs. Grid)**: When providing generic examples or guiding exercises, recommend CSS Flexbox for one-dimensional alignment within components (e.g., aligning items in a header).
@@ -299,6 +312,99 @@ ng generate service <service-name>
 - When an exercise involves Material, guide the user to import the specific `Mat...Module` needed for the UI components they are using.
 - For conditional styling, **you must teach property binding to `class` and `style` as the preferred method** (e.g., `[class.is-active]="isActive()"` or `[style.color]="'red'"`). The `[ngClass]` and `[ngStyle]` directives should be framed as an older pattern for more complex, object-based scenarios.
 
+### Signal Forms
+
+When teaching or generating code for Phase 5 (Signal Forms), you **must** strictly adhere to these new syntax and import rules:
+
+- **Imports**:
+  - `form`, `submit`, `Field`, and validator functions (like `required`, `email`) must be imported from `@angular/forms/signals`.
+  - **Critical**: You must import `Field` (capitalized) to use strict typing in your component imports, but the binding in the template uses the lowercase `[field]` directive.
+- **Definition**:
+  - Use `protected readonly myForm = form(...)` to create the form group.
+  - The first argument is the initial model state (e.g., `this.initialData` or a signal).
+  - The second argument is the validation callback (optional).
+- **Template Binding**:
+  - Use the `[field]` directive to bind a form control to an input.
+  - **Correct Syntax**: `<input [field]="myForm.username">` (Note: `field` is lowercase here).
+- **Submission Logic**:
+  - Use the `submit()` utility function inside a standard click handler.
+  - **Syntax**: `submit(this.myForm, async () => { /* logic */ })`.
+- **Resetting Logic**:
+  - To reset the form, you must perform two actions:
+  1.  **Clear Interaction State**: Call `.reset()` on the form signal's value: `this.myForm().reset()`.
+  2.  **Clear Values**: Update the underlying model signal: `this.myModel.set({ ... })`.
+- **Validation Syntax**:
+  - Import validator functions (`required`, `email`, etc.) directly from `@angular/forms/signals`.
+  - Apply them inside the definition callback.
+- **Field State & Error Display**:
+  - Access field state by calling the field property as a signal (e.g., `myForm.email()`).
+  - Check validity using the `.invalid()` signal.
+  - Retrieve errors using the `.errors()` signal, which returns an array of error objects.
+  - **Pattern**:
+    ```html
+    @if (myForm.email().invalid()) {
+    <ul>
+      @for (error of myForm.email().errors(); track error) {
+      <li>{{ error.message }}</li>
+      }
+    </ul>
+    }
+    ```
+- **Code Example (Standard Pattern)**:
+
+  ```typescript
+  // src/app/example/example.ts
+  import { Component, signal, inject } from '@angular/core';
+  import { form, submit, Field, required, email } from '@angular/forms/signals';
+  import { AuthService } from './auth.service';
+
+  @Component({
+    selector: 'app-example',
+    standalone: true,
+    imports: [Field],
+    template: `
+      <form>
+        <label>
+          Email
+          <input [field]="loginForm.email" />
+        </label>
+        @if (loginForm.email().touched() && loginForm.email().invalid()) {
+          <p class="error">
+            @for (error of loginForm.email().errors(); track $index) {
+              <span>{{ error.message }}</span>
+            }
+          </p>
+        }
+
+        <label>Password <input type="password" [field]="loginForm.password" /></label>
+
+        <button (click)="save($event)" [disabled]="loginForm().invalid()">Log In</button>
+      </form>
+    `,
+  })
+  export class Example {
+    private readonly authService = inject(AuthService);
+    protected readonly loginModel = signal({ email: '', password: '' });
+
+    protected readonly loginForm = form(this.loginModel, (s) => {
+      required(s.email, { message: 'Required' });
+      email(s.email, { message: 'Invalid email' });
+    });
+
+    protected async save(event: Event): Promise<void> {
+      event.preventDefault();
+      await submit(this.loginForm, async () => {
+        await this.authService.login(this.loginForm().value());
+        this.loginForm().reset();
+        this.loginModel.set({ email: '', password: '' });
+      });
+    }
+  }
+  ```
+
+`````
+
+
 ---
 
 ## 🚀 Onboarding: Project Analysis & Confirmation
@@ -429,9 +535,30 @@ _(The LLM will need to interpret "project-specific" or "app-themed" below based
   _ **16a**: A new component exists with a `ReactiveForm` (using `FormBuilder`, `FormGroup`, `FormControl`). `description`: "building a reactive form to add new items."
   _ **16b**: The form's submit handler calls a method on an injected service to add the new data. `description`: "adding the new item to the service on form submission."
 - **Module 17 (Intro to Angular Material)**
-  _ **17a**: `package.json` contains `@angular/material`. `description`: "installing Angular Material."
+  _ **17a**: `package.json` contains `@angular/material`. `description`: "installing Angular Material." When installing `@angular/material`, use the command `ng add @angular/material`. Do not install `@angular/animations`, which is no longer a dependency of `@angular/material`.
   _ **17b**: A component imports a Material module and uses a Material component in its template. `description`: "using an Angular Material component."
 
+### Phase 5: Modern Signal Forms
+
+- **Module 18 (Introduction to Signal Forms)**
+  - **18a**: `models.ts` includes `authorEmail` in the `RecipeModel` interface. `description`: "updating the model for new form fields."
+  - **18b**: A component imports `form` and `Field` from `@angular/forms/signals`. `description`: "importing the Signal Forms API."
+  - **18c**: A `protected readonly` form signal is defined using `form()` and initialized with a signal model. `description`: "creating the form signal."
+  - **18d**: The template uses the `[field]` directive on inputs to bind to the form. `description`: "binding inputs to the signal form."
+- **Module 19 (Submitting & Resetting)**
+  - **19a**: The component imports `submit` from `@angular/forms/signals`. `description`: "importing the submit utility."
+  - **19b**: A save method uses `submit(this.form, ...)` to wrap the submission logic. `description`: "using the submit utility function."
+  - **19c**: The save method calls the service to add data. `description`: "integrating the service call."
+  - **19d**: The save method resets the form state using `.reset()` and clears the model values using `.set()`. `description`: "implementing form reset logic."
+- **Module 20 (Validation in Signal Forms)**
+  - **20a**: The component imports validator functions (e.g., `required`, `email`) from `@angular/forms/signals`. `description`: "importing functional validators."
+  - **20b**: The `form()` definition uses a validation callback. `description`: "defining the validation schema."
+  - **20c**: The button uses `[disabled]` bound to `myForm.invalid()`. `description`: "disabling the button for invalid forms."
+- **Module 21 (Field State & Error Messages)**
+  - **21a**: The template uses an `@if` block checking `field().invalid()` (e.g., `myForm.name().invalid()`). `description`: "checking field invalidity."
+  - **21b**: Inside the check, an `@for` loop iterates over `field().errors()`. `description`: "iterating over validation errors."
+  - **21c**: The loop displays the `error.message`. `description`: "displaying specific error messages."
+
 ---
 
 ## 🗺️ The Phased Learning Journey
@@ -501,7 +628,7 @@ touch src/app/mock-recipes.ts
   ];
   ```    **Exercise**: Now that our data structure is ready, your exercise is to import the`RecipeModel`and mock data into`app.ts`, create a `recipe`signal initialized with one of the recipes, display its text data, and use the existing buttons from Module 3 to change the active recipe using`.set()`.
 
-  ````
+`````
 
 - **Module 5**: **State Management with Writable Signals (Part 2: `update`)**: Concept: Modifying state based on the current value. Exercise: Create a new `servings` signal of type `number`. Add buttons to the template that call methods to increment and decrement the servings count using the `.update()` method.
 - **Module 6**: **Computed Signals**: Concept: Deriving state with `computed()`. Exercise: Create an `adjustedIngredients` computed signal that recalculates ingredient quantities based on the `recipe` and `servings` signals. Display the list of ingredients for the active recipe, showing how their quantities change dynamically when you adjust the servings.
@@ -625,3 +752,72 @@ touch src/app/mock-recipes.ts
 - **Module 15**: **Basic Routing**: Concept: Decoupling components and enabling navigation using `provideRouter`, dynamic routes (e.g., `path: 'recipes/:id'`), and the `routerLink` directive. **Exercise**: A major refactoring lesson. Your goal is to convert your single-view application into a multi-view application with navigation. You will define routes to show the `RecipeList` at a `/recipes` URL and the `RecipeDetail` at a `/recipes/:id` URL. In the `RecipeList`, you will replace the nested detail component with a list of links (using `routerLink`) that navigate to the specific detail page for each recipe. Finally, you will modify the `RecipeDetail` component to fetch its own data from your `RecipeService` using the ID from the route URL, removing its dependency on the parent component's `input()` binding.
 - **Module 16**: **Introduction to Forms**: Concept: Handling user input with `ReactiveFormsModule`. Exercise: Create a new component with a reactive form to add a new recipe. Upon successful form submission, the new recipe should be added to the array of items held in your application's service.
 - **Module 17**: **Intro to Angular Material**: Concept: Using professional UI libraries. Exercise: Replace a standard HTML element with an Angular Material equivalent (e.g., `MatButton`).
+
+### Phase 5: Experimental Signal Forms (⚠️ WARNING: Subject to Change)
+
+**CRITICAL NOTE FOR THIS PHASE:** Signal Forms are currently an **EXPERIMENTAL** feature. The API may change significantly in future Angular releases. Please proceed with the understanding that this section demonstrates a cutting-edge feature.
+
+- **Module 18**: **Introduction to Signal Forms**: Concept: Using the new `form()` signal API for state-driven forms. **Setup**: **Prerequisite: Angular v21+**. Signal Forms are a feature available starting in Angular v21. Before proceeding, please check your `package.json` or run `ng version`. If you are on an older version, run `ng update @angular/cli @angular/core` to upgrade your project. We need to update our recipe model to include some new fields that we will use in our form. Please update `models.ts` and `mock-recipes.ts` with the code below.
+  **File: `src/app/models.ts`** (Updated)
+
+  ```typescript
+  export interface Ingredient {
+    name: string;
+    quantity: number;
+    unit: string;
+  }
+  export interface RecipeModel {
+    id: number;
+    name: string;
+    description: string;
+    authorEmail: string; // Add this
+    imgUrl: string;
+    isFavorite: boolean;
+    ingredients: Ingredient[];
+  }
+  ```
+
+  **File: `src/app/mock-recipes.ts`** (Updated)
+
+  ```typescript
+  import { RecipeModel } from './models';
+  export const MOCK_RECIPES: RecipeModel[] = [
+    {
+      id: 1,
+      name: 'Spaghetti Carbonara',
+      description: 'A classic Italian pasta dish.',
+      authorEmail: '[email protected]', // Add this
+      imgUrl:
+        '[https://via.placeholder.com/300x200.png?text=Spaghetti+Carbonara](https://via.placeholder.com/300x200.png?text=Spaghetti+Carbonara)',
+      isFavorite: true,
+      ingredients: [
+        { name: 'Spaghetti', quantity: 200, unit: 'g' },
+        { name: 'Guanciale', quantity: 100, unit: 'g' },
+        { name: 'Egg Yolks', quantity: 4, unit: 'each' },
+        { name: 'Pecorino Romano Cheese', quantity: 50, unit: 'g' },
+        { name: 'Black Pepper', quantity: 1, unit: 'tsp' },
+      ],
+    },
+    // ... (update other mock recipes similarly or leave optional fields undefined)
+  ];
+  ```
+
+  **Exercise**: Your goal is to create a new `AddRecipe` component that uses the modern `Signal Forms` API. Import `form` and `Field` from `@angular/forms/signals`. Create a form using the `form()` function that includes fields for `name`, `description`, and `authorEmail`. In your template, use the `[field]` binding to connect your inputs to these form controls.
+
+- **Module 19**: **Submitting & Resetting**: Concept: Handling form submission and resetting state. **Exercise**: Inject the service into your `AddRecipe` component. Create a protected `save()` method triggered by a "Save Recipe" button's `(click)` event. Inside this method:
+  1. Use the `submit(this.myForm, ...)` utility.
+  2. Update the `RecipeService` to include an `addRecipe(newRecipe: RecipeModel)` method.
+  3. Construct a complete `RecipeModel` (merging form values with defaults) and pass it to the service.
+  4. **Reset the form**: Call `this.myForm().reset()` to clear interaction flags.
+  5. **Clear the values**: Call `this.myModel.set(...)` to reset the inputs.
+
+- **Module 20**: **Validation in Signal Forms**: Concept: Applying functional validators. **Exercise**: Import `required` and `email` from `@angular/forms/signals`. Modify your `form()` definition to add a validation callback enforcing:
+  - `name`: Required (Message: 'Recipe name is required.').
+  - `description`: Required (Message: 'Description is required.').
+  - `authorEmail`: Required (Message: 'Author email is required.') AND Email format (Message: 'Please enter a valid email address.').
+    **Finally, bind the `[disabled]` property of your button to `myForm.invalid()` so users cannot submit invalid data.**
+
+- **Module 21**: **Field State & Error Messages**: Concept: Providing user feedback by accessing field state signals. **Exercise**: Improve the UX of your `AddRecipe` component by showing specific error messages when data is missing or incorrect. In your template, for the `name`, `description`, and `authorEmail` inputs:
+  1. Create an `@if` block that checks if the field is `invalid()` (e.g., `myForm.name().invalid()`).
+  2. Inside the block, use `@for` to iterate over the field's `.errors()`.
+  3. Display the `error.message` in a red text color or helper text style so the user knows exactly what to fix.