Skip to content

Commit effca52

Browse files
committed
feat(a2ui_flutter): apply a component's accessibility label and description
NodeView wraps every resolved component in a Semantics that carries the component's accessibility label as its label and its description as its hint, so basic and custom components both get them. Without either attribute the Semantics adds no node, and it stays in the tree so that adding one later keeps the component's state. 🤖 Agent-generated
1 parent 7a97d94 commit effca52

3 files changed

Lines changed: 96 additions & 15 deletions

File tree

‎dart/a2ui_flutter/lib/src/node_view.dart‎

Lines changed: 37 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,10 @@ import 'signal_state.dart';
2121

2222
/// Renders one [ComponentNode] and rebuilds when the node's own props change.
2323
///
24-
/// A resolved node renders through its implementation's builder. A pending
25-
/// node renders a [LoadingPlaceholder], and an unknown-type or cyclic node
26-
/// a short diagnostic.
24+
/// A resolved node renders through its implementation's builder, under a
25+
/// semantics node carrying its `accessibility` label and description, if it
26+
/// has either. A pending node renders a [LoadingPlaceholder], and an
27+
/// unknown-type or cyclic node a short diagnostic.
2728
class NodeView extends StatefulWidget {
2829
/// Creates a view of [node], keyed by its instance id.
2930
NodeView(this.node) : super(key: NodeKey(node.instanceId));
@@ -67,17 +68,7 @@ class _NodeViewState extends State<NodeView> with SignalState {
6768
Widget build(BuildContext context) {
6869
final ComponentNode<ComponentImplementation> node = widget.node;
6970
return switch (node.state) {
70-
// A type or catalog change keeps the instance id, so the
71-
// implementation keys the subtree.
72-
NodeState.resolved => KeyedSubtree(
73-
key: ObjectKey(node.impl),
74-
child: node.impl!.builder(
75-
context,
76-
node,
77-
ComponentProps(node.props.peek()),
78-
NodeView.new,
79-
),
80-
),
71+
NodeState.resolved => _buildResolved(context, node),
8172
NodeState.pending => const LoadingPlaceholder(),
8273
NodeState.unknownType => _Diagnostic(
8374
'Unknown component type "${node.type}"',
@@ -89,6 +80,38 @@ class _NodeViewState extends State<NodeView> with SignalState {
8980
}
9081
}
9182

83+
/// Builds a resolved [node] through its implementation, in a [Semantics]
84+
/// with the component's `accessibility` label and description. The
85+
/// [Semantics] is there even without them, so adding one later keeps the
86+
/// subtree's state.
87+
Widget _buildResolved(
88+
BuildContext context,
89+
ComponentNode<ComponentImplementation> node,
90+
) {
91+
final props = ComponentProps(node.props.peek());
92+
final Object? attributes = props.value('accessibility');
93+
String? read(String key) {
94+
final String? text = attributes is Map
95+
? ComponentProps.asString(attributes[key])
96+
: null;
97+
return text == null || text.isEmpty ? null : text;
98+
}
99+
100+
final String? label = read('label');
101+
final String? description = read('description');
102+
return Semantics(
103+
container: label != null || description != null,
104+
label: label,
105+
hint: description,
106+
// A type or catalog change keeps the instance id, so the implementation
107+
// keys the subtree.
108+
child: KeyedSubtree(
109+
key: ObjectKey(node.impl),
110+
child: node.impl!.builder(context, node, props, NodeView.new),
111+
),
112+
);
113+
}
114+
92115
/// A small progress indicator that stands in for a component that has not
93116
/// arrived.
94117
class LoadingPlaceholder extends StatelessWidget {

‎dart/a2ui_flutter/test/node_view_test.dart‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -391,4 +391,57 @@ void main() {
391391
expect(dropped.disposed, isTrue);
392392
expect(tester.takeException(), isNull);
393393
});
394+
395+
group('accessibility', () {
396+
testWidgets('gives a component its label and description', (tester) async {
397+
final SemanticsHandle semantics = tester.ensureSemantics();
398+
add('root', 'Button', {
399+
'child': 'icon',
400+
'accessibility': {'label': 'Close', 'description': 'Closes the order'},
401+
});
402+
add('icon', 'Text', {'text': 'x'});
403+
await pumpRoot(tester);
404+
405+
expect(
406+
tester.getSemantics(find.bySemanticsLabel('Close')),
407+
matchesSemantics(label: 'Close', hint: 'Closes the order'),
408+
);
409+
semantics.dispose();
410+
});
411+
412+
testWidgets('follows a bound label', (tester) async {
413+
final SemanticsHandle semantics = tester.ensureSemantics();
414+
surface.dataModel.set('/label', 'Inbox');
415+
add('root', 'Text', {
416+
'text': 'x',
417+
'accessibility': {
418+
'label': {'path': '/label'},
419+
},
420+
});
421+
await pumpRoot(tester);
422+
expect(find.bySemanticsLabel(RegExp('^Inbox')), findsOneWidget);
423+
424+
surface.dataModel.set('/label', 'Archive');
425+
await tester.pump();
426+
427+
expect(find.bySemanticsLabel(RegExp('^Inbox')), findsNothing);
428+
expect(find.bySemanticsLabel(RegExp('^Archive')), findsOneWidget);
429+
semantics.dispose();
430+
});
431+
432+
testWidgets('keeps the implementation state when a label is added', (
433+
tester,
434+
) async {
435+
add('root', 'Probe', {'label': 'p'});
436+
await pumpRoot(tester);
437+
438+
update('root', {
439+
'label': 'p',
440+
'accessibility': {'label': 'Probe'},
441+
});
442+
await tester.pump();
443+
444+
expect(log.probeStates, ['root']);
445+
});
446+
});
394447
}

‎dart/a2ui_flutter/test/support/fixture_catalog.dart‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,12 @@ CatalogImplementation fixtureCatalog([
5858
ComponentWidgetBuilder builder,
5959
) => ComponentImplementation(
6060
name: name,
61-
schema: Schema.object(properties: properties),
61+
schema: Schema.object(
62+
properties: {
63+
...properties,
64+
'accessibility': CommonSchemas.accessibilityAttributes,
65+
},
66+
),
6267
builder: (context, node, props, buildChild) {
6368
log?.builds.add(node.componentId);
6469
log?.nodes[node.instanceId] = node;

0 commit comments

Comments
 (0)