docs: Add docs for LoginScreen and LoginBloc.

Author: BURG3R5

lib/data/services/remote/api_service.dart

@@ -123,6 +123,7 @@ class ApiService {
     headers.addAll({'authorization': utils.authToken});
   }
 
+  /// Strict validation. Used after authentication.
   static bool _validateStrict(int? status) {
     if (status == 401) {
       utils.clearAuthToken();
@@ -131,6 +132,7 @@ class ApiService {
     return status! < 500;
   }
 
+  /// Looser validation. Used before authentication.
   static bool _validateLoose(int? status) {
     return status! < 500;
   }

lib/domain/models/status.dart

@@ -3,8 +3,15 @@ import 'package:freezed_annotation/freezed_annotation.dart';
 part 'status.freezed.dart';
 
 @freezed
+
+/// State of a screen.
 class Status with _$Status {
+  /// State of a screen.
   const factory Status([String? message]) = Idle;
+
+  /// State of a screen.
   const factory Status.loading() = Loading;
-  const factory Status.error(String message) = Error;
+
+  /// State of a screen.
+  const factory Status.error(String errorMessage) = Error;
 }

lib/domain/repositories/user_repository.dart

@@ -53,6 +53,7 @@ class UserRepository {
     return null;
   }
 
+  /// Logs in the user.
   static Future<String?> login({
     required String username,
     required String password,
@@ -76,7 +77,6 @@ class UserRepository {
           shouldPersist: rememberMe,
         );
         StorageService.user = await fetchUserDetails();
-
         return 'Success';
       case 401:
         return 'Unauthorized';
@@ -110,6 +110,7 @@ class UserRepository {
     return response['status_code'] == 200;
   }
 
+  /// Requests a password reset.
   static Future<bool?> resetPassword(String email) async {
     const endpoint = 'user/password-reset-email';
 

lib/presentation/SAMPLE

@@ -0,0 +1,62 @@
+import 'package:flutter/material.dart';
+
+import '../../../data/constants/colors.dart';
+import '../../../data/constants/styles.dart';
+
+/// App-wide common customization of [TextFormField].
+class TextInput extends StatelessWidget {
+  /// App-wide common customization of [TextFormField].
+  const TextInput({
+    required this.hint,
+    this.action = TextInputAction.next,
+    this.controller,
+    this.initialValue = '',
+    this.keyboard,
+    this.maxLines = 1,
+    this.obscureText = false,
+    this.onChanged,
+    this.prefix,
+    Key? key,
+  })  : assert(
+          controller != null || onChanged != null,
+          'Both controller and onChanged cannot be null',
+        ),
+        super(key: key);
+
+  final bool obscureText;
+  final int maxLines;
+  final String initialValue;
+  final String hint;
+  final Function(String)? onChanged;
+  final TextInputAction action;
+  final TextInputType? keyboard;
+  final TextEditingController? controller;
+  final Widget? prefix;
+
+  @override
+  Widget build(BuildContext context) {
+    return TextFormField(
+      controller: controller,
+      decoration: InputDecoration(
+        hintText: hint,
+        hintStyle: AppStyles.h6,
+        prefixIcon: prefix,
+        border: const OutlineInputBorder(
+          borderSide: BorderSide(color: AppColors.primary),
+        ),
+        focusedBorder: const OutlineInputBorder(
+          borderSide: BorderSide(
+            color: AppColors.primary,
+            width: 1.5,
+          ),
+        ),
+      ),
+      initialValue: controller == null ? initialValue : null,
+      keyboardType: keyboard,
+      maxLines: maxLines,
+      onChanged: onChanged,
+      style: AppStyles.h6.copyWith(color: AppColors.grey3),
+      textInputAction: action,
+    );
+  }
+}

lib/presentation/components/SAMPLE

@@ -12,7 +12,9 @@ part 'login_bloc.freezed.dart';
 part 'login_event.dart';
 part 'login_state.dart';
 
+/// The Bloc for the login screen.
 class LoginBloc extends Bloc<LoginEvent, LoginState> {
+  /// The Bloc for the login screen.
   LoginBloc() : super(const LoginState()) {
     on<ToggleDialog>(_toggleDialog);
     on<PasswordInput>(_updatePasswordInput);
@@ -25,7 +27,11 @@ class LoginBloc extends Bloc<LoginEvent, LoginState> {
   void _submitForm(Submit event, Emitter<LoginState> emit) async {
     if (!state.isFormFilled()) return;
 
-    emit(state.copyWith(status: const Status.loading()));
+    emit(state.copyWith(
+      isPasswordFocused: false,
+      isUsernameFocused: false,
+      status: const Status.loading(),
+    ));
 
     final result = await UserRepository.login(
       username: state.username,

lib/presentation/components/inputs/text_input.dart

@@ -1,13 +1,17 @@
 part of 'login_bloc.dart';
 
+/// Base event class for [LoginBloc].
 abstract class LoginEvent extends Equatable {
+  /// Base event class for [LoginBloc].
   const LoginEvent();
 
   @override
   List<Object?> get props => [];
 }
 
+/// Added when the text in the password field is changed.
 class PasswordInput extends LoginEvent {
+  /// Added when the text in the password field is changed.
   const PasswordInput(this.value);
 
   final String value;
@@ -16,28 +20,39 @@ class PasswordInput extends LoginEvent {
   List<Object> get props => [value];
 }
 
+/// Added when the login button is pressed.
 class Submit extends LoginEvent {
+  /// Added when the login button is pressed.
   const Submit();
 }
 
+/// Added when the "Forgot Password" button is pressed or the dialog is closed.
 class ToggleDialog extends LoginEvent {
+  /// Added when the "Forgot Password" button is pressed or the dialog is closed.
   const ToggleDialog({this.email});
 
+  /// Value entered in the text field in the dialog.
   final String? email;
 
   @override
   List<Object?> get props => [email];
 }
 
+/// Added when the password field's eye icon is pressed.
 class ToggleObscure extends LoginEvent {
+  /// Added when the password field's eye icon is pressed.
   const ToggleObscure();
 }
 
+/// Added when the "Keep me signed in" checkbox is toggled.
 class ToggleRememberMe extends LoginEvent {
+  /// Added when the "Keep me signed in" checkbox is toggled.
   const ToggleRememberMe();
 }
 
+/// Added when the text in the username field is changed.
 class UsernameInput extends LoginEvent {
+  /// Added when the text in the username field is changed.
   const UsernameInput(this.value);
 
   final String value;

lib/presentation/login/bloc/login_bloc.dart

@@ -1,21 +1,41 @@
 part of 'login_bloc.dart';
 
 @freezed
+
+/// State class for [LoginBloc].
 class LoginState with _$LoginState {
+  /// State class for [LoginBloc].
   const factory LoginState({
-    @Default(true) bool rememberMe,
+    /// Whether the username field is in focus.
     @Default(false) bool isUsernameFocused,
+
+    /// Whether the password field is in focus.
     @Default(false) bool isPasswordFocused,
+
+    /// Whether the password field should be obscured.
     @Default(true) bool obscurePassword,
+
+    /// State of the "Keep me signed in" checkbox.
+    @Default(true) bool rememberMe,
+
+    /// Whether the "Forgot Password" dialog should be displayed.
     @Default(false) bool showDialog,
+
+    /// State of the screen.
     @Default(Status()) Status status,
+
+    /// Value in the username field.
     @Default('') String username,
+
+    /// Value in the password field.
     @Default('') String password,
   }) = _LoginState;
 
   const LoginState._();
 
+  /// The form is considered filled when both fields are non-empty.
   bool isFormFilled() => username.isNotEmpty && password.isNotEmpty;
 
+  /// The login button is active when the form is filled and the screen is not loading.
   bool isLoginButtonActive() => isFormFilled() && status is! Loading;
 }

lib/presentation/login/bloc/login_event.dart

@@ -6,7 +6,9 @@ import '../../data/constants/styles.dart';
 import 'bloc/login_bloc.dart';
 import 'widgets/login_widgets.dart';
 
+/// The login screen widget.
 class LoginScreen extends StatelessWidget {
+  /// The login screen widget.
   const LoginScreen({Key? key}) : super(key: key);
 
   @override