Skip to content

Commit d6ffa40

Browse files
authored
[web] Preserve DOM focus on role update and honor isAccessibilityFocusBlocked (flutter#192963)
## Description Fixes two web accessibility focus and modal-blocking regressions in `lib/web_ui`: 1. **Preserve DOM focus across semantic role re-creation (`flutter#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, `flutter#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 flutter#192792 Fixes flutter#191484 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing.
1 parent ede4f67 commit d6ffa40

5 files changed

Lines changed: 218 additions & 3 deletions

File tree

‎engine/src/flutter/lib/web_ui/lib/src/engine/semantics/focusable.dart‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,9 @@ class Focusable extends SemanticBehavior {
6363
);
6464
} else {
6565
_focusManager.stopManaging();
66+
if (semanticsObject.isAccessibilityFocusBlocked) {
67+
owner.element.removeAttribute('tabindex');
68+
}
6669
}
6770
}
6871

‎engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -455,6 +455,10 @@ class LabelAndValue extends SemanticBehavior {
455455

456456
@override
457457
void update() {
458+
if (semanticsObject.isAccessibilityFocusBlocked) {
459+
_cleanUpDom();
460+
return;
461+
}
458462
final String? computedLabel = _computeLabel();
459463

460464
if (computedLabel == null) {
@@ -584,6 +588,7 @@ class LabelAndValue extends SemanticBehavior {
584588
void _cleanUpDom() {
585589
_cleanUpDescriptionOrDescribedBy();
586590
_representation?.cleanUp();
591+
_representation = null;
587592
}
588593

589594
@override

‎engine/src/flutter/lib/web_ui/lib/src/engine/semantics/semantics.dart‎

Lines changed: 40 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -896,6 +896,12 @@ abstract class SemanticRole {
896896
/// the object.
897897
@mustCallSuper
898898
void update() {
899+
if (semanticsObject.isAccessibilityFocusBlocked && !semanticsObject.hasChildren) {
900+
setAttribute('aria-hidden', 'true');
901+
} else {
902+
removeAttribute('aria-hidden');
903+
}
904+
899905
if (semanticsObject.isValidationResultDirty) {
900906
updateValidationResult();
901907
}
@@ -1091,6 +1097,16 @@ final class GenericRole extends SemanticRole {
10911097

10921098
@override
10931099
void update() {
1100+
if (semanticsObject.isAccessibilityFocusBlocked) {
1101+
if (semanticsObject.hasChildren) {
1102+
setAriaRole('none');
1103+
} else {
1104+
removeAttribute('role');
1105+
}
1106+
super.update();
1107+
return;
1108+
}
1109+
10941110
if (!semanticsObject.hasLabel) {
10951111
// The node didn't get a more specific role, and it has no label. It is
10961112
// likely that this node is simply there for positioning its children and
@@ -1119,6 +1135,7 @@ final class GenericRole extends SemanticRole {
11191135
// In HTML text has no ARIA role. It's just a DOM node with text inside
11201136
// it. Previously, role="text" was used, but it was only supported by
11211137
// Safari, and it was removed starting Safari 17.
1138+
11221139
if (semanticsObject.hasChildren) {
11231140
labelAndValue!.preferredRepresentation = LabelRepresentation.ariaLabel;
11241141
setAriaRole('group');
@@ -1134,6 +1151,9 @@ final class GenericRole extends SemanticRole {
11341151

11351152
@override
11361153
bool focusAsRouteDefault() {
1154+
if (semanticsObject.isAccessibilityFocusBlocked) {
1155+
return false;
1156+
}
11371157
// Case 1: current node has input focus. Let the input focus system decide
11381158
// default focusability.
11391159
if (semanticsObject.isFocusable) {
@@ -1762,8 +1782,11 @@ class SemanticsObject {
17621782
/// Whether [actions] contains the given action.
17631783
bool hasAction(ui.SemanticsAction action) => (_actions! & action.index) != 0;
17641784

1785+
/// Whether accessibility focus on this node is blocked.
1786+
bool get isAccessibilityFocusBlocked => flags.isAccessibilityFocusBlocked;
1787+
17651788
/// Whether this object represents a widget that can receive input focus.
1766-
bool get isFocusable => flags.isFocused != ui.Tristate.none;
1789+
bool get isFocusable => flags.isFocused != ui.Tristate.none && !isAccessibilityFocusBlocked;
17671790

17681791
/// Whether this object currently has input focus.
17691792
///
@@ -2384,6 +2407,11 @@ class SemanticsObject {
23842407
SemanticRole? currentSemanticRole = semanticRole;
23852408
final EngineSemanticsRole kind = _getEngineSemanticsRole();
23862409
final DomElement? previousElement = semanticRole?.element;
2410+
final DomElement? previouslyFocusedElement = domDocument.activeElement;
2411+
final bool hadSubtreeFocus =
2412+
previouslyFocusedElement != null &&
2413+
previousElement != null &&
2414+
previousElement.contains(previouslyFocusedElement);
23872415

23882416
if (currentSemanticRole != null) {
23892417
if (currentSemanticRole.kind == kind) {
@@ -2414,16 +2442,25 @@ class SemanticsObject {
24142442

24152443
// Reparent element.
24162444
if (previousElement != element) {
2445+
final DomElement? parent = previousElement?.parent;
2446+
if (parent != null) {
2447+
parent.insertBefore(element, previousElement);
2448+
}
24172449
if (_currentChildrenInRenderOrder != null) {
24182450
for (final SemanticsObject child in _currentChildrenInRenderOrder!) {
24192451
element.append(child.element);
24202452
}
24212453
}
2422-
final DomElement? parent = previousElement?.parent;
24232454
if (parent != null) {
2424-
parent.insertBefore(element, previousElement);
24252455
previousElement!.remove();
24262456
}
2457+
if (hadSubtreeFocus && domDocument.activeElement != previouslyFocusedElement) {
2458+
if (element.contains(previouslyFocusedElement)) {
2459+
previouslyFocusedElement.focusWithoutScroll();
2460+
} else {
2461+
element.focusWithoutScroll();
2462+
}
2463+
}
24272464
}
24282465
}
24292466

‎engine/src/flutter/lib/web_ui/lib/src/engine/semantics/text_field.dart‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -415,6 +415,9 @@ class SemanticTextField extends SemanticRole {
415415
editableElement.addEventListener(
416416
'blur',
417417
createDomEventListener((DomEvent event) {
418+
if (semanticsObject.owner.phase != SemanticsUpdatePhase.idle && semanticsObject.hasFocus) {
419+
return;
420+
}
418421
SemanticsTextEditingStrategy._instance?.deactivate(this);
419422
}),
420423
);

‎engine/src/flutter/lib/web_ui/test/engine/semantics/semantics_test.dart‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6523,6 +6523,173 @@ void _testLoadingSpinner() {
65236523
expect(object.semanticRole?.kind, EngineSemanticsRole.loadingSpinner);
65246524
});
65256525

6526+
test('preserves active DOM focus when ancestor role updates (#192792)', () {
6527+
semantics()
6528+
..debugOverrideTimestampFunction(() => _testTime)
6529+
..semanticsEnabled = true;
6530+
6531+
final tester = SemanticsTester(owner());
6532+
tester.updateNode(
6533+
id: 0,
6534+
children: <SemanticsNodeUpdate>[
6535+
tester.updateNode(
6536+
id: 1,
6537+
flags: const ui.SemanticsFlags(
6538+
isTextField: true,
6539+
isFocused: ui.Tristate.isTrue,
6540+
isEnabled: ui.Tristate.isTrue,
6541+
),
6542+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
6543+
),
6544+
],
6545+
);
6546+
tester.apply();
6547+
6548+
final DomElement textFieldInput = owner().debugSemanticsTree![1]!.element.querySelector(
6549+
'input',
6550+
)!;
6551+
expect(domDocument.activeElement, textFieldInput);
6552+
6553+
// Trigger a role change on ancestor node 0 (e.g. GenericRole -> SemanticScrollable).
6554+
tester.updateNode(
6555+
id: 0,
6556+
flags: const ui.SemanticsFlags(hasImplicitScrolling: true),
6557+
actions: 0 | ui.SemanticsAction.scrollUp.index,
6558+
children: <SemanticsNodeUpdate>[
6559+
tester.updateNode(
6560+
id: 1,
6561+
flags: const ui.SemanticsFlags(
6562+
isTextField: true,
6563+
isFocused: ui.Tristate.isTrue,
6564+
isEnabled: ui.Tristate.isTrue,
6565+
),
6566+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
6567+
),
6568+
],
6569+
);
6570+
tester.apply();
6571+
6572+
expect(domDocument.activeElement, textFieldInput);
6573+
});
6574+
6575+
test('respects isAccessibilityFocusBlocked on leaf and container nodes and restores label on unblock (#191484)', () {
6576+
semantics()
6577+
..debugOverrideTimestampFunction(() => _testTime)
6578+
..semanticsEnabled = true;
6579+
6580+
final tester = SemanticsTester(owner());
6581+
// 1. Start unblocked so leaf text node creates SizedSpanRepresentation (<span>Status ready</span>).
6582+
tester.updateNode(
6583+
id: 0,
6584+
label: 'Blocked container',
6585+
flags: const ui.SemanticsFlags(isFocused: ui.Tristate.isFalse),
6586+
children: <SemanticsNodeUpdate>[
6587+
tester.updateNode(
6588+
id: 1,
6589+
label: 'Status ready',
6590+
flags: const ui.SemanticsFlags(isLiveRegion: true),
6591+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
6592+
),
6593+
tester.updateNode(
6594+
id: 2,
6595+
label: 'Accessible child',
6596+
rect: const ui.Rect.fromLTRB(0, 50, 100, 100),
6597+
),
6598+
tester.updateNode(
6599+
id: 3,
6600+
label: 'Blocked button',
6601+
flags: const ui.SemanticsFlags(isButton: true, isFocused: ui.Tristate.isFalse),
6602+
rect: const ui.Rect.fromLTRB(0, 100, 100, 150),
6603+
),
6604+
],
6605+
);
6606+
tester.apply();
6607+
6608+
final SemanticsObject blockedContainer = tester.getSemanticsObject(0);
6609+
final SemanticsObject blockedLeaf = tester.getSemanticsObject(1);
6610+
final SemanticsObject blockedButton = tester.getSemanticsObject(3);
6611+
expect(blockedLeaf.element.text, 'Status ready');
6612+
6613+
// 2. Block nodes.
6614+
tester.updateNode(
6615+
id: 0,
6616+
label: 'Blocked container',
6617+
flags: const ui.SemanticsFlags(
6618+
isAccessibilityFocusBlocked: true,
6619+
isFocused: ui.Tristate.isFalse,
6620+
),
6621+
children: <SemanticsNodeUpdate>[
6622+
tester.updateNode(
6623+
id: 1,
6624+
label: 'Status ready',
6625+
flags: const ui.SemanticsFlags(isAccessibilityFocusBlocked: true, isLiveRegion: true),
6626+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
6627+
),
6628+
tester.updateNode(
6629+
id: 2,
6630+
label: 'Accessible child',
6631+
rect: const ui.Rect.fromLTRB(0, 50, 100, 100),
6632+
),
6633+
tester.updateNode(
6634+
id: 3,
6635+
label: 'Blocked button',
6636+
flags: const ui.SemanticsFlags(
6637+
isButton: true,
6638+
isAccessibilityFocusBlocked: true,
6639+
isFocused: ui.Tristate.isFalse,
6640+
),
6641+
rect: const ui.Rect.fromLTRB(0, 100, 100, 150),
6642+
),
6643+
],
6644+
);
6645+
tester.apply();
6646+
6647+
expect(blockedContainer.isFocusable, isFalse);
6648+
expect(blockedContainer.element.getAttribute('role'), 'none');
6649+
expect(blockedContainer.element.getAttribute('aria-label'), isNull);
6650+
expect(blockedLeaf.element.getAttribute('aria-hidden'), 'true');
6651+
expect(blockedLeaf.element.text, isEmpty);
6652+
expect(blockedButton.isFocusable, isFalse);
6653+
expect(blockedButton.element.getAttribute('aria-hidden'), 'true');
6654+
expect(blockedButton.element.getAttribute('tabindex'), isNull);
6655+
6656+
// 3. Unblock nodes and verify label and focusability are restored.
6657+
tester.updateNode(
6658+
id: 0,
6659+
label: 'Blocked container',
6660+
flags: const ui.SemanticsFlags(isFocused: ui.Tristate.isFalse),
6661+
children: <SemanticsNodeUpdate>[
6662+
tester.updateNode(
6663+
id: 1,
6664+
label: 'Status ready',
6665+
flags: const ui.SemanticsFlags(isLiveRegion: true),
6666+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
6667+
),
6668+
tester.updateNode(
6669+
id: 2,
6670+
label: 'Accessible child',
6671+
rect: const ui.Rect.fromLTRB(0, 50, 100, 100),
6672+
),
6673+
tester.updateNode(
6674+
id: 3,
6675+
label: 'Blocked button',
6676+
flags: const ui.SemanticsFlags(isButton: true, isFocused: ui.Tristate.isFalse),
6677+
rect: const ui.Rect.fromLTRB(0, 100, 100, 150),
6678+
),
6679+
],
6680+
);
6681+
tester.apply();
6682+
6683+
expect(blockedContainer.isFocusable, isTrue);
6684+
expect(blockedContainer.element.getAttribute('role'), 'group');
6685+
expect(blockedContainer.element.getAttribute('aria-label'), 'Blocked container');
6686+
expect(blockedLeaf.element.getAttribute('aria-hidden'), isNull);
6687+
expect(blockedLeaf.element.text, 'Status ready');
6688+
expect(blockedButton.isFocusable, isTrue);
6689+
expect(blockedButton.element.getAttribute('aria-hidden'), isNull);
6690+
expect(blockedButton.element.getAttribute('tabindex'), '0');
6691+
});
6692+
65266693
semantics().semanticsEnabled = false;
65276694
}
65286695

0 commit comments

Comments
 (0)