image: Respect iOS "Auto-Play Animated Images" setting on iOS 18+

lib/model/binding.dart

@@ -262,6 +262,17 @@ class IosDeviceInfo extends BaseDeviceInfo {
   /// See: https://developer.apple.com/documentation/uikit/uidevice/1620043-systemversion
   final String systemVersion;
 
+  /// The major component of the iOS version, from [systemVersion].
+  ///
+  /// Returns null if [systemVersion] can't be parsed.
+  ///
+  /// Callers should write e.g. `// TODO(ios-18)`
+  /// so we remember to simplify our code as our minimum iOS version advances.
+  // TODO(log) if can't be parsed
+  int? get majorVersion =>
+    // [IosDeviceInfo.systemVersion] is a dotted string, e.g. "17.5.1".
+    int.tryParse(systemVersion.split('.').first, radix: 10);
+
   const IosDeviceInfo({required this.systemVersion});
 }
 

lib/widgets/image.dart

@@ -1,8 +1,8 @@
-import 'package:flutter/foundation.dart';
 import 'package:flutter/widgets.dart';
 
 import '../api/core.dart';
 import '../api/model/initial_snapshot.dart';
+import '../model/binding.dart';
 import '../model/content.dart';
 import 'store.dart';
 
@@ -137,14 +137,27 @@ enum ImageAnimationMode {
         //   https://github.com/zulip/zulip-flutter/pull/410#discussion_r1408522293
         if (MediaQuery.disableAnimationsOf(context)) return false;
 
-        if (
-          defaultTargetPlatform == TargetPlatform.iOS
-          // TODO(#1924) On iOS 17+ (new in 2023), there's a more closely
-          //   relevant setting than "reduce motion". It's called "auto-play
-          //   animated images"; we should use that once Flutter exposes it.
-          && WidgetsBinding.instance.platformDispatcher.accessibilityFeatures.reduceMotion
-        ) {
-          return false;
+        final deviceInfo = ZulipBinding.instance.syncDeviceInfo;
+        if (deviceInfo case IosDeviceInfo(:final majorVersion)) {
+          final accessibilityFeatures =
+            WidgetsBinding.instance.platformDispatcher.accessibilityFeatures;
+
+          if (majorVersion == null || majorVersion < 18) {
+            // [AccessibilityFeatures.autoPlayAnimatedImages] reflects iOS's
+            // Accessibility > Motion > "Auto-Play Animated Images" on iOS 18+.
+            // The setting was new in iOS 17:
+            //   https://support.apple.com/guide/iphone/reduce-onscreen-motion-iph0b691d3ed/17.0/ios/17.0
+            // but the API for *reading* it is iOS 18+:
+            //   https://developer.apple.com/documentation/accessibility/accessibilitysettings/animatedimagesenabled
+            // Flutter's behavior pre-18 is to always return true:
+            //   https://github.com/flutter/flutter/blob/0841ce10a/engine/src/flutter/shell/platform/darwin/ios/framework/Source/AccessibilityFeatures.swift#L178-L186
+            // so we do our own version check to fall back to the older
+            // "Reduce motion" setting.
+            // TODO(ios-18) simplify away
+            return !accessibilityFeatures.reduceMotion;
+          }
+
+          return accessibilityFeatures.autoPlayAnimatedImages;
         }
 
         return true;

test/model/binding_checks.dart

@@ -0,0 +1,6 @@
+import 'package:checks/checks.dart';
+import 'package:zulip/model/binding.dart';
+
+extension IosDeviceInfoChecks on Subject<IosDeviceInfo> {
+  Subject<int?> get majorVersion => has((x) => x.majorVersion, 'majorVersion');
+}

test/model/binding_test.dart

@@ -0,0 +1,28 @@
+import 'package:checks/checks.dart';
+import 'package:test/scaffolding.dart';
+import 'package:zulip/model/binding.dart';
+
+import 'binding.dart';
+import 'binding_checks.dart';
+
+void main() {
+  TestZulipBinding.ensureInitialized();
+
+  group('IosDeviceInfo.majorVersion', () {
+    test('typical', () {
+      check(const IosDeviceInfo(systemVersion: '17.5.1')).majorVersion.equals(17);
+    });
+
+    test('two-part', () {
+      check(const IosDeviceInfo(systemVersion: '18')).majorVersion.equals(18);
+    });
+
+    test('unparseable', () {
+      check(const IosDeviceInfo(systemVersion: 'garbage')).majorVersion.isNull();
+    });
+
+    test('unparseable (empty string)', () {
+      check(const IosDeviceInfo(systemVersion: '')).majorVersion.isNull();
+    });
+  });
+}

test/widgets/image_test.dart

@@ -1,8 +1,10 @@
 import 'package:checks/checks.dart';
+import 'package:flutter/foundation.dart';
 import 'package:flutter/widgets.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:zulip/api/core.dart';
 import 'package:zulip/api/model/initial_snapshot.dart';
+import 'package:zulip/model/binding.dart';
 import 'package:zulip/model/content.dart';
 import 'package:zulip/model/store.dart';
 import 'package:zulip/widgets/image.dart';
@@ -197,4 +199,114 @@ void main() {
         .equals('https://chat.example/user_uploads/thumbnail/1/2/a/pic.jpg/840x560.webp?x=y#abc');
     });
   });
+
+  group('ImageAnimationMode.shouldAnimate', () {
+    Future<void> doCheck(WidgetTester tester, {
+      required TargetPlatform platform,
+      BaseDeviceInfo? deviceInfo,
+      bool mediaQueryDisableAnimations = false,
+      bool reduceMotion = false,
+      bool autoPlayAnimatedImages = true,
+      required ImageAnimationMode mode,
+      required bool expected,
+    }) async {
+      addTearDown(testBinding.reset);
+      if (deviceInfo != null) testBinding.deviceInfoResult = deviceInfo;
+      tester.platformDispatcher.accessibilityFeaturesTestValue =
+        FakeAccessibilityFeatures(
+          reduceMotion: reduceMotion,
+          autoPlayAnimatedImages: autoPlayAnimatedImages);
+      addTearDown(tester.platformDispatcher.clearAccessibilityFeaturesTestValue);
+
+      debugDefaultTargetPlatformOverride = platform;
+      try {
+        await tester.pumpWidget(MediaQuery(
+          data: MediaQueryData(disableAnimations: mediaQueryDisableAnimations),
+          child: const Placeholder()));
+        final context = tester.element(find.byType(Placeholder));
+        check(mode.shouldAnimate(context)).equals(expected);
+      } finally {
+        debugDefaultTargetPlatformOverride = null;
+      }
+    }
+
+    testWidgets('animateAlways gives true regardless of device settings', (tester) async {
+      await doCheck(tester, mode: ImageAnimationMode.animateAlways, expected: true,
+        platform: .iOS,
+        deviceInfo: const IosDeviceInfo(systemVersion: '18.0'),
+        mediaQueryDisableAnimations: true, reduceMotion: true,
+        autoPlayAnimatedImages: false);
+    });
+
+    testWidgets('animateNever gives false regardless of device settings', (tester) async {
+      await doCheck(tester, mode: ImageAnimationMode.animateNever, expected: false,
+        platform: .iOS);
+    });
+
+    group('animateConditionally', () {
+      const mode = ImageAnimationMode.animateConditionally;
+
+      testWidgets('MediaQuery.disableAnimations suppresses animation', (tester) async {
+        await doCheck(tester, mode: mode, expected: false,
+          platform: .android,
+          mediaQueryDisableAnimations: true);
+      });
+
+      testWidgets('Android ignores reduceMotion and autoPlayAnimatedImages', (tester) async {
+        await doCheck(tester, mode: mode, expected: true,
+          platform: .android,
+          reduceMotion: true, autoPlayAnimatedImages: false);
+      });
+
+      group('iOS 18+ (Flutter reports Auto-Play Animated Images)', () {
+        const ios18 = IosDeviceInfo(systemVersion: '18.0');
+
+        testWidgets('animate when auto-play on and reduce-motion off', (tester) async {
+          await doCheck(tester, mode: mode, expected: true,
+            platform: .iOS, deviceInfo: ios18,
+            reduceMotion: false, autoPlayAnimatedImages: true);
+        });
+
+        testWidgets('no animate when auto-play off', (tester) async {
+          await doCheck(tester, mode: mode, expected: false,
+            platform: .iOS, deviceInfo: ios18,
+            reduceMotion: false, autoPlayAnimatedImages: false);
+        });
+
+        testWidgets('animate when auto-play on even if reduce-motion on', (tester) async {
+          // On iOS 18+, [autoPlayAnimatedImages] reflects the user's explicit
+          // choice; respect it over the broader [reduceMotion] preference.
+          await doCheck(tester, mode: mode, expected: true,
+            platform: .iOS, deviceInfo: ios18,
+            reduceMotion: true, autoPlayAnimatedImages: true);
+        });
+      });
+
+      group('iOS <18 (Flutter cannot read Auto-Play Animated Images)', () {
+        // Flutter always reports autoPlayAnimatedImages as true on iOS <18,
+        // regardless of the OS setting.
+
+        testWidgets('iOS 17: no animate when reduce-motion on', (tester) async {
+          await doCheck(tester, mode: mode, expected: false,
+            platform: .iOS,
+            deviceInfo: const IosDeviceInfo(systemVersion: '17.5'),
+            reduceMotion: true, autoPlayAnimatedImages: true);
+        });
+
+        testWidgets('iOS 17: animate when reduce-motion off', (tester) async {
+          await doCheck(tester, mode: mode, expected: true,
+            platform: .iOS,
+            deviceInfo: const IosDeviceInfo(systemVersion: '17.5'),
+            reduceMotion: false, autoPlayAnimatedImages: true);
+        });
+
+        testWidgets('unparseable systemVersion: fall back to reduce-motion', (tester) async {
+          await doCheck(tester, mode: mode, expected: false,
+            platform: .iOS,
+            deviceInfo: const IosDeviceInfo(systemVersion: 'garbage'),
+            reduceMotion: true, autoPlayAnimatedImages: true);
+        });
+      });
+    });
+  });
 }