diff --git a/packages/wyatt_ui_components/README.md b/packages/wyatt_ui_components/README.md index 4c2d773d..5fedb940 100644 --- a/packages/wyatt_ui_components/README.md +++ b/packages/wyatt_ui_components/README.md @@ -7,7 +7,7 @@ * the Free Software Foundation, either version 3 of the License, or * any later version. - * This program is distributed in the hope that it will be useful, + * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. @@ -16,48 +16,35 @@ * along with this program. If not, see . --> -# Flutter - Wyatt Ui Components +# Wyatt UI Components

- - Style: Wyatt Analysis - + Style: Wyatt Analysis SDK: Flutter

-Wyatt Ui Components for Flutter. +Wyatt UI Components for Flutter. This package defines all the components used in Wyatt Studio with their set of properties. But there is no implementation of the components. You have to create your own or check out [Wyatt UI Kit](https://git.wyatt-studio.fr/Wyatt-FOSS/wyatt-packages/src/branch/master/packages/wyatt_ui_kit) package. ## Usage ### Configuration -First create all your custom components in `core/design_system/components/`folder. For exemple : +First create all your custom components in `domain/entities` folder. For exemple : -├── design_system -│ ├── components +``` +├── domain +│ ├── entities │ │ ├── custom_app_bar.dart │ │ ├── custom_bottom_navigation_bar.dart │ │ └── ... │ └── ... └── ... - -You have to override `confgure` method. - -Then create AppComponentTheme class in `core/design_system/` folder and add all your components. For Example : - -```dart -class AppThemeComponent { - static ComponentThemeData get components => ComponentThemeData.raw( - appBar: const CustomAppBar(), - bottomNavigationBar: CustomBottomNavigationBar( - onTap: (context, index) { - print('$index'); - }, - ), - ); -} ``` +> Run `flutter pub run build_runner build` to generate your components. + +Then, add your components to `ComponentThemeData` class. + ### Provider In you main file, before calling router, call `ComponentTheme` widget and give your app as child. For example : @@ -72,7 +59,7 @@ class MyApp extends StatelessWidget { @override Widget build(BuildContext context) => ComponentTheme( - themDataWidget: AppThemeComponent.components, + componentThemeWidget: AppThemeComponent.components, child: MaterialApp( title: 'Wyatt Ui Layout Example', theme: ThemeData( @@ -102,12 +89,32 @@ For example : ) ``` -If you need specific settings, or pass parameters to your component, call `configure` method. It will use default paramters you've passed in your app comppnent theme file, and update the parameter you need to change. For example : +If you need specific settings, or pass parameters to your component, call `copyWith.call` method. ```dart @override Widget build(BuildContext context) => Scaffold( - appBar: context.components.appBar.configure({title:'New Title !}), + appBar: context.components.appBar.copyWith.call({title: 'New Title !'}), body: ... ) ``` + +## Development + +> Common to this, and Wyatt UI Kit packages. + +Add a new component : + +**Wyatt UI Components side** + + 1. Create a new file in `lib/src/domain/entities` folder. + 2. Add your component class. + 3. Add your component class to `ComponentThemeData` abstract class. + 4. Run `flutter pub run build_runner build` to generate your component proxy properties. + +**Wyatt UI Kit side** + 1. Create a new file in `lib/src/components` folder. + 2. Add your component class, styles, (and logic if needed) + 3. Run `flutter pub run build_runner build` to generate your component copy with method. + 4. Add a theme extension to your component class in `lib/src/domain/` + 5. Add your component class `wyattComponentThemeData` static property in `lib/src/features/wyatt_component_theme_data.dart` diff --git a/packages/wyatt_ui_components/analysis_options.yaml b/packages/wyatt_ui_components/analysis_options.yaml index 90d6bd51..8c9daa4e 100644 --- a/packages/wyatt_ui_components/analysis_options.yaml +++ b/packages/wyatt_ui_components/analysis_options.yaml @@ -1,17 +1 @@ -# Copyright (C) 2023 WYATT GROUP -# Please see the AUTHORS file for details. -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - include: package:wyatt_analysis/analysis_options.flutter.yaml diff --git a/packages/wyatt_ui_components/lib/src/core/enums/status_state.dart b/packages/wyatt_ui_components/lib/src/core/enums/status_state.dart index 878899f6..9add284a 100644 --- a/packages/wyatt_ui_components/lib/src/core/enums/status_state.dart +++ b/packages/wyatt_ui_components/lib/src/core/enums/status_state.dart @@ -14,6 +14,7 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +/// Defines status states enum StatusState { initial, success, diff --git a/packages/wyatt_ui_components/lib/src/core/extensions/build_context_extensions.dart b/packages/wyatt_ui_components/lib/src/core/extensions/build_context_extensions.dart index be5e6045..b00fdb3f 100644 --- a/packages/wyatt_ui_components/lib/src/core/extensions/build_context_extensions.dart +++ b/packages/wyatt_ui_components/lib/src/core/extensions/build_context_extensions.dart @@ -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); } diff --git a/packages/wyatt_ui_components/lib/src/core/mixins/copy_with_mixin.dart b/packages/wyatt_ui_components/lib/src/core/mixins/copy_with_mixin.dart index cd7bd5a9..728622c5 100644 --- a/packages/wyatt_ui_components/lib/src/core/mixins/copy_with_mixin.dart +++ b/packages/wyatt_ui_components/lib/src/core/mixins/copy_with_mixin.dart @@ -15,5 +15,8 @@ // along with this program. If not, see . mixin CopyWithMixin { + /// 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; } diff --git a/packages/wyatt_ui_components/lib/src/core/utils/multi_color.dart b/packages/wyatt_ui_components/lib/src/core/utils/multi_color.dart index d64ac9a3..1a3aa44e 100644 --- a/packages/wyatt_ui_components/lib/src/core/utils/multi_color.dart +++ b/packages/wyatt_ui_components/lib/src/core/utils/multi_color.dart @@ -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? _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 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; diff --git a/packages/wyatt_ui_components/lib/src/core/utils/text_wrapper.dart b/packages/wyatt_ui_components/lib/src/core/utils/text_wrapper.dart index ba23b89b..2c6e248e 100644 --- a/packages/wyatt_ui_components/lib/src/core/utils/text_wrapper.dart +++ b/packages/wyatt_ui_components/lib/src/core/utils/text_wrapper.dart @@ -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, diff --git a/packages/wyatt_ui_components/lib/src/core/utils/theme_helper.dart b/packages/wyatt_ui_components/lib/src/core/utils/theme_helper.dart index abefa83f..97fe94a0 100644 --- a/packages/wyatt_ui_components/lib/src/core/utils/theme_helper.dart +++ b/packages/wyatt_ui_components/lib/src/core/utils/theme_helper.dart @@ -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( List? styles, { required T? Function(P?)? transform, diff --git a/packages/wyatt_ui_components/lib/src/domain/entities/component.dart b/packages/wyatt_ui_components/lib/src/domain/entities/component.dart index e7f984f1..9cd334b5 100644 --- a/packages/wyatt_ui_components/lib/src/domain/entities/component.dart +++ b/packages/wyatt_ui_components/lib/src/domain/entities/component.dart @@ -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}); diff --git a/packages/wyatt_ui_components/lib/src/domain/entities/theme_style.dart b/packages/wyatt_ui_components/lib/src/domain/entities/theme_style.dart index a0a69ffb..89db71e2 100644 --- a/packages/wyatt_ui_components/lib/src/domain/entities/theme_style.dart +++ b/packages/wyatt_ui_components/lib/src/domain/entities/theme_style.dart @@ -14,7 +14,11 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . +/// {@template theme_style} +/// Base class for all theme styles. +/// {@endtemplate} abstract class ThemeStyle { + /// {@macro theme_style} const ThemeStyle(); /// Merges non-null `other` attributes in `this` and returns a copy. diff --git a/packages/wyatt_ui_components/lib/src/features/component_theme.dart b/packages/wyatt_ui_components/lib/src/features/component_theme.dart index 0ed44487..c7dc79d3 100644 --- a/packages/wyatt_ui_components/lib/src/features/component_theme.dart +++ b/packages/wyatt_ui_components/lib/src/features/component_theme.dart @@ -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, diff --git a/packages/wyatt_ui_components/lib/src/features/component_theme_data.dart b/packages/wyatt_ui_components/lib/src/features/component_theme_data.dart index aaff531d..c08e2502 100644 --- a/packages/wyatt_ui_components/lib/src/features/component_theme_data.dart +++ b/packages/wyatt_ui_components/lib/src/features/component_theme_data.dart @@ -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({ diff --git a/packages/wyatt_ui_components/lib/wyatt_ui_components.dart b/packages/wyatt_ui_components/lib/wyatt_ui_components.dart index 3f16c3b1..e8cce321 100644 --- a/packages/wyatt_ui_components/lib/wyatt_ui_components.dart +++ b/packages/wyatt_ui_components/lib/wyatt_ui_components.dart @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . -/// Wyatt Ui Components +/// Wyatt UI Components library wyatt_ui_components; export 'src/src.dart'; diff --git a/packages/wyatt_ui_components/pubspec.yaml b/packages/wyatt_ui_components/pubspec.yaml index 81f439f9..eecf6f81 100644 --- a/packages/wyatt_ui_components/pubspec.yaml +++ b/packages/wyatt_ui_components/pubspec.yaml @@ -1,9 +1,9 @@ name: wyatt_ui_components -description: Primary ui components +description: Components that can be implemented in any application with copy constructor. repository: https://git.wyatt-studio.fr/Wyatt-FOSS/wyatt-packages/src/branch/master/packages/wyatt_ui_components version: 0.0.1 -publish_to: none +publish_to: https://git.wyatt-studio.fr/api/packages/Wyatt-FOSS/pub environment: sdk: ">=2.17.0 <3.0.0" @@ -12,9 +12,8 @@ dependencies: flutter: { sdk: flutter } copy_with_extension: ^5.0.0 wyatt_component_copy_with_extension: - git: - url: ssh://git@git.wyatt-studio.fr:993/Wyatt-FOSS/wyatt-packages.git - path: packages/wyatt_component_copy_with_extension + hosted: https://git.wyatt-studio.fr/api/packages/Wyatt-FOSS/pub + version: ^1.0.0 dev_dependencies: flutter_test: { sdk: flutter } @@ -25,6 +24,5 @@ dev_dependencies: build_runner: ^2.3.3 copy_with_extension_gen: ^5.0.0 wyatt_component_copy_with_gen: - git: - url: ssh://git@git.wyatt-studio.fr:993/Wyatt-FOSS/wyatt-packages.git - path: packages/wyatt_component_copy_with_gen + hosted: https://git.wyatt-studio.fr/api/packages/Wyatt-FOSS/pub + version: ^1.0.0