From 5bacca0319ea0a15389221706079797bc577932f Mon Sep 17 00:00:00 2001
From: Matthieu Riegler <kyro38@gmail.com>
Date: Thu, 28 May 2026 01:00:07 +0200
Subject: [PATCH] docs: align `main` and `22.0.x` for aria guides

---
 adev/src/content/guide/aria/autocomplete.md | 89 ++++++++++++++-------
 1 file changed, 60 insertions(+), 29 deletions(-)

diff --git a/adev/src/content/guide/aria/autocomplete.md b/adev/src/content/guide/aria/autocomplete.md
index 8646256a97db..e7f629a124f4 100644
--- a/adev/src/content/guide/aria/autocomplete.md
+++ b/adev/src/content/guide/aria/autocomplete.md
@@ -5,7 +5,7 @@
 
 An accessible input field that filters and suggests options as users type, helping them find and select values from a list.
 
-<!-- <docs-tab-group>
+<docs-tab-group>
   <docs-tab label="Basic">
     <docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/basic/app/app.ts">
       <docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/basic/app/app.ts"/>
@@ -29,7 +29,7 @@ An accessible input field that filters and suggests options as users type, helpi
       <docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/basic/retro/app/app.css"/>
     </docs-code-multifile>
   </docs-tab>
-</docs-tab-group> -->
+</docs-tab-group>
 
 ## Usage
 
@@ -52,7 +52,7 @@ Angular's autocomplete provides a fully accessible combobox implementation with:
 
 - **Keyboard Navigation** - Navigate options with arrow keys, select with Enter, close with Escape
 - **Screen Reader Support** - Built-in ARIA attributes for assistive technologies
-- **Three Filter Modes** - Choose between auto-select, manual selection, or highlighting behavior
+- **Dynamic Highlight Behavior** - Built-in support for inline selection suggestions
 - **Signal-Based Reactivity** - Reactive state management using Angular signals
 - **Popover API Integration** - Leverages the native HTML Popover API for optimal positioning
 - **Bidirectional Text Support** - Automatically handles right-to-left (RTL) languages
@@ -63,7 +63,7 @@ Angular's autocomplete provides a fully accessible combobox implementation with:
 
 Users typing partial text expect immediate confirmation that their input matches an available option. Auto-select mode updates the input value to match the first filtered option as users type, reducing the number of keystrokes needed and providing instant feedback that their search is on the right track.
 
-<!-- <docs-tab-group>
+<docs-tab-group>
   <docs-tab label="Basic">
     <docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/basic/app/app.ts">
       <docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/basic/app/app.ts"/>
@@ -87,13 +87,13 @@ Users typing partial text expect immediate confirmation that their input matches
       <docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/basic/retro/app/app.css"/>
     </docs-code-multifile>
   </docs-tab>
-</docs-tab-group> -->
+</docs-tab-group>
 
 ### Manual selection mode
 
 Manual selection mode keeps the typed text unchanged while users navigate the suggestion list, preventing confusion from automatic updates. The input only changes when users explicitly confirm their choice with Enter or a click.
 
-<!-- <docs-tab-group>
+<docs-tab-group>
   <docs-tab label="Basic">
     <docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/manual/app/app.ts">
       <docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/manual/app/app.ts"/>
@@ -117,13 +117,13 @@ Manual selection mode keeps the typed text unchanged while users navigate the su
       <docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/manual/retro/app/app.css"/>
     </docs-code-multifile>
   </docs-tab>
-</docs-tab-group> -->
+</docs-tab-group>
 
 ### Highlight mode
 
 Highlight mode allows the user to navigate options with arrow keys without changing the input value as they browse until they explicitly select a new option with Enter or click.
 
-<!-- <docs-tab-group>
+<docs-tab-group>
   <docs-tab label="Basic">
     <docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/highlight/app/app.ts">
       <docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/highlight/app/app.ts"/>
@@ -147,44 +147,75 @@ Highlight mode allows the user to navigate options with arrow keys without chang
       <docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/highlight/retro/app/app.css"/>
     </docs-code-multifile>
   </docs-tab>
-</docs-tab-group> -->
+</docs-tab-group>
 
 ## APIs
 
 ### Combobox Directive
 
-The `ngCombobox` directive provides the container for autocomplete functionality.
+The `ngCombobox` directive is applied directly onto the editable text `<input>` or `<textarea>` to manage keyboard triggers and popover states.
 
 #### Inputs
 
-| Property     | Type                                           | Default    | Description                                       |
-| ------------ | ---------------------------------------------- | ---------- | ------------------------------------------------- |
-| `filterMode` | `'auto-select'` \| `'manual'` \| `'highlight'` | `'manual'` | Controls selection behavior                       |
-| `disabled`   | `boolean`                                      | `false`    | Disables the combobox                             |
-| `firstMatch` | `string`                                       | -          | The value of the first matching item in the popup |
+| Property           | Type                  | Default     | Description                                                     |
+| ------------------ | --------------------- | ----------- | --------------------------------------------------------------- |
+| `disabled`         | `boolean`             | `false`     | Disables the combobox                                           |
+| `softDisabled`     | `boolean`             | `true`      | Focusable when disabled                                         |
+| `inlineSuggestion` | `string \| undefined` | `undefined` | Displays an inline completion suggestion for autocomplete modes |
 
-#### Outputs
+#### Models
 
-| Property   | Type              | Description                                           |
-| ---------- | ----------------- | ----------------------------------------------------- |
-| `expanded` | `Signal<boolean>` | Signal indicating whether the popup is currently open |
+| Property   | Type                   | Default | Description                                                       |
+| ---------- | ---------------------- | ------- | ----------------------------------------------------------------- |
+| `value`    | `ModelSignal<string>`  | `''`    | Two-way bindable value of the input using `[(value)]`             |
+| `expanded` | `ModelSignal<boolean>` | `false` | Two-way bindable expanded state of the popup using `[(expanded)]` |
 
-### ComboboxInput Directive
+---
 
-The `ngComboboxInput` directive connects an input element to the combobox.
+### ComboboxPopup Directive
 
-#### Model
+A structural directive applied to `<ng-template>` to mark the container used as the popup.
 
-| Property | Type     | Description                                                  |
-| -------- | -------- | ------------------------------------------------------------ |
-| `value`  | `string` | Two-way bindable string value of the input using `[(value)]` |
+#### Inputs
+
+| Property   | Type       | Description                                 |
+| ---------- | ---------- | ------------------------------------------- |
+| `combobox` | `Combobox` | Required reference to the parent `Combobox` |
+
+---
+
+### ComboboxWidget Directive
+
+Applied to the popup content container to bridge active-descendant focus changes to the input trigger.
+
+#### Inputs
+
+| Property           | Type                  | Description                                                                       |
+| ------------------ | --------------------- | --------------------------------------------------------------------------------- |
+| `activeDescendant` | `string \| undefined` | The ID of the currently active descendant (bound to `listbox.activeDescendant()`) |
+
+---
+
+### Listbox Directives
+
+Autocomplete suggestion lists use the standard standalone listbox directives.
+
+#### Inputs
+
+| Property        | Type                               | Default    | Description                                                                                          |
+| --------------- | ---------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
+| `selectionMode` | `'follow'` \| `'explicit'`         | `'follow'` | In manual/explicit mode, updates are committed explicitly on click/Enter rather than following focus |
+| `focusMode`     | `'roving'` \| `'activedescendant'` | `'roving'` | Set to `'activedescendant'` so browser focus stays on the trigger input                              |
+| `tabIndex`      | `number`                           | `0`        | Set to `-1` to prevent keyboard tab focus from entering the popup listbox container                  |
 
-### ComboboxPopupContainer Directive
+#### Models
 
-The `ngComboboxPopupContainer` directive wraps the popup content and manages its display.
+| Property | Type                 | Description                                                 |
+| -------- | -------------------- | ----------------------------------------------------------- |
+| `value`  | `ModelSignal<any[]>` | Two-way bindable array of selected values using `[(value)]` |
 
-Must be used with `<ng-template>` inside a popover element.
+---
 
 ### Related components
 
-Autocomplete uses [Listbox](/api/aria/listbox/Listbox) and [Option](/api/aria/listbox/Option) directives to render the suggestion list. See the [Listbox documentation](/guide/aria/listbox) for additional customization options.
+Autocomplete uses standard standalone [Listbox](/api/aria/listbox/Listbox) and [Option](/api/aria/listbox/Option) directives. See the [Listbox documentation](/guide/aria/listbox) for advanced options.