Add support for fill, weight, grade, and optical size to Icon (#106896)

* wip

* update documentation

* x

* remove trailing spaces

* x

* remove useless CupertinoIconThemeData copyWith override

* add tests

* remove trailing spaces

* fix isConcrete

* x

* x

* x

* remove trailing spaces

* tweak docs

* mention that font filenames often indicate the supported axes

* add back cupertino IconThemeData copyWith

* update copyWith

Author: guidezpl

packages/flutter/lib/src/cupertino/icon_theme_data.dart

@@ -10,13 +10,14 @@ import 'colors.dart';
 /// using [IconTheme.of].
 class CupertinoIconThemeData extends IconThemeData with Diagnosticable {
   /// Creates a [CupertinoIconThemeData].
-  ///
-  /// The opacity applies to both explicit and default icon colors. The value
-  /// is clamped between 0.0 and 1.0.
   const CupertinoIconThemeData({
+    super.size,
+    super.fill,
+    super.weight,
+    super.grade,
+    super.opticalSize,
     super.color,
     super.opacity,
-    super.size,
     super.shadows,
   });
 
@@ -30,11 +31,24 @@ class CupertinoIconThemeData extends IconThemeData with Diagnosticable {
   /// Creates a copy of this icon theme but with the given fields replaced with
   /// the new values.
   @override
-  CupertinoIconThemeData copyWith({ Color? color, double? opacity, double? size, List<Shadow>? shadows }) {
+  CupertinoIconThemeData copyWith({
+    double? size,
+    double? fill,
+    double? weight,
+    double? grade,
+    double? opticalSize,
+    Color? color,
+    double? opacity,
+    List<Shadow>? shadows,
+  }) {
     return CupertinoIconThemeData(
+      size: size ?? this.size,
+      fill: fill ?? this.fill,
+      weight: weight ?? this.weight,
+      grade: grade ?? this.grade,
+      opticalSize: opticalSize ?? this.opticalSize,
       color: color ?? this.color,
       opacity: opacity ?? this.opacity,
-      size: size ?? this.size,
       shadows: shadows ?? this.shadows,
     );
   }

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

@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+import 'dart:ui';
+
 import 'package:flutter/foundation.dart';
 import 'package:flutter/rendering.dart';
 
@@ -61,22 +63,26 @@ import 'icon_theme_data.dart';
 /// See also:
 ///
 ///  * [IconButton], for interactive icons.
-///  * [Icons], the library of Material Icons available for use with this class.
+///  * [Icons], for the list of available Material Icons for use with this class.
 ///  * [IconTheme], which provides ambient configuration for icons.
 ///  * [ImageIcon], for showing icons from [AssetImage]s or other [ImageProvider]s.
 class Icon extends StatelessWidget {
   /// Creates an icon.
-  ///
-  /// The [size] and [color] default to the value given by the current [IconTheme].
   const Icon(
     this.icon, {
     super.key,
     this.size,
+    this.fill,
+    this.weight,
+    this.grade,
+    this.opticalSize,
     this.color,
+    this.shadows,
     this.semanticLabel,
     this.textDirection,
-    this.shadows,
-  });
+  }) : assert(fill == null || (0.0 <= fill && fill <= 1.0)),
+       assert(weight == null || (0.0 < weight)),
+       assert(opticalSize == null || (0.0 < opticalSize));
 
   /// The icon to display. The available icons are described in [Icons].
   ///
@@ -88,33 +94,95 @@ class Icon extends StatelessWidget {
   ///
   /// Icons occupy a square with width and height equal to size.
   ///
-  /// Defaults to the current [IconTheme] size, if any. If there is no
-  /// [IconTheme], or it does not specify an explicit size, then it defaults to
-  /// 24.0.
+  /// Defaults to the nearest [IconTheme]'s [IconThemeData.size].
   ///
   /// If this [Icon] is being placed inside an [IconButton], then use
   /// [IconButton.iconSize] instead, so that the [IconButton] can make the splash
   /// area the appropriate size as well. The [IconButton] uses an [IconTheme] to
   /// pass down the size to the [Icon].
   final double? size;
 
-  /// The color to use when drawing the icon.
+  /// The fill for drawing the icon.
   ///
-  /// Defaults to the current [IconTheme] color, if any.
+  /// Requires the underlying icon font to support the `FILL` [FontVariation]
+  /// axis, otherwise has no effect. Variable font filenames often indicate
+  /// the supported axes. Must be between 0.0 (unfilled) and 1.0 (filled),
+  /// inclusive.
   ///
-  /// The color (whether specified explicitly here or obtained from the
-  /// [IconTheme]) will be further adjusted by the opacity of the current
-  /// [IconTheme], if any.
+  /// Can be used to convey a state transition for animation or interaction.
+  ///
+  /// Defaults to nearest [IconTheme]'s [IconThemeData.fill].
+  ///
+  /// See also:
+  ///  * [weight], for controlling stroke weight.
+  ///  * [grade], for controlling stroke weight in a more granular way.
+  ///  * [opticalSize], for controlling optical size.
+  final double? fill;
+
+  /// The stroke weight for drawing the icon.
+  ///
+  /// Requires the underlying icon font to support the `wght` [FontVariation]
+  /// axis, otherwise has no effect. Variable font filenames often indicate
+  /// the supported axes. Must be greater than 0.
+  ///
+  /// Defaults to nearest [IconTheme]'s [IconThemeData.weight].
+  ///
+  /// See also:
+  ///  * [fill], for controlling fill.
+  ///  * [grade], for controlling stroke weight in a more granular way.
+  ///  * [opticalSize], for controlling optical size.
+  ///  * https://fonts.google.com/knowledge/glossary/weight_axis
+  final double? weight;
+
+  /// The grade (granular stroke weight) for drawing the icon.
+  ///
+  /// Requires the underlying icon font to support the `GRAD` [FontVariation]
+  /// axis, otherwise has no effect. Variable font filenames often indicate
+  /// the supported axes. Can be negative.
+  ///
+  /// Grade and [weight] both affect a symbol's stroke weight (thickness), but
+  /// grade has a smaller impact on the size of the symbol.
+  ///
+  /// Grade is also available in some text fonts. One can match grade levels
+  /// between text and symbols for a harmonious visual effect. For example, if
+  /// the text font has a -25 grade value, the symbols can match it with a
+  /// suitable value, say -25.
+  ///
+  /// Defaults to nearest [IconTheme]'s [IconThemeData.grade].
+  ///
+  /// See also:
+  ///  * [fill], for controlling fill.
+  ///  * [weight], for controlling stroke weight in a less granular way.
+  ///  * [opticalSize], for controlling optical size.
+  ///  * https://fonts.google.com/knowledge/glossary/grade_axis
+  final double? grade;
+
+  /// The optical size for drawing the icon.
+  ///
+  /// Requires the underlying icon font to support the `opsz` [FontVariation]
+  /// axis, otherwise has no effect. Variable font filenames often indicate
+  /// the supported axes. Must be greater than 0.
+  ///
+  /// For an icon to look the same at different sizes, the stroke weight
+  /// (thickness) must change as the icon size scales. Optical size offers a way
+  /// to automatically adjust the stroke weight as icon size changes.
+  ///
+  /// Defaults to nearest [IconTheme]'s [IconThemeData.opticalSize].
   ///
-  /// In material apps, if there is a [Theme] without any [IconTheme]s
-  /// specified, icon colors default to white if the theme is dark
-  /// and black if the theme is light.
+  /// See also:
+  ///  * [fill], for controlling fill.
+  ///  * [weight], for controlling stroke weight.
+  ///  * [grade], for controlling stroke weight in a more granular way.
+  ///  * https://fonts.google.com/knowledge/glossary/optical_size_axis
+  final double? opticalSize;
+
+  /// The color to use when drawing the icon.
   ///
-  /// If no [IconTheme] and no [Theme] is specified, icons will default to
-  /// black.
+  /// Defaults to the nearest [IconTheme]'s [IconThemeData.color].
   ///
-  /// See [Theme] to set the current theme and [ThemeData.brightness]
-  /// for setting the current theme's brightness.
+  /// The color (whether specified explicitly here or obtained from the
+  /// [IconTheme]) will be further adjusted by the nearest [IconTheme]'s
+  /// [IconThemeData.opacity].
   ///
   /// {@tool snippet}
   /// Typically, a Material Design color will be used, as follows:
@@ -128,6 +196,17 @@ class Icon extends StatelessWidget {
   /// {@end-tool}
   final Color? color;
 
+  /// A list of [Shadow]s that will be painted underneath the icon.
+  ///
+  /// Multiple shadows are supported to replicate lighting from multiple light
+  /// sources.
+  ///
+  /// Shadows must be in the same order for [Icon] to be considered as
+  /// equivalent as order produces differing transparency.
+  ///
+  /// Defaults to the nearest [IconTheme]'s [IconThemeData.shadows].
+  final List<Shadow>? shadows;
+
   /// Semantic label for the icon.
   ///
   /// Announced in accessibility modes (e.g TalkBack/VoiceOver).
@@ -152,15 +231,6 @@ class Icon extends StatelessWidget {
   /// specified, either directly using this property or using [Directionality].
   final TextDirection? textDirection;
 
-  /// A list of [Shadow]s that will be painted underneath the icon.
-  ///
-  /// Multiple shadows are supported to replicate lighting from multiple light
-  /// sources.
-  ///
-  /// Shadows must be in the same order for [Icon] to be considered as
-  /// equivalent as order produces differing transparency.
-  final List<Shadow>? shadows;
-
   @override
   Widget build(BuildContext context) {
     assert(this.textDirection != null || debugCheckHasDirectionality(context));
@@ -191,6 +261,12 @@ class Icon extends StatelessWidget {
       text: TextSpan(
         text: String.fromCharCode(icon!.codePoint),
         style: TextStyle(
+          fontVariations: <FontVariation>[
+            if (fill != null) FontVariation('FILL', fill!),
+            if (weight != null) FontVariation('wght', weight!),
+            if (grade != null) FontVariation('GRAD', grade!),
+            if (opticalSize != null) FontVariation('opsz', opticalSize!),
+          ],
           inherit: false,
           color: iconColor,
           fontSize: iconSize,
@@ -235,7 +311,13 @@ class Icon extends StatelessWidget {
     super.debugFillProperties(properties);
     properties.add(IconDataProperty('icon', icon, ifNull: '<empty>', showName: false));
     properties.add(DoubleProperty('size', size, defaultValue: null));
+    properties.add(DoubleProperty('fill', fill, defaultValue: null));
+    properties.add(DoubleProperty('weight', weight, defaultValue: null));
+    properties.add(DoubleProperty('grade', grade, defaultValue: null));
+    properties.add(DoubleProperty('opticalSize', opticalSize, defaultValue: null));
     properties.add(ColorProperty('color', color, defaultValue: null));
     properties.add(IterableProperty<Shadow>('shadows', shadows, defaultValue: null));
+    properties.add(StringProperty('semanticLabel', semanticLabel, defaultValue: null));
+    properties.add(EnumProperty<TextDirection>('textDirection', textDirection, defaultValue: null));
   }
 }

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

@@ -9,12 +9,11 @@ import 'framework.dart';
 import 'icon_theme_data.dart';
 import 'inherited_theme.dart';
 
-/// Controls the default color, opacity, and size of icons in a widget subtree.
+/// Controls the default properties of icons in a widget subtree.
 ///
 /// The icon theme is honored by [Icon] and [ImageIcon] widgets.
 class IconTheme extends InheritedTheme {
-  /// Creates an icon theme that controls the color, opacity, and size of
-  /// descendant widgets.
+  /// Creates an icon theme that controls properties of descendant widgets.
   ///
   /// Both [data] and [child] arguments must not be null.
   const IconTheme({
@@ -24,7 +23,7 @@ class IconTheme extends InheritedTheme {
   }) : assert(data != null),
        assert(child != null);
 
-  /// Creates an icon theme that controls the color, opacity, and size of
+  /// Creates an icon theme that controls the properties of
   /// descendant widgets, and merges in the current icon theme, if any.
   ///
   /// The [data] and [child] arguments must not be null.
@@ -44,7 +43,7 @@ class IconTheme extends InheritedTheme {
     );
   }
 
-  /// The color, opacity, and size to use for icons in this subtree.
+  /// The set of properties to use for icons in this subtree.
   final IconThemeData data;
 
   /// The data from the closest instance of this class that encloses the given
@@ -72,6 +71,10 @@ class IconTheme extends InheritedTheme {
       ? iconThemeData
       : iconThemeData.copyWith(
         size: iconThemeData.size ?? const IconThemeData.fallback().size,
+        fill: iconThemeData.fill ?? const IconThemeData.fallback().fill,
+        weight: iconThemeData.weight ?? const IconThemeData.fallback().weight,
+        grade: iconThemeData.grade ?? const IconThemeData.fallback().grade,
+        opticalSize: iconThemeData.opticalSize ?? const IconThemeData.fallback().opticalSize,
         color: iconThemeData.color ?? const IconThemeData.fallback().color,
         opacity: iconThemeData.opacity ?? const IconThemeData.fallback().opacity,
         shadows: iconThemeData.shadows ?? const IconThemeData.fallback().shadows,