feat(vector_graphics): add imageBuilder property to VectorGraphic

Adds an optional imageBuilder callback that wraps the loaded vector
graphic widget, enabling post-load decoration such as borders or
gesture detectors without affecting placeholder or error states.

Resolves flutter/flutter#182635

Author: suojae

packages/vector_graphics/CHANGELOG.md

@@ -1,6 +1,7 @@
-## NEXT
+## 1.1.20
 
 * Updates minimum supported SDK version to Flutter 3.35/Dart 3.9.
+* Adds `imageBuilder` property to `VectorGraphic` for wrapping the loaded vector graphic widget.
 
 ## 1.1.19
 

packages/vector_graphics/lib/src/vector_graphics.dart

@@ -47,6 +47,11 @@ enum RenderingStrategy {
 typedef VectorGraphicsErrorWidget =
     Widget Function(BuildContext context, Object error, StackTrace stackTrace);
 
+/// The signature that [VectorGraphic.imageBuilder] uses to wrap the
+/// successfully loaded vector graphic widget.
+typedef VectorGraphicsImageWidget =
+    Widget Function(BuildContext context, Widget child);
+
 /// A vector graphic/flutter_svg compatibility shim.
 VectorGraphic createCompatVectorGraphic({
   Key? key,
@@ -61,6 +66,7 @@ VectorGraphic createCompatVectorGraphic({
   Duration? transitionDuration,
   WidgetBuilder? placeholderBuilder,
   VectorGraphicsErrorWidget? errorBuilder,
+  VectorGraphicsImageWidget? imageBuilder,
   ColorFilter? colorFilter,
   Animation<double>? opacity,
   RenderingStrategy strategy = RenderingStrategy.picture,
@@ -80,6 +86,7 @@ VectorGraphic createCompatVectorGraphic({
     transitionDuration: transitionDuration,
     placeholderBuilder: placeholderBuilder,
     errorBuilder: errorBuilder,
+    imageBuilder: imageBuilder,
     colorFilter: colorFilter,
     opacity: opacity,
     strategy: strategy,
@@ -120,6 +127,7 @@ class VectorGraphic extends StatefulWidget {
     this.transitionDuration,
     this.placeholderBuilder,
     this.errorBuilder,
+    this.imageBuilder,
     this.colorFilter,
     this.opacity,
     this.clipViewbox = true,
@@ -140,6 +148,7 @@ class VectorGraphic extends StatefulWidget {
     this.transitionDuration,
     this.placeholderBuilder,
     this.errorBuilder,
+    this.imageBuilder,
     this.colorFilter,
     this.opacity,
     this.strategy = RenderingStrategy.picture,
@@ -219,6 +228,13 @@ class VectorGraphic extends StatefulWidget {
   /// A callback that fires if some exception happens during data acquisition or decoding.
   final VectorGraphicsErrorWidget? errorBuilder;
 
+  /// A builder that wraps the successfully loaded vector graphic widget.
+  ///
+  /// This builder is only called when the vector graphic has been successfully
+  /// loaded and is ready to be painted. It can be used to apply decorations
+  /// such as borders or shadows only when the image is available.
+  final VectorGraphicsImageWidget? imageBuilder;
+
   /// Set transition duration while switching from placeholder to url image
   final Duration? transitionDuration;
 
@@ -517,6 +533,10 @@ class _VectorGraphicWidgetState extends State<VectorGraphic> {
           child: SizedBox.fromSize(size: pictureInfo.size, child: child),
         ),
       );
+
+      if (widget.imageBuilder != null) {
+        child = widget.imageBuilder!(context, child);
+      }
     } else if (_error != null && widget.errorBuilder != null) {
       child = widget.errorBuilder!(
         context,

packages/vector_graphics/lib/vector_graphics_compat.dart

@@ -11,5 +11,6 @@ export 'src/vector_graphics.dart'
         RenderingStrategy,
         VectorGraphic,
         VectorGraphicUtilities,
+        VectorGraphicsImageWidget,
         createCompatVectorGraphic,
         vg;

packages/vector_graphics/pubspec.yaml

@@ -2,7 +2,7 @@ name: vector_graphics
 description: A vector graphics rendering package for Flutter using a binary encoding.
 repository: https://github.com/flutter/packages/tree/main/packages/vector_graphics
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+vector_graphics%22
-version: 1.1.19
+version: 1.1.20
 
 environment:
   sdk: ^3.9.0

packages/vector_graphics/test/vector_graphics_test.dart

@@ -690,6 +690,70 @@ void main() {
     expect(matrix.row1.y, 1);
   });
 
+  testWidgets('imageBuilder wraps the loaded vector graphic', (
+    WidgetTester tester,
+  ) async {
+    final buffer = VectorGraphicsBuffer();
+    codec.writeSize(buffer, 100, 200);
+    final ByteData data = buffer.done();
+
+    await tester.pumpWidget(
+      Directionality(
+        textDirection: TextDirection.ltr,
+        child: VectorGraphic(
+          loader: TestBytesLoader(data),
+          imageBuilder: (BuildContext context, Widget child) {
+            return Container(
+              key: const ValueKey<String>('image-builder'),
+              child: child,
+            );
+          },
+        ),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.byKey(const ValueKey<String>('image-builder')), findsOneWidget);
+  });
+
+  testWidgets('imageBuilder is not called during placeholder state', (
+    WidgetTester tester,
+  ) async {
+    final completer = Completer<ByteData>();
+
+    await tester.pumpWidget(
+      Directionality(
+        textDirection: TextDirection.ltr,
+        child: VectorGraphic(
+          loader: DelayedBytesLoader(completer.future),
+          imageBuilder: (BuildContext context, Widget child) {
+            return Container(
+              key: const ValueKey<String>('image-builder'),
+              child: child,
+            );
+          },
+          placeholderBuilder: (BuildContext context) {
+            return Container(key: const ValueKey<String>('placeholder'));
+          },
+        ),
+      ),
+    );
+
+    // During loading: placeholder visible, imageBuilder not called
+    expect(find.byKey(const ValueKey<String>('placeholder')), findsOneWidget);
+    expect(find.byKey(const ValueKey<String>('image-builder')), findsNothing);
+
+    // Complete loading
+    final buffer = VectorGraphicsBuffer();
+    codec.writeSize(buffer, 100, 200);
+    completer.complete(buffer.done());
+    await tester.pumpAndSettle();
+
+    // After loading: imageBuilder visible, placeholder gone
+    expect(find.byKey(const ValueKey<String>('image-builder')), findsOneWidget);
+    expect(find.byKey(const ValueKey<String>('placeholder')), findsNothing);
+  });
+
   testWidgets('VectorGraphicsWidget can handle errors from bytes loader', (
     WidgetTester tester,
   ) async {