diff --git a/packages/wyatt_authentication_bloc/lib/src/core/constants/form_field.dart b/packages/wyatt_authentication_bloc/lib/src/core/constants/form_field.dart index bbfc22e8..590e9ae6 100644 --- a/packages/wyatt_authentication_bloc/lib/src/core/constants/form_field.dart +++ b/packages/wyatt_authentication_bloc/lib/src/core/constants/form_field.dart @@ -18,8 +18,10 @@ abstract class AuthFormField { /// Email field: `wyattEmailField` static const email = 'wyattEmailField'; + /// Password field: `wyattPasswordField` static const password = 'wyattPasswordField'; + /// Confirm Password field: `wyattConfirmPasswordField` static const confirmPassword = 'wyattConfirmPasswordField'; } diff --git a/packages/wyatt_authentication_bloc/lib/src/core/constants/form_name.dart b/packages/wyatt_authentication_bloc/lib/src/core/constants/form_name.dart index 16f58cf0..17281b1e 100644 --- a/packages/wyatt_authentication_bloc/lib/src/core/constants/form_name.dart +++ b/packages/wyatt_authentication_bloc/lib/src/core/constants/form_name.dart @@ -18,10 +18,13 @@ abstract class AuthFormName { /// Sign Up form: `wyattSignUpForm` static const String signUpForm = 'wyattSignUpForm'; + /// Sign In form: `wyattSignInForm` static const String signInForm = 'wyattSignInForm'; + /// Password reset form: `wyattPasswordResetForm` static const String passwordResetForm = 'wyattPasswordResetForm'; + /// Edit account form: `wyattEditAccountForm` static const String editAccountForm = 'wyattEditAccountForm'; } diff --git a/packages/wyatt_authentication_bloc/lib/src/core/enums/authentication_status.dart b/packages/wyatt_authentication_bloc/lib/src/core/enums/authentication_status.dart index b88a7407..4a96cc46 100644 --- a/packages/wyatt_authentication_bloc/lib/src/core/enums/authentication_status.dart +++ b/packages/wyatt_authentication_bloc/lib/src/core/enums/authentication_status.dart @@ -18,8 +18,10 @@ enum AuthenticationStatus { /// At the application launch. unknown, + /// When the user is logged authenticated, + /// When the user is not logged unauthenticated, } diff --git a/packages/wyatt_authentication_bloc/lib/src/core/extensions/build_context_extension.dart b/packages/wyatt_authentication_bloc/lib/src/core/extensions/build_context_extension.dart index 83a4867c..d473dace 100644 --- a/packages/wyatt_authentication_bloc/lib/src/core/extensions/build_context_extension.dart +++ b/packages/wyatt_authentication_bloc/lib/src/core/extensions/build_context_extension.dart @@ -21,8 +21,8 @@ import 'package:wyatt_authentication_bloc/src/domain/entities/auth_session.dart' import 'package:wyatt_authentication_bloc/src/domain/entities/authentication_change_event/authentication_change_event.dart'; import 'package:wyatt_authentication_bloc/src/features/authentication/cubit/authentication_cubit.dart'; -/// Extension that helps to quickly access useful resources like wrapper, -/// session, account or data. +/// Extension that helps to quickly access useful resources +/// from the context. extension BuildContextExtension on BuildContext { /// Read session in context from a specific AuthenticationCubit type [T] AuthenticationSession? diff --git a/packages/wyatt_authentication_bloc/lib/src/core/utils/custom_routine.dart b/packages/wyatt_authentication_bloc/lib/src/core/utils/custom_routine.dart index bdd1eb7a..ff58f8df 100644 --- a/packages/wyatt_authentication_bloc/lib/src/core/utils/custom_routine.dart +++ b/packages/wyatt_authentication_bloc/lib/src/core/utils/custom_routine.dart @@ -20,10 +20,12 @@ import 'dart:async'; import 'package:wyatt_architecture/wyatt_architecture.dart'; import 'package:wyatt_type_utils/wyatt_type_utils.dart'; -/// Calls on each cubit action of this package. -/// -/// Useful to register custom logic on pre-implemented logic. +/// {@template custom_routine} +/// A custom routine that can be used to call a routine and +/// attach custom logic to it. +/// {@endtemplate} class CustomRoutine { + /// {@macro custom_routine} const CustomRoutine({ required this.routine, required this.attachedLogic, @@ -31,13 +33,21 @@ class CustomRoutine { required this.onSuccess, }); + /// The routine to be called final FutureOr> Function() routine; + + /// The custom logic to be attached to the routine final FutureOr> Function( Result routineResult, ) attachedLogic; + + /// The callback to be called when an error occurs final void Function(AppException exception) onError; + + /// The callback to be called when no error occurs final void Function(R result, Data? data) onSuccess; + /// Calls the routine and calls the custom attached logic FutureOr call() async { final result = await routine.call(); diff --git a/packages/wyatt_authentication_bloc/lib/src/core/utils/forms.dart b/packages/wyatt_authentication_bloc/lib/src/core/utils/forms.dart index f8f8bf17..ec95768b 100644 --- a/packages/wyatt_authentication_bloc/lib/src/core/utils/forms.dart +++ b/packages/wyatt_authentication_bloc/lib/src/core/utils/forms.dart @@ -17,7 +17,9 @@ import 'package:wyatt_authentication_bloc/wyatt_authentication_bloc.dart'; import 'package:wyatt_form_bloc/wyatt_form_bloc.dart'; +/// This class contains all the forms used in the authentication process. abstract class Forms { + /// Builds a sign in form. static WyattForm buildSignInForm( FormInputValidator? customEmailValidator, FormInputValidator? customPasswordValidator, @@ -36,6 +38,7 @@ abstract class Forms { name: AuthFormName.signInForm, ); + /// Builds a sign up form. static WyattForm buildSignUpForm( FormInputValidator? customEmailValidator, FormInputValidator? customPasswordValidator, @@ -57,6 +60,7 @@ abstract class Forms { name: AuthFormName.signUpForm, ); + /// Builds a password reset form. static WyattForm buildPasswordResetForm( FormInputValidator? customEmailValidator, ) => @@ -70,6 +74,7 @@ abstract class Forms { name: AuthFormName.passwordResetForm, ); + /// Builds an edit account form. static WyattForm buildEditAccountForm( FormInputValidator? customEmailValidator, FormInputValidator? customPasswordValidator, diff --git a/packages/wyatt_authentication_bloc/lib/src/data/models/account_model.dart b/packages/wyatt_authentication_bloc/lib/src/data/models/account_model.dart index cca70988..ebc29f93 100644 --- a/packages/wyatt_authentication_bloc/lib/src/data/models/account_model.dart +++ b/packages/wyatt_authentication_bloc/lib/src/data/models/account_model.dart @@ -18,8 +18,11 @@ import 'package:firebase_auth/firebase_auth.dart'; import 'package:wyatt_authentication_bloc/src/core/exceptions/exceptions.dart'; import 'package:wyatt_authentication_bloc/src/domain/entities/account.dart'; +/// {@template account_model} /// Account Model to parse Firebase User data +/// {@endtemplate} class AccountModel extends Account { + /// {@macro account_model} factory AccountModel.fromFirebaseUserCredential( UserCredential? userCredential, { required String? accessToken, @@ -47,6 +50,7 @@ class AccountModel extends Account { } } + /// {@macro account_model} factory AccountModel.fromFirebaseUser( User? user, { required String? accessToken, @@ -72,6 +76,7 @@ class AccountModel extends Account { throw ModelParsingFailureFirebase('null-user', 'User cannot be null'); } } + const AccountModel._({ required this.user, required super.id, @@ -87,6 +92,7 @@ class AccountModel extends Account { super.accessToken, }); + /// The Firebase User final User? user; @override diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/account.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/account.dart index ee6cd353..c0186496 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/account.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/account.dart @@ -17,9 +17,12 @@ import 'package:equatable/equatable.dart'; import 'package:wyatt_architecture/wyatt_architecture.dart'; -/// Represents a user [Account] in the +/// {@template account} +/// Represents a user [Account] in the /// various identity provisioning systems. +/// {@endtemplate} class Account extends Equatable implements Entity { + /// {@macro account} const Account({ required this.id, required this.isAnonymous, diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/auth_session.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/auth_session.dart index a5a37cf2..bdcbff74 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/auth_session.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/auth_session.dart @@ -17,16 +17,20 @@ import 'package:equatable/equatable.dart'; import 'package:wyatt_authentication_bloc/wyatt_authentication_bloc.dart'; +/// {@template authentication_session} /// The [AuthenticationSession] object is used to transport and propagate /// the last event issued by an authentication state change, a user account /// if connected, and the associated data. +/// {@endtemplate} class AuthenticationSession extends Equatable { + /// {@macro authentication_session} const AuthenticationSession({ required this.latestEvent, this.account, this.data, }); + /// Creates a new [AuthenticationSession] from an [AuthenticationChangeEvent]. factory AuthenticationSession.fromEvent( AuthenticationChangeEvent latestEvent, { Data? data, @@ -44,8 +48,13 @@ class AuthenticationSession extends Equatable { ); } + /// The last event issued by an authentication state change. final AuthenticationChangeEvent latestEvent; + + /// The user account if connected. final Account? account; + + /// The associated data. final Data? data; @override diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/authenticated_change_event.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/authenticated_change_event.dart index 03bb2d50..fb9487dd 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/authenticated_change_event.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/authenticated_change_event.dart @@ -16,11 +16,14 @@ part of 'authentication_change_event.dart'; - +/// {@template authenticated_change_event} /// Represents every event where user is authenticated. +/// {@endtemplate} abstract class AuthenticatedChangeEvent extends AuthenticationChangeEvent { + /// {@macro authenticated_change_event} const AuthenticatedChangeEvent({required this.account}); + /// The user's account. final Account account; @override diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/authentication_change_event.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/authentication_change_event.dart index 08312b7c..b32b68b4 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/authentication_change_event.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/authentication_change_event.dart @@ -29,9 +29,12 @@ part 'signed_up_event.dart'; part 'unknown_authentication_event.dart'; part 'updated_event.dart'; +/// {@template authentication_change_event} /// Represents an event initiated by a change in /// the user's authentication status. +/// {@endtemplate} abstract class AuthenticationChangeEvent extends Equatable implements Entity { + /// {@macro authentication_change_event} const AuthenticationChangeEvent(); @override diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/deleted_event.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/deleted_event.dart index 2eff8187..0ab52ae9 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/deleted_event.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/deleted_event.dart @@ -16,7 +16,10 @@ part of 'authentication_change_event.dart'; +/// {@template deleted_event} /// When a user deleted his account. +/// {@endtemplate} class DeletedEvent extends AuthenticationChangeEvent { + /// {@macro deleted_event} const DeletedEvent(); } diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/reauthenticated_event.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/reauthenticated_event.dart index 4cd8e13c..fa7e066a 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/reauthenticated_event.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/reauthenticated_event.dart @@ -16,9 +16,12 @@ part of 'authentication_change_event.dart'; +/// {@template reauthenticated_event} /// When a user re-authenticates (from the logged in state to the /// logged in state with a different and fresh access /// token and a different login time) +/// {@endtemplate} class ReauthenticatedEvent extends AuthenticatedChangeEvent { + /// {@macro reauthenticated_event} const ReauthenticatedEvent({required super.account}); } diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/refreshed_event.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/refreshed_event.dart index e2971cc4..f765c3cc 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/refreshed_event.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/refreshed_event.dart @@ -16,8 +16,11 @@ part of 'authentication_change_event.dart'; +/// {@template refreshed_event} /// When a user access token is refreshed (from the logged in state to the /// logged in state with a different access token) +/// {@endtemplate} class RefreshedEvent extends AuthenticatedChangeEvent { + /// {@macro refreshed_event} const RefreshedEvent({required super.account}); } diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_in_event.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_in_event.dart index 8d2fa0e3..17b2ae3e 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_in_event.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_in_event.dart @@ -16,7 +16,10 @@ part of 'authentication_change_event.dart'; +/// {@template signed_in_event} /// When a user authenticates (from not logged in to logged in). +/// {@endtemplate} class SignedInEvent extends AuthenticatedChangeEvent { + /// {@macro signed_in_event} const SignedInEvent({required super.account}); } diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_in_from_cache_event.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_in_from_cache_event.dart index a4e57dda..01bf868d 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_in_from_cache_event.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_in_from_cache_event.dart @@ -16,7 +16,10 @@ part of 'authentication_change_event.dart'; +/// {@template signed_in_from_cache_event} /// When a user authenticates automatically (from not logged in to logged in). +/// {@endtemplate} class SignedInFromCacheEvent extends AuthenticatedChangeEvent { + /// {@macro signed_in_from_cache_event} const SignedInFromCacheEvent({required super.account}); } diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_out_event.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_out_event.dart index e7579097..dc4ea4cd 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_out_event.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_out_event.dart @@ -16,7 +16,10 @@ part of 'authentication_change_event.dart'; +/// {@template signed_out_event} /// When a user logs out. +/// {@endtemplate} class SignedOutEvent extends AuthenticationChangeEvent { + /// {@macro signed_out_event} const SignedOutEvent(); } diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_up_event.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_up_event.dart index 903adbf1..f95f7e5e 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_up_event.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/signed_up_event.dart @@ -16,7 +16,10 @@ part of 'authentication_change_event.dart'; +/// {@template signed_up_event} /// When a user creates an account. +/// {@endtemplate} class SignedUpEvent extends AuthenticatedChangeEvent { + /// {@macro signed_up_event} const SignedUpEvent({required super.account}); } diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/unknown_authentication_event.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/unknown_authentication_event.dart index 93c56dec..287b53a0 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/unknown_authentication_event.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/unknown_authentication_event.dart @@ -16,7 +16,10 @@ part of 'authentication_change_event.dart'; +/// {@template unknown_authentication_event} /// When a user's login status is unknown. +/// {@endtemplate} class UnknownAuthenticationEvent extends AuthenticationChangeEvent { + /// {@macro unknown_authentication_event} const UnknownAuthenticationEvent(); } diff --git a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/updated_event.dart b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/updated_event.dart index 117cc725..2178a56e 100644 --- a/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/updated_event.dart +++ b/packages/wyatt_authentication_bloc/lib/src/domain/entities/authentication_change_event/updated_event.dart @@ -16,7 +16,10 @@ part of 'authentication_change_event.dart'; +/// {@template updated_event} /// When the user's account has been updated. +/// {@endtemplate} class UpdatedEvent extends AuthenticatedChangeEvent { + /// {@macro updated_event} const UpdatedEvent({required super.account}); } diff --git a/packages/wyatt_authentication_bloc/lib/src/features/authentication/builder/authentication_builder.dart b/packages/wyatt_authentication_bloc/lib/src/features/authentication/builder/authentication_builder.dart index 3c9f1999..46eb0a57 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/authentication/builder/authentication_builder.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/authentication/builder/authentication_builder.dart @@ -20,7 +20,11 @@ import 'package:wyatt_authentication_bloc/src/core/enums/authentication_status.d import 'package:wyatt_authentication_bloc/src/domain/entities/auth_session.dart'; import 'package:wyatt_authentication_bloc/src/features/authentication/cubit/authentication_cubit.dart'; +/// {@template authentication_builder} +/// A widget that builds itself based on the current authentication state. +/// {@endtemplate} class AuthenticationBuilder extends StatelessWidget { + /// {@macro authentication_builder} const AuthenticationBuilder({ required this.authenticated, required this.unauthenticated, @@ -28,11 +32,16 @@ class AuthenticationBuilder extends StatelessWidget { super.key, }); + /// Widget to show when the user is authenticated. final Widget Function( BuildContext context, AuthenticationSession session, ) authenticated; + + /// Widget to show when the user is unauthenticated. final Widget Function(BuildContext context) unauthenticated; + + /// Widget to show when the authentication status is unknown. final Widget Function(BuildContext context) unknown; @override diff --git a/packages/wyatt_authentication_bloc/lib/src/features/authentication/cubit/authentication_state.dart b/packages/wyatt_authentication_bloc/lib/src/features/authentication/cubit/authentication_state.dart index 1f3a1c72..8a51d674 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/authentication/cubit/authentication_state.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/authentication/cubit/authentication_state.dart @@ -16,22 +16,32 @@ part of 'authentication_cubit.dart'; +/// {@template authentication_status} +/// The status of the authentication cubit. +/// {@endtemplate} class AuthenticationState extends Equatable { + /// {@macro authentication_status} const AuthenticationState._(this.status, this.session); + /// The user is not authenticated. const AuthenticationState.unauthenticated() : this._(AuthenticationStatus.unauthenticated, null); + /// The user is authenticated. const AuthenticationState.authenticated(AuthenticationSession session) : this._( AuthenticationStatus.authenticated, session, ); + /// The user's authentication status is unknown. const AuthenticationState.unknown() : this._(AuthenticationStatus.unknown, null); + /// The status of the authentication cubit. final AuthenticationStatus status; + + /// The session of the authentication cubit. final AuthenticationSession? session; @override diff --git a/packages/wyatt_authentication_bloc/lib/src/features/edit_account/cubit/base_edit_account_cubit.dart b/packages/wyatt_authentication_bloc/lib/src/features/edit_account/cubit/base_edit_account_cubit.dart index 3d6ba12d..119e16fd 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/edit_account/cubit/base_edit_account_cubit.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/edit_account/cubit/base_edit_account_cubit.dart @@ -16,10 +16,13 @@ part of 'edit_account_cubit.dart'; +/// {@template edit_account_cubit} /// Abstract edit account cubit useful for implementing a cubit with fine /// granularity by adding only the required mixins. +/// {@endtemplate} abstract class BaseEditAccountCubit extends FormDataCubit { + /// {@macro edit_account_cubit} BaseEditAccountCubit({ required this.authenticationRepository, }) : super( @@ -28,6 +31,8 @@ abstract class BaseEditAccountCubit .accessForm(AuthFormName.signInForm), ), ); + + /// The authentication repository. final AuthenticationRepository authenticationRepository; FormRepository get formRepository => authenticationRepository.formRepository; diff --git a/packages/wyatt_authentication_bloc/lib/src/features/edit_account/cubit/edit_account_cubit.dart b/packages/wyatt_authentication_bloc/lib/src/features/edit_account/cubit/edit_account_cubit.dart index b3fcc2b2..abc378cc 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/edit_account/cubit/edit_account_cubit.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/edit_account/cubit/edit_account_cubit.dart @@ -28,11 +28,14 @@ import 'package:wyatt_type_utils/wyatt_type_utils.dart'; part 'base_edit_account_cubit.dart'; part 'edit_account_state.dart'; +/// {@template edit_account_cubit} /// Fully featured edit account cubit. /// /// Sufficient in most cases. (Where fine granularity is not required.) +/// {@endtemplate} class EditAccountCubit extends BaseEditAccountCubit with UpdateEmail, UpdatePassword { + /// {@macro edit_account_cubit} EditAccountCubit({required super.authenticationRepository}); @override diff --git a/packages/wyatt_authentication_bloc/lib/src/features/edit_account/cubit/edit_account_state.dart b/packages/wyatt_authentication_bloc/lib/src/features/edit_account/cubit/edit_account_state.dart index 0c8fbfba..d7dd5032 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/edit_account/cubit/edit_account_state.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/edit_account/cubit/edit_account_state.dart @@ -16,15 +16,22 @@ part of 'edit_account_cubit.dart'; +/// {@template edit_account_state} /// Edit account cubit state to manage the form. +/// {@endtemplate} class EditAccountState extends FormDataState { + /// {@macro edit_account_state} const EditAccountState({ required super.form, super.status = FormStatus.pure, super.errorMessage, }); + + /// Email validator of the form FormInputValidator get email => form.validatorOf(AuthFormField.email); + + /// Password validator of the form FormInputValidator get password => form.validatorOf(AuthFormField.password); diff --git a/packages/wyatt_authentication_bloc/lib/src/features/edit_account/listener/edit_account_listener.dart b/packages/wyatt_authentication_bloc/lib/src/features/edit_account/listener/edit_account_listener.dart index 62134eb5..9adcb5ec 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/edit_account/listener/edit_account_listener.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/edit_account/listener/edit_account_listener.dart @@ -19,9 +19,12 @@ import 'package:flutter_bloc/flutter_bloc.dart'; import 'package:wyatt_authentication_bloc/src/features/edit_account/cubit/edit_account_cubit.dart'; import 'package:wyatt_form_bloc/wyatt_form_bloc.dart'; +/// {@template edit_account_listener} /// Widget that listens and builds a child based on the state of /// the edit account cubit +/// {@endtemplate} class EditAccountListener extends StatelessWidget { + /// {@macro edit_account_listener} const EditAccountListener({ required this.child, this.onProgress, @@ -31,15 +34,25 @@ class EditAccountListener extends StatelessWidget { super.key, }); + /// Callback to show when the edit account is in progress final void Function(BuildContext context)? onProgress; + + /// Callback to show when the edit account is successful final void Function(BuildContext context)? onSuccess; + + /// Callback to show when the edit account is unsuccessful final void Function( BuildContext context, FormStatus status, String? errorMessage, )? onError; + + /// Custom builder to show when the edit account is in progress, successful, + /// or unsuccessful final void Function(BuildContext context, EditAccountState state)? customBuilder; + + /// Child of the widget final Widget child; @override diff --git a/packages/wyatt_authentication_bloc/lib/src/features/email_verification/builder/email_verification_builder.dart b/packages/wyatt_authentication_bloc/lib/src/features/email_verification/builder/email_verification_builder.dart index 0de3bdf3..c030260d 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/email_verification/builder/email_verification_builder.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/email_verification/builder/email_verification_builder.dart @@ -19,7 +19,11 @@ import 'package:flutter_bloc/flutter_bloc.dart'; import 'package:wyatt_authentication_bloc/src/features/email_verification/cubit/email_verification_cubit.dart'; import 'package:wyatt_form_bloc/wyatt_form_bloc.dart'; +/// {@template email_verification_builder} +/// A widget that builds itself based on the latest [EmailVerificationState]. +/// {@endtemplate} class EmailVerificationBuilder extends StatelessWidget { + /// {@macro email_verification_builder} const EmailVerificationBuilder({ required this.verified, required this.notVerified, @@ -28,14 +32,21 @@ class EmailVerificationBuilder extends StatelessWidget { super.key, }); + /// Widget to show when the email is verified final Widget Function(BuildContext context) verified; + + /// Widget to show when the email is not verified final Widget Function(BuildContext context) notVerified; + + /// Widget to show when the email verification is unsuccessful final Widget Function( BuildContext context, FormStatus status, String? errorMessage, ) onError; + /// Custom builder to show when the email is verified, not verified, or + /// unsuccessful final Widget Function(BuildContext context, EmailVerificationState)? customBuilder; diff --git a/packages/wyatt_authentication_bloc/lib/src/features/email_verification/cubit/email_verification_cubit.dart b/packages/wyatt_authentication_bloc/lib/src/features/email_verification/cubit/email_verification_cubit.dart index 56297baa..92227e52 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/email_verification/cubit/email_verification_cubit.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/email_verification/cubit/email_verification_cubit.dart @@ -23,11 +23,16 @@ import 'package:wyatt_form_bloc/wyatt_form_bloc.dart'; part 'email_verification_state.dart'; +/// {@template email_verification_cubit} +/// Cubit for sending email verification. +/// {@endtemplate} class EmailVerificationCubit extends Cubit { + /// {@macro email_verification_cubit} EmailVerificationCubit({ required this.authenticationRepository, }) : super(const EmailVerificationState()); + /// The [AuthenticationRepository] used to send email verification. final AuthenticationRepository authenticationRepository; FutureOr sendEmailVerification() async { diff --git a/packages/wyatt_authentication_bloc/lib/src/features/email_verification/cubit/email_verification_state.dart b/packages/wyatt_authentication_bloc/lib/src/features/email_verification/cubit/email_verification_state.dart index aa12191d..22ac24c7 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/email_verification/cubit/email_verification_state.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/email_verification/cubit/email_verification_state.dart @@ -16,15 +16,24 @@ part of 'email_verification_cubit.dart'; +/// {@template email_verification_state} +/// The state of the [EmailVerificationCubit]. +/// {@endtemplate} class EmailVerificationState extends Equatable { + /// {@macro email_verification_state} const EmailVerificationState({ this.isVerified = false, this.status = FormStatus.pure, this.errorMessage, }); + /// The status of the form. final FormStatus status; + + /// Whether the email is verified. final bool isVerified; + + /// The error message if any. final String? errorMessage; EmailVerificationState copyWith({ diff --git a/packages/wyatt_authentication_bloc/lib/src/features/password_reset/cubit/password_reset_cubit.dart b/packages/wyatt_authentication_bloc/lib/src/features/password_reset/cubit/password_reset_cubit.dart index c8624fc6..969528e3 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/password_reset/cubit/password_reset_cubit.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/password_reset/cubit/password_reset_cubit.dart @@ -24,8 +24,11 @@ import 'package:wyatt_type_utils/wyatt_type_utils.dart'; part 'password_reset_state.dart'; +/// {@template password_reset_cubit} /// Cubit that allows user to reset his password +/// {@endtemplate} class PasswordResetCubit extends FormDataCubit { + /// {@macro password_reset_cubit} PasswordResetCubit({ required this.authenticationRepository, }) : super( @@ -34,6 +37,8 @@ class PasswordResetCubit extends FormDataCubit { .accessForm(AuthFormName.passwordResetForm), ), ); + + /// The repository that handles the authentication final AuthenticationRepository authenticationRepository; FormRepository get formRepository => authenticationRepository.formRepository; diff --git a/packages/wyatt_authentication_bloc/lib/src/features/password_reset/cubit/password_reset_state.dart b/packages/wyatt_authentication_bloc/lib/src/features/password_reset/cubit/password_reset_state.dart index cace663f..eafbf6b6 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/password_reset/cubit/password_reset_state.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/password_reset/cubit/password_reset_state.dart @@ -16,12 +16,18 @@ part of 'password_reset_cubit.dart'; +/// {@template password_reset_state} +/// The state of the [PasswordResetCubit]. +/// {@endtemplate} class PasswordResetState extends FormDataState { + /// {@macro password_reset_state} const PasswordResetState({ required super.form, super.status = FormStatus.pure, super.errorMessage, }); + + /// The email validator of the form. Email get email => form.validatorOf(AuthFormField.email); PasswordResetState copyWith({ diff --git a/packages/wyatt_authentication_bloc/lib/src/features/sign_in/cubit/base_sign_in_cubit.dart b/packages/wyatt_authentication_bloc/lib/src/features/sign_in/cubit/base_sign_in_cubit.dart index bc55b6a8..3d59bee5 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/sign_in/cubit/base_sign_in_cubit.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/sign_in/cubit/base_sign_in_cubit.dart @@ -16,9 +16,12 @@ part of 'sign_in_cubit.dart'; -/// Abstract sign in cubit useful for implementing a cubit with fine +/// {@template sign_in_cubit} +/// Abstract sign in cubit useful for implementing a cubit with fine /// granularity by adding only the required mixins. +/// {@endtemplate} abstract class BaseSignInCubit extends FormDataCubit { + /// {@macro sign_in_cubit} BaseSignInCubit({ required this.authenticationRepository, }) : super( @@ -27,6 +30,8 @@ abstract class BaseSignInCubit extends FormDataCubit { .accessForm(AuthFormName.signInForm), ), ); + + /// The authentication repository. final AuthenticationRepository authenticationRepository; FormRepository get formRepository => authenticationRepository.formRepository; diff --git a/packages/wyatt_authentication_bloc/lib/src/features/sign_in/cubit/sign_in_cubit.dart b/packages/wyatt_authentication_bloc/lib/src/features/sign_in/cubit/sign_in_cubit.dart index f1f3ccd5..fbde339c 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/sign_in/cubit/sign_in_cubit.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/sign_in/cubit/sign_in_cubit.dart @@ -14,7 +14,6 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . - import 'dart:async'; import 'package:wyatt_architecture/wyatt_architecture.dart'; @@ -31,14 +30,17 @@ import 'package:wyatt_type_utils/wyatt_type_utils.dart'; part 'base_sign_in_cubit.dart'; part 'sign_in_state.dart'; +/// {@template sign_in_cubit} /// Fully featured sign in cubit. -/// +/// /// Sufficient in most cases. (Where fine granularity is not required.) +/// {@endtemplate} class SignInCubit extends BaseSignInCubit with SignInAnonymously, SignInWithEmailPassword, SignInWithGoogle { + /// {@macro sign_in_cubit} SignInCubit({required super.authenticationRepository}); @override diff --git a/packages/wyatt_authentication_bloc/lib/src/features/sign_in/cubit/sign_in_state.dart b/packages/wyatt_authentication_bloc/lib/src/features/sign_in/cubit/sign_in_state.dart index acb975b5..39ed623f 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/sign_in/cubit/sign_in_state.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/sign_in/cubit/sign_in_state.dart @@ -16,15 +16,22 @@ part of 'sign_in_cubit.dart'; +/// {@template sign_in_state} /// Sign in cubit state to manage the form. +/// {@endtemplate} class SignInState extends FormDataState { + /// {@macro sign_in_state} const SignInState({ required super.form, super.status = FormStatus.pure, super.errorMessage, }); + + /// Email validator of the form FormInputValidator get email => form.validatorOf(AuthFormField.email); + + /// Password validator of the form FormInputValidator get password => form.validatorOf(AuthFormField.password); diff --git a/packages/wyatt_authentication_bloc/lib/src/features/sign_in/listener/sign_in_listener.dart b/packages/wyatt_authentication_bloc/lib/src/features/sign_in/listener/sign_in_listener.dart index cc66ac36..2d55fe16 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/sign_in/listener/sign_in_listener.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/sign_in/listener/sign_in_listener.dart @@ -19,9 +19,12 @@ import 'package:flutter_bloc/flutter_bloc.dart'; import 'package:wyatt_authentication_bloc/src/features/sign_in/sign_in.dart'; import 'package:wyatt_form_bloc/wyatt_form_bloc.dart'; -/// Widget that listens and builds a child based on the state of +/// {@template sign_in_listener} +/// Widget that listens and builds a child based on the state of /// the sign in cubit +/// {@endtemplate} class SignInListener extends StatelessWidget { + /// {@macro sign_in_listener} const SignInListener({ required this.child, this.onProgress, @@ -31,14 +34,24 @@ class SignInListener extends StatelessWidget { super.key, }); + /// Callback to show when the sign in is in progress final void Function(BuildContext context)? onProgress; + + /// Callback to show when the sign in is successful final void Function(BuildContext context)? onSuccess; + + /// Callback to show when the sign in is unsuccessful final void Function( BuildContext context, FormStatus status, String? errorMessage, )? onError; + + /// Custom builder to show when the sign in is in progress, successful, or + /// unsuccessful final void Function(BuildContext context, SignInState state)? customBuilder; + + /// Child of the widget final Widget child; @override diff --git a/packages/wyatt_authentication_bloc/lib/src/features/sign_up/cubit/base_sign_up_cubit.dart b/packages/wyatt_authentication_bloc/lib/src/features/sign_up/cubit/base_sign_up_cubit.dart index 42747ce3..3691f4c5 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/sign_up/cubit/base_sign_up_cubit.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/sign_up/cubit/base_sign_up_cubit.dart @@ -16,9 +16,12 @@ part of 'sign_up_cubit.dart'; -/// Abstract sign up cubit useful for implementing a cubit with fine +/// {@template base_sign_up_cubit} +/// Abstract sign up cubit useful for implementing a cubit with fine /// granularity by adding only the required mixins. +/// {@endtemplate} abstract class BaseSignUpCubit extends FormDataCubit { + /// {@macro base_sign_up_cubit} BaseSignUpCubit({ required this.authenticationRepository, }) : super( @@ -27,6 +30,8 @@ abstract class BaseSignUpCubit extends FormDataCubit { .accessForm(AuthFormName.signUpForm), ), ); + + /// The authentication repository. final AuthenticationRepository authenticationRepository; FormRepository get formRepository => authenticationRepository.formRepository; diff --git a/packages/wyatt_authentication_bloc/lib/src/features/sign_up/cubit/sign_up_cubit.dart b/packages/wyatt_authentication_bloc/lib/src/features/sign_up/cubit/sign_up_cubit.dart index 75c285cf..09a76667 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/sign_up/cubit/sign_up_cubit.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/sign_up/cubit/sign_up_cubit.dart @@ -28,11 +28,14 @@ import 'package:wyatt_type_utils/wyatt_type_utils.dart'; part 'base_sign_up_cubit.dart'; part 'sign_up_state.dart'; +/// {@template sign_up_cubit} /// Fully featured sign up cubit. -/// +/// /// Sufficient in most cases. (Where fine granularity is not required.) +/// {@endtemplate} class SignUpCubit extends BaseSignUpCubit with SignUpWithEmailPassword { + /// {@macro sign_up_cubit} SignUpCubit({required super.authenticationRepository}); @override diff --git a/packages/wyatt_authentication_bloc/lib/src/features/sign_up/cubit/sign_up_state.dart b/packages/wyatt_authentication_bloc/lib/src/features/sign_up/cubit/sign_up_state.dart index a66a3693..ac04efd5 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/sign_up/cubit/sign_up_state.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/sign_up/cubit/sign_up_state.dart @@ -16,15 +16,22 @@ part of 'sign_up_cubit.dart'; +/// {@template sign_up_state} /// Sign up cubit state to manage the form. +/// {@endtemplate} class SignUpState extends FormDataState { + /// {@macro sign_up_state} const SignUpState({ required super.form, super.status = FormStatus.pure, super.errorMessage, }); + + /// Email validator of the form FormInputValidator get email => form.validatorOf(AuthFormField.email); + + /// Password validator of the form FormInputValidator get password => form.validatorOf(AuthFormField.password); @@ -42,7 +49,6 @@ class SignUpState extends FormDataState { @override List get props => [email, password, status, form]; - @override @override String toString() => 'SignUpState(status: ${status.name} ' '${(errorMessage != null) ? " [$errorMessage]" : ""}, $form)'; diff --git a/packages/wyatt_authentication_bloc/lib/src/features/sign_up/listener/sign_up_listener.dart b/packages/wyatt_authentication_bloc/lib/src/features/sign_up/listener/sign_up_listener.dart index 1493df64..b4e5ad39 100644 --- a/packages/wyatt_authentication_bloc/lib/src/features/sign_up/listener/sign_up_listener.dart +++ b/packages/wyatt_authentication_bloc/lib/src/features/sign_up/listener/sign_up_listener.dart @@ -19,9 +19,12 @@ import 'package:flutter_bloc/flutter_bloc.dart'; import 'package:wyatt_authentication_bloc/src/features/sign_up/cubit/sign_up_cubit.dart'; import 'package:wyatt_form_bloc/wyatt_form_bloc.dart'; -/// Widget that listens and builds a child based on the state of +/// {@template sign_up_listener} +/// Widget that listens and builds a child based on the state of /// the sign up cubit +/// {@endtemplate} class SignUpListener extends StatelessWidget { + /// {@macro sign_up_listener} const SignUpListener({ required this.child, this.onProgress, @@ -31,14 +34,24 @@ class SignUpListener extends StatelessWidget { super.key, }); + /// Callback to show when the sign up is in progress final void Function(BuildContext context)? onProgress; + + /// Callback to show when the sign up is successful final void Function(BuildContext context)? onSuccess; + + /// Callback to show when the sign up is unsuccessful final void Function( BuildContext context, FormStatus status, String? errorMessage, )? onError; + + /// Custom builder to show when the sign up is in progress, successful, or + /// unsuccessful final void Function(BuildContext context, SignUpState state)? customBuilder; + + /// Child of the widget final Widget child; @override