chore(authenticator): Refactor step state instantiation (#25)

Author: mattcreaser

authenticator-screenshots/src/test/java/com/amplifyframework/ui/authenticator/MockAuthenticatorData.kt

@@ -25,10 +25,10 @@ import com.amplifyframework.ui.authenticator.forms.MutablePasswordFieldState
 
 fun mockForm(
     vararg fields: MutableFieldData,
-    submitting: Boolean = false
+    enabled: Boolean = true
 ) = object : MutableFormState {
     override val fields = fields.associateBy { it.config.key }
-    override val submitting = submitting
+    override var enabled = enabled
 }
 
 fun mockFieldData(
@@ -46,7 +46,7 @@ fun mockFieldState(
     error: FieldError? = null
 ) = object : MutableFieldState {
     override var content = content
-    override val error = error
+    override var error = error
 }
 
 fun mockPasswordFieldState(
@@ -56,5 +56,5 @@ fun mockPasswordFieldState(
 ) = object : MutablePasswordFieldState {
     override var fieldContentVisible = visible
     override var content = content
-    override val error: FieldError? = error
+    override var error: FieldError? = error
 }

authenticator/src/main/java/com/amplifyframework/ui/authenticator/AuthenticatorState.kt

@@ -62,9 +62,9 @@ fun rememberAuthenticatorState(
 @Stable
 interface AuthenticatorState {
     /**
-     * The state holder instance for the current content visible to the user.
+     * The state holder instance for the current [AuthenticatorStep] being shown to the user.
      */
-    val screenState: AuthenticatorScreenState
+    val stepState: AuthenticatorStepState
 
     /**
      * A flow of [AuthenticatorMessage] that may be presented to the user, such as messages indicating a
@@ -78,15 +78,15 @@ interface AuthenticatorState {
 internal class AuthenticatorStateImpl constructor(
     private val viewModel: AuthenticatorViewModel
 ) : AuthenticatorState {
-    override var screenState by mutableStateOf<AuthenticatorScreenState>(LoadingState)
+    override var stepState by mutableStateOf<AuthenticatorStepState>(LoadingState)
 
     override val messages: Flow<AuthenticatorMessage>
         get() = viewModel.events
 
     init {
         viewModel.viewModelScope.launch {
-            viewModel.screenState.collect {
-                screenState = it
+            viewModel.stepState.collect {
+                stepState = it
             }
         }
     }

authenticator/src/main/java/com/amplifyframework/ui/authenticator/AuthenticatorScreenState.kt renamed to authenticator/src/main/java/com/amplifyframework/ui/authenticator/AuthenticatorStepState.kt

@@ -27,18 +27,21 @@ import com.amplifyframework.ui.authenticator.enums.AuthenticatorStep
 import com.amplifyframework.ui.authenticator.forms.MutableFormState
 
 /**
- * A Screen State is a state holder for the UI for a specific [AuthenticatorStep].
+ * A state holder for the UI for a specific [AuthenticatorStep].
  */
 @Stable
-interface AuthenticatorScreenState {
+interface AuthenticatorStepState {
+    /**
+     * The [AuthenticatorStep] that this state holder represents.
+     */
     val step: AuthenticatorStep
 }
 
 /**
  * The Authenticator is loading the current state of the user's Auth session.
  */
 @Immutable
-object LoadingState : AuthenticatorScreenState {
+object LoadingState : AuthenticatorStepState {
     override val step = AuthenticatorStep.Loading
 }
 
@@ -47,15 +50,15 @@ object LoadingState : AuthenticatorScreenState {
  * @param error The error that occurred.
  */
 @Immutable
-data class ErrorState(val error: AuthException) : AuthenticatorScreenState {
+data class ErrorState(val error: AuthException) : AuthenticatorStepState {
     override val step = AuthenticatorStep.Error
 }
 
 /**
  * The user has completed the sign in process.
  */
 @Immutable
-interface SignedInState : AuthenticatorScreenState {
+interface SignedInState : AuthenticatorStepState {
     /**
      * The [AuthUser] instance for the signed in user.
      */
@@ -69,19 +72,23 @@ interface SignedInState : AuthenticatorScreenState {
 }
 
 /**
- * An [AuthenticatorScreenState] for a part of UI that contains an input form.
+ * The user is on the Sign In step. They can enter their Sign In information to authenticate with Amplify.
  */
 @Stable
-interface FormHolderState : AuthenticatorScreenState {
+interface SignInState : AuthenticatorStepState {
+    /**
+     * The input form state holder for this step.
+     */
     val form: MutableFormState
-}
 
-/**
- * The user is on the Sign In step. They can enter their Sign In information to authenticate with Amplify.
- */
-@Stable
-interface SignInState : FormHolderState {
+    /**
+     * Move the user to a different [AuthenticatorInitialStep].
+     */
     fun moveTo(step: AuthenticatorInitialStep)
+
+    /**
+     * Initiate a sign in with the information entered into the [form].
+     */
     suspend fun signIn()
 }
 
@@ -90,9 +97,25 @@ interface SignInState : FormHolderState {
  * message to complete the sign in process.
  */
 @Stable
-interface SignInConfirmMfaState : FormHolderState {
+interface SignInConfirmMfaState : AuthenticatorStepState {
+    /**
+     * The input form state holder for this step.
+     */
+    val form: MutableFormState
+
+    /**
+     * The [AuthCodeDeliveryDetails] for the confirmation code that was sent to the user when entering this state.
+     */
     val deliveryDetails: AuthCodeDeliveryDetails?
+
+    /**
+     * Move the user to a different [AuthenticatorInitialStep].
+     */
     fun moveTo(step: AuthenticatorInitialStep)
+
+    /**
+     * Confirm the user's sign in using the information entered into the [form].
+     */
     suspend fun confirmSignIn()
 }
 
@@ -101,10 +124,32 @@ interface SignInConfirmMfaState : FormHolderState {
  * challenge to complete the sign in process.
  */
 @Stable
-interface SignInConfirmCustomState : FormHolderState {
+interface SignInConfirmCustomState : AuthenticatorStepState {
+    /**
+     * The input form state holder for this step.
+     */
+    val form: MutableFormState
+
+    /**
+     * The additional info that is configured with your custom challenge. For more information, please see
+     * how to [sign in with a custom flow](https://docs.amplify.aws/lib/auth/signin_with_custom_flow/q/platform/android)
+     * in the Amplify documentation.
+     */
     val additionalInfo: Map<String, String>
+
+    /**
+     * The [AuthCodeDeliveryDetails] for the confirmation code that was sent to the user when entering this state.
+     */
     val deliveryDetails: AuthCodeDeliveryDetails?
+
+    /**
+     * Move the user to a different [AuthenticatorInitialStep].
+     */
     fun moveTo(step: AuthenticatorInitialStep)
+
+    /**
+     * Confirm the user's sign in using the information entered into the [form].
+     */
     suspend fun confirmSignIn()
 }
 
@@ -113,37 +158,93 @@ interface SignInConfirmCustomState : FormHolderState {
  * the sign in process.
  */
 @Stable
-interface SignInConfirmNewPasswordState : FormHolderState {
+interface SignInConfirmNewPasswordState : AuthenticatorStepState {
+    /**
+     * The input form state holder for this step.
+     */
+    val form: MutableFormState
+
+    /**
+     * Move the user to a different [AuthenticatorInitialStep].
+     */
     fun moveTo(step: AuthenticatorInitialStep)
+
+    /**
+     * Confirm the user's sign in using the information entered into the [form].
+     */
     suspend fun confirmSignIn()
 }
 
 /**
  * The user is on the Sign Up step, and can fill out the account creation form to Sign Up.
  */
 @Stable
-interface SignUpState : FormHolderState {
+interface SignUpState : AuthenticatorStepState {
+    /**
+     * The input form state holder for this step.
+     */
+    val form: MutableFormState
+
+    /**
+     * Move the user to a different [AuthenticatorInitialStep].
+     */
     fun moveTo(step: AuthenticatorInitialStep)
+
+    /**
+     * Initiate the sign up using the information entered into the [form].
+     */
     suspend fun signUp()
 }
 
 /**
  * The user has signed up, but needs to enter a confirmation code sent to them.
  */
 @Stable
-interface SignUpConfirmState : FormHolderState {
+interface SignUpConfirmState : AuthenticatorStepState {
+    /**
+     * The input form state holder for this step.
+     */
+    val form: MutableFormState
+
+    /**
+     * The [AuthCodeDeliveryDetails] for the confirmation code that was sent to the user when entering this state.
+     */
     val deliveryDetails: AuthCodeDeliveryDetails?
+
+    /**
+     * Move the user to a different [AuthenticatorInitialStep].
+     */
     fun moveTo(step: AuthenticatorInitialStep)
+
+    /**
+     * Confirm the sign up using the information entered into the [form].
+     */
     suspend fun confirmSignUp()
+
+    /**
+     * Re-send the confirmation code to the user.
+     */
     suspend fun resendCode()
 }
 
 /**
  * The user is on the Password Reset step. They can enter their username to begin the password reset.
  */
 @Stable
-interface PasswordResetState : FormHolderState {
+interface PasswordResetState : AuthenticatorStepState {
+    /**
+     * The input form state holder for this step.
+     */
+    val form: MutableFormState
+
+    /**
+     * Move the user to a different [AuthenticatorInitialStep].
+     */
     fun moveTo(step: AuthenticatorInitialStep)
+
+    /**
+     * Initiate the password reset using the information entered into the [form].
+     */
     suspend fun submitPasswordReset()
 }
 
@@ -152,17 +253,39 @@ interface PasswordResetState : FormHolderState {
  * password to complete the password reset.
  */
 @Stable
-interface PasswordResetConfirmState : FormHolderState {
+interface PasswordResetConfirmState : AuthenticatorStepState {
+    /**
+     * The input form state holder for this step.
+     */
+    val form: MutableFormState
+
+    /**
+     * The [AuthCodeDeliveryDetails] for the confirmation code that was sent to the user when entering this state.
+     */
     val deliveryDetails: AuthCodeDeliveryDetails?
+
+    /**
+     * Move the user to a different [AuthenticatorInitialStep].
+     */
     fun moveTo(step: AuthenticatorInitialStep)
+
+    /**
+     * Confirm the password reset using the information entered into the [form].
+     */
     suspend fun submitPasswordResetConfirm()
 }
 
 /**
- * The user has successfully signed in and their account is confirmed, however they do not have any means of account recovery (email, phone) that is confirmed.
+ * The user has successfully signed in and their account is confirmed, however they do not have any means of account
+ * recovery (email, phone) that is confirmed.
  */
 @Stable
-interface VerifyUserState : FormHolderState {
+interface VerifyUserState : AuthenticatorStepState {
+    /**
+     * The input form state holder for this step.
+     */
+    val form: MutableFormState
+
     /**
      * The list of unverified attributes.
      */
@@ -174,16 +297,22 @@ interface VerifyUserState : FormHolderState {
     suspend fun verifyUser()
 
     /**
-     * Skip verification and move to the Signed In state
+     * Skip verification and move to the Signed In state.
      */
     fun skip()
 }
 
 /**
- * The user has initiated verification of an account recovery mechanism (email, phone) and needs to provide a confirmation code.
+ * The user has initiated verification of an account recovery mechanism (email, phone) and needs to provide a
+ * confirmation code.
  */
 @Stable
-interface VerifyUserConfirmState : FormHolderState {
+interface VerifyUserConfirmState : AuthenticatorStepState {
+    /**
+     * The input form state holder for this step.
+     */
+    val form: MutableFormState
+
     /**
      * The details of where the verification code was sent.
      */
@@ -200,7 +329,7 @@ interface VerifyUserConfirmState : FormHolderState {
     suspend fun resendCode()
 
     /**
-     * Skip verification and move to the Signed In state
+     * Skip verification and move to the Signed In state.
      */
     fun skip()
 }