ready for review

docs/pages/docs/avatar.mdx

@@ -0,0 +1,31 @@
+import { Tabs } from 'nextra/components';
+import { Widget } from "../../components/widget";
+
+# Avatar
+An image element with a fallback for representing the user.
+
+<Tabs items={['Preview', 'Code']}>
+  <Tabs.Tab>
+      <Widget name='avatar' query={{}}/>
+  </Tabs.Tab>
+  <Tabs.Tab>
+      ```dart
+      FAvatar(
+        image: const NetworkImage('https://picsum.photos/250?image=9'),
+        placeholderBuilder: (_) => const Text('MN'),
+      ),
+      ```
+  </Tabs.Tab>
+</Tabs>
+
+## Usage
+
+### `FAvatar(...)`
+
+```dart
+FAvatar(
+  image: const NetworkImage('https://picsum.photos/250?image=9'),
+  placeholderBuilder: (_) => const Text('MN'),
+),
+```
+

forui/example/lib/example.dart

@@ -23,10 +23,9 @@ class _ExampleState extends State<Example> {
           const SizedBox(height: 100),
           FProgress(value: 0.9),
           const SizedBox(height: 10),
-          const FAvatar(
-            image: NetworkImage('https://picsum.photos/'),
-            //backgroundImage: NetworkImage('https://picsum.photos/250?image=9'),
-            placeholder: Text('DC'),
+           FAvatar(
+            image: const NetworkImage('https://picsum.photos/'),
+            placeholderBuilder: (_) => const Text('DC'),
           ),
           const SizedBox(height: 20),
         ],

forui/lib/src/widgets/avatar.dart

@@ -10,29 +10,29 @@ import 'package:forui/forui.dart';
 /// Typically used with a user's profile image, or, in the absence of
 /// such an image, the user's initials.
 ///
-/// If [image] fails then [placeholder] is used.
+/// If [image] fails then [placeholderBuilder] is used.
 class FAvatar extends StatelessWidget {
   /// The style. Defaults to [FThemeData.avatarStyle].
   final FAvatarStyle? style;
 
   /// The background image of the circle.
   ///
-  /// If the [FAvatar] is to have the user's initials, use [placeholder] instead.
+  /// If the [FAvatar] is to have the user's initials, use [placeholderBuilder] instead.
   final ImageProvider image;
 
   /// The fallback widget if [image] cannot be displayed.
   ///
   /// If the avatar is to just have the user's initials, they are typically
-  /// provided using a [Text] widget as the [placeholder] with a [FAvatarStyle.backgroundColor]
+  /// provided using a [Text] widget in the [placeholderBuilder] with a [FAvatarStyle.backgroundColor]
   ///
   /// If the [FAvatar] is to have an image, use [image] instead.
-  final Widget? placeholder;
+  final Widget Function(BuildContext)? placeholderBuilder;
 
   /// Creates an [FAvatar].
   const FAvatar({
     required this.image,
     this.style,
-    this.placeholder,
+    this.placeholderBuilder,
     super.key,
   });
 
@@ -49,11 +49,33 @@ class FAvatar extends StatelessWidget {
       clipBehavior: Clip.hardEdge,
       child: Center(
         child: Image(
+          filterQuality: FilterQuality.medium,
           image: image,
           errorBuilder: (context, exception, stacktrace) => DefaultTextStyle(
             style: style.text,
-            child: placeholder ?? const _Placeholder(),
+            child: placeholderBuilder != null ? placeholderBuilder!(context) : const _Placeholder(),
           ),
+          frameBuilder: (context, child, frame, wasSynchronouslyLoaded) {
+            if (wasSynchronouslyLoaded) {
+              return child;
+            }
+            if (frame == null) {
+              return DefaultTextStyle(
+                style: style.text,
+                child: placeholderBuilder != null ? placeholderBuilder!(context) : const _Placeholder(),
+              );
+            }
+            return child;
+          },
+          loadingBuilder: (context, child, loadingProgress) {
+            if (loadingProgress == null) {
+              return child;
+            }
+            return DefaultTextStyle(
+              style: style.text,
+              child: placeholderBuilder != null ? placeholderBuilder!(context) : const _Placeholder(),
+            );
+          },
           fit: BoxFit.cover,
         ),
       ),
@@ -65,7 +87,8 @@ class FAvatar extends StatelessWidget {
     super.debugFillProperties(properties);
     properties
       ..add(DiagnosticsProperty('style', style))
-      ..add(DiagnosticsProperty('image', image));
+      ..add(DiagnosticsProperty('image', image))
+      ..add(ObjectFlagProperty<Widget Function(BuildContext p1)?>.has('placeholderBuilder', placeholderBuilder));
   }
 }
 

forui/test/src/widgets/avatar_golden_test.dart

@@ -0,0 +1,54 @@
+@Tags(['golden'])
+library;
+
+import 'dart:io';
+
+import 'package:flutter/material.dart';
+
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:forui/forui.dart';
+import '../test_scaffold.dart';
+
+void main() {
+  group(
+    'FAvatar',
+    () {
+      for (final (name, theme, _) in TestScaffold.themes) {
+        testWidgets('$name with image', (tester) async {
+          final testWidget = MaterialApp(
+            home: TestScaffold(
+              data: theme,
+              child: Padding(
+                padding: const EdgeInsets.symmetric(horizontal: 20),
+                child: FAvatar(
+                  image: FileImage(File('./test/resources/pante.jpg')),
+                  placeholderBuilder: (_) => const Text('MN'),
+                ),
+              ),
+            ),
+          );
+
+          /// current workaround for flaky image asset testing.
+          /// https://github.com/flutter/flutter/issues/38997
+          await tester.runAsync(() async {
+            await tester.pumpWidget(testWidget);
+            for (final element in find.byType(Image).evaluate()) {
+              final Image widget = element.widget as Image;
+              final ImageProvider image = widget.image;
+              await precacheImage(image, element);
+              await tester.pumpAndSettle();
+            }
+          });
+          await expectLater(
+            find.byType(TestScaffold),
+            matchesGoldenFile('avatar/$name-with-image.png'),
+          );
+        });
+
+        /// We will not be testing for the fallback behavior due to this issue on flutter
+        /// https://github.com/flutter/flutter/issues/107416
+      }
+    },
+  );
+}

samples/lib/main.dart

@@ -43,6 +43,10 @@ class _AppRouter extends $_AppRouter {
           path: '/alert/default',
           page: AlertRoute.page,
         ),
+    AutoRoute(
+      path: '/avatar/default',
+      page: AvatarRoute.page,
+    ),
         AutoRoute(
           path: '/badge/default',
           page: BadgeRoute.page,

samples/lib/widgets/avatar.dart

@@ -0,0 +1,26 @@
+import 'dart:io';
+
+import 'package:flutter/material.dart';
+
+import 'package:auto_route/auto_route.dart';
+import 'package:forui/forui.dart';
+
+import 'package:forui_samples/sample_scaffold.dart';
+
+@RoutePage()
+class AvatarPage extends SampleScaffold {
+  AvatarPage({
+    @queryParam super.theme,
+  });
+
+  @override
+  Widget child(BuildContext context) => Column(
+    mainAxisAlignment: MainAxisAlignment.center,
+    children: [
+      FAvatar(
+        image: const NetworkImage('https://picsum.photos/250?image=9'),
+        placeholderBuilder: (_) => const Text('MN'),
+      ),
+    ],
+  );
+}