Add animated theme (#671)

* Refactor style_generator

* Add FWidgetStateMap.lerp

* WIP adding lerp method

* Generate lerp function for styles

* Add lerp generator

* Add FAnimatedTheme

* Commit from GitHub Actions (Forui Internal Gen Presubmit)

* Prepare Forui for review

* Update card

* Fix failing test

* Prepare Forui for review

* Update windows-latest goldens

* Fix failing internal gen build test

* Increase timeout

---------

Co-authored-by: Pante <[email protected]>

Author: Pante

.github/workflows/forui_internal_gen_build.yaml

@@ -27,6 +27,7 @@ jobs:
         with:
           flutter-version: ${{ matrix.flutter-version }}
           cache: true
-      - run: flutter pub get
+      - run: dart pub get
       - run: dart run build_runner build --delete-conflicting-outputs
-      - run: flutter analyze
+      - run: dart analyze
+      - run: dart test

docs/app/docs/localization/page.mdx

@@ -12,7 +12,7 @@ MaterialApp(
   supportedLocales: [
     // Add locales supported by your application here.
   ],
-  builder: (context, child) => FTheme(
+  builder: (context, child) => FAnimatedTheme(
     data: FThemes.zinc.light,
     child: child!,
   ),
@@ -27,7 +27,7 @@ these instead of providing them manually if your application doesn't have any ot
 MaterialApp(
   localizationsDelegates: FLocalizations.localizationsDelegates,
   supportedLocales: FLocalizations.supportedLocales,
-  builder: (context, child) => FTheme(
+  builder: (context, child) => FAnimatedTheme(
     data: FThemes.zinc.light,
     child: child!,
   ),

docs/app/docs/page.mdx

@@ -49,19 +49,91 @@ flutter pub add forui_assets
 ## Usage
 
 To use Forui widgets in your Flutter app, import the Forui package and place the
-[`FTheme`](https://pub.dev/documentation/forui/latest/forui.theme/FTheme-class.html) widget underneath `CupertinoApp`,
-`MaterialApp`, or `WidgetsApp` at the root of the widget tree.
+[`FAnimatedTheme`](https://pub.dev/documentation/forui/latest/forui.theme/FAnimatedTheme-class.html) widget underneath
+`CupertinoApp`, `MaterialApp`, or `WidgetsApp` at the root of the widget tree.
 
 To generate a basic Forui app structure in your project, run:
 
 ```bash filename="bash" copy
 dart run forui init
 ```
 
+Or copy & paste the following code snippet:
+```dart filename='main.dart' copy
+import 'package:flutter/material.dart';
+import 'package:forui/forui.dart';
+
+void main() {
+  runApp(const Application());
+}
+
+class Application extends StatelessWidget {
+  const Application({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    /// Try changing this and hot reloading the application.
+    ///
+    /// To create a custom theme:
+    /// ```shell
+    /// dart forui theme create [theme template].
+    /// ```
+    final theme = FThemes.zinc.dark;
+
+    return MaterialApp(
+      // TODO: replace with your application's supported locales.
+      supportedLocales: FLocalizations.supportedLocales,
+      // TODO: add your application's localizations delegates.
+      localizationsDelegates: const [...FLocalizations.localizationsDelegates],
+      // MaterialApp's theme is also animated by default with the same duration and curve.
+      // See https://api.flutter.dev/flutter/material/MaterialApp/themeAnimationStyle.html for how to configure this.
+      //
+      // There is a known issue with implicitly animated widgets where their transition occurs AFTER the theme's.
+      // See https://github.com/forus-labs/forui/issues/670.
+      theme: theme.toApproximateMaterialTheme(),
+      builder: (_, child) => FAnimatedTheme(data: theme, child: child!),
+      // You can also replace FScaffold with Material Scaffold.
+      home: const FScaffold(
+        // TODO: replace with your widget.
+        child: Example(),
+      ),
+    );
+  }
+}
+
+class Example extends StatefulWidget {
+  const Example({super.key});
+
+  @override
+  State<Example> createState() => _ExampleState();
+}
+
+class _ExampleState extends State<Example> {
+  int _count = 0;
+
+  @override
+  Widget build(BuildContext context) => Center(
+    child: Column(
+      mainAxisSize: MainAxisSize.min,
+      spacing: 10,
+      children: [
+        Text('Count: $_count'),
+        FButton(
+          onPress: () => setState(() => _count++),
+          suffix: const Icon(FIcons.chevronsUp),
+          child: const Text('Increase'),
+        ),
+      ],
+    ),
+  );
+}
+
+```
+
 It is perfectly fine to use Cupertino/Material widgets alongside Forui widgets!
 
 ```dart filename="main.dart" {3,12-18} copy
-import 'package:flutter/material.dart';
+import 'package:flutter/cupertino.dart';
 
 import 'package:forui/forui.dart';
 
@@ -72,8 +144,8 @@ void main() {
 class Application extends StatelessWidget {
   const Application({super.key});
 
-  Widget build(BuildContext context) => MaterialApp(
-    builder: (context, child) => FTheme(
+  Widget build(BuildContext context) => CupertinoApp(
+    builder: (context, child) => FAnimatedTheme(
       data: FThemes.zinc.light,
       child: child!,
     ),

docs/app/docs/themes/page.mdx

@@ -18,11 +18,11 @@ to generate themes and styles that can be directly modified in your project.
 
 <Callout type="info">
     Forui does not manage the theme brightness (light or dark) automatically.
-    You need to specify the theme explicitly in `FTheme(...)`.
+    You need to specify the theme explicitly in `FAnimatedTheme(...)`.
 
     ```dart filename="main.dart" {3} copy
     @override
-    Widget build(BuildContext context) => FTheme(
+    Widget build(BuildContext context) => FAnimatedTheme(
       data: FThemes.zinc.light, // or FThemes.zinc.dark
       child: FScaffold(...),
     );
@@ -51,8 +51,8 @@ Forui includes predefined themes that can be used out of the box. They are heavi
 title: Forui Theming System
 ---
 classDiagram
-class FTheme {
-    +FTheme(...)
+class FAnimatedTheme {
+    +FAnimatedTheme(...)
 }
 
 class FThemeData {
@@ -78,7 +78,7 @@ class FAccordionStyle {
 }
 note for FAccordionStyle "Each Forui widget has a corresponding style.\nWe use FAccordionStyle here as an example."
 
-FTheme --> FThemeData
+FAnimatedTheme --> FThemeData
 FThemeData --> FColors
 FThemeData --> FTypography
 FThemeData --> FStyle
@@ -87,7 +87,7 @@ FThemeData --> FAccordionStyle
 
 There are **5** core components in Forui's theming system.
 
-- **[`FTheme`](https://pub.dev/documentation/forui/latest/forui.theme/FTheme-class.html)**: The root widget that provides the theme data to all widgets in the subtree.
+- **[`FAnimatedTheme`](https://pub.dev/documentation/forui/latest/forui.theme/FAnimatedTheme-class.html)**: The root widget that provides the theme data to all widgets in the subtree.
 - **[`FThemeData`](https://pub.dev/documentation/forui/latest/forui.theme/FThemeData-class.html)**: Main class that holds:
   - **[`FColors`](https://pub.dev/documentation/forui/latest/forui.theme/FColors-class.html)**: Color scheme including primary, foreground, and background colors.
   - **[`FTypography`](https://pub.dev/documentation/forui/latest/forui.theme/FTypography-class.html)**: Typography settings including font family and text styles.
@@ -173,7 +173,7 @@ method is provided to quickly scale all the font sizes.
 
 ```dart {5-7} copy
 @override
-Widget build(BuildContext context) => FTheme(
+Widget build(BuildContext context) => FAnimatedTheme(
   data: FThemeData(
     colors: FThemes.zinc.light.colors,
     typography: FThemes.zinc.light.typography.copyWith(
@@ -290,7 +290,7 @@ class Application extends StatelessWidget {
     return MaterialApp(
       localizationsDelegates: FLocalizations.localizationsDelegates,
       supportedLocales: FLocalizations.supportedLocales,
-      builder: (_, child) => FTheme(data: theme, child: child!),
+      builder: (_, child) => FAnimatedTheme(data: theme, child: child!),
       theme: theme.toApproximateMaterialTheme(),
       home: const FScaffold(
         // TODO: replace with your widget.

forui/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 0.16.0 (Next)
+
+### Better Generated Documentation
+
+We've improved the generated documentation for styles. They should be much easier to navigate and understand.
+
+
+### `FThemeData`
+We've added support for animated theme transitions. This should make transitions between themes gradual instead of abrupt.
+
+* Add `FThemeData.lerp(...)`.
+* Change `FThemeData.copyWith(...)` to accept style builder functions.
+
+
+### `FWidgetStateMap`
+* Add `FWidgetStateMap.lerpBoxDecoration(...)`.
+* Add `FWidgetStateMap.lerpColor(...)`.
+* Add `FWidgetStateMap.lerpIconThemeData(...)`.
+* Add `FWidgetStateMap.lerpTextStyle(...)`.
+* Add `FWidgetStateMap.lerpWhere(...)`.
+
+
 ## 0.15.1
 * Fix CLI generating incorrect icon mappings.
 * Fix CLI generating theme that references private constant.

forui/bin/commands/snippet/snippet.dart

@@ -12,7 +12,6 @@ export 'src/foundation/rendering.dart' hide Alignments, DefaultData, RenderBoxes
 export 'src/foundation/tappable.dart' hide AnimatedTappable, AnimatedTappableState;
 export 'src/foundation/time.dart';
 export 'src/foundation/typeahead_controller.dart';
-export 'src/foundation/widget_states_delta.dart';
 export 'src/foundation/portal/portal.dart';
 export 'src/foundation/portal/portal_constraints.dart' hide FixedConstraints;
 export 'src/foundation/portal/portal_shift.dart';

forui/lib/foundation.dart

@@ -1,3 +1,5 @@
+import 'dart:ui';
+
 import 'package:flutter/foundation.dart';
 import 'package:flutter/rendering.dart';
 import 'package:flutter/widgets.dart';

forui/lib/src/foundation/focused_outline.dart

@@ -0,0 +1,75 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/widgets.dart';
+
+import 'package:forui/forui.dart';
+
+/// An animated version of [FTheme] which automatically transitions the colors, typography, and other properties over a
+/// given duration whenever the provided [FThemeData] changes.
+///
+/// See:
+/// * [FTheme] which is a non-animated version of this widget.
+/// * [FThemeData] which describes the actual configuration of a theme.
+class FAnimatedTheme extends ImplicitlyAnimatedWidget {
+  /// Motion-related properties for the animation.
+  final FAnimatedThemeMotion motion;
+
+  /// The theme.
+  final FThemeData data;
+
+  /// The widget below this widget in the tree.
+  final Widget child;
+
+  /// Creates an animated theme.
+  FAnimatedTheme({
+    required this.data,
+    required this.child,
+    this.motion = const FAnimatedThemeMotion(),
+    super.onEnd,
+    super.key,
+  }) : super(duration: motion.duration, curve: motion.curve);
+
+  @override
+  AnimatedWidgetBaseState<FAnimatedTheme> createState() => _State();
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties
+      ..add(DiagnosticsProperty('motion', motion))
+      ..add(DiagnosticsProperty('data', data));
+  }
+}
+
+/// The motion-related properties for [FAnimatedTheme].
+class FAnimatedThemeMotion {
+  /// The animation's duration. Defaults to 200 milliseconds.
+  final Duration duration;
+
+  /// The animation's curve. Defaults to [Curves.linear].
+  ///
+  /// We recommend [Curves.linear], especially if only the theme's colors are changing.
+  /// See https://pow.rs/blog/animation-easings/ for more information.
+  final Curve curve;
+
+  /// Creates a [FAnimatedThemeMotion].
+  const FAnimatedThemeMotion({this.duration = const Duration(milliseconds: 200), this.curve = Curves.linear});
+}
+
+class _State extends AnimatedWidgetBaseState<FAnimatedTheme> {
+  _Tween? _tween;
+
+  @override
+  void forEachTween(TweenVisitor<dynamic> visitor) {
+    _tween = visitor(_tween, widget.data, (value) => _Tween(begin: value as FThemeData))! as _Tween;
+  }
+
+  @override
+  Widget build(BuildContext context) => FTheme(data: _tween!.evaluate(animation), child: widget.child);
+}
+
+class _Tween extends Tween<FThemeData> {
+  _Tween({super.begin});
+
+  @override
+  FThemeData lerp(double t) => FThemeData.lerp(begin!, end!, t);
+}

forui/lib/src/theme/animated_theme.dart

@@ -159,6 +159,29 @@ final class FColors with Diagnosticable {
        assert(0.0 <= hoverDarken && hoverDarken <= 1.0, 'The hoverDarken must be between 0 and 1.'),
        assert(0 <= disabledOpacity && disabledOpacity <= 1, 'The disabledOpacity must be between 0 and 1.');
 
+  /// Creates a linear interpolation between two [FColors] using the given factor [t].
+  factory FColors.lerp(FColors a, FColors b, double t) => FColors(
+    brightness: t < 0.5 ? a.brightness : b.brightness,
+    systemOverlayStyle: t < 0.5 ? a.systemOverlayStyle : b.systemOverlayStyle,
+    barrier: Color.lerp(a.barrier, b.barrier, t)!,
+    background: Color.lerp(a.background, b.background, t)!,
+    foreground: Color.lerp(a.foreground, b.foreground, t)!,
+    primary: Color.lerp(a.primary, b.primary, t)!,
+    primaryForeground: Color.lerp(a.primaryForeground, b.primaryForeground, t)!,
+    secondary: Color.lerp(a.secondary, b.secondary, t)!,
+    secondaryForeground: Color.lerp(a.secondaryForeground, b.secondaryForeground, t)!,
+    muted: Color.lerp(a.muted, b.muted, t)!,
+    mutedForeground: Color.lerp(a.mutedForeground, b.mutedForeground, t)!,
+    destructive: Color.lerp(a.destructive, b.destructive, t)!,
+    destructiveForeground: Color.lerp(a.destructiveForeground, b.destructiveForeground, t)!,
+    error: Color.lerp(a.error, b.error, t)!,
+    errorForeground: Color.lerp(a.errorForeground, b.errorForeground, t)!,
+    border: Color.lerp(a.border, b.border, t)!,
+    hoverLighten: lerpDouble(a.hoverLighten, b.hoverLighten, t)!,
+    hoverDarken: lerpDouble(a.hoverDarken, b.hoverDarken, t)!,
+    disabledOpacity: lerpDouble(a.disabledOpacity, b.disabledOpacity, t)!,
+  );
+
   /// Generates a hovered variant of the given [color] by darkening light colors and lighting dark colors based on their
   /// HSL lightness.
   ///