feat: Enhance keyboard scroll modifier (bringIntoView) to support different list types (#421)

- Enhance keyboard scroll modifier (`bringIntoView`) to support
different types of `ScrollableState`:
  - `ScrollState`
  - `LazyListState`
- Move the modifier into `uk.gov.android.ui.patterns.utils.scroll`
- Remove the old modifier

## Context

-
govuk-one-login/mobile-android-one-login-app#825 (comment)

DCMAW-19031

---------

Co-authored-by: Bianca Mihaila <bianca.mihaila@digital.cabinet-office.gov.uk>

Author: jonnyandrew

patterns/src/main/java/uk/gov/android/ui/patterns/centrealignedscreen/CentreAlignedScreen.kt

@@ -46,7 +46,7 @@ import uk.gov.android.ui.patterns.centrealignedscreen.CentreAlignedScreenDefault
 import uk.gov.android.ui.patterns.centrealignedscreen.CentreAlignedScreenDefaults.NoPadding
 import uk.gov.android.ui.patterns.centrealignedscreen.CentreAlignedScreenDefaults.VerticalPadding
 import uk.gov.android.ui.patterns.centrealignedscreen.CentreAlignedScreenTestTag.BODY_LAZY_COLUMN_TEST_TAG
-import uk.gov.android.ui.patterns.leftalignedscreen.bringIntoView
+import uk.gov.android.ui.patterns.utils.ModifierExtensions.bringIntoView
 import uk.gov.android.ui.patterns.utils.clearListSemanticsForTalkBack
 import uk.gov.android.ui.theme.m3.GdsTheme
 import uk.gov.android.ui.theme.m3.Typography

patterns/src/main/java/uk/gov/android/ui/patterns/errorscreen/v2/ErrorScreen.kt

@@ -39,7 +39,7 @@ import uk.gov.android.ui.patterns.errorscreen.v2.ErrorScreenDefaults.HorizontalP
 import uk.gov.android.ui.patterns.errorscreen.v2.ErrorScreenDefaults.VerticalPadding
 import uk.gov.android.ui.patterns.errorscreen.v2.ErrorScreenTitleTestTag.ERROR_BODY_LAZY_COLUMN_TEST_TAG
 import uk.gov.android.ui.patterns.errorscreen.v2.ErrorScreenTitleTestTag.ERROR_SCREEN_TITLE_TEST_TAG
-import uk.gov.android.ui.patterns.leftalignedscreen.bringIntoView
+import uk.gov.android.ui.patterns.utils.ModifierExtensions.bringIntoView
 import uk.gov.android.ui.patterns.utils.clearListSemanticsForTalkBack
 import uk.gov.android.ui.theme.m3.GdsTheme
 import uk.gov.android.ui.theme.meta.ExcludeFromJacocoGeneratedReport

patterns/src/main/java/uk/gov/android/ui/patterns/leftalignedscreen/LeftAlignedScreen.kt

@@ -36,6 +36,7 @@ import uk.gov.android.ui.patterns.leftalignedscreen.LeftAlignedScreenTestTag.BOD
 import uk.gov.android.ui.patterns.utils.clearListSemanticsForTalkBack
 import uk.gov.android.ui.theme.m3.GdsTheme
 import uk.gov.android.ui.theme.spacingDouble
+import uk.gov.android.ui.patterns.utils.ModifierExtensions.bringIntoView as bringIntoViewV2
 
 private const val ONE_THIRD = 1f / 3f
 private const val FONT_SCALE_DOUBLE = 2f
@@ -324,7 +325,7 @@ private fun MainContent(
     val columnModifier = if (forceScroll) {
         Modifier
             .fillMaxSize()
-            .bringIntoView(scrollState)
+            .bringIntoViewV2(scrollState)
     } else {
         Modifier.fillMaxSize()
     }

patterns/src/main/java/uk/gov/android/ui/patterns/leftalignedscreen/LeftAlignedScreenContentV2.kt

@@ -1,9 +1,6 @@
 package uk.gov.android.ui.patterns.leftalignedscreen
 
 import androidx.compose.foundation.Image
-import androidx.compose.foundation.focusable
-import androidx.compose.foundation.gestures.animateScrollBy
-import androidx.compose.foundation.interaction.MutableInteractionSource
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.PaddingValues
 import androidx.compose.foundation.layout.fillMaxWidth
@@ -15,20 +12,9 @@ import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.MaterialTheme.colorScheme
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.getValue
-import androidx.compose.runtime.remember
-import androidx.compose.runtime.rememberCoroutineScope
-import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
-import androidx.compose.ui.focus.FocusRequester
-import androidx.compose.ui.focus.focusRequester
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.graphics.vector.ImageVector
-import androidx.compose.ui.input.key.Key
-import androidx.compose.ui.input.key.KeyEventType
-import androidx.compose.ui.input.key.key
-import androidx.compose.ui.input.key.onKeyEvent
-import androidx.compose.ui.input.key.type
 import androidx.compose.ui.layout.ContentScale
 import androidx.compose.ui.res.painterResource
 import androidx.compose.ui.res.stringResource
@@ -37,7 +23,6 @@ import androidx.compose.ui.text.AnnotatedString
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.unit.Dp
 import kotlinx.collections.immutable.ImmutableList
-import kotlinx.coroutines.launch
 import uk.gov.android.ui.componentsv2.R
 import uk.gov.android.ui.componentsv2.button.ButtonTypeV2
 import uk.gov.android.ui.componentsv2.button.GdsButton
@@ -56,6 +41,7 @@ import uk.gov.android.ui.componentsv2.row.RowList
 import uk.gov.android.ui.componentsv2.supportingtext.GdsSupportingText
 import uk.gov.android.ui.componentsv2.warning.GdsWarningText
 import uk.gov.android.ui.theme.dividerThickness
+import uk.gov.android.ui.patterns.utils.ModifierExtensions.bringIntoView as bringIntoViewV2
 
 internal data class LeftAlignedScreenContentV2(
     val title: String,
@@ -359,39 +345,9 @@ private fun LazyListScope.toAnnotatedText(
  * @param scrollState [LazyListState] represents the list state
  * @return augmented [Modifier]
  */
+@Deprecated(
+    "Use uk.gov.android.ui.patterns.utils.scroll.bringIntoView",
+    level = DeprecationLevel.WARNING,
+)
 @Composable
-fun Modifier.bringIntoView(scrollState: LazyListState): Modifier {
-    val coroutineScope = rememberCoroutineScope()
-    val interactionSource = remember { MutableInteractionSource() }
-    val focusRequester = remember { FocusRequester() }
-    return this
-        .onKeyEvent {
-            when {
-                it.type == KeyEventType.KeyDown && it.key == Key.DirectionDown &&
-                    scrollState.canScrollForward -> {
-                    coroutineScope.launch {
-                        scrollState.animateScrollBy(
-                            SCROLL_MULTIPLIER * scrollState.layoutInfo.viewportSize.height,
-                        )
-                    }
-                    true
-                }
-
-                it.type == KeyEventType.KeyDown && it.key == Key.DirectionUp &&
-                    scrollState.canScrollBackward -> {
-                    coroutineScope.launch {
-                        scrollState.animateScrollBy(
-                            -SCROLL_MULTIPLIER * scrollState.layoutInfo.viewportSize.height,
-                        )
-                    }
-                    true
-                }
-
-                else -> false
-            }
-        }
-        .focusRequester(focusRequester)
-        .focusable(interactionSource = interactionSource)
-}
-
-private const val SCROLL_MULTIPLIER = 0.4f
+fun Modifier.bringIntoView(scrollState: LazyListState): Modifier = this.bringIntoViewV2(scrollState)

patterns/src/main/java/uk/gov/android/ui/patterns/utils/ModifierExtensions.kt

@@ -0,0 +1,71 @@
+package uk.gov.android.ui.patterns.utils
+
+import androidx.compose.foundation.ScrollState
+import androidx.compose.foundation.focusable
+import androidx.compose.foundation.gestures.ScrollableState
+import androidx.compose.foundation.gestures.animateScrollBy
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.lazy.LazyListState
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.focus.FocusRequester
+import androidx.compose.ui.focus.focusRequester
+import androidx.compose.ui.input.key.Key
+import androidx.compose.ui.input.key.KeyEventType
+import androidx.compose.ui.input.key.key
+import androidx.compose.ui.input.key.onKeyEvent
+import androidx.compose.ui.input.key.type
+import kotlinx.coroutines.launch
+
+object ModifierExtensions {
+    /**
+     * Adds a downwards and upwards scroll when a keyboard down or up arrow is pressed
+     *
+     * @param scrollState [ScrollState] represents the list state
+     * @return augmented [Modifier]
+     */
+    @Composable
+    fun Modifier.bringIntoView(scrollState: ScrollableState): Modifier {
+        val coroutineScope = rememberCoroutineScope()
+        val interactionSource = remember { MutableInteractionSource() }
+        val focusRequester = remember { FocusRequester() }
+        return this
+            .onKeyEvent {
+                when {
+                    it.type == KeyEventType.KeyDown && it.key == Key.DirectionDown &&
+                        scrollState.canScrollForward -> {
+                        coroutineScope.launch {
+                            scrollState.animateScrollBy(
+                                SCROLL_MULTIPLIER * scrollState.viewportHeight(),
+                            )
+                        }
+                        true
+                    }
+
+                    it.type == KeyEventType.KeyDown && it.key == Key.DirectionUp &&
+                        scrollState.canScrollBackward -> {
+                        coroutineScope.launch {
+                            scrollState.animateScrollBy(
+                                -SCROLL_MULTIPLIER * scrollState.viewportHeight(),
+                            )
+                        }
+                        true
+                    }
+
+                    else -> false
+                }
+            }
+            .focusRequester(focusRequester)
+            .focusable(interactionSource = interactionSource)
+    }
+
+    private fun ScrollableState.viewportHeight(): Float = when (this) {
+        is LazyListState -> layoutInfo.viewportSize.height.toFloat()
+        is ScrollState -> viewportSize.toFloat()
+        else -> error("scrollable type not yet supported")
+    }
+
+    private const val SCROLL_MULTIPLIER = 0.4f
+}

patterns/src/test/java/uk/gov/android/ui/patterns/utils/BringIntoViewTest.kt

@@ -0,0 +1,184 @@
+package uk.gov.android.ui.patterns.utils
+
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.LazyListState
+import androidx.compose.foundation.lazy.rememberLazyListState
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.text.BasicText
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.focus.FocusRequester
+import androidx.compose.ui.focus.focusRequester
+import androidx.compose.ui.input.InputMode
+import androidx.compose.ui.input.InputModeManager
+import androidx.compose.ui.input.key.Key
+import androidx.compose.ui.platform.LocalInputModeManager
+import androidx.compose.ui.platform.testTag
+import androidx.compose.ui.test.ExperimentalTestApi
+import androidx.compose.ui.test.assertIsDisplayed
+import androidx.compose.ui.test.assertIsNotDisplayed
+import androidx.compose.ui.test.junit4.ComposeTestRule
+import androidx.compose.ui.test.junit4.createComposeRule
+import androidx.compose.ui.test.onNodeWithTag
+import androidx.compose.ui.test.onNodeWithText
+import androidx.compose.ui.test.performKeyInput
+import androidx.compose.ui.test.pressKey
+import androidx.compose.ui.unit.dp
+import org.junit.Rule
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import uk.gov.android.ui.patterns.utils.BringIntoViewTest.Companion.NUM_ITEMS
+import uk.gov.android.ui.patterns.utils.BringIntoViewTest.Companion.containerHeight
+import uk.gov.android.ui.patterns.utils.BringIntoViewTest.Companion.itemHeight
+import uk.gov.android.ui.patterns.utils.ModifierExtensions.bringIntoView
+
+@OptIn(ExperimentalTestApi::class)
+@RunWith(RobolectricTestRunner::class)
+class BringIntoViewTest {
+    @get:Rule
+    val composeTestRule = createComposeRule()
+
+    private val focusRequester = FocusRequester()
+
+    @Test
+    fun `keyboard can scroll down and up for non-lazy list`() {
+        setUpColumn()
+
+        composeTestRule.pressDirectionDown()
+        composeTestRule.onNodeWithText(FIRST_ITEM).assertIsNotDisplayed()
+
+        composeTestRule.pressDirectionUp()
+        composeTestRule.onNodeWithText(FIRST_ITEM).assertIsDisplayed()
+    }
+
+    @Test
+    fun `keyboard can scroll down then up for lazy list`() {
+        setUpLazyColumn()
+
+        composeTestRule.pressDirectionDown()
+        composeTestRule.onNodeWithText(FIRST_ITEM).assertIsNotDisplayed()
+
+        composeTestRule.pressDirectionUp()
+        composeTestRule.onNodeWithText(FIRST_ITEM).assertIsDisplayed()
+    }
+
+    @Test
+    fun `keyboard does not scroll down when content fits`() {
+        setUpColumn(numItems = 1)
+
+        composeTestRule.onNodeWithText(FIRST_ITEM).assertIsDisplayed()
+
+        composeTestRule.pressDirectionDown()
+        composeTestRule.onNodeWithText(FIRST_ITEM).assertIsDisplayed()
+    }
+
+    @Test
+    fun `keyboard does not scroll up when already at top`() {
+        setUpColumn()
+
+        composeTestRule.onNodeWithText(FIRST_ITEM).assertIsDisplayed()
+
+        composeTestRule.pressDirectionUp()
+        composeTestRule.onNodeWithText(FIRST_ITEM).assertIsDisplayed()
+    }
+
+    private fun setUpColumn(
+        numItems: Int = NUM_ITEMS,
+    ) {
+        setContent {
+            val scrollState = rememberScrollState()
+            TestColumn(
+                scrollState = scrollState,
+                numItems = numItems,
+                modifier = Modifier
+                    .focusRequester(focusRequester)
+                    .bringIntoView(scrollState),
+            )
+        }
+    }
+
+    private fun setUpLazyColumn() {
+        setContent {
+            val listState = rememberLazyListState()
+            TestLazyColumn(
+                listState = listState,
+                modifier = Modifier
+                    .focusRequester(focusRequester)
+                    .bringIntoView(listState),
+            )
+        }
+    }
+
+    private fun setContent(content: @Composable () -> Unit) {
+        lateinit var inputModeManager: InputModeManager
+        composeTestRule.setContent {
+            inputModeManager = LocalInputModeManager.current
+            content()
+        }
+        composeTestRule.runOnIdle {
+            inputModeManager.requestInputMode(InputMode.Keyboard)
+            focusRequester.requestFocus()
+        }
+    }
+
+    private fun ComposeTestRule.pressDirectionUp() =
+        onNodeWithTag(TEST_TAG)
+            .performKeyInput { pressKey(Key.DirectionUp) }
+
+    private fun ComposeTestRule.pressDirectionDown() =
+        onNodeWithTag(TEST_TAG)
+            .performKeyInput { pressKey(Key.DirectionDown) }
+
+    companion object {
+        const val TEST_TAG = "bringIntoViewTest"
+        const val NUM_ITEMS = 50
+        const val FIRST_ITEM = "Item 0"
+        val containerHeight = 100.dp
+        val itemHeight = 30.dp
+    }
+}
+
+@Composable
+private fun TestColumn(
+    scrollState: androidx.compose.foundation.ScrollState,
+    modifier: Modifier = Modifier,
+    numItems: Int = NUM_ITEMS,
+) =
+    Column(
+        modifier = modifier
+            .height(containerHeight)
+            .verticalScroll(scrollState)
+            .testTag(BringIntoViewTest.TEST_TAG),
+    ) {
+        repeat(numItems) { index ->
+            BasicText(
+                text = "Item $index",
+                modifier = Modifier.fillMaxWidth().height(itemHeight),
+            )
+        }
+    }
+
+@Composable
+private fun TestLazyColumn(
+    listState: LazyListState,
+    modifier: Modifier = Modifier,
+    numItems: Int = NUM_ITEMS,
+) =
+    LazyColumn(
+        state = listState,
+        modifier = modifier
+            .height(containerHeight)
+            .testTag(BringIntoViewTest.TEST_TAG),
+    ) {
+        items(numItems) { index ->
+            BasicText(
+                text = "Item $index",
+                modifier = Modifier.fillMaxWidth().height(itemHeight),
+            )
+        }
+    }