fix: expose disclosure trigger-to-panel semantics relationship

.github/workflows/integration-web.yml

@@ -68,12 +68,23 @@ jobs:
             --browser-dimension=800x600@1 \
             --chrome-binary="${{ steps.chrome.outputs.chrome-path }}" \
             2>&1 | tee build/web-integration.log
+          flutter drive \
+            --driver=test_driver/integration_test_behavior.dart \
+            --target=integration_test/web_disclosure_semantics.dart \
+            -d web-server \
+            --browser-name=chrome \
+            --browser-dimension=800x600@1 \
+            --chrome-binary="${{ steps.chrome.outputs.chrome-path }}" \
+            2>&1 | tee build/web-semantics-integration.log
 
       - name: Verify web integration evidence
         run: |
           log=packages/example/build/web-integration.log
           grep -F "All tests passed." "$log"
-          if grep -Eq 'TimeoutException|Some tests failed\.| \[E\]' "$log"; then
+          semantics_log=packages/example/build/web-semantics-integration.log
+          grep -F "All tests passed." "$semantics_log"
+          if grep -Eq 'TimeoutException|Some tests failed\.| \[E\]' \
+            "$log" "$semantics_log"; then
             echo "The in-app test runner reported failures." >&2
             exit 1
           fi
@@ -85,6 +96,7 @@ jobs:
           name: integration-web-${{ github.sha }}
           path: |
             packages/example/build/web-integration.log
+            packages/example/build/web-semantics-integration.log
             packages/example/build/integration_response_data.json
           if-no-files-found: warn
           retention-days: 14

docs/widget/disclosure.mdx

@@ -123,6 +123,10 @@ reopened panel.
 
 - The trigger is the only button and the only disclosure tap target.
 - Visible trigger text supplies the accessible name by default.
+- While expanded, the trigger identifies a distinct panel semantics container it
+  controls. Flutter web maps this relationship to `aria-controls`.
+- The relationship is removed while collapsed because the panel is absent from
+  the semantics tree.
 - A non-empty `semanticLabel` replaces trigger-descendant semantics; use
   `semanticHint` for short additional context.
 - `excludeSemantics: true` hides both the trigger and panel.

packages/example/integration_test/web_disclosure_semantics.dart

@@ -0,0 +1,93 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:integration_test/integration_test.dart';
+import 'package:naked_ui/naked_ui.dart';
+import 'package:web/web.dart' as web;
+
+void main() {
+  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+
+  testWidgets('disclosure controls each remounted web semantics panel', (
+    tester,
+  ) async {
+    final semantics = tester.ensureSemantics();
+
+    await tester.pumpWidget(
+      const MaterialApp(
+        home: Scaffold(
+          body: Center(
+            child: NakedDisclosure(
+              autofocus: true,
+              defaultExpanded: true,
+              semanticLabel: 'Disclosure trigger',
+              panel: Text('Panel'),
+              child: Text('Trigger'),
+            ),
+          ),
+        ),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    final panelIds = <String>{};
+    final panelIdentifiers = <String>{};
+
+    void expectExpandedRelationship() {
+      final trigger = web.document.querySelector(
+        '[role="button"][aria-expanded]',
+      );
+      expect(trigger, isNotNull);
+      expect(trigger!.getAttribute('aria-expanded'), 'true');
+
+      final controls = trigger.getAttribute('aria-controls');
+      expect(controls, isNotNull);
+      final panel = web.document.getElementById(controls!);
+      expect(panel, isNotNull);
+      expect(
+        panel!.getAttribute('flt-semantics-identifier'),
+        startsWith('naked-disclosure-panel-'),
+      );
+      expect(panel.textContent, contains('Panel'));
+      panelIds.add(panel.id);
+      panelIdentifiers.add(panel.getAttribute('flt-semantics-identifier')!);
+    }
+
+    void expectCollapsedRelationship() {
+      final trigger = web.document.querySelector(
+        '[role="button"][aria-expanded]',
+      );
+      expect(trigger, isNotNull);
+      expect(trigger!.getAttribute('aria-expanded'), 'false');
+      expect(trigger.getAttribute('aria-controls'), isNull);
+      expect(
+        web.document.querySelector(
+          '[flt-semantics-identifier^="naked-disclosure-panel-"]',
+        ),
+        isNull,
+      );
+    }
+
+    expectExpandedRelationship();
+
+    await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+    await tester.pumpAndSettle();
+    expectCollapsedRelationship();
+
+    await tester.sendKeyEvent(LogicalKeyboardKey.space);
+    await tester.pumpAndSettle();
+    expectExpandedRelationship();
+
+    await tester.sendKeyEvent(LogicalKeyboardKey.enter);
+    await tester.pumpAndSettle();
+    expectCollapsedRelationship();
+
+    await tester.sendKeyEvent(LogicalKeyboardKey.space);
+    await tester.pumpAndSettle();
+    expectExpandedRelationship();
+
+    expect(panelIds, hasLength(3));
+    expect(panelIdentifiers, hasLength(3));
+    semantics.dispose();
+  });
+}

packages/example/pubspec.yaml

@@ -23,6 +23,7 @@ dev_dependencies:
     sdk: flutter
   integration_test:
     sdk: flutter
+  web: ^1.1.1
 
 flutter:
   uses-material-design: true

packages/naked_ui/lib/src/naked_disclosure.dart

@@ -1,5 +1,6 @@
 import 'dart:async';
 
+import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:flutter/widgets.dart';
 
 import 'mixins/naked_mixins.dart';
@@ -178,14 +179,20 @@ class _NakedDisclosureState extends State<NakedDisclosure>
         WidgetStatesMixin<NakedDisclosure>,
         FocusNodeMixin<NakedDisclosure>,
         SingleTickerProviderStateMixin<NakedDisclosure> {
+  static int _nextPanelSemanticsIdentifier = 0;
+
   Timer? _keyboardPressTimer;
+  late String _panelSemanticsIdentifier = _newPanelSemanticsIdentifier();
+  final GlobalKey? _webTriggerSubtreeKey = kIsWeb ? GlobalKey() : null;
   final FocusNode _panelFocusNode = FocusNode(
     debugLabel: 'NakedDisclosure panel',
   );
   late final AnimationController _animationController;
   late CurvedAnimation _animation;
   late bool _uncontrolledExpanded;
   late bool _panelMounted;
+  late bool _panelSemanticsReady;
+  int _webTriggerSemanticsGeneration = 0;
   bool _animationsDisabled = false;
   int _transitionGeneration = 0;
 
@@ -201,6 +208,9 @@ class _NakedDisclosureState extends State<NakedDisclosure>
       widget.animationStyle != AnimationStyle.noAnimation &&
       !_animationsDisabled;
 
+  static String _newPanelSemanticsIdentifier() =>
+      'naked-disclosure-panel-${_nextPanelSemanticsIdentifier++}';
+
   Duration get _forwardDuration =>
       widget.animationStyle.duration ?? const Duration(milliseconds: 200);
 
@@ -227,6 +237,7 @@ class _NakedDisclosureState extends State<NakedDisclosure>
     // WidgetStatesMixin initializes state from _isExpanded in super.initState.
     _uncontrolledExpanded = widget.defaultExpanded;
     _panelMounted = _isExpanded;
+    _panelSemanticsReady = _isExpanded;
     super.initState();
     _animationController = AnimationController(
       value: _isExpanded ? 1 : 0,
@@ -283,6 +294,9 @@ class _NakedDisclosureState extends State<NakedDisclosure>
     }
 
     updateSelectedState(_isExpanded, null);
+    if (oldExpanded != _isExpanded) {
+      _refreshPanelSemanticsRelationship();
+    }
     if (oldExpanded != _isExpanded ||
         oldWidget.transitionBuilder != widget.transitionBuilder ||
         oldWidget.animationStyle != widget.animationStyle) {
@@ -301,13 +315,40 @@ class _NakedDisclosureState extends State<NakedDisclosure>
 
     if (!_isControlled) {
       _uncontrolledExpanded = nextExpanded;
+      _refreshPanelSemanticsRelationship();
       updateSelectedState(nextExpanded, null);
       _applyExpansion();
     }
 
     widget.onExpandedChanged?.call(nextExpanded);
   }
 
+  void _refreshPanelSemanticsRelationship() {
+    if (!kIsWeb) {
+      _panelSemanticsReady = _isExpanded;
+      return;
+    }
+
+    _panelSemanticsReady = false;
+    if (!_isExpanded) return;
+    _panelSemanticsIdentifier = _newPanelSemanticsIdentifier();
+    _scheduleWebPanelSemanticsRelationship();
+  }
+
+  void _scheduleWebPanelSemanticsRelationship() {
+    // Flutter web resolves controlsNodes to a DOM node ID when the semantics
+    // update arrives, so wait until the remounted panel has registered itself.
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (!mounted || !_isExpanded || _panelSemanticsReady) return;
+      setState(() {
+        // Recreate the trigger semantics boundary because Flutter web does
+        // not re-resolve controlsNodes there after its target remounts.
+        _webTriggerSemanticsGeneration += 1;
+        _panelSemanticsReady = true;
+      });
+    });
+  }
+
   void _handleTap() {
     if (!_isInteractive) return;
     if (widget.enableFeedback) Feedback.forTap(context);
@@ -365,12 +406,17 @@ class _NakedDisclosureState extends State<NakedDisclosure>
 
   Widget _buildPanel(BuildContext context) {
     final panelHidden = !_isExpanded;
-    final panel = Focus(
-      focusNode: _panelFocusNode,
-      canRequestFocus: false,
-      skipTraversal: true,
-      includeSemantics: false,
-      child: widget.panel,
+    final panel = Semantics(
+      container: true,
+      explicitChildNodes: true,
+      identifier: _panelSemanticsIdentifier,
+      child: Focus(
+        focusNode: _panelFocusNode,
+        canRequestFocus: false,
+        skipTraversal: true,
+        includeSemantics: false,
+        child: widget.panel,
+      ),
     );
     final transitionBuilder = widget.transitionBuilder;
     final transitionedPanel = transitionBuilder == null
@@ -430,18 +476,8 @@ class _NakedDisclosureState extends State<NakedDisclosure>
             child: trigger,
           );
 
-          final semanticTrigger = Semantics(
-            enabled: _isInteractive,
-            button: true,
-            expanded: _isExpanded,
-            label: hasReplacementLabel ? semanticLabel : null,
-            hint: widget.semanticHint,
-            excludeSemantics: hasReplacementLabel,
-            onTap: _isInteractive ? _handleTap : null,
-            child: triggerContent,
-          );
-
           final focusableTrigger = NakedFocusableDetector(
+            key: _webTriggerSubtreeKey,
             enabled: _isInteractive,
             autofocus: widget.autofocus,
             onFocusChange: (focused) =>
@@ -456,10 +492,26 @@ class _NakedDisclosureState extends State<NakedDisclosure>
             actions: NakedIntentActions.button.actions(
               onPressed: _handleKeyboardActivation,
             ),
-            child: semanticTrigger,
+            child: triggerContent,
+          );
+
+          final semanticTrigger = Semantics(
+            key: kIsWeb ? ValueKey(_webTriggerSemanticsGeneration) : null,
+            container: true,
+            enabled: _isInteractive,
+            button: true,
+            expanded: _isExpanded,
+            controlsNodes: _isExpanded && _panelSemanticsReady
+                ? {_panelSemanticsIdentifier}
+                : null,
+            label: hasReplacementLabel ? semanticLabel : null,
+            hint: widget.semanticHint,
+            excludeSemantics: hasReplacementLabel,
+            onTap: _isInteractive ? _handleTap : null,
+            child: focusableTrigger,
           );
 
-          final children = <Widget>[focusableTrigger];
+          final children = <Widget>[semanticTrigger];
           if (_panelMounted) children.add(_buildPanel(context));
           final assembledItem = Column(
             mainAxisSize: MainAxisSize.min,