diff --git a/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/di/SavingsApplicationModule.kt b/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/di/SavingsApplicationModule.kt index 5b6c211d30..29c248b68d 100644 --- a/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/di/SavingsApplicationModule.kt +++ b/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/di/SavingsApplicationModule.kt @@ -14,7 +14,21 @@ import org.koin.dsl.module import org.mifos.mobile.feature.savings.application.fillApplication.SavingsFillApplicationViewModel import org.mifos.mobile.feature.savings.application.savingsApplication.SavingsApplyViewModel +/** + * Koin module for providing dependencies related to the Savings Application feature. + * + * This module declares the ViewModels used in the savings account application process, + * allowing Koin's dependency injection framework to construct and provide them where needed. + */ val savingsApplicationModule = module { + /** + * Provides an instance of [SavingsApplyViewModel]. + * This ViewModel manages the logic for the initial savings application screen. + */ viewModelOf(::SavingsApplyViewModel) + /** + * Provides an instance of [SavingsFillApplicationViewModel]. + * This ViewModel handles the logic for filling out the details of a new savings application. + */ viewModelOf(::SavingsFillApplicationViewModel) } diff --git a/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/fillApplication/FillApplicationRoute.kt b/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/fillApplication/FillApplicationRoute.kt index f1a941075d..3f4b0dff5c 100644 --- a/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/fillApplication/FillApplicationRoute.kt +++ b/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/fillApplication/FillApplicationRoute.kt @@ -17,6 +17,16 @@ import androidx.navigation.NavOptions import kotlinx.serialization.Serializable import org.mifos.mobile.core.ui.composableWithSlideTransitions +/** + * A type-safe, serializable route for the "Fill Savings Application" screen. + * + * This class encapsulates the necessary parameters required to fill out a new + * savings account application, ensuring robust and error-free navigation. + * + * @property savingsProductId The unique identifier of the selected savings product. + * @property fieldOfficerId The unique identifier of the assigned field officer. + * @property fieldOfficerName The name of the assigned field officer. + */ @Serializable data class SavingsFillApplicationRoute( val savingsProductId: Long, @@ -24,6 +34,18 @@ data class SavingsFillApplicationRoute( val fieldOfficerName: String, ) +/** + * Navigates to the "Fill Savings Application" screen. + * + * This is an extension function on [NavController] that simplifies the process + * of navigating to the application form by constructing and passing the + * [SavingsFillApplicationRoute] with the required product and officer details. + * + * @param savingsProductId The ID of the savings product. + * @param fieldOfficerId The ID of the field officer. + * @param fieldOfficerName The name of the field officer. + * @param navOptions Optional [NavOptions] to apply to this navigation operation. + */ fun NavController.navigateToSavingsFillApplicationScreen( savingsProductId: Long, fieldOfficerId: Long, @@ -33,6 +55,19 @@ fun NavController.navigateToSavingsFillApplicationScreen( this.navigate(SavingsFillApplicationRoute(savingsProductId, fieldOfficerId, fieldOfficerName), navOptions) } +/** + * Defines the composable destination for the "Fill Savings Application" screen + * within the navigation graph. + * + * This function sets up the route and the screen content (`SavingsFillApplicationScreen`), + * and wires up the necessary navigation callbacks for actions initiated from the screen. + * + * @param navigateToAuthenticateScreen A lambda to navigate to an authentication screen, + * typically required before submitting the application. + * @param navigateToStatusScreen A lambda to navigate to a generic status/result screen + * after the application submission is complete. + * @param navigateBack A lambda function to handle the back navigation event. + */ fun NavGraphBuilder.savingsFillApplicationDestination( navigateToAuthenticateScreen: () -> Unit, navigateToStatusScreen: (String, String, String, String, String) -> Unit, diff --git a/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/fillApplication/FillApplicationScreen.kt b/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/fillApplication/FillApplicationScreen.kt index 9570c6a3a1..9d2a206d98 100644 --- a/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/fillApplication/FillApplicationScreen.kt +++ b/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/fillApplication/FillApplicationScreen.kt @@ -63,6 +63,17 @@ import org.mifos.mobile.core.ui.component.MifosProgressIndicatorOverlay import org.mifos.mobile.core.ui.utils.EventsEffect import org.mifos.mobile.core.ui.utils.ScreenUiState +/** + * A stateful composable serving as the entry point for the "Fill Savings Application" screen. + * + * This function connects to the [SavingsFillApplicationViewModel] to observe state, handle UI + * events, and orchestrate navigation based on user actions and ViewModel commands. + * + * @param navigateBack A lambda to handle the back navigation event. + * @param navigateToStatusScreen A lambda to navigate to a generic status screen after an operation. + * @param navigateToAuthenticateScreen A lambda to navigate to an authentication screen for sensitive actions. + * @param viewModel The ViewModel responsible for the screen's logic and state. + */ @Composable internal fun SavingsFillApplicationScreen( navigateBack: () -> Unit, @@ -106,6 +117,16 @@ internal fun SavingsFillApplicationScreen( ) } +/** + * A composable responsible for displaying dialogs based on the [SavingsApplicationDialogState]. + * + * This function handles the presentation of error dialogs and confirmation dialogs + * for unsaved changes. + * + * @param state The current [SavingsApplicationState] used for context like network status. + * @param dialogState The current state of the dialog to be displayed. + * @param onAction A callback to send actions (like dismiss or confirm) to the ViewModel. + */ @Composable internal fun SavingsFillApplicationDialog( state: SavingsApplicationState, @@ -135,6 +156,16 @@ internal fun SavingsFillApplicationDialog( } } +/** + * A stateless composable that renders the main UI for the "Fill Savings Application" screen. + * + * It conditionally displays UI based on the [ScreenUiState] (e.g., loading, error, success). + * The success state includes a form with various input fields for the application details. + * + * @param state The current [SavingsApplicationState] to render. + * @param onAction A callback to send user actions to the ViewModel. + * @param modifier The [Modifier] to be applied to the layout. + */ @Composable internal fun SavingsFillApplicationContent( state: SavingsApplicationState, diff --git a/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/navigation/SavingsApplicationNavGraph.kt b/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/navigation/SavingsApplicationNavGraph.kt index 8d2513f31d..767e6c6c85 100644 --- a/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/navigation/SavingsApplicationNavGraph.kt +++ b/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/navigation/SavingsApplicationNavGraph.kt @@ -19,13 +19,38 @@ import org.mifos.mobile.feature.savings.application.fillApplication.savingsFillA import org.mifos.mobile.feature.savings.application.savingsApplication.SavingsApplyRoute import org.mifos.mobile.feature.savings.application.savingsApplication.savingsApplyDestination +/** + * A type-safe, serializable object representing the route for the nested + * Savings Application navigation graph. + */ @Serializable data object SavingsApplicationNavGraph +/** + * Navigates to the Savings Application navigation graph. + * + * This is a convenience extension function on [NavController] that encapsulates + * the logic for navigating to the start of the savings application feature. + * + * @param navOptions Optional [NavOptions] to apply to this navigation operation. + */ fun NavController.navigateToSavingsApplicationGraph(navOptions: NavOptions? = null) { this.navigate(SavingsApplicationNavGraph, navOptions) } +/** + * Builds the nested navigation graph for the savings account application feature. + * + * This function defines all the destinations within the savings application module + * (product selection and form filling) and wires them together. It promotes a + * decoupled architecture by accepting lambdas for navigation to external screens. + * + * @param navController The [NavController] used for handling navigation events within the graph. + * @param navigateToAuthenticateScreen Lambda to navigate to an authentication screen, + * required before submitting the application. + * @param navigateToStatusScreen Lambda to navigate to a generic status/result screen + * after the application submission is complete. + */ fun NavGraphBuilder.savingsApplicationNavGraph( navController: NavController, navigateToAuthenticateScreen: () -> Unit, diff --git a/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/savingsApplication/SavingsApplyRoute.kt b/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/savingsApplication/SavingsApplyRoute.kt index 754f921401..198b120a4e 100644 --- a/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/savingsApplication/SavingsApplyRoute.kt +++ b/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/savingsApplication/SavingsApplyRoute.kt @@ -15,14 +15,38 @@ import androidx.navigation.NavOptions import kotlinx.serialization.Serializable import org.mifos.mobile.core.ui.composableWithSlideTransitions +/** + * A type-safe, serializable object representing the route for the initial + * "Apply for Savings Account" screen. This serves as the entry point for + * the savings application flow. + */ @Serializable data object SavingsApplyRoute +/** + * Navigates to the "Apply for Savings Account" screen. + * + * This is an extension function on [NavController] that simplifies navigating + * to the savings product selection screen. + * + * @param navOptions Optional [NavOptions] to apply to this navigation operation. + */ fun NavController.navigateToSavingsApplyScreen( navOptions: NavOptions? = null, ) = navigate(SavingsApplyRoute, navOptions) +/** + * Defines the composable destination for the "Apply for Savings Account" screen + * within the navigation graph. + * + * This function sets up the route, the screen content (`SavingsApplyScreen`), + * and wires up the navigation callbacks for actions initiated from this screen. + * + * @param navigateToFillDetailsScreen A lambda to navigate to the application form screen, + * passing the selected product ID, officer ID, and officer name. + * @param navigateBack A lambda function to handle the back navigation event. + */ fun NavGraphBuilder.savingsApplyDestination( navigateToFillDetailsScreen: (Long, Long, String) -> Unit, navigateBack: () -> Unit, diff --git a/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/savingsApplication/SavingsApplyScreen.kt b/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/savingsApplication/SavingsApplyScreen.kt index 292632eb3e..84fc901184 100644 --- a/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/savingsApplication/SavingsApplyScreen.kt +++ b/feature/savings-application/src/commonMain/kotlin/org/mifos/mobile/feature/savings/application/savingsApplication/SavingsApplyScreen.kt @@ -51,6 +51,18 @@ import org.mifos.mobile.core.ui.component.MifosProgressIndicatorOverlay import org.mifos.mobile.core.ui.utils.EventsEffect import org.mifos.mobile.core.ui.utils.ScreenUiState +/** + * A stateful composable that serves as the entry point for the "Apply for Savings" screen. + * + * This function connects to the [SavingsApplyViewModel] to observe UI state and handle + * one-time events. It is responsible for orchestrating navigation to the next step + * in the application process. + * + * @param navigateBack A lambda function to handle back navigation events. + * @param navigateToFillDetailsScreen A lambda to navigate to the detailed application form, + * passing product and officer information. + * @param viewModel The ViewModel responsible for the screen's logic and state. + */ @Composable internal fun SavingsApplyScreen( navigateBack: () -> Unit, @@ -87,6 +99,15 @@ internal fun SavingsApplyScreen( ) } +/** + * A composable responsible for displaying dialogs based on the [SavingsApplicationDialogState]. + * + * This function handles the presentation of error dialogs and confirmation dialogs + * for unsaved changes. + * + * @param dialogState The current state of the dialog to be displayed. + * @param onAction A callback to send actions (like dismiss or confirm) to the ViewModel. + */ @Composable internal fun SavingsAccountDialog( dialogState: SavingsApplicationDialogState?, @@ -114,6 +135,16 @@ internal fun SavingsAccountDialog( } } +/** + * A stateless composable that renders the main UI for the "Apply for Savings" screen. + * + * It conditionally displays UI based on the [ScreenUiState] (e.g., loading, error, success). + * The success state includes dropdowns for selecting a savings product and a field officer. + * + * @param state The current [SavingsApplicationState] to render. + * @param onAction A callback to send user actions to the ViewModel. + * @param modifier The [Modifier] to be applied to the layout. + */ @Composable internal fun SavingsAccountContent( state: SavingsApplicationState,