Skip to content

docs: modernize multiselect guide and standalone examples#68805

Open
tjshiu wants to merge 3 commits into
angular:mainfrom
tjshiu:combobox-adev
Open

docs: modernize multiselect guide and standalone examples#68805
tjshiu wants to merge 3 commits into
angular:mainfrom
tjshiu:combobox-adev

Conversation

@tjshiu
Copy link
Copy Markdown
Contributor

@tjshiu tjshiu commented May 19, 2026

Update the multiselect guide and all 27 interactive examples to utilize the modern standalone, Signal-based Angular ARIA APIs.

  • Modernize all examples (Standard, Material, Retro) to use standalone directives, animations, and focus suppression.
  • Update the multiselect guide API tables and templates:
    • Document ngComboboxPopup, cdkConnectedOverlay, and disabled input.
    • Document ngListbox selectionMode, focusMode, tabIndex, and value signal.
    • Document activeDescendant active focus tracking with ngComboboxWidget.

PR Checklist

Please check if your PR fulfills the following requirements:

PR Type

What kind of change does this PR introduce?

  • Bugfix
  • Feature
  • Code style update (formatting, local variables)
  • Refactoring (no functional changes, no api changes)
  • Build related changes
  • CI related changes
  • Documentation content changes
  • angular.dev application / infrastructure changes
  • Other... Please describe:

What is the current behavior?

The multiselect guide and its associated interactive examples in ADEV still reference the legacy wrapped, non-Signal-based combobox and listbox directives.

Issue Number: N/A

What is the new behavior?

Modernizes the multiselect guide and all 27 interactive examples to utilize modern standalone, Signal-based @angular/aria APIs:

  1. Guide Mappings:
    • Documents ngComboboxPopup structural overlay templates and standard cdkConnectedOverlay configuration.
    • Documents the ngComboboxWidget directive and [activeDescendant] input mapping to bridge listbox focus state.
    • Updates inputs tables for ngListbox (adding selectionMode, focusMode, tabIndex) and documents the renamed value signal model binding.
  2. Examples Upgrade:
    • Replaces legacy wrapped HTML with standalone direct directive bindings.
    • Integrates custom overlay exit transition delays (180ms) to prevent animation clipping on close.
    • Integrates popup scroll resets to ensure the listbox scrolls to the top upon re-opening.
    • Suppresses native browser focus rings (outline: none) in all variations (Standard, Material, Retro, Icons, Limited) to preserve custom highlight styling.
  3. Style & Tone Preservation:
    • Retains the original legacy third-person tone ("Users need to select..."), Title Case bullet items, and layout spacing to keep the documentation diff clean and avoid cosmetic prose noise.

Does this PR introduce a breaking change?

  • Yes
  • No

Other information

All modernized examples have been fully verified to ensure structural and visual parity with the original designs.

@tjshiu tjshiu requested a review from ok7sai May 19, 2026 19:31
@angular-robot angular-robot Bot added the area: docs Related to the documentation label May 19, 2026
@ngbot ngbot Bot added this to the Backlog milestone May 19, 2026
@tjshiu tjshiu added adev: preview target: major This PR is targeted for the next major release labels May 19, 2026
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 19, 2026

Deployed adev-preview for 59a2427 to: https://ng-dev-previews-fw--pr-angular-angular-68805-adev-prev-qckpp44u.web.app

Note: As new commits are pushed to this pull request, this link is updated after the preview is rebuilt.

Comment thread adev/src/content/examples/aria/multiselect/src/basic/material/app/app.ts Outdated
@tjshiu tjshiu marked this pull request as ready for review May 19, 2026 22:28
@pullapprove pullapprove Bot requested a review from atscott May 19, 2026 22:28
Comment thread adev/src/content/examples/aria/multiselect/src/basic/app/app.ts Outdated
Copy link
Copy Markdown
Member

@ok7sai ok7sai left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good!

tjshiu added 3 commits May 19, 2026 20:56
Update the multiselect guide and all 27 interactive examples to utilize
the modern standalone, Signal-based Angular ARIA APIs.

* Modernize all examples (Standard, Material, Retro)
  to use standalone directives, animations, and focus suppression.
* Update the multiselect guide API tables and templates:
  - Document ngComboboxPopup, cdkConnectedOverlay, and disabled input.
  - Document ngListbox selectionMode, focusMode, tabIndex, and value signal.
  - Document activeDescendant active focus tracking with ngComboboxWidget.
Remove the delayed overlayOpen signals and synchronization effects across all 9 multiselect example variations. Bind cdkConnectedOverlayOpen directly to popupExpanded() and remove conditional closing classes to simplify code.
@tjshiu tjshiu added the action: review The PR is still awaiting reviews from at least one requested reviewer label May 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

action: review The PR is still awaiting reviews from at least one requested reviewer adev: preview area: docs Related to the documentation target: major This PR is targeted for the next major release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants