Merge branch 'faeture/refactor-library' of https://github.com/forus-l…

…abs/forui into faeture/refactor-library

docs/pages/docs/card.mdx

@@ -12,13 +12,22 @@ A card, typically with a title, subtitle, and child widget.
 
 <Tabs items={['Preview', 'Code']}>
   <Tabs.Tab>
-      <Widget name='card' query={{}}/>
+      <Widget name='card' query={{}}  height={400}/>
   </Tabs.Tab>
   <Tabs.Tab>
       ```dart
       FCard(
-          title: const Text('Notification'),
-          subtitle: const Text('You have 3 unread messages.'),
+        image: Container(
+          decoration: BoxDecoration(
+            image: DecorationImage(
+              image: AssetImage(path('avatar.png')),
+              fit: BoxFit.cover,
+            ),
+          ),
+          height: 200,
+        ),
+        title: const Text('Gratitude'),
+        subtitle: const Text('The quality of being thankful; readiness to show appreciation for and to return kindness.'),
       );
       ```
   </Tabs.Tab>

forui/CHANGELOG.md

@@ -4,6 +4,7 @@
 * Add `FAvatar`.
 * **Breaking:** Add `FCalendarEntryStyle.focusedBorderColor`. This only affects users that customized `FCalendarEntryStyle`.
 * Add `FResizable`.
+* Add `image` parameter to `FCard`.
 
 ### Changes
 * Change number of years displayed per page in `FCalendar` from 12 to 15.

forui/lib/src/foundation/util.dart

@@ -0,0 +1,45 @@
+import 'package:flutter/widgets.dart';
+
+/// Creates a default text style that overrides the text styles in scope at
+/// this point in the widget tree.
+///
+/// The given [style] is merged with the [style] from the default text style
+/// for the [BuildContext] where the widget is inserted, and any of the other
+/// arguments that are not null replace the corresponding properties on that
+/// same default text style.
+///
+/// This constructor cannot be used to override the [maxLines] property of the
+/// ancestor with the value null, since null here is used to mean "defer to
+/// ancestor". To replace a non-null [maxLines] from an ancestor with the null
+/// value (to remove the restriction on number of lines), manually obtain the
+/// ambient [DefaultTextStyle] using [DefaultTextStyle.of], then create a new
+/// [DefaultTextStyle] using the [DefaultTextStyle.new] constructor directly.
+/// See the source below for an example of how to do this (since that's
+/// essentially what this constructor does).
+Widget merge({
+  required Widget child,
+  Key? key,
+  TextStyle? style,
+  TextAlign? textAlign,
+  bool? softWrap,
+  TextOverflow? overflow,
+  int? maxLines,
+  TextWidthBasis? textWidthBasis,
+  TextHeightBehavior? textHeightBehavior,
+}) =>
+    Builder(
+      builder: (context) {
+        final DefaultTextStyle parent = DefaultTextStyle.of(context);
+        return DefaultTextStyle(
+          key: key,
+          style: parent.style.merge(style),
+          textAlign: textAlign ?? parent.textAlign,
+          softWrap: softWrap ?? parent.softWrap,
+          overflow: overflow ?? parent.overflow,
+          maxLines: maxLines ?? parent.maxLines,
+          textWidthBasis: textWidthBasis ?? parent.textWidthBasis,
+          textHeightBehavior: textHeightBehavior ?? parent.textHeightBehavior,
+          child: child,
+        );
+      },
+    );

forui/lib/src/widgets/card/card.dart

@@ -4,6 +4,7 @@ import 'package:flutter/widgets.dart';
 import 'package:meta/meta.dart';
 
 import 'package:forui/forui.dart';
+import 'package:forui/src/foundation/util.dart';
 
 part 'card_content.dart';
 
@@ -26,19 +27,23 @@ final class FCard extends StatelessWidget {
   /// The card's layout is as follows:
   /// ```
   /// |---------------------------|
+  /// |  [image]                  |
+  /// |                           |
   /// |  [title]                  |
   /// |  [subtitle]               |
   /// |                           |
   /// |  [child]                  |
   /// |---------------------------|
   /// ```
   FCard({
+    Widget? image,
     Widget? title,
     Widget? subtitle,
     Widget? child,
     this.style,
     super.key,
   }) : child = _FCardContent(
+          image: image,
           title: title,
           subtitle: subtitle,
           style: style?.content,

forui/lib/src/widgets/card/card_content.dart

@@ -1,12 +1,14 @@
 part of 'card.dart';
 
 final class _FCardContent extends StatelessWidget {
+  final Widget? image;
   final Widget? title;
   final Widget? subtitle;
   final Widget? child;
   final FCardContentStyle? style;
 
   const _FCardContent({
+    this.image,
     this.title,
     this.subtitle,
     this.child,
@@ -22,23 +24,33 @@ final class _FCardContent extends StatelessWidget {
       child: Column(
         crossAxisAlignment: CrossAxisAlignment.start,
         children: [
+          if (image != null)
+            ClipRRect(
+              borderRadius: context.theme.style.borderRadius,
+              child: image,
+            ),
+          if ((title != null || subtitle != null || child != null) && image != null) const SizedBox(height: 10),
           if (title != null)
-            Padding(
-              padding: const EdgeInsets.only(bottom: 2),
-              child: DefaultTextStyle.merge(
-                style: style.titleTextStyle,
-                child: title!,
+            // TODO: replace with DefaultTextStyle.merge when textHeightBehavior has been added.
+            merge(
+              textHeightBehavior: const TextHeightBehavior(
+                applyHeightToFirstAscent: false,
+                applyHeightToLastDescent: false,
               ),
+              style: style.titleTextStyle,
+              child: title!,
             ),
           if (subtitle != null)
-            Padding(
-              padding: const EdgeInsets.only(bottom: 2),
-              child: DefaultTextStyle.merge(
-                style: style.subtitleTextStyle,
-                child: subtitle!,
+            // TODO: replace with DefaultTextStyle.merge when textHeightBehavior has been added.
+            merge(
+              textHeightBehavior: const TextHeightBehavior(
+                applyHeightToFirstAscent: false,
+                applyHeightToLastDescent: false,
               ),
+              style: style.subtitleTextStyle,
+              child: subtitle!,
             ),
-          if (title != null && subtitle != null) const SizedBox(height: 8),
+          if (title != null && subtitle != null && image == null) const SizedBox(height: 8),
           if (child != null) child!,
         ],
       ),
@@ -48,7 +60,9 @@ final class _FCardContent extends StatelessWidget {
   @override
   void debugFillProperties(DiagnosticPropertiesBuilder properties) {
     super.debugFillProperties(properties);
-    properties.add(DiagnosticsProperty('style', style));
+    properties
+      ..add(DiagnosticsProperty('style', style))
+      ..add(DiagnosticsProperty('image', image));
   }
 }
 
@@ -60,7 +74,7 @@ final class FCardContentStyle with Diagnosticable {
   /// The subtitle's [TextStyle].
   final TextStyle subtitleTextStyle;
 
-  /// The padding. Defaults to `EdgeInsets.fromLTRB(16, 12, 16, 16)`.
+  /// The padding. Defaults to `EdgeInsets.all(16)`.
   final EdgeInsets padding;
 
   /// Creates a [FCardContentStyle].
@@ -78,7 +92,7 @@ final class FCardContentStyle with Diagnosticable {
           height: 1.5,
         ),
         subtitleTextStyle = typography.sm.copyWith(color: colorScheme.mutedForeground),
-        padding = const EdgeInsets.fromLTRB(16, 12, 16, 16);
+        padding = const EdgeInsets.all(16);
 
   /// Returns a copy of this [FCardContentStyle] with the given properties replaced.
   ///

forui/lib/widgets/scaffold.dart

@@ -1,6 +1,6 @@
 /// {@category Widgets}
 ///
-/// A Scaffold.
+/// A scaffold.
 library forui.widgets.scaffold;
 
 export '../src/widgets/scaffold.dart';

forui/test/src/widgets/card_golden_test.dart

@@ -34,6 +34,34 @@ void main() {
         );
       });
 
+      testWidgets('$name with image', (tester) async {
+        await tester.pumpWidget(
+          TestScaffold(
+            data: theme,
+            background: background,
+            child: Column(
+              mainAxisAlignment: MainAxisAlignment.center,
+              children: [
+                FCard(
+                  image: Container(
+                    color: Colors.blue,
+                    height: 100,
+                    width: 200,
+                  ),
+                  title: const Text('Notifications'),
+                  subtitle: const Text('You have 3 unread messages.'),
+                ),
+              ],
+            ),
+          ),
+        );
+
+        await expectLater(
+          find.byType(TestScaffold),
+          matchesGoldenFile('card/$name-content-image.png'),
+        );
+      });
+
       testWidgets('$name with raw content', (tester) async {
         await tester.pumpWidget(
           TestScaffold(

samples/lib/widgets/card.dart

@@ -1,10 +1,13 @@
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 
 import 'package:auto_route/auto_route.dart';
 import 'package:forui/forui.dart';
 
 import 'package:forui_samples/sample_scaffold.dart';
 
+String path(String str) => kIsWeb ? 'assets/$str' : str;
+
 @RoutePage()
 class CardPage extends SampleScaffold {
   CardPage({
@@ -16,8 +19,18 @@ class CardPage extends SampleScaffold {
         mainAxisAlignment: MainAxisAlignment.center,
         children: [
           FCard(
-            title: const Text('Notifications'),
-            subtitle: const Text('You have 3 unread messages.'),
+            image: Container(
+              decoration: BoxDecoration(
+                image: DecorationImage(
+                  image: AssetImage(path('avatar.png')),
+                  fit: BoxFit.cover,
+                ),
+              ),
+              height: 200,
+            ),
+            title: const Text('Gratitude'),
+            subtitle:
+                const Text('The quality of being thankful; readiness to show appreciation for and to return kindness.'),
           ),
         ],
       );