docs(ui_components): add some documentation + readme

2023-04-13 23:29:27 +02:00
parent 5fe8d84cf6
commit afbb911a0f
14 changed files with 101 additions and 54 deletions
@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.

+/// Defines status states
 enum StatusState {
  initial,
  success,
@@ -18,5 +18,13 @@ import 'package:flutter/material.dart';
 import 'package:wyatt_ui_components/src/features/features.dart';

 extension ThemeComponentBuildContext on BuildContext {
+  /// Returns the [ComponentThemeData] of the current [BuildContext].
+  ///
+  /// Throws an [AssertionError] if the current [BuildContext] does not contain
+  /// a [ComponentTheme].
  ComponentThemeData get components => ComponentTheme.of(this);
+
+  /// Returns the [ComponentThemeData] of the current [BuildContext] if it
+  /// exists.
+  ComponentThemeData? get maybeComponents => ComponentTheme.maybeOf(this);
 }
@@ -15,5 +15,8 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.

 mixin CopyWithMixin<Proxy> {
+  /// Returns a copy of the current object with the specified properties
+  /// overridden by the specified values.
+  /// You have to call the `.call()` method on the returned object.
  Proxy get copyWith;
 }
@@ -16,13 +16,20 @@

 import 'package:flutter/widgets.dart';

+/// {@template multi_color}
+/// A class that can hold a [Color] or a [List] of [Color]s.
+/// {@endtemplate}
 class MultiColor {
+  /// {@macro multi_color}
  const MultiColor(this._colors) : _color = null;
+
+  /// {@macro multi_color}
  const MultiColor.single(this._color) : _colors = null;

  final List<Color>? _colors;
  final Color? _color;

+  /// Returns a [Color] or the first [Color] in the [List] of [Color]s.
  Color get color => _color != null
      ? _color!
      : _colors?.isNotEmpty ?? false
@@ -33,11 +40,20 @@ class MultiColor {
              message: '_color is not defined or _colors is empty.',
            );

+  /// Returns the [List] of [Color]s.
+  /// If the [List] is empty or if it is a single [MultiColor], it will return
+  /// an empty [List].
  List<Color> get colors => _colors ?? [];

+  /// Returns `true` if the [MultiColor] is a [List] of [Color]s that is not
+  /// empty with a length greater than 1.
  bool get isGradient => (_colors?.length ?? 0) > 1;
+
+  /// Returns `true` if the [MultiColor] is a [Color] or a [List] of [Color]s
+  /// that is not empty with a length greater than 1.
  bool get isColor => _color != null || isGradient;

+  /// Lerps between two [MultiColor]s.
  static MultiColor? lerp(MultiColor? a, MultiColor? b, double t) {
    if (a == null && b == null) {
      return null;
@@ -17,9 +17,12 @@
 import 'package:flutter/material.dart';
 import 'package:wyatt_ui_components/wyatt_ui_components.dart';

+/// {@template text_wrapper}
 /// Wraps [String] and [TextStyle] into one object that can be
 /// a [Text] or a [RichText].
+/// {@endtemplate}
 class TextWrapper {
+  /// {@macro text_wrapper}
  const TextWrapper(
    this.data, {
    this.style,
@@ -32,6 +35,7 @@ class TextWrapper {
    this.selectionColor,
  });

+  /// Creates a [TextWrapper] from a [Text] widget.
  const TextWrapper.text(this.data)
      : style = null,
        gradientColors = null,
@@ -28,7 +28,6 @@ abstract class ThemeHelper {
  /// determines if a style element is valid.
  /// [combine]: A function that combines two [P] type objects to create
  /// a new object.
-
  static T? getThemeElement<P, T>(
    List<P?>? styles, {
    required T? Function(P?)? transform,
@@ -17,6 +17,9 @@
 import 'package:flutter/material.dart';
 import 'package:wyatt_ui_components/src/core/utils/theme_resolver.dart';

+/// {@template component}
+/// Base class for all components.
+/// {@endtemplate}
 abstract class Component extends StatelessWidget {
  const Component({this.themeResolver, super.key});

@@ -14,7 +14,11 @@
 // You should have received a copy of the GNU General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.

+/// {@template theme_style}
+/// Base class for all theme styles.
+/// {@endtemplate}
 abstract class ThemeStyle<T> {
+  /// {@macro theme_style}
  const ThemeStyle();

  /// Merges non-null `other` attributes in `this` and returns a copy.
@@ -17,7 +17,12 @@
 import 'package:flutter/material.dart';
 import 'package:wyatt_ui_components/src/features/features.dart';

+/// {@template component_theme}
+/// A [ComponentTheme] widget that provides a [ComponentThemeData] to its
+/// descendants.
+/// {@endtemplate}
 class ComponentTheme extends StatelessWidget {
+  /// {@macro component_theme}
  const ComponentTheme({
    required this.child,
    required this.componentThemeWidget,
@@ -26,6 +31,9 @@ class ComponentTheme extends StatelessWidget {
  final Widget child;
  final ComponentThemeData componentThemeWidget;

+  /// Returns the [ComponentThemeData] of the closest ancestor [ComponentTheme]
+  /// widget. If there is no ancestor [ComponentTheme] widget, it throws an
+  /// assertion error.
  static ComponentThemeData of(BuildContext context) {
    final _InheritedComponentTheme? inheritedThemeComponent =
        context.dependOnInheritedWidgetOfExactType<_InheritedComponentTheme>();
@@ -37,6 +45,15 @@ class ComponentTheme extends StatelessWidget {
    return inheritedThemeComponent!.themeWidget.componentThemeWidget;
  }

+  /// Returns the [ComponentThemeData] of the closest ancestor [ComponentTheme]
+  /// widget. If there is no ancestor [ComponentTheme] widget, it returns null.
+  static ComponentThemeData? maybeOf(BuildContext context) {
+    final _InheritedComponentTheme? inheritedThemeComponent =
+        context.dependOnInheritedWidgetOfExactType<_InheritedComponentTheme>();
+
+    return inheritedThemeComponent?.themeWidget.componentThemeWidget;
+  }
+
  @override
  Widget build(BuildContext context) => _InheritedComponentTheme(
        this,
@@ -18,6 +18,9 @@ import 'package:copy_with_extension/copy_with_extension.dart';
 import 'package:wyatt_ui_components/src/domain/entities/entities.dart';
 part 'component_theme_data.g.dart';

+/// {@template component_theme_data}
+/// A class that holds all the components that are used in the app.
+/// {@endtemplate}
@CopyWith()
 class ComponentThemeData {
  factory ComponentThemeData({