Avatar Improvements, documentation changes

docs/pages/docs/avatar.mdx

@@ -11,7 +11,7 @@ An image element with a fallback for representing the user.
   <Tabs.Tab>
       ```dart
       FAvatar(
-        image: const NetworkImage('https://picsum.photos/250?image=9'),
+        image: const NetworkImage('https://raw.githubusercontent.com/forus-labs/forui/main/samples/assets/avatar.png'),
         placeholderBuilder: (_) => const Text('MN'),
       ),
       ```
@@ -24,9 +24,50 @@ An image element with a fallback for representing the user.
 
 ```dart
 FAvatar(
-  image: const NetworkImage('https://picsum.photos/250?image=9'),
-  size: 60,
+  image: const NetworkImage('https://raw.githubusercontent.com/forus-labs/forui/main/samples/assets/avatar.png'),
   placeholderBuilder: (_) => const Text('MN'),
 ),
 ```
 
+### `FAvatar.raw(...)`
+
+```dart
+FButton.raw(
+  child: const Text('MN'),
+  size: 60,
+);
+```
+
+
+## Examples
+
+### Invalid image with Placeholder
+<Tabs items={['Preview', 'Code']}>
+    <Tabs.Tab>
+        <Widget name='avatar' query={{image: 'error'}}/>
+    </Tabs.Tab>
+    <Tabs.Tab>
+        ```dart
+        FAvatar(
+          image: const NetworkImage(''),
+          placeholderBuilder: (_) => const Text('MN'),
+        ),
+        ```
+    </Tabs.Tab>
+</Tabs>
+
+### Invalid image without Placeholder
+<Tabs items={['Preview', 'Code']}>
+    <Tabs.Tab>
+        <Widget name='avatar' query={{image: 'error', child: 'empty'}}/>
+    </Tabs.Tab>
+    <Tabs.Tab>
+        ```dart
+        FAvatar(
+          image: const NetworkImage(''),
+        ),
+        ```
+    </Tabs.Tab>
+</Tabs>
+
+

forui/lib/src/widgets/avatar.dart

@@ -7,37 +7,41 @@ import 'package:forui/forui.dart';
 
 /// An image element with a fallback for representing the user.
 ///
+/// use image property to provide a profile image displayed within the circle.
 /// Typically used with a user's profile image. If the image fails to load,
-/// [placeholderBuilder] is used instead, which usually displays the user's initials.
+/// the placeholderBuilder property is used instead, which usually displays the user's initials.
 ///
-/// If the user's profile has no image, use [placeholderBuilder] to provide
+/// If the user's profile has no image, use the placeholderBuilder property to provide
 /// the initials using a [Text] widget styled with [FAvatarStyle.backgroundColor].
 class FAvatar extends StatelessWidget {
   /// The style. Defaults to [FThemeData.avatarStyle].
   final FAvatarStyle? style;
 
-  /// The profile image displayed within the circle.
-  ///
-  /// If the user's initials are used, use [placeholderBuilder] instead.
-  final ImageProvider image;
-
   /// The circle's size.
   final double size;
 
-  /// The fallback widget displayed if [image] fails to load.
-  ///
-  /// Typically used to display the user's initials using a [Text] widget
-  /// styled with [FAvatarStyle.backgroundColor].
-  ///
-  /// Use [image] to display an image; use [placeholderBuilder] for initials.
-  final Widget Function(BuildContext)? placeholderBuilder;
+  /// The child.
+  final Widget child;
 
   /// Creates an [FAvatar].
-  const FAvatar({
-    required this.image,
+  FAvatar({
+    required ImageProvider image,
+    Widget Function(BuildContext)? placeholderBuilder,
+    this.size = 40.0,
     this.style,
+    super.key,
+  }) : child = _Avatar(
+          style: style,
+          size: size,
+          image: image,
+          placeholderBuilder: placeholderBuilder,
+        );
+
+  /// Creates a [FAvatar] with custom child.
+  const FAvatar.raw({
+    required this.child,
     this.size = 40.0,
-    this.placeholderBuilder,
+    this.style,
     super.key,
   });
 
@@ -53,51 +57,16 @@ class FAvatar extends StatelessWidget {
         shape: BoxShape.circle,
       ),
       clipBehavior: Clip.hardEdge,
-      child: Center(
-        child: Image(
-          filterQuality: FilterQuality.medium,
-          image: image,
-          errorBuilder: (context, exception, stacktrace) => DefaultTextStyle(
-            style: style.text,
-            child: placeholderBuilder != null ? placeholderBuilder!(context) : _Placeholder(size: size),
-          ),
-          frameBuilder: (context, child, frame, wasSynchronouslyLoaded) {
-            if (wasSynchronouslyLoaded) {
-              return child;
-            }
-            return AnimatedSwitcher(
-              duration: const Duration(milliseconds: 500),
-              child: frame == null
-                  ? DefaultTextStyle(
-                      style: style.text,
-                      child: placeholderBuilder != null ? placeholderBuilder!(context) : _Placeholder(size: size),
-                    )
-                  : child,
-            );
-          },
-          loadingBuilder: (context, child, loadingProgress) {
-            if (loadingProgress == null) {
-              return child;
-            }
-            return DefaultTextStyle(
-              style: style.text,
-              child: placeholderBuilder != null ? placeholderBuilder!(context) : _Placeholder(size: size),
-            );
-          },
-          fit: BoxFit.cover,
-        ),
-      ),
+      child: child,
     );
   }
 
   @override
   void debugFillProperties(DiagnosticPropertiesBuilder properties) {
     super.debugFillProperties(properties);
     properties
-      ..add(DiagnosticsProperty('image', image))
       ..add(DoubleProperty('size', size))
-      ..add(DiagnosticsProperty('style', style))
-      ..add(ObjectFlagProperty.has('placeholderBuilder', placeholderBuilder));
+      ..add(DiagnosticsProperty('style', style));
   }
 }
 
@@ -113,7 +82,7 @@ final class FAvatarStyle with Diagnosticable {
   final TextStyle text;
 
   /// Creates a [FAvatarStyle].
-  FAvatarStyle({
+  const FAvatarStyle({
     required this.backgroundColor,
     required this.fadeInDuration,
     required this.text,
@@ -175,6 +144,83 @@ final class FAvatarStyle with Diagnosticable {
   int get hashCode => backgroundColor.hashCode ^ fadeInDuration.hashCode ^ text.hashCode;
 }
 
+class _Avatar extends StatelessWidget {
+  final FAvatarStyle? style;
+
+  /// The circle's size.
+  final double size;
+
+  /// The profile image displayed within the circle.
+  ///
+  /// If the user's initials are used, use [placeholderBuilder] instead.
+  final ImageProvider image;
+
+  /// The fallback widget displayed if [image] fails to load.
+  ///
+  /// Typically used to display the user's initials using a [Text] widget
+  /// styled with [FAvatarStyle.backgroundColor].
+  ///
+  /// Use [image] to display an image; use [placeholderBuilder] for initials.
+  final Widget Function(BuildContext)? placeholderBuilder;
+
+  const _Avatar({
+    required this.style,
+    required this.size,
+    required this.image,
+    required this.placeholderBuilder,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final style = this.style ?? context.theme.avatarStyle;
+    return Center(
+      child: Image(
+        filterQuality: FilterQuality.medium,
+        image: image,
+        errorBuilder: (context, exception, stacktrace) => DefaultTextStyle(
+          style: style.text,
+          child: placeholderBuilder != null ? placeholderBuilder!(context) : _Placeholder(size: size),
+        ),
+        frameBuilder: (context, child, frame, wasSynchronouslyLoaded) {
+          if (wasSynchronouslyLoaded) {
+            return child;
+          }
+          return AnimatedSwitcher(
+            duration: const Duration(milliseconds: 500),
+            child: frame == null
+                ? DefaultTextStyle(
+                    style: style.text,
+                    child: placeholderBuilder != null ? placeholderBuilder!(context) : _Placeholder(size: size),
+                  )
+                : child,
+          );
+        },
+        loadingBuilder: (context, child, loadingProgress) {
+          if (loadingProgress == null) {
+            return child;
+          }
+          return DefaultTextStyle(
+            style: style.text,
+            child: placeholderBuilder != null ? placeholderBuilder!(context) : _Placeholder(size: size),
+          );
+        },
+        fit: BoxFit.cover,
+      ),
+    );
+  }
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties
+      ..add(DiagnosticsProperty('style', style))
+      ..add(ObjectFlagProperty.has('placeholderBuilder', placeholderBuilder))
+      ..add(DiagnosticsProperty('image', image))
+      ..add(DoubleProperty('size', size))
+      ..add(DiagnosticsProperty('style', style));
+  }
+}
+
 class _Placeholder extends StatelessWidget {
   final double size;
 

samples/lib/widgets/avatar.dart

@@ -5,20 +5,33 @@ import 'package:forui/forui.dart';
 
 import 'package:forui_samples/sample_scaffold.dart';
 
+final images = {
+  'default': const NetworkImage('https://raw.githubusercontent.com/forus-labs/forui/main/samples/assets/avatar.png'),
+  'error': const NetworkImage(''),
+};
+
+final placeholders = {'text': const Text('MN')};
+
 @RoutePage()
 class AvatarPage extends SampleScaffold {
+  final ImageProvider image;
+  final Widget? placeholder;
+
   AvatarPage({
     @queryParam super.theme,
-  });
+    @queryParam String image = 'default',
+    @queryParam String child = 'text',
+  })  : image = images[image] ?? const NetworkImage(''),
+        placeholder = placeholders[child];
 
   @override
   Widget child(BuildContext context) => Column(
         mainAxisAlignment: MainAxisAlignment.center,
         children: [
           FAvatar(
             size: 70,
-            image: const AssetImage('avatar.png'),
-            placeholderBuilder: (_) => const Text('MN'),
+            image: image,
+            placeholderBuilder: placeholder != null ? (_) => placeholder! : null,
           ),
         ],
       );