diff --git a/.agents/skills/angular-developer/SKILL.md b/.agents/skills/angular-developer/SKILL.md index f332e3e08..6ab0e3d77 100644 --- a/.agents/skills/angular-developer/SKILL.md +++ b/.agents/skills/angular-developer/SKILL.md @@ -1,6 +1,6 @@ --- name: angular-developer -description: Generates Angular code and provides architectural guidance. Trigger when creating projects, components, or services, or for best practices on reactivity (signals, linkedSignal, resource), forms, dependency injection, routing, SSR, accessibility (ARIA), animations, styling (component styles, Tailwind CSS), testing, or CLI tooling. +description: Generates Angular code and provides architectural guidance. Trigger when creating projects, components, services, or HTTP communication, or for best practices on reactivity (signals, linkedSignal, resource, httpResource), forms, dependency injection, routing, SSR, accessibility (ARIA), animations, styling (component styles, Tailwind CSS), testing, or CLI tooling. license: MIT metadata: author: Copyright 2026 Google LLC @@ -17,7 +17,7 @@ metadata: ## Creating New Projects -If no guidelines are provided by the user, here are same default rules to follow when creating a new Angular project: +If no guidelines are provided by the user, here are some default rules to follow when creating a new Angular project: 1. Use the latest stable version of Angular unless the user specifies otherwise. 2. Use Signals Forms for form management in new projects (available in Angular v21 and newer) [Find out more](references/signal-forms.md). @@ -61,12 +61,18 @@ When managing state and data reactivity, use Angular Signals and consult the fol - **Async Reactivity (`resource`)**: Fetching asynchronous data directly into signal state. Read [resource.md](references/resource.md) - **Side Effects (`effect`)**: Logging, third-party DOM manipulation (`afterRenderEffect`), and when NOT to use effects. Read [effects.md](references/effects.md) +## HTTP Communication + +When communicating with backend services, use Angular HTTP APIs and consult the following reference: + +- **HTTP Client and Resources**: `provideHttpClient`, `HttpClient`, interceptors, and `httpResource`. Read [http-client.md](references/http-client.md) + ## Forms In most cases for new apps, **prefer signal forms**. When making a forms decision, analyze the project and consider the following guidelines: -- if the application is using v21 or newer and this is a new form, **prefer signal forms**. - -For older applications or when working with existing forms, use the appropriate form type that matches the applications current form strategy. +- If the application is using v21 or newer and this is a new form, **prefer signal forms**. +- For older applications or when working with existing forms, use the appropriate form type that matches the applications current form strategy. - **Signal Forms**: Use signals for form state management. Read [signal-forms.md](references/signal-forms.md) - **Template-driven forms**: Use for simple forms. Read [template-driven-forms.md](references/template-driven-forms.md) @@ -82,6 +88,12 @@ When implementing dependency injection in Angular, follow these guidelines: - **Injection Context**: Where `inject()` is allowed, `runInInjectionContext`, and `assertInInjectionContext`. Read [injection-context.md](references/injection-context.md) - **Hierarchical Injectors**: The `EnvironmentInjector` vs `ElementInjector`, resolution rules, modifiers (`optional`, `skipSelf`), and `providers` vs `viewProviders`. Read [hierarchical-injectors.md](references/hierarchical-injectors.md) +## Pipes + +When formatting values in templates, creating custom pipes, or reusing pipe-like logic in TypeScript, consult the following reference. Prefer pipes in templates; outside templates, avoid injecting pipe classes just to call `transform()`. + +- **Pipes**: Built-in pipe imports, custom pipe naming and implementation, pure vs impure pipes, and TypeScript reuse patterns using standalone formatting functions or extracted plain functions. Read [pipes.md](references/pipes.md) + ## Angular Aria When building accessible custom components for any of the following patterns: Accordion, Listbox, Combobox, Menu, Tabs, Toolbar, Tree, Grid, consult the following reference: @@ -119,7 +131,7 @@ When writing or updating tests, consult the following references based on the ta - **Fundamentals**: Best practices for unit testing (Vitest), async patterns, and `TestBed`. Read [testing-fundamentals.md](references/testing-fundamentals.md) - **Component Harnesses**: Standard patterns for robust component interaction. Read [component-harnesses.md](references/component-harnesses.md) - **Router Testing**: Using `RouterTestingHarness` for reliable navigation tests. Read [router-testing.md](references/router-testing.md) -- **End-to-End (E2E) Testing**: Best practices for E2E tests with Cypress. Read [e2e-testing.md](references/e2e-testing.md) +- **End-to-End (E2E) Testing**: Setting up and running E2E tests. Read [e2e-testing.md](references/e2e-testing.md) ## Tooling @@ -128,3 +140,4 @@ When working with Angular tooling, consult the following references: - **Angular CLI**: Creating applications, generating code (components, routes, services), serving, and building. Read [cli.md](references/cli.md) - **Code Modernization**: Automatically refactoring to modern standards using migrations. Read [migrations.md](references/migrations.md) - **Angular MCP Server**: Available tools, configuration, and experimental features. Read [mcp.md](references/mcp.md) +- **Environment Configuration**: Strategies for build-time and runtime configuration. Read [environment-configuration.md](references/environment-configuration.md) diff --git a/.agents/skills/angular-developer/references/angular-animations.md b/.agents/skills/angular-developer/references/angular-animations.md index c96c4d9c6..4abc961a6 100644 --- a/.agents/skills/angular-developer/references/angular-animations.md +++ b/.agents/skills/angular-developer/references/angular-animations.md @@ -155,6 +155,6 @@ import {trigger, state, style, animate, transition} from '@angular/animations'; template: `
...
`, }) export class OpenClose { - isOpen = signal(true); + protected readonly isOpen = signal(true); } ``` diff --git a/.agents/skills/angular-developer/references/angular-aria.md b/.agents/skills/angular-developer/references/angular-aria.md index 2dd0cf451..4241a2576 100644 --- a/.agents/skills/angular-developer/references/angular-aria.md +++ b/.agents/skills/angular-developer/references/angular-aria.md @@ -44,11 +44,11 @@ export class App { ```html
- -
+

Lazy loaded content here.

 @@ -98,7 +98,7 @@ export class App { ```html -
    +
    • Apple
    • Banana
    @@ -126,37 +126,69 @@ Target `[aria-selected="true"]` for selected state and `:focus-visible` or `[dat ## 3. Combobox, Select, and Multiselect -These patterns combine `ngCombobox` with a popup containing an `ngListbox`. +These patterns combine the `ngCombobox` directive (applied directly to the trigger/combobox element) with a popup containing an `ngListbox` widget. -- **Combobox**: Text input + popup (used for Autocomplete). -- **Select**: Readonly Combobox + single-select Listbox. -- **Multiselect**: Readonly Combobox + multi-select Listbox. - -**Usage:** The Combobox is a low-level primitive directive that synchronizes a text input with a popup, serving as the foundational logic for autocomplete, select, and multiselect patterns. Use it specifically for building custom filtering, unique selection requirements, or specialized input-to-popup coordination that deviates from standard, documented components. +- **Combobox (Autocomplete)**: Applied to an `` element. Ideal when typing filters the list. +- **Select**: Applied to a focusable wrapper like a `
    ` or ` - - -
      -
    • Option 1
      • -
    • Option 2
      • + +
      + + + +
        +
      • Option 1
        • +
      • Option 2
      + + +
      + {{ selectedValue() ?? 'Choose an option' }} + ▼ +
      + + +
        +
      • Option 1
        • +
      • Option 2
        • +
      +       ``` **Styling Strategy:** @@ -186,22 +218,30 @@ For actions, commands, and context menus (not for form selection). **Usage:** The Menubar is a high-level navigation pattern designed for building desktop-style application command bars (e.g., File, Edit, View) that stay persistent across an interface. It is best utilized for organizing complex commands into logical top-level categories with full horizontal keyboard support, but it should be avoided for simple standalone action lists or mobile-first layouts where horizontal space is constrained. -**Imports:** `import {MenuBar, Menu, MenuContent, MenuItem} from '@angular/aria/menu';` +**Imports:** `import {MenuBar, Menu, MenuContent, MenuItem, MenuTrigger} from '@angular/aria/menu';` -**Directives:** `ngMenuBar`, `ngMenu`, `ngMenuItem`, `ngMenuTrigger`. +**Directives:** `ngMenuBar`, `ngMenu`, `ngMenuItem`, `ngMenuTrigger`, `ngMenuContent`. ```html -
        -
      • - -
        • -
      +
      +
      File
      +
      Edit
      +
      -
        -
      • New
        • -
      • Open
        • -
      +
      + +
      New
      +
      Open
      +       +
      + +
      + +
      Cut
      +
      Copy
      +       +
      ``` **Styling Strategy:** @@ -239,7 +279,7 @@ Layered content sections where only one panel is visible. ```html
      -
        +
        • Profile
        • Security
        @@ -328,14 +368,17 @@ Displays hierarchical data (file systems, nested nav). **Imports:** `import {Tree, TreeItem, TreeItemGroup} from '@angular/aria/tree';` -**Directives:** `ngTree`, `ngTreeItem`, `ngTreeGroup`. +**Directives:** `ngTree`, `ngTreeItem`, `ngTreeItemGroup`. ```html -
          -
        • +
            +
          • Documents -
              -
            • Resume.pdf
              • +
                + +
              • Resume.pdf
                • +
              • CoverLetter.pdf
                • +
            @@ -403,8 +446,152 @@ Target `[aria-selected="true"]` for selected cells and `:focus-visible` for the } ``` +## 9. Testing with Component Harnesses + +Angular Aria provides standard Component Harnesses (based on `@angular/cdk/testing`) to make unit testing clean, robust, and decoupled from DOM structural details. + +**Imports:** + +```ts +import {HarnessLoader} from '@angular/cdk/testing'; +import {TestbedHarnessEnvironment} from '@angular/cdk/testing/testbed'; +import {AccordionGroupHarness, AccordionHarness} from '@angular/aria/accordion/testing'; +import {ListboxHarness, ListboxOptionHarness} from '@angular/aria/listbox/testing'; +``` + +### Example: Testing an Accordion with Harnesses + +```ts +describe('MyAccordionComponent', () => { + let fixture: ComponentFixture; + let loader: HarnessLoader; + + beforeEach(async () => { + fixture = TestBed.createComponent(MyAccordionComponent); + await fixture.whenStable(); + loader = TestbedHarnessEnvironment.loader(fixture); + }); + + it('should expand accordion on toggle', async () => { + // Get the harness by its trigger title + const accordion = await loader.getHarness(AccordionHarness.with({title: 'Section 1'})); + + expect(await accordion.isExpanded()).toBeFalse(); + + // Expand the accordion + await accordion.expand(); + + expect(await accordion.isExpanded()).toBeTrue(); + }); +}); +``` + +## 10. Integration with Signal Forms + +Because Angular Aria directives leverage Angular's modern `model()` signals for managing interactive values, they integrate **out-of-the-box** with Angular's new Signal Forms (`@angular/forms/signals`). + +The `[formField]` directive automatically detects directives like `ngCombobox` or `ngListbox` as custom form controls because they expose a `value` model. + +**Imports:** + +```ts +import {form, schema, required} from '@angular/forms/signals'; +import {Combobox, ComboboxPopup, ComboboxWidget} from '@angular/aria/combobox'; +import {Listbox, Option} from '@angular/aria/listbox'; +``` + +### Example 1: Autocomplete Combobox inside a Form + +Given a form model defined in your component: + +```ts +protected readonly citySignal = signal({name: '', city: ''}); +protected readonly myForm = form(this.citySignal, schema(f => { + required(f.city); +})); +``` + +You bind it directly using `[formField]`: + +```html +
            + + + + +
              +
            • San Francisco
              • +
            • New York
              • +
            +             +
            +``` + +### Example 2: Select Component inside a Form + +Apply `ngCombobox` directly to a focusable `div` trigger and bind to `[formField]`: + +```html +
            + +
            + {{ myForm.city.value() || 'Choose your city' }} + ▼ +
            + + +
              +
            • San Francisco
              • +
            • New York
              • +
            +             +
            +``` + +### Example 3: Standalone Listbox (Multi-select) inside a Form + +You can bind a multi-selectable Listbox directly to a form array: + +```html +
              +
            • Sports
              • +
            • Music
              • +
            • Technology
              • +
            +``` + ## General Rules for Agents 1. **Never use native HTML elements like ` }
      @@ -74,15 +74,11 @@ Use directives to bind the model to the view: ## Accessing Controls -Use getters for easy access to controls, especially for `FormArray`. +Use `.controls` for easy access to controls. ```ts -get aliases() { - return this.profileForm.get('aliases') as FormArray; -} - addAlias() { - this.aliases.push(this.fb.control('')); + this.profileForm.controls.aliases.push(this.fb.control('')); } ``` diff --git a/.agents/skills/angular-developer/references/resource.md b/.agents/skills/angular-developer/references/resource.md index e356ea51b..e8efe8c8a 100644 --- a/.agents/skills/angular-developer/references/resource.md +++ b/.agents/skills/angular-developer/references/resource.md @@ -1,8 +1,5 @@ # Async Reactivity with `resource` -> [!IMPORTANT] -> The `resource` API is currently experimental in Angular. - A `Resource` incorporates asynchronous data fetching into Angular's signal-based reactivity. It executes an async loader function whenever its dependencies change, exposing the status and result as synchronous signals. ## Basic Usage @@ -17,9 +14,9 @@ import { Component, resource, signal, computed } from '@angular/core'; @Component({...}) export class UserProfile { - userId = signal('123'); + protected readonly userId = signal('123'); - userResource = resource({ + protected readonly userResource = resource({ // Reactively tracking userId params: () => ({ id: this.userId() }), @@ -32,7 +29,7 @@ export class UserProfile { }); // Use the resource value in computed signals - userName = computed(() => { + protected readonly userName = computed(() => { if (this.userResource.hasValue()) { return this.userResource.value()?.name; } else { diff --git a/.agents/skills/angular-developer/references/router-testing.md b/.agents/skills/angular-developer/references/router-testing.md index fc18d9cad..35328e41e 100644 --- a/.agents/skills/angular-developer/references/router-testing.md +++ b/.agents/skills/angular-developer/references/router-testing.md @@ -22,7 +22,7 @@ describe('Dashboard Component Routing', () => { beforeEach(async () => { // 1. Configure TestBed with test routes - await TestBed.configureTestingModule({ + TestBed.configureTestingModule({ providers: [ // Use provideRouter with your test-specific routes provideRouter([ @@ -30,7 +30,7 @@ describe('Dashboard Component Routing', () => { {path: 'heroes/:id', component: HeroDetail}, ]), ], - }).compileComponents(); + }); // 2. Create the RouterTestingHarness harness = await RouterTestingHarness.create(); diff --git a/.agents/skills/angular-developer/references/signal-forms.md b/.agents/skills/angular-developer/references/signal-forms.md index 992fab10c..1858b87bd 100644 --- a/.agents/skills/angular-developer/references/signal-forms.md +++ b/.agents/skills/angular-developer/references/signal-forms.md @@ -45,7 +45,7 @@ import {form, FormField} from '@angular/forms/signals'; }) export class Example { // 1. Define your model with initial values (avoid undefined) - userModel = signal({ + protected readonly userModel = signal({ name: '', // CRITICAL: NEVER use null or undefined as initial values email: '', age: 0, // Use 0 for numbers, NOT null @@ -64,7 +64,7 @@ export class Example { // }); // 2. Create the form - userForm = form(this.userModel); + protected readonly userForm = form(this.userModel); } ``` @@ -145,10 +145,10 @@ import {disabled, readonly, hidden} from '@angular/forms/signals'; userForm = form(this.userModel, (schemaPath) => { // Conditionally disabled - disabled(schemaPath.password, ({valueOf}) => !valueOf(schemaPath.createAccount)); + disabled(schemaPath.password, {when: ({valueOf}) => !valueOf(schemaPath.createAccount)}); // Conditionally hidden (does NOT remove from model, just marks as hidden) - hidden(schemaPath.shippingAddress, ({valueOf}) => valueOf(schemaPath.sameAsBilling)); + hidden(schemaPath.shippingAddress, {when: ({valueOf}) => valueOf(schemaPath.sameAsBilling)}); // Readonly readonly(schemaPath.username); @@ -170,10 +170,20 @@ Do _NOT_ bind the `name` field. When using `[formField]`, you MUST NOT set the following attributes in the template (either static or bound): - `min`, `max` (Use validators in the schema instead) -- `value`, `[value]`, `[attr.value]` (Already handled by `[formField]`) +- `value`, `[value]`, `[attr.value]` on **text/number/date inputs** (Already handled by `[formField]`) - `[attr.min]`, `[attr.max]` - `[disabled]`, `[readonly]` (Already handled by `[formField]`) +**Exception**: Static `value` on `` and `` is **allowed and required** — it identifies which option the input represents, not the bound field value. + +```html + + + + + +``` + Do NOT do this: `` or ``. ```html @@ -506,39 +516,39 @@ form( ## Common Pitfalls (DO NOT DO THESE) -| Error Scenario | WRONG (Common Mistake) | RIGHT (Correct Way) | -| :--------------------- | :-------------------------------------------- | :---------------------------------------------------------- | -| **Accessing Flags** | `form.field.valid()` | `form.field().valid()` | -| **Accessing value** | `form.field.value()` | `form.field().value()` | -| **Setting value** | `form.field.set(x)` | Update model signal: `this.model.update(...)` | -| **Form root flags** | `form.invalid()` | `form().invalid()` | -| **Double-calling** | `form.field()()` | `form.field().value()` | -| **Rules Context** | `({ touched }) => touched()` | `({ state }) => state.touched()` | -| **Calling Paths** | `applyWhen(p.foo, () => p.foo() === 'x')` | `applyWhen(p.foo, ({ valueOf }) => valueOf(p.foo) === 'x')` | -| **applyWhen args** | `applyWhen(condition, () => {...})` | `applyWhen(path, condition, schemaFn)` - needs 3 args | -| **Array length** | `form.items().length` | `form.items.length` (structural) | -| **Multi-select array** | `` | Use `readonly()` rule in schema | -| **min/max attributes** | `` | Use `min()` and `max()` rules in schema | -| **value binding** | `` | Do NOT use `[value]` with `[formField]` | -| **when option** | `pattern(p.x, /.../, {when: ...})` | `when` only works with `required()` | -| **Submit callback** | `submit(form, () => { ... })` | `submit(form, async () => { ... })` | -| **Async params** | `params: s.field` | `params: ({ value }) => value()` | -| **Async onError** | Omitting `onError` | `onError` is REQUIRED in `validateAsync` | -| **resource() API** | `request: signal` | `params: signal` | -| **applyEach args** | `applyEach(s.items, (item, index) => ...)` | `applyEach(s.items, (item) => ...)` | -| **Nested @for** | `$parent.$index` | Use `let outerIndex = $index` | -| **FormState import** | `import { FormState }` | `FormState` does not exist, use `FieldState` | -| **Null in model** | `signal({ name: null })` | `signal({ name: '' })` or `signal({ age: 0 })` | -| **Validate syntax** | `validate(s.field, { value } => ...)` | `validate(s.field, ({ value }) => ...)` | -| **Checkbox Array** | `[formField]="form.tags"` (string[]) | Checkboxes ONLY bind to `boolean` | +| Error Scenario | WRONG (Common Mistake) | RIGHT (Correct Way) | +| :--------------------- | :-------------------------------------------- | :------------------------------------------------------------------------------- | +| **Accessing Flags** | `form.field.valid()` | `form.field().valid()` | +| **Accessing value** | `form.field.value()` | `form.field().value()` | +| **Setting value** | `form.field.set(x)` | Update model signal: `this.model.update(...)` | +| **Form root flags** | `form.invalid()` | `form().invalid()` | +| **Double-calling** | `form.field()()` | `form.field().value()` | +| **Rules Context** | `({ touched }) => touched()` | `({ state }) => state.touched()` | +| **Calling Paths** | `applyWhen(p.foo, () => p.foo() === 'x')` | `applyWhen(p.foo, ({ valueOf }) => valueOf(p.foo) === 'x')` | +| **applyWhen args** | `applyWhen(condition, () => {...})` | `applyWhen(path, condition, schemaFn)` - needs 3 args | +| **Array length** | `form.items().length` | `form.items.length` (structural) | +| **Multi-select array** | `` | Use `readonly()` rule in schema | +| **min/max attributes** | `` | Use `min()` and `max()` rules in schema | +| **value binding** | `` | Do NOT use `[value]` with `[formField]` (static `value` on radio/checkbox is OK) | +| **when option** | `pattern(p.x, /.../, {when: ...})` | `when` only works with `required()` | +| **Submit callback** | `submit(form, () => { ... })` | `submit(form, async () => { ... })` | +| **Async params** | `params: s.field` | `params: ({ value }) => value()` | +| **Async onError** | Omitting `onError` | `onError` is REQUIRED in `validateAsync` | +| **resource() API** | `request: signal` | `params: signal` | +| **applyEach args** | `applyEach(s.items, (item, index) => ...)` | `applyEach(s.items, (item) => ...)` | +| **Nested @for** | `$parent.$index` | Use `let outerIndex = $index` | +| **FormState import** | `import { FormState }` | `FormState` does not exist, use `FieldState` | +| **Null in model** | `signal({ name: null })` | `signal({ name: '' })` or `signal({ age: 0 })` | +| **Validate syntax** | `validate(s.field, { value } => ...)` | `validate(s.field, ({ value }) => ...)` | +| **Checkbox Array** | `[formField]="form.tags"` (string[]) | Checkboxes ONLY bind to `boolean` | ## Big Form Example ### `src/app/app.ts` ```ts -import {Component, signal, ChangeDetectionStrategy} from '@angular/core'; +import {Component, signal} from '@angular/core'; import { form, FormField, @@ -553,13 +563,11 @@ import { @Component({ selector: 'app-root', - standalone: true, imports: [FormField], templateUrl: './app.html', - changeDetection: ChangeDetectionStrategy.OnPush, }) export class App { - model = signal({ + protected readonly model = signal({ personalInfo: { firstName: '', lastName: '', @@ -577,7 +585,7 @@ export class App { companions: [] as Array<{name: string; relation: string}>, }); - bookingForm = form(this.model, (s) => { + protected readonly bookingForm = form(this.model, (s) => { required(s.personalInfo.firstName, {message: 'First name is required'}); required(s.personalInfo.lastName, {message: 'Last name is required'}); required(s.personalInfo.email, {message: 'Email is required'}); @@ -598,7 +606,7 @@ export class App { }); // valueOf is used to access values of other fields in rules - hidden(s.package.extras, ({valueOf}) => valueOf(s.package.tier) === 'economy'); + hidden(s.package.extras, {when: ({valueOf}) => valueOf(s.package.tier) === 'economy'}); applyEach(s.companions, (companion) => { required(companion.name, {message: 'Companion name required'}); @@ -822,7 +830,7 @@ min(s.age, 18); max(s.age, 99); // Then just: -model = signal({ hasWifi: false, hasGym: false }); +protected readonly model = signal({ hasWifi: false, hasGym: false }); ``` @@ -875,7 +883,7 @@ import {FormState} from '@angular/forms/signals'; {{ totalPrice() | number:'1.2-2' }} -totalPriceFormatted = computed(() => this.totalPrice().toFixed(2)); +protected readonly totalPriceFormatted = computed(() => this.totalPrice().toFixed(2)); {{ totalPriceFormatted() }} ``` diff --git a/.agents/skills/angular-developer/references/testing-fundamentals.md b/.agents/skills/angular-developer/references/testing-fundamentals.md index d58ada3a5..2bd2e0f1c 100644 --- a/.agents/skills/angular-developer/references/testing-fundamentals.md +++ b/.agents/skills/angular-developer/references/testing-fundamentals.md @@ -24,13 +24,10 @@ describe('MyComponent', () => { let fixture: ComponentFixture; let h1: HTMLElement; - beforeEach(async () => { - // 1. Configure the test module - await TestBed.configureTestingModule({ - imports: [MyComponent], - }).compileComponents(); + beforeEach(() => { + TestBed.configureTestingModule({}); - // 2. Create the component fixture + // Create the component fixture fixture = TestBed.createComponent(MyComponent); component = fixture.componentInstance; h1 = fixture.nativeElement.querySelector('h1'); diff --git a/skills-lock.json b/skills-lock.json index 06bf64189..64e946a89 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -5,7 +5,7 @@ "source": "angular/skills", "sourceType": "github", "skillPath": "angular-developer/SKILL.md", - "computedHash": "28eb592b92e5a24c4e3a1c0229a854069f0b8c49bed7b8d2bf6b852812dbe214" + "computedHash": "ded1e95fb8d75d60901201665c6ab7e348eec3b79a6c53824c4a30a487d99f58" }, "karpathy-guidelines": { "source": "multica-ai/andrej-karpathy-skills",