Add framework-side hitTestBehavior support to Semantics (flutter#178817)

This is a reland of flutter#177570, which was reverted in flutter#178744 due to test
failures.

The original PR introduced `hitTestBehavior` to the semantics framework
but incorrectly applied `opaque` behavior to `ModalRoute`, which blocked
platform views from receiving pointer events.

Instead of making the entire modal opaque, we:
1. Keep `ModalRoute` without explicit `hitTestBehavior` (defaults to
`defer`)
2. Make only the dialog/sheet content opaque (blocks clicks to barrier)
3. Platform views remain clickable because they're outside the opaque
content boundary

Fixes flutter#149001
Original PR: flutter#177570
Revert: flutter#178744

Author: flutter-zl

packages/flutter/lib/src/material/bottom_sheet.dart

@@ -6,6 +6,7 @@
 library;
 
 import 'dart:math' as math;
+import 'dart:ui' show SemanticsHitTestBehavior;
 
 import 'package:flutter/foundation.dart';
 import 'package:flutter/gestures.dart';
@@ -1117,10 +1118,13 @@ class ModalBottomSheetRoute<T> extends PopupRoute<T> {
       ),
     );
 
-    final Widget bottomSheet = useSafeArea
+    Widget bottomSheet = useSafeArea
         ? SafeArea(bottom: false, child: content)
         : MediaQuery.removePadding(context: context, removeTop: true, child: content);
 
+    // Prevent clicks inside the bottom sheet from passing through to the barrier
+    bottomSheet = Semantics(hitTestBehavior: SemanticsHitTestBehavior.opaque, child: bottomSheet);
+
     return capturedThemes?.wrap(bottomSheet) ?? bottomSheet;
   }
 

packages/flutter/lib/src/material/dialog.dart

@@ -10,7 +10,7 @@
 /// @docImport 'text_button.dart';
 library;
 
-import 'dart:ui' show SemanticsRole, clampDouble, lerpDouble;
+import 'dart:ui' show SemanticsHitTestBehavior, SemanticsRole, clampDouble, lerpDouble;
 
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/foundation.dart';
@@ -1676,6 +1676,8 @@ class DialogRoute<T> extends RawDialogRoute<T> {
                if (useSafeArea) {
                  dialog = SafeArea(child: dialog);
                }
+               // Prevent clicks inside the dialog from passing through to the barrier
+               dialog = Semantics(hitTestBehavior: SemanticsHitTestBehavior.opaque, child: dialog);
                return dialog;
              },
          barrierLabel: barrierLabel ?? MaterialLocalizations.of(context).modalBarrierDismissLabel,

packages/flutter/lib/src/rendering/custom_paint.dart

@@ -1046,6 +1046,9 @@ class RenderCustomPaint extends RenderProxyBox {
     if (config.validationResult != properties.validationResult) {
       config.validationResult = properties.validationResult;
     }
+    if (properties.hitTestBehavior != null) {
+      config.hitTestBehavior = properties.hitTestBehavior!;
+    }
     if (properties.inputType != null) {
       config.inputType = properties.inputType!;
     }

packages/flutter/lib/src/rendering/object.dart

@@ -4940,6 +4940,10 @@ mixin SemanticsAnnotationsMixin on RenderObject {
       config.validationResult = _properties.validationResult;
     }
 
+    if (_properties.hitTestBehavior != null) {
+      config.hitTestBehavior = _properties.hitTestBehavior!;
+    }
+
     if (_properties.inputType != null) {
       config.inputType = _properties.inputType!;
     }

packages/flutter/lib/src/rendering/platform_view.dart

@@ -5,6 +5,8 @@
 /// @docImport 'package:flutter/widgets.dart';
 library;
 
+import 'dart:ui' as ui show SemanticsHitTestBehavior;
+
 import 'package:flutter/foundation.dart';
 import 'package:flutter/gestures.dart';
 import 'package:flutter/scheduler.dart';
@@ -267,6 +269,9 @@ class RenderAndroidView extends PlatformViewRenderBox {
 
     if (_viewController.isCreated) {
       config.platformViewId = _viewController.viewId;
+      // Platform views should allow pointer events to pass through to the
+      // underlying platform view content.
+      config.hitTestBehavior = ui.SemanticsHitTestBehavior.transparent;
     }
   }
 }
@@ -372,6 +377,9 @@ abstract class RenderDarwinPlatformView<T extends DarwinPlatformViewController>
     super.describeSemanticsConfiguration(config);
     config.isSemanticBoundary = true;
     config.platformViewId = _viewController.id;
+    // Platform views should allow pointer events to pass through to the
+    // underlying platform view content.
+    config.hitTestBehavior = ui.SemanticsHitTestBehavior.transparent;
   }
 
   @override
@@ -737,6 +745,9 @@ class PlatformViewRenderBox extends RenderBox with _PlatformViewGestureMixin {
     super.describeSemanticsConfiguration(config);
     config.isSemanticBoundary = true;
     config.platformViewId = _controller.viewId;
+    // Platform views should allow pointer events to pass through to the
+    // underlying platform view content.
+    config.hitTestBehavior = ui.SemanticsHitTestBehavior.transparent;
   }
 }
 

packages/flutter/lib/src/semantics/semantics.dart

@@ -28,6 +28,7 @@ import 'dart:ui'
         StringAttribute,
         TextDirection,
         Tristate;
+import 'dart:ui' as ui show SemanticsHitTestBehavior;
 
 import 'package:collection/collection.dart';
 import 'package:flutter/foundation.dart';
@@ -1020,6 +1021,7 @@ class SemanticsData with Diagnosticable {
     required this.role,
     required this.controlsNodes,
     required this.validationResult,
+    required this.hitTestBehavior,
     required this.inputType,
     required this.locale,
     this.tags,
@@ -1288,6 +1290,9 @@ class SemanticsData with Diagnosticable {
   /// {@macro flutter.semantics.SemanticsProperties.validationResult}
   final SemanticsValidationResult validationResult;
 
+  /// {@macro flutter.semantics.SemanticsProperties.hitTestBehavior}
+  final ui.SemanticsHitTestBehavior hitTestBehavior;
+
   /// {@macro flutter.semantics.SemanticsNode.inputType}
   final SemanticsInputType inputType;
 
@@ -1415,6 +1420,7 @@ class SemanticsData with Diagnosticable {
         other.role == role &&
         other.validationResult == validationResult &&
         other.inputType == inputType &&
+        other.hitTestBehavior == hitTestBehavior &&
         _sortedListsEqual(other.customSemanticsActionIds, customSemanticsActionIds) &&
         setEquals<String>(controlsNodes, other.controlsNodes);
   }
@@ -1451,8 +1457,7 @@ class SemanticsData with Diagnosticable {
       validationResult,
       controlsNodes == null ? null : Object.hashAll(controlsNodes!),
       inputType,
-      traversalParentIdentifier,
-      traversalChildIdentifier,
+      hitTestBehavior,
     ),
   );
 
@@ -1611,6 +1616,7 @@ class SemanticsProperties extends DiagnosticableTree {
     this.controlsNodes,
     this.inputType,
     this.validationResult = SemanticsValidationResult.none,
+    this.hitTestBehavior,
     this.onTap,
     this.onLongPress,
     this.onScrollLeft,
@@ -2555,6 +2561,13 @@ class SemanticsProperties extends DiagnosticableTree {
   /// {@endtemplate}
   final SemanticsValidationResult validationResult;
 
+  /// {@template flutter.semantics.SemanticsProperties.hitTestBehavior}
+  /// Describes how the semantic node should behave during hit testing.
+  ///
+  /// See [ui.SemanticsHitTestBehavior] for more details.
+  /// {@endtemplate}
+  final ui.SemanticsHitTestBehavior? hitTestBehavior;
+
   /// {@template flutter.semantics.SemanticsProperties.inputType}
   /// The input type for of a editable widget.
   ///
@@ -3235,7 +3248,8 @@ class SemanticsNode with DiagnosticableTreeMixin {
         _headingLevel != config._headingLevel ||
         _linkUrl != config._linkUrl ||
         _role != config.role ||
-        _validationResult != config.validationResult;
+        _validationResult != config.validationResult ||
+        _hitTestBehavior != config.hitTestBehavior;
   }
 
   // TAGS, LABELS, ACTIONS
@@ -3529,6 +3543,10 @@ class SemanticsNode with DiagnosticableTreeMixin {
   SemanticsValidationResult get validationResult => _validationResult;
   SemanticsValidationResult _validationResult = _kEmptyConfig.validationResult;
 
+  /// {@macro flutter.semantics.SemanticsProperties.hitTestBehavior}
+  ui.SemanticsHitTestBehavior get hitTestBehavior => _hitTestBehavior;
+  ui.SemanticsHitTestBehavior _hitTestBehavior = ui.SemanticsHitTestBehavior.defer;
+
   /// {@template flutter.semantics.SemanticsNode.inputType}
   /// The input type for of a editable node.
   ///
@@ -3609,6 +3627,7 @@ class SemanticsNode with DiagnosticableTreeMixin {
     _role = config._role;
     _controlsNodes = config._controlsNodes;
     _validationResult = config._validationResult;
+    _hitTestBehavior = config._hitTestBehavior;
     _inputType = config._inputType;
     _locale = config.locale;
 
@@ -3663,6 +3682,7 @@ class SemanticsNode with DiagnosticableTreeMixin {
     SemanticsRole role = _role;
     Set<String>? controlsNodes = _controlsNodes;
     SemanticsValidationResult validationResult = _validationResult;
+    ui.SemanticsHitTestBehavior hitTestBehavior = _hitTestBehavior;
     SemanticsInputType inputType = _inputType;
     final Locale? locale = _locale;
     final Set<int> customSemanticsActionIds = <int>{};
@@ -3727,6 +3747,9 @@ class SemanticsNode with DiagnosticableTreeMixin {
         if (inputType == SemanticsInputType.none) {
           inputType = node._inputType;
         }
+        if (hitTestBehavior == ui.SemanticsHitTestBehavior.defer) {
+          hitTestBehavior = node._hitTestBehavior;
+        }
         if (tooltip == '') {
           tooltip = node._tooltip;
         }
@@ -3818,6 +3841,7 @@ class SemanticsNode with DiagnosticableTreeMixin {
       role: role,
       controlsNodes: controlsNodes,
       validationResult: validationResult,
+      hitTestBehavior: hitTestBehavior,
       inputType: inputType,
       locale: locale,
     );
@@ -3989,6 +4013,7 @@ class SemanticsNode with DiagnosticableTreeMixin {
       role: data.role,
       controlsNodes: data.controlsNodes?.toList(),
       validationResult: data.validationResult,
+      hitTestBehavior: data.hitTestBehavior,
       inputType: data.inputType,
       locale: data.locale,
     );
@@ -6415,6 +6440,14 @@ class SemanticsConfiguration {
     _hasBeenAnnotated = true;
   }
 
+  /// {@macro flutter.semantics.SemanticsProperties.hitTestBehavior}
+  ui.SemanticsHitTestBehavior get hitTestBehavior => _hitTestBehavior;
+  ui.SemanticsHitTestBehavior _hitTestBehavior = ui.SemanticsHitTestBehavior.defer;
+  set hitTestBehavior(ui.SemanticsHitTestBehavior value) {
+    _hitTestBehavior = value;
+    _hasBeenAnnotated = true;
+  }
+
   /// {@macro flutter.semantics.SemanticsProperties.inputType}
   SemanticsInputType get inputType => _inputType;
   SemanticsInputType _inputType = SemanticsInputType.none;
@@ -6523,6 +6556,10 @@ class SemanticsConfiguration {
     if (_hasExplicitRole && other._hasExplicitRole) {
       return false;
     }
+    if (_hitTestBehavior != ui.SemanticsHitTestBehavior.defer ||
+        other._hitTestBehavior != ui.SemanticsHitTestBehavior.defer) {
+      return false;
+    }
     return true;
   }
 
@@ -6633,6 +6670,11 @@ class SemanticsConfiguration {
       child._accessiblityFocusBlockType,
     );
 
+    if (_hitTestBehavior == ui.SemanticsHitTestBehavior.defer &&
+        child._hitTestBehavior != ui.SemanticsHitTestBehavior.defer) {
+      _hitTestBehavior = child._hitTestBehavior;
+    }
+
     _hasBeenAnnotated = hasBeenAnnotated || child.hasBeenAnnotated;
   }
 
@@ -6678,7 +6720,8 @@ class SemanticsConfiguration {
       .._role = _role
       .._controlsNodes = _controlsNodes
       .._validationResult = _validationResult
-      .._inputType = _inputType;
+      .._inputType = _inputType
+      .._hitTestBehavior = _hitTestBehavior;
   }
 }
 

packages/flutter/lib/src/widgets/basic.dart

@@ -9,7 +9,9 @@
 library;
 
 import 'dart:math' as math;
-import 'dart:ui' as ui show Image, ImageFilter, SemanticsInputType, TextHeightBehavior;
+import 'dart:ui'
+    as ui
+    show Image, ImageFilter, SemanticsHitTestBehavior, SemanticsInputType, TextHeightBehavior;
 
 import 'package:flutter/animation.dart';
 import 'package:flutter/foundation.dart';
@@ -4048,6 +4050,7 @@ sealed class _SemanticsBase extends SingleChildRenderObjectWidget {
     required SemanticsRole? role,
     required Set<String>? controlsNodes,
     required SemanticsValidationResult validationResult,
+    required ui.SemanticsHitTestBehavior? hitTestBehavior,
     required ui.SemanticsInputType? inputType,
     required Locale? localeForSubtree,
   }) : this.fromProperties(
@@ -4133,6 +4136,7 @@ sealed class _SemanticsBase extends SingleChildRenderObjectWidget {
            role: role,
            controlsNodes: controlsNodes,
            validationResult: validationResult,
+           hitTestBehavior: hitTestBehavior,
            inputType: inputType,
          ),
        );
@@ -4382,6 +4386,7 @@ class SliverSemantics extends _SemanticsBase {
     super.role,
     super.controlsNodes,
     super.validationResult = SemanticsValidationResult.none,
+    super.hitTestBehavior,
     super.inputType,
     super.localeForSubtree,
   }) : super(child: sliver);
@@ -7964,6 +7969,7 @@ class Semantics extends _SemanticsBase {
     super.role,
     super.controlsNodes,
     super.validationResult = SemanticsValidationResult.none,
+    super.hitTestBehavior,
     super.inputType,
     super.localeForSubtree,
   });

packages/flutter/lib/src/widgets/routes.dart

@@ -2313,6 +2313,7 @@ abstract class ModalRoute<T> extends TransitionRoute<T> with LocalHistoryRoute<T
     // To be sorted before the _modalBarrier.
     return _modalScopeCache ??= Semantics(
       sortKey: const OrdinalSortKey(0.0),
+      hitTestBehavior: ui.SemanticsHitTestBehavior.opaque,
       child: _ModalScope<T>(
         key: _scopeKey,
         route: this,
@@ -2616,6 +2617,7 @@ class RawDialogRoute<T> extends PopupRoute<T> {
     return Semantics(
       scopesRoute: true,
       explicitChildNodes: true,
+      hitTestBehavior: ui.SemanticsHitTestBehavior.opaque,
       child: DisplayFeatureSubScreen(
         anchorPoint: anchorPoint,
         child: _pageBuilder(context, animation, secondaryAnimation),