feat: Add keyboardScroll modifier and test matcher (#424)

## Changes

- Add `keyboardScroll` modifier to replace `bringIntoView`
- Deprecate the `bringIntoView` modifier
- Add `hasKeyboardScroll` matcher
- Use `hasKeyboardScroll` matcher to check for this behaviour in
relevant screen patterns

## Context

[DCMAW-19030](https://govukverify.atlassian.net/browse/DCMAW-19030)

`keyboardScroll` (formerly `bringIntoView`) enables scrolling using
keyboard up/down arrows.

This PR improves the naming of the modifier so it's clear what it does.

It also enables consumers to test for the presence of the modifier
rather than testing the behaviour directly, which is hard to do. The
behaviour of the modifier is already tested centrally in
`KeyboardScrollTest`.

## Evidence of the change

N/A

## Checklist

### Before creating the pull request

- [ ] Commit messages that conform to conventional commit messages.
- [ ] Ran the app locally ensuring it builds.
- [x] Tests pass locally.
- [x] Pull request has a clear title with a short description about the
feature or update.
- [x] Created a `draft` pull request if it's not ready for review.

### Before the CODEOWNERS review the pull request

- [x] Complete all Acceptance Criteria within Jira ticket.
- [x] Self-review code.
- [ ] Successfully run changes on a testing device.
- [ ] Complete automated Testing:
  * [x] Unit Tests.
  * [ ] Integration Tests.
  * [ ] Instrumentation / Emulator Tests.
- [ ] Review [Accessibility considerations].
- [ ] Handle PR comments.

### Before merging the pull request

- [ ] [Sonar cloud report] passes inspections for your PR.
- [ ] Resolve all comments.

[Sonar cloud report]:
https://sonarcloud.io/project/overview?id=di-mobile-android-ui
[Accessibility considerations]:
https://developer.android.com/guide/topics/ui/accessibility/testing


[DCMAW-19030]:
https://govukverify.atlassian.net/browse/DCMAW-19030?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Author: jonnyandrew

patterns/build.gradle.kts

@@ -92,6 +92,8 @@ dependencies {
     androidTestImplementation(libs.androidx.test.espresso.core)
     androidTestUtil(libs.androidx.test.orchestrator)
 
+    testFixturesApi(libs.androidx.ui.test.android)
+
     testImplementation(libs.androidx.ui.test.android)
     testImplementation(libs.androidx.ui.test.junit4.android)
     testImplementation(libs.arch.core)

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

@@ -45,7 +45,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.utils.ModifierExtensions.bringIntoView
+import uk.gov.android.ui.patterns.utils.ModifierExtensions.keyboardScroll
 import uk.gov.android.ui.patterns.utils.clearListSemanticsForTalkBack
 import uk.gov.android.ui.theme.m3.ExtraTypography
 import uk.gov.android.ui.theme.m3.GdsTheme
@@ -303,7 +303,7 @@ private fun MainContent(
         verticalArrangement = arrangement,
         modifier = modifier
             .fillMaxSize()
-            .bringIntoView(scrollState)
+            .keyboardScroll(scrollState)
             .testTag(BODY_LAZY_COLUMN_TEST_TAG)
             .clearListSemanticsForTalkBack(),
         state = scrollState,

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.utils.ModifierExtensions.bringIntoView
+import uk.gov.android.ui.patterns.utils.ModifierExtensions.keyboardScroll
 import uk.gov.android.ui.patterns.utils.clearListSemanticsForTalkBack
 import uk.gov.android.ui.theme.m3.GdsTheme
 import uk.gov.android.ui.theme.meta.ExcludeFromJacocoGeneratedReport
@@ -183,7 +183,7 @@ private fun MainContent(
         ),
         modifier = modifier
             .fillMaxSize()
-            .bringIntoView(scrollState)
+            .keyboardScroll(scrollState)
             .testTag(ERROR_BODY_LAZY_COLUMN_TEST_TAG)
             .clearListSemanticsForTalkBack(),
         state = scrollState,

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

@@ -33,10 +33,10 @@ import uk.gov.android.ui.componentsv2.heading.GdsHeading
 import uk.gov.android.ui.componentsv2.heading.GdsHeadingAlignment
 import uk.gov.android.ui.componentsv2.supportingtext.GdsSupportingText
 import uk.gov.android.ui.patterns.leftalignedscreen.LeftAlignedScreenTestTag.BODY_LAZY_COLUMN_TEST_TAG
+import uk.gov.android.ui.patterns.utils.ModifierExtensions.keyboardScroll
 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
@@ -325,7 +325,7 @@ private fun MainContent(
     val columnModifier = if (forceScroll) {
         Modifier
             .fillMaxSize()
-            .bringIntoViewV2(scrollState)
+            .keyboardScroll(scrollState)
     } else {
         Modifier.fillMaxSize()
     }

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

@@ -17,21 +17,32 @@ 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.semantics.SemanticsPropertyKey
+import androidx.compose.ui.semantics.SemanticsPropertyReceiver
+import androidx.compose.ui.semantics.semantics
 import kotlinx.coroutines.launch
 
 object ModifierExtensions {
+    internal val HasKeyboardScrollKey: SemanticsPropertyKey<Boolean> =
+        SemanticsPropertyKey("IsScrollableWithKeyboard")
+    internal var SemanticsPropertyReceiver.hasKeyboardScroll: Boolean by HasKeyboardScrollKey
+
     /**
-     * Adds a downwards and upwards scroll when a keyboard down or up arrow is pressed
+     * Adds a downwards and upwards scroll when a keyboard down or up arrow is pressed.
+     *
+     * If you need to check for the presence of this modifier in tests, use the
+     * `hasKeyboardScroll` matcher from the test fixtures.
      *
      * @param scrollState [ScrollState] represents the list state
      * @return augmented [Modifier]
      */
     @Composable
-    fun Modifier.bringIntoView(scrollState: ScrollableState): Modifier {
+    fun Modifier.keyboardScroll(scrollState: ScrollableState): Modifier {
         val coroutineScope = rememberCoroutineScope()
         val interactionSource = remember { MutableInteractionSource() }
         val focusRequester = remember { FocusRequester() }
         return this
+            .semantics { hasKeyboardScroll = true }
             .onKeyEvent {
                 when {
                     it.type == KeyEventType.KeyDown && it.key == Key.DirectionDown &&
@@ -61,6 +72,21 @@ object ModifierExtensions {
             .focusable(interactionSource = interactionSource)
     }
 
+    /**
+     * 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]
+     */
+    @Deprecated(
+        message = "Replace with keyboardScroll. Due to be removed 13th July 2026.",
+        replaceWith = ReplaceWith("keyboardScroll(scrollState)"),
+        level = DeprecationLevel.WARNING,
+    )
+    @Composable
+    fun Modifier.bringIntoView(scrollState: ScrollableState): Modifier =
+        keyboardScroll(scrollState)
+
     private fun ScrollableState.viewportHeight(): Float = when (this) {
         is LazyListState -> layoutInfo.viewportSize.height.toFloat()
         is ScrollState -> viewportSize.toFloat()

patterns/src/test/java/uk/gov/android/ui/patterns/centrealignedscreen/CentreAlignedScreenTest.kt

@@ -25,6 +25,7 @@ import uk.gov.android.ui.componentsv2.list.ListItem
 import uk.gov.android.ui.componentsv2.list.ListTitle
 import uk.gov.android.ui.componentsv2.list.TitleType
 import uk.gov.android.ui.patterns.testutils.Matchers.assertListSemanticsCleared
+import uk.gov.android.ui.patterns.utils.matchers.ScrollableWithKeyboardMatchers.hasKeyboardScroll
 
 @RunWith(RobolectricTestRunner::class)
 class CentreAlignedScreenTest {
@@ -164,4 +165,17 @@ class CentreAlignedScreenTest {
             .onNode(buttonContentDesc)
             .assertIsDisplayed()
     }
+
+    @Test
+    fun `lazy column has keyboard scroll enabled`() {
+        composeTestRule.setContent {
+            CentreAlignedScreen(
+                title = { },
+            )
+        }
+
+        composeTestRule
+            .onNodeWithTag(CentreAlignedScreenTestTag.BODY_LAZY_COLUMN_TEST_TAG)
+            .assert(hasKeyboardScroll())
+    }
 }

patterns/src/test/java/uk/gov/android/ui/patterns/errorscreen/v2/ErrorScreenParameterTest.kt

@@ -9,7 +9,6 @@ import androidx.compose.ui.test.assertIsDisplayed
 import androidx.compose.ui.test.assertIsNotDisplayed
 import androidx.compose.ui.test.junit4.createComposeRule
 import androidx.compose.ui.test.onNodeWithContentDescription
-import androidx.compose.ui.test.onNodeWithTag
 import androidx.compose.ui.test.onNodeWithText
 import org.junit.Rule
 import org.junit.Test
@@ -20,7 +19,6 @@ import uk.gov.android.ui.componentsv2.images.GdsIcon
 import uk.gov.android.ui.patterns.testutils.BDD.Given
 import uk.gov.android.ui.patterns.testutils.BDD.Then
 import uk.gov.android.ui.patterns.testutils.BDD.When
-import uk.gov.android.ui.patterns.testutils.Matchers.assertListSemanticsCleared
 import uk.gov.android.ui.patterns.testutils.TestUtils.getString
 
 @RunWith(RobolectricTestRunner::class)
@@ -356,18 +354,4 @@ class ErrorScreenParameterTest {
             onNodeWithText(tertiaryButtonText).assertIsDisplayed()
         }
     }
-
-    @Test
-    fun `lazy column has semantic collection info with rows and columns set to zero`() {
-        composeTestRule.setContent {
-            ErrorScreen(
-                title = { },
-                icon = { },
-            )
-        }
-
-        composeTestRule
-            .onNodeWithTag(ErrorScreenTitleTestTag.ERROR_BODY_LAZY_COLUMN_TEST_TAG)
-            .assertListSemanticsCleared()
-    }
 }

patterns/src/test/java/uk/gov/android/ui/patterns/errorscreen/v2/ErrorScreenSemanticsTest.kt

@@ -0,0 +1,53 @@
+package uk.gov.android.ui.patterns.errorscreen.v2
+
+import androidx.compose.ui.graphics.vector.ImageVector
+import androidx.compose.ui.res.vectorResource
+import androidx.compose.ui.test.assert
+import androidx.compose.ui.test.junit4.ComposeContentTestRule
+import androidx.compose.ui.test.junit4.createComposeRule
+import androidx.compose.ui.test.onNodeWithTag
+import org.junit.Rule
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import uk.gov.android.ui.componentsv2.heading.GdsHeading
+import uk.gov.android.ui.componentsv2.images.GdsIcon
+import uk.gov.android.ui.patterns.errorscreen.v2.ErrorScreenTitleTestTag.ERROR_BODY_LAZY_COLUMN_TEST_TAG
+import uk.gov.android.ui.patterns.testutils.Matchers.assertListSemanticsCleared
+import uk.gov.android.ui.patterns.utils.matchers.ScrollableWithKeyboardMatchers.hasKeyboardScroll
+
+@RunWith(RobolectricTestRunner::class)
+class ErrorScreenSemanticsTest {
+    @get:Rule
+    val composeTestRule = createComposeRule()
+
+    @Test
+    fun `lazy column has keyboard scroll enabled`() {
+        composeTestRule.setErrorScreenContent()
+
+        composeTestRule
+            .onNodeWithTag(ERROR_BODY_LAZY_COLUMN_TEST_TAG)
+            .assert(hasKeyboardScroll())
+    }
+
+    @Test
+    fun `lazy column has semantic collection info with rows and columns set to zero`() {
+        composeTestRule.setErrorScreenContent()
+
+        composeTestRule
+            .onNodeWithTag(ErrorScreenTitleTestTag.ERROR_BODY_LAZY_COLUMN_TEST_TAG)
+            .assertListSemanticsCleared()
+    }
+
+    private fun ComposeContentTestRule.setErrorScreenContent() = this.setContent {
+        ErrorScreen(
+            icon = {
+                GdsIcon(
+                    image = ImageVector.vectorResource(ErrorScreenIcon.ErrorIcon.icon),
+                    contentDescription = "Error",
+                )
+            },
+            title = { GdsHeading("Title") },
+        )
+    }
+}

…d/ui/patterns/utils/BringIntoViewTest.kt …/ui/patterns/utils/KeyboardScrollTest.ktpatterns/src/test/java/uk/gov/android/ui/patterns/utils/BringIntoViewTest.kt renamed to patterns/src/test/java/uk/gov/android/ui/patterns/utils/KeyboardScrollTest.kt patterns/src/test/java/uk/gov/android/ui/patterns/utils/BringIntoViewTest.kt renamed to patterns/src/test/java/uk/gov/android/ui/patterns/utils/KeyboardScrollTest.kt

@@ -19,6 +19,7 @@ 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.assert
 import androidx.compose.ui.test.assertIsDisplayed
 import androidx.compose.ui.test.assertIsNotDisplayed
 import androidx.compose.ui.test.junit4.ComposeTestRule
@@ -32,19 +33,27 @@ 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
+import uk.gov.android.ui.patterns.utils.KeyboardScrollTest.Companion.NUM_ITEMS
+import uk.gov.android.ui.patterns.utils.KeyboardScrollTest.Companion.containerHeight
+import uk.gov.android.ui.patterns.utils.KeyboardScrollTest.Companion.itemHeight
+import uk.gov.android.ui.patterns.utils.ModifierExtensions.keyboardScroll
+import uk.gov.android.ui.patterns.utils.matchers.ScrollableWithKeyboardMatchers.hasKeyboardScroll
 
 @OptIn(ExperimentalTestApi::class)
 @RunWith(RobolectricTestRunner::class)
-class BringIntoViewTest {
+class KeyboardScrollTest {
     @get:Rule
     val composeTestRule = createComposeRule()
 
     private val focusRequester = FocusRequester()
 
+    @Test
+    fun `modifier exposes semantics for matcher`() {
+        setUpColumn()
+
+        composeTestRule.onNodeWithTag(TEST_TAG).assert(hasKeyboardScroll())
+    }
+
     @Test
     fun `keyboard can scroll down and up for non-lazy list`() {
         setUpColumn()
@@ -97,7 +106,7 @@ class BringIntoViewTest {
                 numItems = numItems,
                 modifier = Modifier
                     .focusRequester(focusRequester)
-                    .bringIntoView(scrollState),
+                    .keyboardScroll(scrollState),
             )
         }
     }
@@ -109,7 +118,7 @@ class BringIntoViewTest {
                 listState = listState,
                 modifier = Modifier
                     .focusRequester(focusRequester)
-                    .bringIntoView(listState),
+                    .keyboardScroll(listState),
             )
         }
     }
@@ -135,7 +144,7 @@ class BringIntoViewTest {
             .performKeyInput { pressKey(Key.DirectionDown) }
 
     companion object {
-        const val TEST_TAG = "bringIntoViewTest"
+        const val TEST_TAG = "keyboardScrollTest"
         const val NUM_ITEMS = 50
         const val FIRST_ITEM = "Item 0"
         val containerHeight = 100.dp
@@ -153,7 +162,7 @@ private fun TestColumn(
         modifier = modifier
             .height(containerHeight)
             .verticalScroll(scrollState)
-            .testTag(BringIntoViewTest.TEST_TAG),
+            .testTag(KeyboardScrollTest.TEST_TAG),
     ) {
         repeat(numItems) { index ->
             BasicText(
@@ -173,7 +182,7 @@ private fun TestLazyColumn(
         state = listState,
         modifier = modifier
             .height(containerHeight)
-            .testTag(BringIntoViewTest.TEST_TAG),
+            .testTag(KeyboardScrollTest.TEST_TAG),
     ) {
         items(numItems) { index ->
             BasicText(

patterns/src/testFixtures/kotlin/uk/gov/android/ui/patterns/utils/matchers/ScrollableWithKeyboardMatchers.kt

@@ -0,0 +1,15 @@
+package uk.gov.android.ui.patterns.utils.matchers
+
+import androidx.compose.ui.test.SemanticsMatcher
+import uk.gov.android.ui.patterns.utils.ModifierExtensions.HasKeyboardScrollKey
+import uk.gov.android.ui.patterns.utils.ModifierExtensions.keyboardScroll
+
+object ScrollableWithKeyboardMatchers {
+    /**
+     * Matches nodes that can be scrolled using the keyboard up/down arrows.
+     *
+     * @see [keyboardScroll].
+     */
+    fun hasKeyboardScroll(): SemanticsMatcher =
+        SemanticsMatcher.expectValue(HasKeyboardScrollKey, true)
+}