Add support for reduced motion/disable animations on the web (#180041)

This PR listens to changes to the value of the `(prefers-reduced-motion:
reduce)` media query to update the `reduceMotion` and
`disableAnimations` properties of the `AccessibilityFeatures`
configuration object.

This is achieved by introducing a new `MediaQueryManager` object to the
`EnginePlatformDispatcher` that handles handles all the engine
configuration values that are driven by media queries: "reduced motion",
"high contrast" and "dark mode".

Unifying the code paths of all these values, allows this PR to slightly
increase testing coverage of those values, by injecting fake browser
events in the `platform_dispatcher_test.dart` file.

### Issues

* Fixes #167566

### Testing

* Added browser tests for new (and existing) media-queries
* Deployed test app to: https://dit-tests.web.app (may get offline!)

## 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.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

Author: ditman

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

@@ -59,7 +59,6 @@ export 'engine/font_fallbacks.dart';
 export 'engine/fonts.dart';
 export 'engine/frame_service.dart';
 export 'engine/frame_timing_recorder.dart';
-export 'engine/high_contrast.dart';
 export 'engine/html_image_element_codec.dart';
 export 'engine/image_decoder.dart';
 export 'engine/image_format_detector.dart';
@@ -87,6 +86,8 @@ export 'engine/occlusion_map.dart';
 export 'engine/onscreen_logging.dart';
 export 'engine/platform_dispatcher.dart';
 export 'engine/platform_dispatcher/app_lifecycle_state.dart';
+export 'engine/platform_dispatcher/media_query_manager.dart';
+export 'engine/platform_dispatcher/system_color_palette_detector.dart';
 export 'engine/platform_dispatcher/view_focus_binding.dart';
 export 'engine/platform_views/content_manager.dart';
 export 'engine/platform_views/embedder.dart';

engine/src/flutter/lib/web_ui/lib/src/engine/dom.dart

@@ -1801,9 +1801,17 @@ extension type DomMediaQueryList._(JSObject _) implements DomEventTarget {
 
 @JS('MediaQueryListEvent')
 extension type DomMediaQueryListEvent._(JSObject _) implements DomEvent {
+  /// https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryListEvent/MediaQueryListEvent
+  @visibleForTesting
+  external DomMediaQueryListEvent(String type, [JSAny initDict]);
   external bool? get matches;
 }
 
+@visibleForTesting
+DomMediaQueryListEvent createDomMediaQueryListEvent(String type, Map<dynamic, dynamic> init) {
+  return DomMediaQueryListEvent(type, init.toJSAnyDeep);
+}
+
 @JS('Path2D')
 extension type DomPath2D._(JSObject _) implements JSObject {
   external DomPath2D([JSAny path]);

engine/src/flutter/lib/web_ui/lib/src/engine/platform_dispatcher.dart

@@ -18,6 +18,11 @@ typedef _KeyDataResponseCallback = void Function(bool handled);
 const StandardMethodCodec standardCodec = StandardMethodCodec();
 const JSONMethodCodec jsonCodec = JSONMethodCodec();
 
+// An object to listen to values coming from media queries in the browser, like
+// prefers-color-scheme or prefers-reduced-motion
+@visibleForTesting
+final MediaQueryManager mediaQueries = MediaQueryManager();
+
 /// Platform event dispatcher.
 ///
 /// This is the central entry point for platform messages and configuration
@@ -26,8 +31,7 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
   /// Private constructor, since only dart:ui is supposed to create one of
   /// these.
   EnginePlatformDispatcher() {
-    _addBrightnessMediaQueryListener();
-    HighContrastSupport.instance.addListener(_updateHighContrast);
+    _registerMediaQueryListeners();
     _addTypographySettingsObserver();
     _addLocaleChangedListener();
     registerHotRestartListener(dispose);
@@ -71,17 +75,16 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
   /// Compute accessibility features based on the current value of high contrast flag
   static EngineAccessibilityFeatures computeAccessibilityFeatures() {
     final builder = EngineAccessibilityFeaturesBuilder(0);
-    if (HighContrastSupport.instance.isHighContrastEnabled) {
+    if (_isHighContrastEnabled) {
       builder.highContrast = true;
     }
     return builder.build();
   }
 
   void dispose() {
-    _removeBrightnessMediaQueryListener();
+    mediaQueries.detachAll();
     _disconnectTypographySettingsObserver();
     _removeLocaleChangedListener();
-    HighContrastSupport.instance.removeListener(_updateHighContrast);
     _appLifecycleState.removeListener(_setAppLifecycleState);
     _viewFocusBinding.dispose();
     accessibilityPlaceholder.remove();
@@ -1219,9 +1222,10 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
 
   /// Updates [_platformBrightness] and invokes [onPlatformBrightnessChanged]
   /// callback if [_platformBrightness] changed.
-  void _updatePlatformBrightness(ui.Brightness value) {
-    if (configuration.platformBrightness != value) {
-      configuration = configuration.copyWith(platformBrightness: value);
+  void _updatePlatformBrightness(bool prefersDark) {
+    final ui.Brightness brightness = prefersDark ? ui.Brightness.dark : ui.Brightness.light;
+    if (configuration.platformBrightness != brightness) {
+      configuration = configuration.copyWith(platformBrightness: brightness);
       invokeOnPlatformConfigurationChanged();
       invokeOnPlatformBrightnessChanged();
     }
@@ -1231,45 +1235,52 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
   @override
   String? get systemFontFamily => configuration.systemFontFamily;
 
+  /// Whether high contrast mode is enabled by the platform.
+  ///
+  /// Used statically by [computeAccessibilityFeatures] to create the initial
+  /// [configuration] object.
+  static bool _isHighContrastEnabled = false;
+
   /// Updates [_highContrast] and invokes [onHighContrastModeChanged]
   /// callback if [_highContrast] changed.
-  void _updateHighContrast(bool value) {
-    if (configuration.accessibilityFeatures.highContrast != value) {
+  void _updateHighContrast(bool enabled) {
+    _isHighContrastEnabled = enabled;
+    if (configuration.accessibilityFeatures.highContrast != enabled) {
       final original = configuration.accessibilityFeatures as EngineAccessibilityFeatures;
       configuration = configuration.copyWith(
-        accessibilityFeatures: original.copyWith(highContrast: value),
+        accessibilityFeatures: original.copyWith(highContrast: enabled),
       );
       invokeOnPlatformConfigurationChanged();
+      invokeOnAccessibilityFeaturesChanged();
     }
   }
 
-  /// Reference to css media query that indicates the user theme preference on the web.
-  final DomMediaQueryList _brightnessMediaQuery = domWindow.matchMedia(
-    '(prefers-color-scheme: dark)',
-  );
-
-  /// A callback that is invoked whenever [_brightnessMediaQuery] changes value.
+  /// Updates [AccessibilityFeatures] `reduceMotion` and `disableAnimations` to
+  /// [reduced], and notifies the framework of the change.
   ///
-  /// Updates the [_platformBrightness] with the new user preference.
-  DomEventListener? _brightnessMediaQueryListener;
-
-  /// Set the callback function for listening changes in [_brightnessMediaQuery] value.
-  void _addBrightnessMediaQueryListener() {
-    _updatePlatformBrightness(
-      _brightnessMediaQuery.matches ? ui.Brightness.dark : ui.Brightness.light,
-    );
-
-    _brightnessMediaQueryListener = (DomEvent event) {
-      final mqEvent = event as DomMediaQueryListEvent;
-      _updatePlatformBrightness(mqEvent.matches! ? ui.Brightness.dark : ui.Brightness.light);
-    }.toJS;
-    _brightnessMediaQuery.addListener(_brightnessMediaQueryListener);
+  /// The web doesn't seem to distinguish between "reduced motion" and "disable
+  /// animations", so we set both at the same time in this update.
+  void _updateReducedMotion(bool reduced) {
+    if (configuration.accessibilityFeatures.reduceMotion != reduced) {
+      final original = configuration.accessibilityFeatures as EngineAccessibilityFeatures;
+      configuration = configuration.copyWith(
+        accessibilityFeatures: original.copyWith(
+          // There's no distinction on the web between "reduceMotion" and
+          // "disableAnimations", so we set both at the same time.
+          reduceMotion: reduced,
+          disableAnimations: reduced,
+        ),
+      );
+      invokeOnPlatformConfigurationChanged();
+      invokeOnAccessibilityFeaturesChanged();
+    }
   }
 
-  /// Remove the callback function for listening changes in [_brightnessMediaQuery] value.
-  void _removeBrightnessMediaQueryListener() {
-    _brightnessMediaQuery.removeListener(_brightnessMediaQueryListener);
-    _brightnessMediaQueryListener = null;
+  // Configures the [_mediaQueries] object.
+  void _registerMediaQueryListeners() {
+    mediaQueries.addListener(MediaQueryManager.DARK_MODE, onMatch: _updatePlatformBrightness);
+    mediaQueries.addListener(MediaQueryManager.REDUCED_MOTION, onMatch: _updateReducedMotion);
+    mediaQueries.addListener(MediaQueryManager.FORCED_COLORS, onMatch: _updateHighContrast);
   }
 
   /// A callback that is invoked whenever [platformBrightness] changes value.

engine/src/flutter/lib/web_ui/lib/src/engine/platform_dispatcher/media_query_manager.dart

@@ -0,0 +1,142 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:js_interop';
+
+import 'package:meta/meta.dart';
+
+import '../../engine.dart';
+
+/// The type of a function that handles whether a media query matches or not.
+typedef MediaQueryMatchHandler = void Function(bool matches);
+
+/// Manages all the [_MediaQueryListeners]s attached to media query tests.
+///
+/// This is used by the [EnginePlatformDispatcher] to detect some properties
+/// from the browser (light/dark mode or reduced motion)
+class MediaQueryManager {
+  /// Detects dark mode.
+  static const DARK_MODE = '(prefers-color-scheme: dark)';
+
+  /// Detects forced colors (high contrast).
+  static const FORCED_COLORS = '(forced-colors: active)';
+
+  /// Detects reduced motion.
+  static const REDUCED_MOTION = '(prefers-reduced-motion: reduce)';
+
+  final Map<String, _MediaQueryListeners> _listeners = {};
+
+  /// Used in tests to inject mock objects that can dispatch arbitrary
+  /// [DomMediaQueryListEvent]s.
+  ///
+  /// When this is not set, [domWindow.matchMedia] is used by default.
+  ///
+  /// This is used to ensure the connection of the [MediaQueryManager] with
+  /// incoming events from the browser.
+  @visibleForTesting
+  MediaQueryBuilder? debugOverrideMediaQueryBuilder;
+
+  /// Used in tests to trigger [event] on all the registered listeners of
+  /// [mediaQueryString].
+  ///
+  /// This is used to test the connection between the [EnginePlatformDispatcher]
+  /// and the [MediaQueryManager], without the browser having to dispatch real
+  /// events.
+  @visibleForTesting
+  void debugTriggerListener(String mediaQueryString, {required DomMediaQueryListEvent event}) {
+    final _MediaQueryListeners? listeners = _listeners[mediaQueryString];
+    assert(listeners != null, 'Cannot find listeners for $mediaQueryString');
+    listeners!.trigger(event);
+  }
+
+  // Creates a [DomMediaQueryList] object from a [mediaQueryString].
+  //
+  // This uses [debugOverrideMediaQueryBuilder] when set for tests.
+  // In production, this uses [domWindow.matchMedia].
+  DomEventTarget _createMediaQuery(String mediaQueryString) {
+    if (debugOverrideMediaQueryBuilder != null) {
+      return debugOverrideMediaQueryBuilder!(mediaQueryString);
+    }
+    return domWindow.matchMedia(mediaQueryString);
+  }
+
+  /// Adds a listener for [mediaQueryString], and triggers [onMatch] as needed.
+  ///
+  /// This function calls [onMatch] synchronously with the initial value of the
+  /// match, and then, through an event listener, every time the value changes.
+  void addListener(String mediaQueryString, {required MediaQueryMatchHandler onMatch}) {
+    // Wrap `onMatch` in a [DomEventListener]
+    final DomEventListener mediaQueryListener = (DomEvent event) {
+      final mqEvent = event as DomMediaQueryListEvent;
+      onMatch(mqEvent.matches ?? false);
+    }.toJS;
+
+    // Attach the listener
+    final _MediaQueryListeners listeners = _listeners.putIfAbsent(mediaQueryString, () {
+      // Create a proper media query object
+      final DomEventTarget mediaQuery = _createMediaQuery(mediaQueryString);
+      return _MediaQueryListeners(mediaQuery);
+    })..addListener(mediaQueryListener);
+
+    // Call onMatch with the immediate value of the media query
+    onMatch(listeners.matches);
+  }
+
+  /// Detaches all registered listeners.
+  void detachAll() {
+    final Iterable<String> mediaQueryStrings = _listeners.keys.toList();
+    mediaQueryStrings.forEach(_removeListeners);
+  }
+
+  /// Detaches all listeners for [mediaQueryString].
+  void _removeListeners(String mediaQueryString) {
+    final _MediaQueryListeners? listeners = _listeners.remove(mediaQueryString);
+    listeners?.detachAll();
+  }
+}
+
+/// Groups the listeners for a media query
+class _MediaQueryListeners {
+  _MediaQueryListeners(this._mediaQuery);
+
+  final DomEventTarget _mediaQuery;
+  final List<DomEventListener> _listeners = [];
+
+  // Returns whether or not the listened [DomMediaQueryList] matches now.
+  bool get matches {
+    // On tests we inject something that is a raw DomEventTarget so we can
+    // dispatch events from it directly, so we check for that case now.
+    if (!_mediaQuery.isA<DomMediaQueryList>()) {
+      return false;
+    }
+    return (_mediaQuery as DomMediaQueryList).matches;
+  }
+
+  void addListener(DomEventListener listener) {
+    _mediaQuery.addEventListener('change', listener);
+    _listeners.add(listener);
+  }
+
+  void detachAll() {
+    _listeners.forEach(_removeListener);
+    _listeners.clear();
+  }
+
+  void _removeListener(DomEventListener listener) {
+    _mediaQuery.removeEventListener('change', listener);
+  }
+
+  /// Triggers [event] on all registered listeners.
+  @visibleForTesting
+  void trigger(DomMediaQueryListEvent event) {
+    for (final JSFunction listener in _listeners) {
+      // This is directly calling the registered JSFunction with [event].
+      listener.callAsFunction(null, event);
+    }
+  }
+}
+
+/// A function to create a fake MediaQuery event from a String.
+@visibleForTesting
+typedef MediaQueryBuilder = DomEventTarget Function(String mediaQuery);

…web_ui/lib/src/engine/high_contrast.dart …tcher/system_color_palette_detector.dartengine/src/flutter/lib/web_ui/lib/src/engine/high_contrast.dart renamed to engine/src/flutter/lib/web_ui/lib/src/engine/platform_dispatcher/system_color_palette_detector.dart engine/src/flutter/lib/web_ui/lib/src/engine/high_contrast.dart renamed to engine/src/flutter/lib/web_ui/lib/src/engine/platform_dispatcher/system_color_palette_detector.dart

@@ -1,54 +1,9 @@
 // Copyright 2013 The Flutter Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
-import 'dart:js_interop';
-
 import 'package:ui/ui.dart' as ui;
 
-import 'dom.dart';
-
-/// Signature of functions added as a listener to high contrast changes
-typedef HighContrastListener = void Function(bool enabled);
-
-/// Determines if high contrast is enabled using media query 'forced-colors: active' for Windows
-class HighContrastSupport {
-  static HighContrastSupport instance = HighContrastSupport();
-  static const String _highContrastMediaQueryString = '(forced-colors: active)';
-
-  final List<HighContrastListener> _listeners = <HighContrastListener>[];
-
-  /// Reference to css media query that indicates whether high contrast is on.
-  final DomMediaQueryList _highContrastMediaQuery = domWindow.matchMedia(
-    _highContrastMediaQueryString,
-  );
-  late final DomEventListener _onHighContrastChangeListener = _onHighContrastChange.toJS;
-
-  bool get isHighContrastEnabled => _highContrastMediaQuery.matches;
-
-  /// Adds function to the list of listeners on high contrast changes
-  void addListener(HighContrastListener listener) {
-    if (_listeners.isEmpty) {
-      _highContrastMediaQuery.addListener(_onHighContrastChangeListener);
-    }
-    _listeners.add(listener);
-  }
-
-  /// Removes function from the list of listeners on high contrast changes
-  void removeListener(HighContrastListener listener) {
-    _listeners.remove(listener);
-    if (_listeners.isEmpty) {
-      _highContrastMediaQuery.removeListener(_onHighContrastChangeListener);
-    }
-  }
-
-  void _onHighContrastChange(DomEvent event) {
-    final mqEvent = event as DomMediaQueryListEvent;
-    final bool isHighContrastEnabled = mqEvent.matches!;
-    for (final HighContrastListener listener in _listeners) {
-      listener(isHighContrastEnabled);
-    }
-  }
-}
+import '../dom.dart';
 
 const List<String> systemColorNames = <String>[
   'AccentColor',