Skip to content

docs: modernize Aria guides #68814

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ok7sai wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: modernize Aria guides #68814

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 13 additions & 14 deletions adev/src/content/guide/aria/accordion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,8 +145,8 @@ Use the `ngAccordionContent` directive on an `ng-template` to defer rendering co
```angular-html
<div ngAccordionGroup>
<div>
<button ngAccordionTrigger panelId="item-1">Trigger Text</button>
<div ngAccordionPanel panelId="item-1">
<button ngAccordionTrigger [panel]="panel1">Trigger Text</button>
<div ngAccordionPanel #panel1="ngAccordionPanel">
<ng-template ngAccordionContent>
<!-- This content only renders when the panel first opens -->
<img src="large-image.jpg" alt="Description" />
Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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
<div ngAccordionPanel panelId="item-1">
<div ngAccordionPanel #panel1="ngAccordionPanel">
<ng-template ngAccordionContent>
<!-- Content here is lazily rendered -->
</ng-template>
Expand Down
28 changes: 28 additions & 0 deletions adev/src/content/guide/aria/grid.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,3 +214,31 @@ Represents an individual cell within a grid row.
| Property | Type | Description |
| -------- | ----------------- | ------------------------------------ |
| `active` | `Signal<boolean>` | 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<HTMLElement>` | — | Optional element reference to receive focus on activation |
| `tabindex` | `number` | — | Tabindex override for the widget |

#### Outputs

| Property | Type | Description |
| ------------- | -------------------------------------------------------- | ---------------------------------------------- |
| `activated` | `EventEmitter<KeyboardEvent \| FocusEvent \| undefined>` | Emits when the cell widget becomes activated |
| `deactivated` | `EventEmitter<KeyboardEvent \| FocusEvent \| undefined>` | Emits when the cell widget becomes deactivated |

#### Methods

| Method | Parameters | Description |
| ------------ | ---------- | --------------------------------- |
| `activate` | none | Forcefully activates the widget |
| `deactivate` | none | Forcefully deactivates the widget |
6 changes: 3 additions & 3 deletions adev/src/content/guide/aria/listbox.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Applications sometimes need selectable lists visible directly on the page rather
<docs-code header="app.html" path="adev/src/content/examples/aria/listbox/src/basic/app/app.html" />
</docs-code-multifile>

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

Expand Down Expand Up @@ -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<V[]>` | Currently selected values as a signal |
| `value` | `Signal<V[]>` | Currently selected values as a signal |

#### Methods

Expand Down
13 changes: 7 additions & 6 deletions adev/src/content/guide/aria/menu.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
12 changes: 7 additions & 5 deletions adev/src/content/guide/aria/menubar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
17 changes: 14 additions & 3 deletions adev/src/content/guide/aria/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,20 @@ Angular Aria is a collection of headless, accessible directives that implement c

## Installation

```shell
npm install @angular/aria
```
<docs-code-multifile>
<docs-code header="npm" language="shell">
npm install @angular/aria
</docs-code>
<docs-code header="yarn" language="shell">
yarn add @angular/aria
</docs-code>
<docs-code header="pnpm" language="shell">
pnpm add @angular/aria
</docs-code>
<docs-code header="bun" language="shell">
bun add @angular/aria
</docs-code>
</docs-code-multifile>

## Showcase

Expand Down
15 changes: 8 additions & 7 deletions adev/src/content/guide/aria/tabs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions adev/src/content/guide/aria/toolbar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
41 changes: 26 additions & 15 deletions adev/src/content/guide/aria/tree.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
<li ngTreeItem value="parent">
Parent Item
<ul ngTreeGroup>
<li ngTreeItem value="child1">Child 1</li>
<li ngTreeItem value="child2">Child 2</li>
</ul>
</li>
<ul ngTree #tree="ngTree">
<li ngTreeItem [parent]="tree" value="parent" #parentItem="ngTreeItem">
Parent Item
<ul role="group">
<ng-template ngTreeItemGroup [ownedBy]="parentItem" #group="ngTreeItemGroup">
<li ngTreeItem [parent]="group" value="child1">Child 1</li>
<li ngTreeItem [parent]="group" value="child2">Child 2</li>
</ng-template>
</ul>
</li>
</ul>
```
Loading