Add documentation for themes (#45)

* Prototype dialog * Add first fully functioning FDialog * Add support for accessibility tools & refactor button * Add golden tests * Regenerate baseline images for golden tests * Commit from GitHub Actions (Forui Presubmit) * increase tolerance of dialog golden tests * Commit from GitHub Actions (Forui Example Presubmit) * Adjust dialog appearance * WIP document theme * Brush up documentation for theme * Commit from GitHub Actions (Forui Presubmit) * Fix bad rebase --------- Co-authored-by: Pante <[email protected]>
forus-labs · Jun 18, 2024 · 17c9a33 · 17c9a33
1 parent ce6f36c
commit 17c9a33
Show file tree

Hide file tree

Showing 9 changed files with 328 additions and 98 deletions.
diff --git a/forui/example/lib/main.dart b/forui/example/lib/main.dart
@@ -28,6 +28,10 @@ class Application extends StatelessWidget {
       );
 }
 
+
+
+
+
 class ExampleWidget extends StatefulWidget {
   const ExampleWidget({super.key});
 

diff --git a/forui/example/pubspec.lock b/forui/example/pubspec.lock
@@ -498,10 +498,10 @@ packages:
     dependency: transitive
     description:
       name: platform
-      sha256: "12220bb4b65720483f8fa9450b4332347737cf8213dd2840d8b2c823e47243ec"
+      sha256: "9b71283fc13df574056616011fb138fd3b793ea47cc509c189a6c3fa5f8a1a65"
       url: "https://pub.dev"
     source: hosted
-    version: "3.1.4"
+    version: "3.1.5"
   plugin_platform_interface:
     dependency: transitive
     description:

diff --git a/forui/lib/src/theme/color_scheme.dart b/forui/lib/src/theme/color_scheme.dart
@@ -1,56 +1,99 @@
 import 'package:flutter/foundation.dart';
 import 'package:flutter/widgets.dart';
 
+import 'package:meta/meta.dart';
+
 import 'package:forui/forui.dart';
 
-/// A set of colors that can be used to configure the colors of most widgets.
+/// A set of colors that is part of a [FThemeData]. It is used to configure the color properties of Forui widgets.
+///
+/// These properties are not used directly by Forui widgets. Instead, they are the defaults for the corresponding colors
+/// of widget styles configured via `inherit(...)` constructors.
+///
+/// The main color groups in this scheme are [primary], [secondary], [muted], [destructive], and [error].
+/// * Primary colors are used for key widgets across the UI.
+/// * Secondary colors are used for less prominent widgets.
+/// * Mute colors are typically used for disabled widgets.
+/// * Destructive colors are used for destructive actions such as "Delete" buttons.
+/// * Error colors are typically used to highlight errors, such as invalid input in text-fields.
 ///
-/// See the pre-defined themes' color schemes in [FThemes].
+/// Each color group includes a `-Foreground` suffixed color, i.e. [primaryForeground], used to color text and other
+/// visual elements on top of their respective background colors.
+///
+/// See [FThemes] for predefined themes and color schemes.
 final class FColorScheme with Diagnosticable {
-
   /// The system brightness.
+  ///
+  /// This is typically used to determine the appearance of native UI elements such as on-screen keyboards.
   final Brightness brightness;
 
   /// The background color.
+  ///
+  /// Typically used as a background for [foreground] colored widgets.
   final Color background;
 
   /// The foreground color.
+  ///
+  /// Typically used to color widgets against a [background].
   final Color foreground;
 
   /// The primary color.
+  ///
+  /// Typically used as a background for [primaryForeground] colored widgets.
   final Color primary;
 
   /// The primary foreground color.
+  ///
+  /// Typically used to color widgets against a [primary] colored background.
   final Color primaryForeground;
 
   /// The secondary color.
+  ///
+  /// Typically used as a background for [secondaryForeground] colored widgets.
   final Color secondary;
 
   /// The secondary foreground color.
+  ///
+  /// Typically used to color widgets against a [secondary] colored background.
   final Color secondaryForeground;
 
   /// The muted color.
+  ///
+  /// Typically used as a background for [mutedForeground] colored widgets.
   final Color muted;
 
   /// The muted foreground color.
+  ///
+  /// Typically used to color widgets against a [muted] colored background.
   final Color mutedForeground;
 
   /// The destructive color.
+  ///
+  /// Typically used as a background for [destructiveForeground] colored widgets.
   final Color destructive;
 
   /// The destructive foreground color.
+  ///
+  /// Typically used to color widgets against a [destructive] colored background.
   final Color destructiveForeground;
 
   /// The error color.
+  ///
+  /// Typically used as a background for [errorForeground] colored widgets.
   final Color error;
 
   /// The error foreground color.
+  ///
+  /// Typically used to color widgets against a [error] colored background.
   final Color errorForeground;
 
   /// The border color.
   final Color border;
 
   /// Creates a [FColorScheme].
+  ///
+  /// **Note:**
+  /// Unless you are creating a completely new color scheme, modifying [FThemes]' predefined color schemes is preferred.
   const FColorScheme({
     required this.brightness,
     required this.background,
@@ -69,7 +112,20 @@ final class FColorScheme with Diagnosticable {
   });
 
   /// Creates a copy of this [FColorScheme] with the given properties replaced.
-  FColorScheme copyWith({
+  ///
+  /// ```dart
+  /// final scheme = FColorScheme(
+  ///   brightness: Brightness.light,
+  ///   background: Colors.blue,
+  ///   // Other arguments omitted for brevity
+  /// );
+  ///
+  /// final copy = scheme.copyWith(brightness: Brightness.dark);
+  ///
+  /// print(copy.brightness); // Brightness.dark
+  /// print(copy.background); // Colors.blue
+  /// ```
+  @useResult FColorScheme copyWith({
     Brightness? brightness,
     Color? background,
     Color? foreground,
@@ -123,37 +179,38 @@ final class FColorScheme with Diagnosticable {
   }
 
   @override
-  bool operator ==(Object other) => identical(this, other) || other is FColorScheme &&
-    brightness == other.brightness &&
-    background == other.background &&
-    foreground == other.foreground &&
-    primary == other.primary &&
-    primaryForeground == other.primaryForeground &&
-    secondary == other.secondary &&
-    secondaryForeground == other.secondaryForeground &&
-    muted == other.muted &&
-    mutedForeground == other.mutedForeground &&
-    destructive == other.destructive &&
-    destructiveForeground == other.destructiveForeground &&
-    error == other.error &&
-    errorForeground == other.errorForeground &&
-    border == other.border;
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is FColorScheme &&
+          brightness == other.brightness &&
+          background == other.background &&
+          foreground == other.foreground &&
+          primary == other.primary &&
+          primaryForeground == other.primaryForeground &&
+          secondary == other.secondary &&
+          secondaryForeground == other.secondaryForeground &&
+          muted == other.muted &&
+          mutedForeground == other.mutedForeground &&
+          destructive == other.destructive &&
+          destructiveForeground == other.destructiveForeground &&
+          error == other.error &&
+          errorForeground == other.errorForeground &&
+          border == other.border;
 
   @override
   int get hashCode =>
-    brightness.hashCode ^
-    background.hashCode ^
-    foreground.hashCode ^
-    primary.hashCode ^
-    primaryForeground.hashCode ^
-    secondary.hashCode ^
-    secondaryForeground.hashCode ^
-    muted.hashCode ^
-    mutedForeground.hashCode ^
-    destructive.hashCode ^
-    destructiveForeground.hashCode ^
-    error.hashCode ^
-    errorForeground.hashCode ^
-    border.hashCode;
-
+      brightness.hashCode ^
+      background.hashCode ^
+      foreground.hashCode ^
+      primary.hashCode ^
+      primaryForeground.hashCode ^
+      secondary.hashCode ^
+      secondaryForeground.hashCode ^
+      muted.hashCode ^
+      mutedForeground.hashCode ^
+      destructive.hashCode ^
+      destructiveForeground.hashCode ^
+      error.hashCode ^
+      errorForeground.hashCode ^
+      border.hashCode;
 }
diff --git a/forui/lib/src/theme/style.dart b/forui/lib/src/theme/style.dart
@@ -1,25 +1,56 @@
 import 'package:flutter/foundation.dart';
 import 'package:flutter/widgets.dart';
 
-/// The fallback global style is used to configure the widget-specific styles if they are not provided.
-final class FStyle with Diagnosticable {
+import 'package:meta/meta.dart';
+
+import 'package:forui/forui.dart';
 
-  /// The border radius.
+/// A set of miscellaneous properties that is part of a [FThemeData].
+///
+/// These properties are not used directly by Forui widgets. Instead, they are the defaults for the corresponding
+/// properties of widget styles configured via `inherit(...)` constructors.
+final class FStyle with Diagnosticable {
+  /// The border radius. Defaults to `BorderRadius.circular(8)`.
   final BorderRadius borderRadius;
 
-  /// The border width.
+  /// The border width. Defaults to 1.
   final double borderWidth;
 
   /// Creates an [FStyle].
-  FStyle({BorderRadius? borderRadius, double? borderWidth}):
-    borderRadius = borderRadius ?? BorderRadius.circular(8),
-    borderWidth = borderWidth ?? 1;
+  ///
+  /// **Note:**
+  /// Unless you are creating a completely new style, modifying [FThemes]' predefined styles should be preferred.
+  const FStyle({
+    this.borderRadius = const BorderRadius.all(Radius.circular(8)),
+    this.borderWidth = 1,
+  });
+
+  /// Creates a copy of this [FStyle] with the given properties replaced.
+  ///
+  /// ```dart
+  /// final style = FStyle(
+  ///   borderRadius: BorderRadius.circular(1),
+  ///   borderWidth: 2,
+  /// );
+  ///
+  /// final copy = style.copyWith(borderWidth: 3);
+  ///
+  /// print(copy.borderRadius); // BorderRadius.circular(1)
+  /// print(copy.borderWidth); // 3
+  /// ```
+  @useResult FStyle copyWith({
+    BorderRadius? borderRadius,
+    double? borderWidth,
+  }) => FStyle(
+    borderRadius: borderRadius ?? this.borderRadius,
+    borderWidth: borderWidth ?? this.borderWidth,
+  );
 
   @override
   void debugFillProperties(DiagnosticPropertiesBuilder properties) {
     super.debugFillProperties(properties);
     properties
-      ..add(DiagnosticsProperty<BorderRadius>('borderRadius', borderRadius, defaultValue: BorderRadius.circular(8)))
+      ..add(DiagnosticsProperty('borderRadius', borderRadius, defaultValue: BorderRadius.circular(8)))
       ..add(DoubleProperty('borderWidth', borderWidth, defaultValue: 1));
   }
 
@@ -33,5 +64,4 @@ final class FStyle with Diagnosticable {
 
   @override
   int get hashCode => borderRadius.hashCode ^ borderWidth.hashCode;
-
 }
-Original file line number
+Diff line change
@@ Expand Up / @@ -28,6 +28,10 @@ class Application extends StatelessWidget { @@
           );
     }
     class ExampleWidget extends StatefulWidget {
       const ExampleWidget({super.key});
@@ Expand Down @@