diff --git a/skills/dev-skills/angular-developer/references/angular-aria.md b/skills/dev-skills/angular-developer/references/angular-aria.md index 2dd0cf451fa5..99d1b5e281c6 100644 --- a/skills/dev-skills/angular-developer/references/angular-aria.md +++ b/skills/dev-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); + fixture.detectChanges(); + 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 `