[flutter_svg] feat: Expose the colorMapper property in SvgPicture (flutter#9043)

## Description

This pull request exposes the existing `colorMapper` functionality in the `flutter_svg` package, allowing developers to customize SVG colors during parsing. 

## Related Issue

- flutter/flutter#158634

## Motivation

The `colorMapper` functionality was already present within the `flutter_svg` package but was not directly accessible through the `SvgPicture` constructors. By exposing this property, developers gain a powerful and flexible way to dynamically modify the colors of SVG assets based on custom logic. This can be useful for various scenarios, such as theming or branding.

## Example Usage

```dart
import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';

const String svgString = '''
<svg viewBox="0 0 100 100">
  <rect width="50" height="50" fill="#FF0000" />
  <circle cx="75" cy="75" r="25" fill="#00FF00" />
</svg>
''';

class MyColorMapper extends ColorMapper {
  const MyColorMapper();

  @OverRide
  Color substitute(
      String? id, String elementName, String attributeName, Color color) {
    if (color == const Color(0xFFFF0000)) {
      return Colors.blue;
    }
    if (color == const Color(0xFF00FF00)) {
      return Colors.yellow;
    }
    return color;
  }
}

void main() {
  runApp(MaterialApp(
    home: Scaffold(
      body: Center(
        child: SvgPicture.string(
          svgString,
          width: 200,
          height: 200,
          colorMapper: const MyColorMapper(),
        ),
      ),
    ),
  ));
}
```

Author: ricardodalarme

AUTHORS

@@ -78,3 +78,4 @@ Taskulu LDA <contributions@taskulu.com>
 Alexander Rabin <alex.rabin@sentracam.com>
 LinXunFeng <linxunfeng@yeah.net>
 Hashir Shoaib <hashirshoaeb@gmail.com>
+Ricardo Dalarme <ricardodalarme@outlook.com>

third_party/packages/flutter_svg/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.1.0
+
+* Exposes `colorMapper` in `SvgPicture` constructors.
+
 ## 2.0.17
 
 * Implement errorBuilder callback

third_party/packages/flutter_svg/README.md

@@ -33,6 +33,53 @@ final Widget svgIcon = SvgPicture.asset(
 );
 ```
 
+For more advanced color manipulation, you can use the `colorMapper` property.
+This allows you to define a custom mapping function that will be called for
+every color encountered during SVG parsing, enabling you to substitute colors
+based on various criteria like the color value itself, the element name, or the
+attribute name.
+
+To use this feature, you need to create a class that extends `ColorMapper` and
+override the `substitute` method.
+
+Here's an example of how to implement a `ColorMapper` to replace specific colors in an SVG:
+
+<?code-excerpt "example/lib/readme_excerpts.dart (ColorMapper)"?>
+```dart
+class _MyColorMapper extends ColorMapper {
+  const _MyColorMapper();
+
+  @override
+  Color substitute(
+    String? id,
+    String elementName,
+    String attributeName,
+    Color color,
+  ) {
+    if (color == const Color(0xFFFF0000)) {
+      return Colors.blue;
+    }
+    if (color == const Color(0xFF00FF00)) {
+      return Colors.yellow;
+    }
+    return color;
+  }
+}
+// ···
+  const String svgString = '''
+<svg viewBox="0 0 100 100">
+  <rect width="50" height="50" fill="#FF0000" />
+  <circle cx="75" cy="75" r="25" fill="#00FF00" />
+</svg>
+''';
+  final Widget svgIcon = SvgPicture.string(
+    svgString,
+    colorMapper: const _MyColorMapper(),
+  );
+```
+
+In this example, all red colors in the SVG will be rendered as blue, and all green colors will be rendered as yellow. You can customize the `substitute` method to implement more complex color mapping logic based on your requirements.
+
 The default placeholder is an empty box (`LimitedBox`) - although if a `height`
 or `width` is specified on the `SvgPicture`, a `SizedBox` will be used instead
 (which ensures better layout experience). There is currently no way to show an
@@ -67,6 +114,7 @@ If you'd like to render the SVG to some other canvas, you can do something like:
 <?code-excerpt "example/lib/readme_excerpts.dart (OutputConversion)"?>
 ```dart
 import 'dart:ui' as ui;
+
 // ···
   const String rawSvg = '''<svg ...>...</svg>''';
   final PictureInfo pictureInfo =

third_party/packages/flutter_svg/example/lib/readme_excerpts.dart

@@ -7,6 +7,7 @@
 
 // #docregion OutputConversion
 import 'dart:ui' as ui;
+
 // #enddocregion OutputConversion
 
 import 'package:flutter/material.dart';
@@ -101,3 +102,42 @@ Future<ui.Image> convertSvgOutput() async {
   // #enddocregion OutputConversion
   return image;
 }
+
+// #docregion ColorMapper
+class _MyColorMapper extends ColorMapper {
+  const _MyColorMapper();
+
+  @override
+  Color substitute(
+    String? id,
+    String elementName,
+    String attributeName,
+    Color color,
+  ) {
+    if (color == const Color(0xFFFF0000)) {
+      return Colors.blue;
+    }
+    if (color == const Color(0xFF00FF00)) {
+      return Colors.yellow;
+    }
+    return color;
+  }
+}
+// #enddocregion ColorMapper
+
+/// Demonstrates loading an SVG asset with a color mapping.
+Widget loadWithColorMapper() {
+  // #docregion ColorMapper
+  const String svgString = '''
+<svg viewBox="0 0 100 100">
+  <rect width="50" height="50" fill="#FF0000" />
+  <circle cx="75" cy="75" r="25" fill="#00FF00" />
+</svg>
+''';
+  final Widget svgIcon = SvgPicture.string(
+    svgString,
+    colorMapper: const _MyColorMapper(),
+  );
+  // #enddocregion ColorMapper
+  return svgIcon;
+}

third_party/packages/flutter_svg/lib/svg.dart

@@ -195,6 +195,7 @@ class SvgPicture extends StatelessWidget {
     this.clipBehavior = Clip.hardEdge,
     this.errorBuilder,
     SvgTheme? theme,
+    ColorMapper? colorMapper,
     ui.ColorFilter? colorFilter,
     @Deprecated('Use colorFilter instead.') ui.Color? color,
     @Deprecated('Use colorFilter instead.')
@@ -205,6 +206,7 @@ class SvgPicture extends StatelessWidget {
           packageName: package,
           assetBundle: bundle,
           theme: theme,
+          colorMapper: colorMapper,
         ),
         colorFilter = colorFilter ?? _getColorFilter(color, colorBlendMode);
 
@@ -261,11 +263,13 @@ class SvgPicture extends StatelessWidget {
     this.errorBuilder,
     @Deprecated('This no longer does anything.') bool cacheColorFilter = false,
     SvgTheme? theme,
+    ColorMapper? colorMapper,
     http.Client? httpClient,
   })  : bytesLoader = SvgNetworkLoader(
           url,
           headers: headers,
           theme: theme,
+          colorMapper: colorMapper,
           httpClient: httpClient,
         ),
         colorFilter = colorFilter ?? _getColorFilter(color, colorBlendMode);
@@ -319,8 +323,13 @@ class SvgPicture extends StatelessWidget {
     this.clipBehavior = Clip.hardEdge,
     this.errorBuilder,
     SvgTheme? theme,
+    ColorMapper? colorMapper,
     @Deprecated('This no longer does anything.') bool cacheColorFilter = false,
-  })  : bytesLoader = SvgFileLoader(file, theme: theme),
+  })  : bytesLoader = SvgFileLoader(
+          file,
+          theme: theme,
+          colorMapper: colorMapper,
+        ),
         colorFilter = colorFilter ?? _getColorFilter(color, colorBlendMode);
 
   /// Creates a widget that displays an SVG obtained from a [Uint8List].
@@ -369,8 +378,13 @@ class SvgPicture extends StatelessWidget {
     this.clipBehavior = Clip.hardEdge,
     this.errorBuilder,
     SvgTheme? theme,
+    ColorMapper? colorMapper,
     @Deprecated('This no longer does anything.') bool cacheColorFilter = false,
-  })  : bytesLoader = SvgBytesLoader(bytes, theme: theme),
+  })  : bytesLoader = SvgBytesLoader(
+          bytes,
+          theme: theme,
+          colorMapper: colorMapper,
+        ),
         colorFilter = colorFilter ?? _getColorFilter(color, colorBlendMode);
 
   /// Creates a widget that displays an SVG obtained from a [String].
@@ -419,8 +433,13 @@ class SvgPicture extends StatelessWidget {
     this.clipBehavior = Clip.hardEdge,
     this.errorBuilder,
     SvgTheme? theme,
+    ColorMapper? colorMapper,
     @Deprecated('This no longer does anything.') bool cacheColorFilter = false,
-  })  : bytesLoader = SvgStringLoader(string, theme: theme),
+  })  : bytesLoader = SvgStringLoader(
+          string,
+          theme: theme,
+          colorMapper: colorMapper,
+        ),
         colorFilter = colorFilter ?? _getColorFilter(color, colorBlendMode);
 
   static ColorFilter? _getColorFilter(

third_party/packages/flutter_svg/pubspec.yaml

@@ -2,7 +2,7 @@ name: flutter_svg
 description: An SVG rendering and widget library for Flutter, which allows painting and displaying Scalable Vector Graphics 1.1 files.
 repository: https://github.com/flutter/packages/tree/main/third_party/packages/flutter_svg
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+flutter_svg%22
-version: 2.0.17
+version: 2.1.0
 
 environment:
   sdk: ^3.4.0