Fixes #5572 : Softer redirection for learners who need to revisit earlier cards

app/src/sharedTest/java/org/oppia/android/app/player/state/StateFragmentTest.kt

@@ -5238,6 +5238,52 @@ class StateFragmentTest {
     }
   }
 
+  @Test
+  fun testStateFragment_usesSofterRedirection_afterRevisitingEarlierCard() {
+    setUpTestWithLanguageSwitchingFeatureOff()
+    launchForExploration(RATIOS_EXPLORATION_ID_0, shouldSavePartialProgress = false).use {
+      startPlayingExploration()
+
+      playThroughRatioExplorationState1()
+      playThroughRatioExplorationState2()
+      playThroughRatioExplorationState3()
+      playThroughRatioExplorationState4()
+      playThroughRatioExplorationState5()
+      playThroughRatioExplorationState6()
+      playThroughRatioExplorationState7()
+      playThroughRatioExplorationState8()
+      playThroughRatioExplorationState9()
+      playThroughRatioExplorationState10()
+      playThroughRatioExplorationState11()
+      playThroughRatioExplorationState12()
+      playThroughRatioExplorationState13()
+      playThroughRatioExplorationState14()
+      playThroughRatioExplorationState15()
+
+      onView(
+        atPositionOnView(
+          recyclerViewId = R.id.selection_interaction_recyclerview,
+          position = 1,
+          targetViewId = R.id.multiple_choice_content_text_view
+        )
+      ).perform(click())
+      clickSubmitAnswerButton()
+      clickContinueNavigationButton()
+
+      scrollToViewType(NEXT_NAVIGATION_BUTTON)
+      onView(withId(R.id.next_state_navigation_button)).check(matches(isDisplayed()))
+      onView(withId(R.id.feedback_text_view))
+        .check(matches(withText(containsString("Please continue."))))
+
+      clickNextNavigationButton()
+      clickNextNavigationButton()
+      clickNextNavigationButton()
+      clickNextNavigationButton()
+
+      verifySubmitAnswerButtonIsEnabled()
+    }
+  }
+
   private fun playThroughRatioExplorationState1() {
     clickContinueInteractionButton()
   }
@@ -5311,6 +5357,12 @@ class StateFragmentTest {
     clickContinueNavigationButton()
   }
 
+  private fun playThroughRatioExplorationState15() {
+    typeTextInput("2:1")
+    clickSubmitAnswerButton()
+    clickContinueNavigationButton()
+  }
+
   private fun addShadowMediaPlayerException(dataSource: Any, exception: Exception) {
     val classLoader = StateFragmentTest::class.java.classLoader!!
     val shadowMediaPlayerClass = classLoader.loadClass("org.robolectric.shadows.ShadowMediaPlayer")

domain/src/main/java/org/oppia/android/domain/exploration/ExplorationProgressController.kt

@@ -699,6 +699,14 @@ class ExplorationProgressController @Inject constructor(
         when {
           answerOutcome.destinationCase == AnswerOutcome.DestinationCase.STATE_NAME -> {
             endState()
+            // Determines if a revision is required for the user based on the answer outcome.
+            if (!answerOutcome.labelledAsCorrectAnswer &&
+              answerOutcome.feedback.contentId.contains("feedback", true)
+            ) {
+              explorationProgress.stateDeck.turnOnRevisitEarlierCard(true)
+            } else {
+              explorationProgress.stateDeck.turnOnRevisitEarlierCard(false)
+            }
             val newState = explorationProgress.stateGraph.getState(answerOutcome.stateName)
             explorationProgress.stateDeck.pushState(
               newState,

domain/src/main/java/org/oppia/android/domain/state/StateDeck.kt

@@ -24,6 +24,7 @@ class StateDeck constructor(
   private val previousStates: MutableList<EphemeralState> = ArrayList()
   private val currentDialogInteractions: MutableList<AnswerAndResponse> = ArrayList()
   private var stateIndex: Int = 0
+  private var shouldRevisitEarlierCard: Boolean = false
 
   /** Resets this deck to a new, specified initial [State]. */
   fun resetDeck(initialState: State) {
@@ -46,6 +47,7 @@ class StateDeck constructor(
     this.previousStates.addAll(previousStates)
     this.currentDialogInteractions.addAll(currentDialogInteractions)
     this.stateIndex = stateIndex
+    if (getStateIndexOfEarlierCard(pendingTopState.name) != null) shouldRevisitEarlierCard = true
   }
 
   /** Navigates to the previous state in the deck, or fails if this isn't possible. */
@@ -57,12 +59,19 @@ class StateDeck constructor(
   /** Navigates to the next state in the deck, or fails if this isn't possible. */
   fun navigateToNextState() {
     check(!isCurrentStateTopOfDeck()) { "Cannot navigate to next state; at most recent state." }
-    val previousState = previousStates[stateIndex]
-    stateIndex++
-    if (!previousState.hasNextState) {
-      // Update the previous state to indicate that it has a next state now that its next state has
-      // actually been reated' by navigating to it.
-      previousStates[stateIndex - 1] = previousState.toBuilder().setHasNextState(true).build()
+
+    val revisionIdx = getStateIndexOfEarlierCard(pendingTopState.name)
+
+    if (revisionIdx != null && stateIndex == previousStates.size - 1 && shouldRevisitEarlierCard) {
+      handleRevisitEarlierCard(revisionIdx)
+    } else {
+      val previousState = previousStates[stateIndex]
+      stateIndex++
+      if (!previousState.hasNextState) {
+        // Update the previous state to indicate that it has a next state now that its next state has
+        // actually been created' by navigating to it.
+        previousStates[stateIndex - 1] = previousState.toBuilder().setHasNextState(true).build()
+      }
     }
   }
 
@@ -151,7 +160,9 @@ class StateDeck constructor(
       .setContinueButtonAnimationTimestampMs(timestamp)
       .setShowContinueButtonAnimation(!isContinueButtonAnimationSeen && isCurrentStateInitial())
       .build()
-    currentDialogInteractions.clear()
+    if (!shouldRevisitEarlierCard || getStateIndexOfEarlierCard(state.name) == null) {
+      currentDialogInteractions.clear()
+    }
     pendingTopState = state
   }
 
@@ -251,4 +262,52 @@ class StateDeck constructor(
   private fun isTopOfDeckTerminal(): Boolean {
     return isTopOfDeckTerminalChecker(pendingTopState)
   }
+
+  /**
+   * Handles revisiting an earlier card when the user clicks the continue button.
+   *
+   * This function adjusts the state to facilitate revisiting a previously viewed card.
+   * - Removes the last added ephemeral state from [previousStates], which was added when user
+   *   submitted a wrong answer.
+   * - Updates [pendingTopState] to the current state with the stored [currentDialogInteractions],
+   *   marking it as a pending state where the user needs to submit a correct answer.
+   * - Updates [stateIndex] to the provided [revisionIdx].
+   * - Turns off the revisit mode by setting [shouldRevisitEarlierCard] to `false`.
+   *
+   * @param revisionIdx the index of the state to revisit.
+   */
+  private fun handleRevisitEarlierCard(revisionIdx: Int) {
+    val timestamp = previousStates[previousStates.size - 1].continueButtonAnimationTimestampMs
+    val showContinueButtonSeen =
+      previousStates[previousStates.size - 1].showContinueButtonAnimation
+    val currentState = previousStates[previousStates.size - 1].state
+
+    previousStates.removeAt(previousStates.size - 1)
+
+    pendingTopState = EphemeralState.newBuilder()
+      .setState(currentState)
+      .setHasPreviousState(!isCurrentStateInitial())
+      .setPendingState(PendingState.newBuilder().addAllWrongAnswer(currentDialogInteractions))
+      .setContinueButtonAnimationTimestampMs(timestamp)
+      .setShowContinueButtonAnimation(showContinueButtonSeen)
+      .build().state
+
+    stateIndex = revisionIdx
+    turnOnRevisitEarlierCard(false)
+  }
+
+  /** Returns [stateIndex] if state present on [previousStates] list. */
+  private fun getStateIndexOfEarlierCard(stateName: String): Int? {
+    for (i in previousStates.size - 1 downTo 0) {
+      if (previousStates[i].state.name == stateName) {
+        return i
+      }
+    }
+    return null
+  }
+
+  /** Sets whether the user should revisit an earlier card. */
+  fun turnOnRevisitEarlierCard(value: Boolean) {
+    shouldRevisitEarlierCard = value
+  }
 }