DON-1319 Add scroll callback to BpkCalendar (#2254)

Update readme based on Copilot's advice and with example.

Author: henrik-sky

backpack-compose/src/androidTest/kotlin/net/skyscanner/backpack/compose/calendar/BpkCalendarTest.kt

@@ -25,13 +25,15 @@ import androidx.compose.ui.test.SemanticsMatcher
 import androidx.compose.ui.test.SemanticsNodeInteraction
 import androidx.compose.ui.test.assert
 import androidx.compose.ui.test.assertIsNotSelected
+import androidx.compose.ui.test.hasContentDescription
 import androidx.compose.ui.test.junit4.createComposeRule
 import androidx.compose.ui.test.onAllNodesWithText
 import androidx.compose.ui.test.onFirst
 import androidx.compose.ui.test.onLast
 import androidx.compose.ui.test.onNodeWithTag
 import androidx.compose.ui.test.performClick
 import androidx.compose.ui.test.performScrollToIndex
+import androidx.compose.ui.test.performScrollToNode
 import kotlinx.coroutines.test.runTest
 import net.skyscanner.backpack.calendar2.CalendarParams
 import net.skyscanner.backpack.calendar2.CalendarSelection
@@ -41,6 +43,7 @@ import org.junit.Assert.assertEquals
 import org.junit.Rule
 import org.junit.Test
 import java.time.LocalDate
+import java.time.YearMonth
 import java.util.Locale
 
 class BpkCalendarTest {
@@ -215,6 +218,27 @@ class BpkCalendarTest {
         assertEquals(expected, state.selection)
     }
 
+    @Test
+    fun withScrollHandling() = runTest {
+        val controller = createController(DefaultSingle)
+        var visitedMonth = YearMonth.of(2019, 1)
+
+        composeTestRule.setContent {
+            BpkTheme {
+                BpkCalendar(controller, onScrollToMonth = {
+                    visitedMonth = it
+                })
+            }
+        }
+
+        composeTestRule.onNodeWithTag(CALENDAR_GRID_TEST_TAG)
+            .performScrollToNode(hasContentDescription("October 2019", substring = true))
+
+        composeTestRule.waitForIdle()
+
+        assert(visitedMonth.monthValue > 1)
+    }
+
     private fun createController(params: CalendarParams): BpkCalendarController =
         BpkCalendarController(initialParams = params, onSelectionChanged = {})
 }

backpack-compose/src/main/kotlin/net/skyscanner/backpack/compose/calendar/BpkCalendar.kt

@@ -24,19 +24,22 @@ import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import net.skyscanner.backpack.calendar2.data.CalendarInteraction
 import net.skyscanner.backpack.compose.calendar.internal.BpkCalendarBadge
 import net.skyscanner.backpack.compose.calendar.internal.BpkCalendarGrid
 import net.skyscanner.backpack.compose.calendar.internal.BpkCalendarHeader
 import net.skyscanner.backpack.compose.tokens.BpkSpacing
+import java.time.YearMonth
 
 @Composable
 fun BpkCalendar(
     controller: BpkCalendarController,
     modifier: Modifier = Modifier,
     customDateHandling: ((CalendarInteraction) -> Unit)? = null,
+    onScrollToMonth: ((YearMonth) -> Unit)? = null,
 ) {
 
     val state = controller.state
@@ -67,5 +70,11 @@ fun BpkCalendar(
                 )
             }
         }
+
+        onScrollToMonth?.let {
+            LaunchedEffect(onScrollToMonth, controller.firstVisibleItemMonth) {
+                onScrollToMonth(controller.firstVisibleItemMonth)
+            }
+        }
     }
 }

backpack-compose/src/main/kotlin/net/skyscanner/backpack/compose/calendar/BpkCalendarController.kt

@@ -36,6 +36,7 @@ import net.skyscanner.backpack.calendar2.data.dispatchClick
 import net.skyscanner.backpack.calendar2.data.dispatchSetSelection
 import java.io.Serializable
 import java.time.LocalDate
+import java.time.YearMonth
 
 class BpkCalendarController(
     initialParams: CalendarParams,
@@ -89,11 +90,14 @@ class BpkCalendarController(
         }
     }
 
+    internal val firstVisibleItemMonth: YearMonth
+        get() = _state.cells[lazyGridState.firstVisibleItemIndex].yearMonth
+
     /**
      * Returns the first visible item year.
      */
     internal val firstVisibleItemYear: Int
-        get() = _state.cells[lazyGridState.firstVisibleItemIndex].yearMonth.year
+        get() = firstVisibleItemMonth.year
 
     /**
      * Handles the click events of a calendar.

docs/compose/Calendar2/README.md

@@ -89,6 +89,27 @@ This property is a lambda that will be called when a date is selected by the use
 You can use it to handle the selection manually.
 You can then set the selection in the controller using the `setSelection` method.
 
+### (Optional) Handling Calendar Scroll Updates
+
+To receive notifications when the calendar is scrolled, you can utilize the `onScrollToMonth` parameter.
+This callback is triggered whenever the `lazyGridState.firstVisibleItemIndex` property of the `BpkCalendarController` is
+updated.
+
+For example you can show the furthest scrolled month's number (i.e. January = 1, February = 2, etc.) in a `BpkText` label:
+
+```Kotlin
+Column {
+    var month: YearMonth by remember { mutableStateOf(YearMonth.now()) }
+    BpkText("Month: ${month.monthValue}")
+    BpkCalendar(
+        controller = controller,
+        onScrollToMonth = {
+            month = it
+        }
+    )
+}
+```
+
 ### Advanced Dates Customisation
 
 You can attach some information to each date displayed in the calendar.