From 709cd5b822008deacdfcfbef099dc5b7031cb3a0 Mon Sep 17 00:00:00 2001 From: Cheng-Hsuan Tsai Date: Wed, 20 May 2026 07:24:44 +0000 Subject: [PATCH] docs: modernize Aria guides --- adev/src/content/guide/aria/accordion.md | 27 ++++++++-------- adev/src/content/guide/aria/grid.md | 28 ++++++++++++++++ adev/src/content/guide/aria/listbox.md | 6 ++-- adev/src/content/guide/aria/menu.md | 13 ++++---- adev/src/content/guide/aria/menubar.md | 12 ++++--- adev/src/content/guide/aria/overview.md | 17 ++++++++-- adev/src/content/guide/aria/tabs.md | 15 +++++---- adev/src/content/guide/aria/toolbar.md | 1 + adev/src/content/guide/aria/tree.md | 41 +++++++++++++++--------- 9 files changed, 107 insertions(+), 53 deletions(-) diff --git a/adev/src/content/guide/aria/accordion.md b/adev/src/content/guide/aria/accordion.md index 4a27dc5e0b3d..2546ede7b62c 100644 --- a/adev/src/content/guide/aria/accordion.md +++ b/adev/src/content/guide/aria/accordion.md @@ -145,8 +145,8 @@ Use the `ngAccordionContent` directive on an `ng-template` to defer rendering co ```angular-html
- -
+ +
Description @@ -187,12 +187,12 @@ The directive applied to the button element that toggles panel visibility. #### Inputs -| Property | Type | Default | Description | -| ---------- | --------- | ------- | -------------------------------------------------------------- | -| `id` | `string` | auto | Unique identifier for the trigger | -| `panelId` | `string` | — | **Required.** Must match the `panelId` of the associated panel | -| `disabled` | `boolean` | `false` | Disables this trigger | -| `expanded` | `boolean` | `false` | Whether the panel is expanded (supports two-way binding) | +| Property | Type | Default | Description | +| ---------- | ---------------- | ------- | -------------------------------------------------------------- | +| `panel` | `AccordionPanel` | — | **Required.** The reference of the controlled accordion panel. | +| `id` | `string` | auto | Unique identifier for the trigger | +| `disabled` | `boolean` | `false` | Disables this trigger | +| `expanded` | `boolean` | `false` | Whether the panel is expanded (supports two-way binding) | #### Signals @@ -214,11 +214,10 @@ The directive applied to the element containing the collapsible content. #### Inputs -| Property | Type | Default | Description | -| ----------------- | --------- | ------- | ---------------------------------------------------------------- | -| `id` | `string` | auto | Unique identifier for the panel | -| `panelId` | `string` | — | **Required.** Must match the `panelId` of the associated trigger | -| `preserveContent` | `boolean` | `true` | Whether to keep content in DOM after panel collapses | +| Property | Type | Default | Description | +| ----------------- | --------- | ------- | ---------------------------------------------------- | +| `id` | `string` | auto | Unique identifier for the panel | +| `preserveContent` | `boolean` | `true` | Whether to keep content in DOM after panel collapses | #### Signals @@ -241,7 +240,7 @@ The structural directive applied to an `ng-template` inside an accordion panel t This directive has no inputs, outputs, or methods. Apply it to an `ng-template` element: ```angular-html -
+
diff --git a/adev/src/content/guide/aria/grid.md b/adev/src/content/guide/aria/grid.md index e91a02a4b32b..90daffb71b6e 100644 --- a/adev/src/content/guide/aria/grid.md +++ b/adev/src/content/guide/aria/grid.md @@ -214,3 +214,31 @@ Represents an individual cell within a grid row. | Property | Type | Description | | -------- | ----------------- | ------------------------------------ | | `active` | `Signal` | Whether the cell currently has focus | + +### GridCellWidget + +Applied to an interactive element inside a grid cell to allow for pausing grid navigation. + +#### Inputs + +| Property | Type | Default | Description | +| ------------- | ------------------------------------- | ---------- | --------------------------------------------------------- | +| `id` | `string` | auto | Unique identifier for the widget | +| `widgetType` | `'simple' \| 'complex' \| 'editable'` | `'simple'` | The widget type, controlling how activation behaves | +| `disabled` | `boolean` | `false` | Disables this cell widget | +| `focusTarget` | `ElementResolver` | — | Optional element reference to receive focus on activation | +| `tabindex` | `number` | — | Tabindex override for the widget | + +#### Outputs + +| Property | Type | Description | +| ------------- | -------------------------------------------------------- | ---------------------------------------------- | +| `activated` | `EventEmitter` | Emits when the cell widget becomes activated | +| `deactivated` | `EventEmitter` | Emits when the cell widget becomes deactivated | + +#### Methods + +| Method | Parameters | Description | +| ------------ | ---------- | --------------------------------- | +| `activate` | none | Forcefully activates the widget | +| `deactivate` | none | Forcefully deactivates the widget | diff --git a/adev/src/content/guide/aria/listbox.md b/adev/src/content/guide/aria/listbox.md index 38238eb3e233..56864e9b9b44 100644 --- a/adev/src/content/guide/aria/listbox.md +++ b/adev/src/content/guide/aria/listbox.md @@ -72,7 +72,7 @@ Applications sometimes need selectable lists visible directly on the page rather -The `values` model signal provides two-way binding to the selected items. With `selectionMode="explicit"`, users press Space or Enter to select options. For dropdown patterns that combine listbox with combobox and overlay positioning, see the [Select](guide/aria/select) pattern. +The `value` model signal provides two-way binding to the selected items. With `selectionMode="explicit"`, users press Space or Enter to select options. For dropdown patterns that combine listbox with combobox and overlay positioning, see the [Select](guide/aria/select) pattern. ### Horizontal listbox @@ -158,13 +158,13 @@ The `ngListbox` directive creates an accessible list of selectable options. | Property | Type | Description | | -------- | ----- | ----------------------------------------- | -| `values` | `V[]` | Two-way bindable array of selected values | +| `value` | `V[]` | Two-way bindable array of selected values | #### Signals | Property | Type | Description | | -------- | ------------- | ------------------------------------- | -| `values` | `Signal` | Currently selected values as a signal | +| `value` | `Signal` | Currently selected values as a signal | #### Methods diff --git a/adev/src/content/guide/aria/menu.md b/adev/src/content/guide/aria/menu.md index fe69c67c6d8e..54c0a278b982 100644 --- a/adev/src/content/guide/aria/menu.md +++ b/adev/src/content/guide/aria/menu.md @@ -212,12 +212,13 @@ An individual item within a menu. #### Inputs -| Property | Type | Default | Description | -| ------------ | --------- | ------- | ---------------------------------------------------- | -| `value` | `any` | — | **Required.** Value for this item | -| `disabled` | `boolean` | `false` | Disables this menu item | -| `submenu` | `Menu` | — | Reference to a submenu | -| `searchTerm` | `string` | `''` | Search term for typeahead (supports two-way binding) | +| Property | Type | Default | Description | +| ------------ | ----------------------------------------------------- | ------------ | ---------------------------------------------------- | +| `value` | `any` | — | **Required.** Value for this item | +| `role` | `'menuitem' \| 'menuitemcheckbox' \| 'menuitemradio'` | `'menuitem'` | The ARIA role for the menu item | +| `disabled` | `boolean` | `false` | Disables this menu item | +| `submenu` | `Menu` | — | Reference to a submenu | +| `searchTerm` | `string` | `''` | Search term for typeahead (supports two-way binding) | #### Signals diff --git a/adev/src/content/guide/aria/menubar.md b/adev/src/content/guide/aria/menubar.md index 3d48c3e87f0c..57770adba72f 100644 --- a/adev/src/content/guide/aria/menubar.md +++ b/adev/src/content/guide/aria/menubar.md @@ -174,11 +174,13 @@ The horizontal container for top-level menu items. #### Inputs -| Property | Type | Default | Description | -| -------------- | --------- | ------- | ------------------------------------------------------------- | -| `disabled` | `boolean` | `false` | Disables the entire menubar | -| `wrap` | `boolean` | `true` | Whether keyboard navigation wraps from last to first item | -| `softDisabled` | `boolean` | `true` | When `true`, disabled items are focusable but not interactive | +| Property | Type | Default | Description | +| ---------------- | --------- | ------- | ------------------------------------------------------------- | +| `disabled` | `boolean` | `false` | Disables the entire menubar | +| `wrap` | `boolean` | `true` | Whether keyboard navigation wraps from last to first item | +| `softDisabled` | `boolean` | `true` | When `true`, disabled items are focusable but not interactive | +| `value` | `V[]` | `[]` | Selected menu item values (supports two-way binding) | +| `typeaheadDelay` | `number` | `500` | Milliseconds before the typeahead buffer is reset | See the [Menu API documentation](guide/aria/menu#apis) for complete details on all available inputs and signals. diff --git a/adev/src/content/guide/aria/overview.md b/adev/src/content/guide/aria/overview.md index 380ca0d4f992..159425cde67b 100644 --- a/adev/src/content/guide/aria/overview.md +++ b/adev/src/content/guide/aria/overview.md @@ -9,9 +9,20 @@ Angular Aria is a collection of headless, accessible directives that implement c ## Installation -```shell -npm install @angular/aria -``` + + + npm install @angular/aria + + + yarn add @angular/aria + + + pnpm add @angular/aria + + + bun add @angular/aria + + ## Showcase diff --git a/adev/src/content/guide/aria/tabs.md b/adev/src/content/guide/aria/tabs.md index 29a292c37b79..e96eaea3cddc 100644 --- a/adev/src/content/guide/aria/tabs.md +++ b/adev/src/content/guide/aria/tabs.md @@ -238,13 +238,14 @@ The container for tab buttons that manages selection and keyboard navigation. #### Inputs -| Property | Type | Default | Description | -| --------------- | ---------------------------- | -------------- | ------------------------------------------------------------------ | -| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Tab list layout direction | -| `wrap` | `boolean` | `false` | Whether keyboard navigation wraps from last to first tab | -| `softDisabled` | `boolean` | `true` | When `true`, disabled tabs are focusable but not activatable | -| `selectionMode` | `'follow' \| 'explicit'` | `'follow'` | Whether tabs activate on focus or require explicit activation | -| `selectedTab` | `any` | — | The value of the currently selected tab (supports two-way binding) | +| Property | Type | Default | Description | +| --------------- | -------------------------------- | -------------- | ------------------------------------------------------------------ | +| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Tab list layout direction | +| `wrap` | `boolean` | `true` | Whether keyboard navigation wraps from last to first tab | +| `softDisabled` | `boolean` | `true` | When `true`, disabled tabs are focusable but not activatable | +| `selectionMode` | `'follow' \| 'explicit'` | `'follow'` | Whether tabs activate on focus or require explicit activation | +| `focusMode` | `'roving' \| 'activedescendant'` | `'roving'` | Focus management strategy | +| `selectedTab` | `any` | — | The value of the currently selected tab (supports two-way binding) | ### Tab diff --git a/adev/src/content/guide/aria/toolbar.md b/adev/src/content/guide/aria/toolbar.md index 926e8c4410ee..c44774394a6a 100644 --- a/adev/src/content/guide/aria/toolbar.md +++ b/adev/src/content/guide/aria/toolbar.md @@ -228,6 +228,7 @@ The `ngToolbar` directive provides the container for toolbar functionality. | `disabled` | `boolean` | `false` | Disables the entire toolbar | | `softDisabled` | `boolean` | `true` | Whether disabled items can receive focus | | `wrap` | `boolean` | `true` | Whether focus should wrap at the edges | +| `value` | `V[]` | `[]` | Selected widget values (supports two-way binding) | ### ToolbarWidget Directive diff --git a/adev/src/content/guide/aria/tree.md b/adev/src/content/guide/aria/tree.md index 712ab9cc4d08..673ea420517d 100644 --- a/adev/src/content/guide/aria/tree.md +++ b/adev/src/content/guide/aria/tree.md @@ -191,11 +191,12 @@ An individual node in the tree that can contain child nodes. #### Inputs -| Property | Type | Default | Description | -| ---------- | --------- | ------- | ------------------------------------------------------- | -| `value` | `any` | — | **Required.** Unique value for this tree item | -| `disabled` | `boolean` | `false` | Disables this item | -| `expanded` | `boolean` | `false` | Whether the node is expanded (supports two-way binding) | +| Property | Type | Default | Description | +| ---------- | ----------------------- | ------- | ------------------------------------------------------- | +| `parent` | `Tree \| TreeItemGroup` | — | **Required.** The parent Tree root or TreeItemGroup. | +| `value` | `any` | — | **Required.** Unique value for this tree item | +| `disabled` | `boolean` | `false` | Disables this item | +| `expanded` | `boolean` | `false` | Whether the node is expanded (supports two-way binding) | #### Signals @@ -213,18 +214,28 @@ An individual node in the tree that can contain child nodes. | `collapse` | none | Collapses this node | | `toggle` | none | Toggles the expansion state | -### TreeGroup +### TreeItemGroup -A container for child tree items. +The structural directive applied to an `ng-template` that holds the children nodes of an expandable tree item. -This directive has no inputs, outputs, or methods. It serves as a container to organize child `ngTreeItem` elements: +#### Inputs + +| Property | Type | Default | Description | +| --------- | ---------- | ------- | ------------------------------------------------------- | +| `ownedBy` | `TreeItem` | — | **Required.** The reference of the parent `ngTreeItem`. | + +#### Usage ```angular-html -
  • - Parent Item -
      -
    • Child 1
      • -
    • Child 2
      • -
    -
    • +
      +
    • + Parent Item +
        + +
      • Child 1
        • +
      • Child 2
        • +         +
      +
      • +
    ```