color: Add withFadedAlpha helper

This adds a new helper on `ColorExtension` following a similar
naming and documentation style as other method like `withValues`. The
motivation for this is to support a faded effect applies to colors
that are possibly already transparent (i.e. have a non-one alpha
channel value).

Signed-off-by: Zixuan James Li <[email protected]>

Author: PIG208

lib/widgets/color.dart

@@ -38,4 +38,13 @@ extension ColorExtension on Color {
            ((g * 255.0).round() & 0xff) << 8 |
            ((b * 255.0).round() & 0xff) << 0;
   }
+
+  /// Makes a copy of this color with the alpha channel multiplied by `factor`.
+  ///
+  /// `factor` must not be less than 0 or greater than 1.
+  Color withFadedAlpha(double factor) {
+    assert(factor >= 0);
+    assert(factor <= 1);
+    return withValues(alpha: a * factor);
+  }
 }

test/widgets/color_test.dart

@@ -1,6 +1,7 @@
 import 'dart:ui';
 
 import 'package:checks/checks.dart';
+import 'package:flutter_checks/flutter_checks.dart';
 import 'package:test/scaffolding.dart';
 import 'package:zulip/widgets/color.dart';
 
@@ -14,5 +15,15 @@ void main() {
         check(Color(testCase).argbInt).equals(testCase);
       }
     });
+
+    test('withFadedAlpha smoke', () {
+      const color = Color.fromRGBO(100, 200, 100, 0.5);
+
+      check(color.withFadedAlpha(0.5))
+        .isSameColorAs(color.withValues(alpha: 0.25));
+
+      check(() => color.withFadedAlpha(1.1)).throws<AssertionError>();
+      check(() => color.withFadedAlpha(-0.1)).throws<AssertionError>();
+    });
   });
 }