Use aria-hidden attribute for platform view accessibility on web (flutter#177969)

Use aria-hidden attribute for platform view accessibility on web

Before change:
https://map-1023-before.web.app/

After change:
https://map-1023-after.web.app/

Fixes flutter#171948.

Note: When a descendant element receives focus (for example, a marker),
the browser automatically overrides aria-hidden. This behavior is
correct and expected for accessibility compliance.

Author: flutter-zl

engine/src/flutter/lib/web_ui/lib/src/engine/platform_views/content_manager.dart

@@ -37,6 +37,9 @@ class PlatformViewManager {
   /// rendering of PlatformViews into the web app.
   static PlatformViewManager instance = PlatformViewManager();
 
+  /// The attribute name used to hide platform views from accessibility.
+  static const String _ariaHiddenAttribute = 'aria-hidden';
+
   // The factory functions, indexed by the viewType
   final Map<String, Function> _factories = <String, Function>{};
 
@@ -119,7 +122,7 @@ class PlatformViewManager {
   /// The resulting DOM for the `contents` of a Platform View looks like this:
   ///
   /// ```html
-  /// <flt-platform-view id="flt-pv-VIEW_ID" slot="...">
+  /// <flt-platform-view id="flt-pv-VIEW_ID" slot="..." aria-hidden="true">
   ///   <arbitrary-html-elements />
   /// </flt-platform-view-slot>
   /// ```
@@ -131,6 +134,9 @@ class PlatformViewManager {
   /// a place where to attach the `slot` property, that will tell the browser
   /// what `slot` tag will reveal this `contents`, **without modifying the returned
   /// html from the `factory` function**.
+  ///
+  /// By default, platform views are hidden from accessibility using aria-hidden.
+  /// The semantics layer will remove this when a semantic node is created.
   DomElement renderContent(String viewType, int viewId, Object? params) {
     assert(
       knowsViewType(viewType),
@@ -158,6 +164,8 @@ class PlatformViewManager {
       _ensureContentCorrectlySized(content, viewType);
       wrapper.append(content);
 
+      wrapper.setAttribute(_ariaHiddenAttribute, 'true');
+
       return wrapper;
     });
   }
@@ -209,6 +217,23 @@ class PlatformViewManager {
   /// component.
   bool isVisible(int viewId) => !isInvisible(viewId);
 
+  /// Updates the accessibility attributes of a platform view.
+  ///
+  /// This is called by the semantics layer to hide or show platform views
+  /// from screen readers based on semantic properties like ExcludeSemantics.
+  void updatePlatformViewAccessibility(int viewId, bool isHidden) {
+    final DomElement? wrapper = getSlottedContent(viewId);
+    if (wrapper == null) {
+      return;
+    }
+
+    if (isHidden) {
+      wrapper.setAttribute(_ariaHiddenAttribute, 'true');
+    } else {
+      wrapper.removeAttribute(_ariaHiddenAttribute);
+    }
+  }
+
   /// Clears the state. Used in tests.
   void debugClear() {
     _contents.keys.toList().forEach(clearPlatformView);

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

@@ -2,6 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+import '../platform_views/content_manager.dart';
 import '../platform_views/slots.dart';
 import 'label_and_value.dart';
 import 'semantics.dart';
@@ -40,9 +41,18 @@ class SemanticPlatformView extends SemanticRole {
     super.update();
 
     if (semanticsObject.isPlatformView) {
-      if (semanticsObject.isPlatformViewIdDirty) {
-        setAttribute('aria-owns', getPlatformViewDomId(semanticsObject.platformViewId));
+      final int platformViewId = semanticsObject.platformViewId;
+      final bool isHidden = semanticsObject.flags.isHidden;
+
+      if (isHidden) {
+        // When hidden, remove aria-owns since the platform view is not part
+        // of the accessibility tree.
+        removeAttribute('aria-owns');
+      } else {
+        setAttribute('aria-owns', getPlatformViewDomId(platformViewId));
       }
+
+      PlatformViewManager.instance.updatePlatformViewAccessibility(platformViewId, isHidden);
     } else {
       removeAttribute('aria-owns');
     }

engine/src/flutter/lib/web_ui/test/engine/platform_views/content_manager_test.dart

@@ -242,5 +242,72 @@ void testMain() {
       expect(contentManager.isVisible(viewId + 2), isTrue);
       expect(contentManager.isInvisible(viewId + 2), isFalse);
     });
+
+    group('updatePlatformViewAccessibility', () {
+      setUp(() {
+        contentManager.registerFactory(viewType, (int id) => createDomHTMLDivElement());
+      });
+
+      test('sets aria-hidden attribute by default when rendering', () {
+        final DomElement wrapper = contentManager.renderContent(viewType, viewId, null);
+
+        expect(
+          wrapper.getAttribute('aria-hidden'),
+          'true',
+          reason: 'Platform views should be aria-hidden by default for ExcludeSemantics support',
+        );
+      });
+
+      test('hides platform view from accessibility when isHidden is true', () {
+        final DomElement wrapper = contentManager.renderContent(viewType, viewId, null);
+
+        wrapper.removeAttribute('aria-hidden');
+        expect(wrapper.hasAttribute('aria-hidden'), isFalse);
+
+        contentManager.updatePlatformViewAccessibility(viewId, true);
+
+        expect(
+          wrapper.getAttribute('aria-hidden'),
+          'true',
+          reason: 'aria-hidden should be set to true when isHidden is true',
+        );
+      });
+
+      test('makes platform view accessible when isHidden is false', () {
+        final DomElement wrapper = contentManager.renderContent(viewType, viewId, null);
+
+        expect(
+          wrapper.getAttribute('aria-hidden'),
+          'true',
+          reason: 'Platform view should start with aria-hidden=true',
+        );
+
+        contentManager.updatePlatformViewAccessibility(viewId, false);
+
+        expect(
+          wrapper.hasAttribute('aria-hidden'),
+          isFalse,
+          reason: 'aria-hidden should be removed when isHidden is false',
+        );
+      });
+
+      test('handles toggle between hidden and accessible states', () {
+        final DomElement wrapper = contentManager.renderContent(viewType, viewId, null);
+
+        contentManager.updatePlatformViewAccessibility(viewId, false);
+        expect(wrapper.hasAttribute('aria-hidden'), isFalse);
+
+        contentManager.updatePlatformViewAccessibility(viewId, true);
+        expect(wrapper.getAttribute('aria-hidden'), 'true');
+
+        contentManager.updatePlatformViewAccessibility(viewId, false);
+        expect(wrapper.hasAttribute('aria-hidden'), isFalse);
+      });
+
+      test('does nothing when viewId does not exist', () {
+        expect(() => contentManager.updatePlatformViewAccessibility(999, true), returnsNormally);
+        expect(() => contentManager.updatePlatformViewAccessibility(999, false), returnsNormally);
+      });
+    });
   });
 }

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

@@ -3960,6 +3960,43 @@ void _testPlatformView() {
 
     semantics().semanticsEnabled = false;
   });
+
+  test('removes aria-owns when platform view is hidden', () async {
+    semantics()
+      ..debugOverrideTimestampFunction(() => _testTime)
+      ..semanticsEnabled = true;
+
+    // Create a platform view that is visible (has aria-owns).
+    {
+      final ui.SemanticsUpdateBuilder builder = ui.SemanticsUpdateBuilder();
+      updateNode(builder, platformViewId: 5, rect: const ui.Rect.fromLTRB(0, 0, 100, 50));
+      owner().updateSemantics(builder.build());
+      expectSemanticsTree(owner(), '<sem aria-owns="flt-pv-5"></sem>');
+    }
+
+    // Hide the platform view (should remove aria-owns).
+    {
+      final ui.SemanticsUpdateBuilder builder = ui.SemanticsUpdateBuilder();
+      updateNode(
+        builder,
+        platformViewId: 5,
+        flags: const ui.SemanticsFlags(isHidden: true),
+        rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
+      );
+      owner().updateSemantics(builder.build());
+      expectSemanticsTree(owner(), '<sem></sem>');
+    }
+
+    // Show the platform view again (should restore aria-owns).
+    {
+      final ui.SemanticsUpdateBuilder builder = ui.SemanticsUpdateBuilder();
+      updateNode(builder, platformViewId: 5, rect: const ui.Rect.fromLTRB(0, 0, 100, 50));
+      owner().updateSemantics(builder.build());
+      expectSemanticsTree(owner(), '<sem aria-owns="flt-pv-5"></sem>');
+    }
+
+    semantics().semanticsEnabled = false;
+  });
 }
 
 void _testGroup() {