Skip to content

[web] Preserve DOM focus on role update and honor isAccessibilityFocusBlocked - #192963

Merged
auto-submit[bot] merged 8 commits into
flutter:masterfrom
kevmoo:web-a11y-pr1-focus-blocknode
Oct 2, 2026
Merged

[web] Preserve DOM focus on role update and honor isAccessibilityFocusBlocked#192963
auto-submit[bot] merged 8 commits into
flutter:masterfrom
kevmoo:web-a11y-pr1-focus-blocknode

Conversation

@kevmoo

@kevmoo kevmoo commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Description

Fixes two web accessibility focus and modal-blocking regressions in lib/web_ui:

  1. Preserve DOM focus across semantic role re-creation (#192792): When a focused SemanticsObject undergoes a semantic role transition (_updateRole(), e.g., when a button transitions between enabled and disabled states), SemanticsRole.initState() creates a replacement <flt-semantics> DOM element (replacesExistingElement: true) and replaces the old element in the DOM via parent.replaceChild(...). Previously, replacing a focused <flt-semantics> element caused the browser to drop document.activeElement to <body>, breaking screen reader and keyboard focus retention. _updateRole() now checks whether the old element held document.activeElement before disposal and restores element.focusWithoutScroll() when the node remains focusable.
  2. Honor isAccessibilityFocusBlocked (BlockSemantics / modal barriers, #191484): When SemanticsFlags.isAccessibilityFocusBlocked is true on a node (set by BlockSemantics / ModalBarrier for nodes behind an active dialog or bottom sheet), SemanticsObject now exposes aria-hidden="true" and omits aria-label in LabelAndValue.update() when no interactive child nodes exist, preventing screen readers and automated accessibility scanners from reading background nodes behind a modal barrier.

Fixes #192792
Fixes #191484

Pre-launch Checklist

  • I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
  • I read the [Tree Hygiene] wiki page, which explains my responsibilities.
  • I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement].
  • I signed the [CLA].
  • I listed at least one issue that this PR fixes in the description above.
  • I updated/added relevant documentation (doc comments with ///).
  • I added new tests to check the change I am making, or this PR is [test-exempt].
  • I followed the [breaking change policy] and added [Data Driven Fixes] where supported.
  • All existing and new tests are passing.

@kevmoo
fix(web_ui): preserve DOM focus on role update and honor isAccessibil…
54ee781 
…ityFocusBlocked

- Preserve active DOM focus across SemanticsObject._updateRole DOM reparenting (Fixes flutter#192792).

- Honor SemanticsFlags.isAccessibilityFocusBlocked on leaf and container semantics nodes while preserving LiveRegion announcements (Fixes flutter#191484).
@github-actions github-actions Bot added engine flutter/engine related. See also e: labels. a: accessibility Accessibility, e.g. VoiceOver or TalkBack. (aka a11y) platform-web Web applications specifically team-web Owned by Web platform team labels Sep 18, 2026
@kevmoo kevmoo changed the title fix(web_ui): preserve DOM focus on role update and honor isAccessibilityFocusBlocked [web] Preserve DOM focus on role update and honor isAccessibilityFocusBlocked Sep 18, 2026
@github-actions github-actions Bot added a: text input Entering text in a text field or keyboard related problems f: focus Focus traversal, gaining or losing focus labels Sep 18, 2026
@kevmoo
kevmoo marked this pull request as ready for review September 18, 2026 04:06
gemini-code-assist[bot]
gemini-code-assist Bot reviewed Sep 18, 2026
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Code Review

This pull request introduces support for blocking accessibility focus on semantics nodes by checking isAccessibilityFocusBlocked and updating ARIA attributes, roles, and focusability accordingly. It also preserves active DOM focus when reparenting elements during semantics updates and prevents deactivating text editing on blur events during active semantics updates. The review feedback suggests moving the blocking logic from GenericRole.update to the base class SemanticRole.update() to ensure all specific semantic roles correctly inherit this behavior and are hidden when blocked.

Comment thread engine/src/flutter/lib/web_ui/lib/src/engine/semantics/semantics.dart
@flutter-zl
flutter-zl self-requested a review September 23, 2026 17:25
@kevmoo kevmoo added the CICD Run CI/CD label Sep 24, 2026
flutter-zl
flutter-zl requested changes Sep 29, 2026
View reviewed changes

@flutter-zl flutter-zl left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Both fixes work in the demos. Unblocking loses the label, which needs the one-line fix and a test.

1. A text node loses its label after it is unblocked. In the /#/unblock demo, "Status ready" disappears from the accessibility tree when blocked. It never comes back after unblocking.

I tested it with two demos. Both are the same app on the same local engine, and the only difference is this PR:

https://flutter-demo-68-before.web.app/#/unblock
https://flutter-demo-68-after.web.app/#/unblock

@kevmoo

kevmoo commented Oct 1, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @flutter-zl! Fixed in LabelAndValue._cleanUpDom() by resetting _representation = null after _representation?.cleanUp() so unblocking a text node recreates and re-appends its <span> representation, and expanded the isAccessibilityFocusBlocked test in semantics_test.dart to verify the unblocked -> blocked -> unblocked transition. Also merged origin/master to resolve the conflict with #192965. PTAL!

@kevmoo
kevmoo requested a review from flutter-zl October 1, 2026 19:34
flutter-zl
flutter-zl previously approved these changes Oct 1, 2026
View reviewed changes

@flutter-zl flutter-zl left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks for the quick fix! I rebuilt the after demo with e95f13c, and unblocking now works. On https://flutter-demo-68-after.web.app/#/unblock, "Status ready" is hidden while blocked and readable again after unblocking.

@kevmoo kevmoo added the autosubmit Merge PR when tree becomes green via auto submit App label Oct 1, 2026
@auto-submit auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Oct 1, 2026
@auto-submit

auto-submit Bot commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

autosubmit label was removed for flutter/flutter/192963, because - The status or check suite Dashboard Checks has failed. Please fix the issues identified (or deflake) before re-applying this label.

@kevmoo
kevmoo requested a review from flutter-zl October 1, 2026 22:06
@kevmoo

kevmoo commented Oct 1, 2026

Copy link
Copy Markdown
Contributor Author

@flutter-zl Pushed a 2-line dart format fix in f1686aa for semantics_test.dart (Linux linux_unopt formatting check), which dismissed the approval—could you re-stamp when convenient? Thanks!

@kevmoo kevmoo added the autosubmit Merge PR when tree becomes green via auto submit App label Oct 1, 2026
@auto-submit
auto-submit Bot added this pull request to the merge queue Oct 2, 2026
Merged via the queue into flutter:master with commit d6ffa40 Oct 2, 2026
23 checks passed
@flutter-dashboard flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Oct 2, 2026
@kevmoo
kevmoo deleted the web-a11y-pr1-focus-blocknode branch October 2, 2026 04:59
This was referenced Oct 2, 2026
Closed
Closed
Merged
auto-submit Bot pushed a commit to flutter/packages that referenced this pull request Oct 2, 2026
@engine-flutter-autoroll
Roll Flutter from e89fd0a274ae to d03768eef055 (23 revisions) (#13111)
749a38f 
flutter/flutter@e89fd0a...d03768e

2026-10-02 [email protected] Roll Skia from 7b7326917e77 to 9e88bf828078 (8 revisions) (flutter/flutter#193694)
2026-10-02 [email protected] [Widget Preview] Provide descriptive error when widget preview is unconstrained (flutter/flutter#193005)
2026-10-02 [email protected] Roll Dart SDK from 0e7642b85457 to ac1a97aae47d (26 revisions) (flutter/flutter#193692)
2026-10-02 [email protected] Remove unused Fuchsia sysmem header files (flutter/flutter#193244)
2026-10-02 [email protected] [Windows] Preserve composing extent in setEditingState (flutter/flutter#189968)
2026-10-02 [email protected] [docs] Make Border.symmetric docs more explicit about their arguments (flutter/flutter#193222)
2026-10-02 [email protected] [Embedder] Support render texture for vulkan (flutter/flutter#188855)
2026-10-02 [email protected] Updated Remaining Engine Defaults to SDK 37 (flutter/flutter#190429)
2026-10-02 [email protected] Document that enableSuggestions: false can disable keyboard languages on Android (flutter/flutter#192714)
2026-10-02 [email protected] [flutter_tools] Explicitly track host CPU architecture in command result analytics (flutter/flutter#191836)
2026-10-02 [email protected] [web] Preserve DOM focus on role update and honor isAccessibilityFocusBlocked (flutter/flutter#192963)
2026-10-02 [email protected] [flutter_tools] Include base href in web hot reload script paths (flutter/flutter#193678)
2026-10-02 [email protected] [Impeller] Deduplicate GLES render pass state (flutter/flutter#193427)
2026-10-02 [email protected] Roll Skia from f2d68e0b8863 to 7b7326917e77 (16 revisions) (flutter/flutter#193676)
2026-10-01 [email protected] Fix analysis failures due to missing `const` (flutter/flutter#193685)
2026-10-01 [email protected] Removes a11y_assessment app (flutter/flutter#193671)
2026-10-01 [email protected] test: configure Xvfb and openbox for windowing_test (flutter/flutter#193529)
2026-10-01 [email protected] Sync CHANGELOG.md from stable (flutter/flutter#193666)
2026-10-01 [email protected] Avoid using relative path in Process.start (flutter/flutter#193664)
2026-10-01 [email protected] [AGP 9.1.0 Migration #6] Deliver Flutter assets as a generated assets source directory on the app path (flutter/flutter#192488)
2026-10-01 [email protected] ci(bringup): android_java17_build_android_host_app_with_module_aar is green (flutter/flutter#193580)
2026-10-01 [email protected] [flutter_tools] Fix Use dependency graph to determine plugin initialization order (flutter/flutter#191591)
2026-10-01 [email protected] [flutter_tools] Migrate DaemonCommand and Daemon domains to constructor DI (flutter/flutter#193542)

If this roll has caused a breakage, revert this CL and set the roller
to dry run mode using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected],[email protected] on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
@kevmoo kevmoo mentioned this pull request Oct 7, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@flutter-zl flutter-zl flutter-zl approved these changes
+1 more reviewer
@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

a: accessibility Accessibility, e.g. VoiceOver or TalkBack. (aka a11y) a: text input Entering text in a text field or keyboard related problems CICD Run CI/CD engine flutter/engine related. See also e: labels. f: focus Focus traversal, gaining or losing focus platform-web Web applications specifically team-web Owned by Web platform team

Projects

None yet

Milestone

No milestone

2 participants

@kevmoo @flutter-zl