[Pager] Re-write Pager on top of LazyRow|Column

docs/pager.md

@@ -24,9 +24,7 @@ The simplest usage looks like the following:
 
 ``` kotlin
 // Display 10 items
-val pagerState = rememberPagerState(pageCount = 10)
-
-HorizontalPager(state = pagerState) { page ->
+HorizontalPager(count = 10) { page ->
     // Our page content
     Text(
         text = "Page: $page",
@@ -37,6 +35,19 @@ HorizontalPager(state = pagerState) { page ->
 
 If you want to jump to a specific page, you either call call `pagerState.scrollToPage(index)` or  `pagerState.animateScrollToPage(index)` method in a `CoroutineScope`.
 
+``` kotlin
+val pagerState = rememberPagerState()
+
+HorizontalPager(count = 10, state = pagerState) { page ->
+    // ...page content
+}
+
+// Later, scroll to page 2
+scope.launch {
+    pagerState.scrollToPage(2)
+}
+```
+
 ## VerticalPager
 
 [`VerticalPager`][api-vertpager] is very similar to [`HorizontalPager`][api-horizpager] but items are laid out vertically, and react to vertical swipes:
@@ -51,9 +62,7 @@ If you want to jump to a specific page, you either call call `pagerState.scrollT
 
 ``` kotlin
 // Display 10 items
-val pagerState = rememberPagerState(pageCount = 10)
-
-VerticalPager(state = pagerState) { page ->
+VerticalPager(count = 10) { page ->
     // Our page content
     Text(
         text = "Page: $page",
@@ -66,20 +75,62 @@ VerticalPager(state = pagerState) { page ->
 
 Pages in both [`HorizontalPager`][api-horizpager] and [`VerticalPager`][api-vertpager] are lazily composed and laid-out as required by the layout. As the user scrolls through pages, any pages which are no longer required are removed from the content.
 
-### Offscreen Limit
+Under the covers, `HorizontalPager` use [`LazyRow`](https://developer.android.com/jetpack/compose/lists#lazy), and `VerticalPager` uses [`LazyColumn`](https://developer.android.com/jetpack/compose/lists#lazy).
 
-The [PagerState][pagerstate-api] API allows the setting of the `initialOffscreenLimit`, which defines the number of pages that should be retained on either side of the current page. Pages beyond this limit will be removed, and then recreated as needed. This value defaults to `1`, but can be increased to enable pre-loading of more content:
 
-```kotlin
-val pagerState = rememberPagerState(
-    pageCount = 10,
-    initialOffscreenLimit = 2,
-)
+## Content Padding
 
-HorizontalPager(state = pagerState) { page ->
-    // ...
-}
-```
+`HorizontalPager` and `VerticalPager` both support the setting of content padding, which allows you to influence the maximum size and alignment of pages.
+
+You can see how different content padding values affect a `HorizontalPager` below:
+
+=== "start = 64.dp"
+
+    Setting the start padding has the effect of aligning the pages towards the end.
+
+    ![](contentpadding-start.png){: loading=lazy width=70% align=center }
+
+    ``` kotlin
+    HorizontalPager(
+        count = 4,
+        contentPadding = PaddingValues(start = 64.dp),
+    ) { page ->
+        // page content
+    }
+    ```
+
+=== "horizontal = 32.dp"
+
+    Setting both the start and end padding to the same value has the effect of centering the item horizontally.
+
+    ![](contentpadding-horizontal.png){: loading=lazy width=70% align=center }
+
+    ``` kotlin
+    HorizontalPager(
+        count = 4,
+        contentPadding = PaddingValues(horizontal = 32.dp),
+    ) { page ->
+        // page content
+    }
+    ```
+
+=== "end = 64.dp"
+
+    Setting the end padding has the effect of aligning the pages towards the start.
+
+    ![](contentpadding-end.png){: loading=lazy width=70% align=center }
+
+    ``` kotlin
+    HorizontalPager(
+        count = 4,
+        contentPadding = PaddingValues(end = 64.dp),
+    ) { page ->
+        // page content
+    }
+    ```
+
+Similar effects for `VerticalPager` can be achieved by setting the `top` and `bottom` values. The value `32.dp` is only used
+here as an example, you can set each of the padding dimensions to whatever value you wish.
 
 ## Item scroll effects
 
@@ -101,7 +152,7 @@ The scope provided to your pager content allows apps to easily reference the [`c
 ``` kotlin
 import com.google.accompanist.pager.calculateCurrentOffsetForPage
 
-HorizontalPager(state = pagerState) { page ->
+HorizontalPager(count = 4) { page ->
     Card(
         Modifier
             .graphicsLayer {
@@ -138,11 +189,21 @@ HorizontalPager(state = pagerState) { page ->
 The [`PagerState.currentPage`][currentpage-api] property is updated whenever the selected page changes. You can use the `snapshowFlow` function to observe changes in a flow:
 
 ``` kotlin
+val pagerState = rememberPagerState()
+
 LaunchedEffect(pagerState) {
+    // Collect from the a snapshotFlow reading the currentPage
     snapshotFlow { pagerState.currentPage }.collect { page ->
-        // Selected page has changed...
+        AnalyticsService.sendPageSelectedEvent(page)
     }
 }
+
+VerticalPager(
+    count = 10,
+    state = pagerState,
+) { page ->
+    Text(text = "Page: $page")
+}
 ```
 
 ## Indicators
@@ -176,7 +237,7 @@ A common use-case for [`HorizontalPager`][api-horizpager] is to be used in conju
 Provided in the `pager-indicators` library is a modifier which can be used on a tab indicator like so:
 
 ``` kotlin
-val pagerState = rememberPagerState(pageCount = pages.size)
+val pagerState = rememberPagerState()
 
 TabRow(
     // Our selected tab is our current page
@@ -198,11 +259,33 @@ TabRow(
     }
 }
 
-HorizontalPager(state = pagerState) { page ->
+HorizontalPager(
+    count = pages.size,
+    state = pagerState,
+) { page ->
     // TODO: page content
 }
 ```
 
+## Changes in v0.19.0
+
+In v0.19.0 both `HorizontalPager` and `VerticalPager` were re-written to be based on `LazyRow` and `LazyColumn` respectively. As part of this change, a number of feature and API changes were made:
+
+### PagerState
+
+- The `pageCount` parameter on `rememberPagerState()` has been removed, replaced with the `count` parameter on `HorizontalPager()` and `VerticalPager()`.
+- The `animationSpec`, `initialVelocity` and `skipPages` parameters on `animateScrollToPage()` have been removed. The lazy components handle this automatically.
+
+### HorizontalPager & VerticalPager
+
+- Ability to set `contentPadding` (see [above](#content-padding)).
+- Ability to specify a `key` for each page.
+- The `horizontalAlignment` parameter on `HorizontalPager`, and the `verticalAlignment` parameter on `VerticalPager` have been removed. A similar effect can be implemented with an appropriate content padding (see [above](#content-padding)).
+- The `infiniteLooping` parameter and feature have been removed. A sample demonstrating how to achieve this effect can be found [here][looping-sample].
+- The `offscreenLimit` parameter has been removed. We no longer have control of what items are laid out 'off screen'.
+- The `dragEnabled` parameter has removed.
+- `PagerScope` (the page item scope) no longer implements `BoxScope`. 
+
 ---
 
 ## Usage
@@ -255,3 +338,4 @@ limitations under the License.
   [currentpageoffset-api]: ../api/pager/pager/com.google.accompanist.pager/-pager-state/current-page-offset.html
   [calcoffsetpage]: ../api/pager/pager/com.google.accompanist.pager/calculate-current-offset-for-page.html
   [pagerstate-api]: ../api/pager/pager/com.google.accompanist.pager/remember-pager-state.html
+  [looping-sample]: https://github.com/google/accompanist/blob/main/sample/src/main/java/com/google/accompanist/sample/pager/HorizontalPagerLoopingSample.kt

internal-testutils/src/main/java/com/google/accompanist/internal/test/Assertions.kt

@@ -20,6 +20,9 @@ import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.graphics.ImageBitmap
 import androidx.compose.ui.graphics.toPixelMap
 import androidx.compose.ui.test.SemanticsNodeInteraction
+import androidx.compose.ui.test.assertHeightIsAtLeast
+import androidx.compose.ui.test.assertWidthIsAtLeast
+import androidx.compose.ui.unit.Dp
 import com.google.common.truth.Truth.assertThat
 
 /**
@@ -56,3 +59,19 @@ fun SemanticsNodeInteraction.assertWithTimeout(
     // Run block one last time...
     return block()
 }
+
+val SemanticsNodeInteraction.exists: Boolean
+    get() = try {
+        assertExists()
+        true
+    } catch (t: Throwable) {
+        false
+    }
+
+val SemanticsNodeInteraction.isLaidOut: Boolean
+    get() = try {
+        assertWidthIsAtLeast(Dp.Hairline).assertHeightIsAtLeast(Dp.Hairline)
+        true
+    } catch (t: Throwable) {
+        false
+    }

pager-indicators/src/sharedTest/kotlin/com/google/accompanist/insets/TabIndicatorTest.kt

@@ -41,7 +41,7 @@ class TabIndicatorTest {
     fun emptyPager() {
         rule.setContent {
             MaterialTheme {
-                val pagerState = rememberPagerState(pageCount = 0)
+                val pagerState = rememberPagerState()
                 ScrollableTabRow(
                     selectedTabIndex = pagerState.currentPage,
                     indicator = { tabPositions ->

pager/api/current.api

@@ -1,34 +1,32 @@
 // Signature format: 4.0
 package com.google.accompanist.pager {
 
-  public final class ClippingKt {
-  }
-
   @kotlin.RequiresOptIn(message="Accompanist Pager is experimental. The API may be changed in the future.") @kotlin.annotation.Retention(kotlin.annotation.AnnotationRetention) public @interface ExperimentalPagerApi {
   }
 
   public final class Pager {
-    method @androidx.compose.runtime.Composable @com.google.accompanist.pager.ExperimentalPagerApi public static void HorizontalPager(com.google.accompanist.pager.PagerState state, optional androidx.compose.ui.Modifier modifier, optional boolean reverseLayout, optional float itemSpacing, optional boolean dragEnabled, optional androidx.compose.foundation.gestures.FlingBehavior flingBehavior, optional androidx.compose.ui.Alignment.Vertical verticalAlignment, optional androidx.compose.ui.Alignment.Horizontal horizontalAlignment, kotlin.jvm.functions.Function2<? super com.google.accompanist.pager.PagerScope,? super java.lang.Integer,kotlin.Unit> content);
-    method @androidx.compose.runtime.Composable @com.google.accompanist.pager.ExperimentalPagerApi public static void VerticalPager(com.google.accompanist.pager.PagerState state, optional androidx.compose.ui.Modifier modifier, optional boolean reverseLayout, optional float itemSpacing, optional boolean dragEnabled, optional androidx.compose.foundation.gestures.FlingBehavior flingBehavior, optional androidx.compose.ui.Alignment.Vertical verticalAlignment, optional androidx.compose.ui.Alignment.Horizontal horizontalAlignment, kotlin.jvm.functions.Function2<? super com.google.accompanist.pager.PagerScope,? super java.lang.Integer,kotlin.Unit> content);
+    method @androidx.compose.runtime.Composable @com.google.accompanist.pager.ExperimentalPagerApi public static void HorizontalPager(int count, optional androidx.compose.ui.Modifier modifier, optional com.google.accompanist.pager.PagerState state, optional boolean reverseLayout, optional float itemSpacing, optional androidx.compose.foundation.gestures.FlingBehavior flingBehavior, optional androidx.compose.ui.Alignment.Vertical verticalAlignment, optional kotlin.jvm.functions.Function1<? super java.lang.Integer,?>? key, optional androidx.compose.foundation.layout.PaddingValues contentPadding, kotlin.jvm.functions.Function2<? super com.google.accompanist.pager.PagerScope,? super java.lang.Integer,kotlin.Unit> content);
+    method @androidx.compose.runtime.Composable @com.google.accompanist.pager.ExperimentalPagerApi public static void VerticalPager(int count, optional androidx.compose.ui.Modifier modifier, optional com.google.accompanist.pager.PagerState state, optional boolean reverseLayout, optional float itemSpacing, optional androidx.compose.foundation.gestures.FlingBehavior flingBehavior, optional androidx.compose.ui.Alignment.Horizontal horizontalAlignment, optional kotlin.jvm.functions.Function1<? super java.lang.Integer,?>? key, optional androidx.compose.foundation.layout.PaddingValues contentPadding, kotlin.jvm.functions.Function2<? super com.google.accompanist.pager.PagerScope,? super java.lang.Integer,kotlin.Unit> content);
     method @com.google.accompanist.pager.ExperimentalPagerApi public static float calculateCurrentOffsetForPage(com.google.accompanist.pager.PagerScope, int page);
   }
 
   @com.google.accompanist.pager.ExperimentalPagerApi public final class PagerDefaults {
-    method @Deprecated @androidx.compose.runtime.Composable public androidx.compose.foundation.gestures.FlingBehavior defaultPagerFlingConfig(com.google.accompanist.pager.PagerState state, optional androidx.compose.animation.core.DecayAnimationSpec<java.lang.Float> decayAnimationSpec, optional androidx.compose.animation.core.AnimationSpec<java.lang.Float> snapAnimationSpec);
-    method @androidx.compose.runtime.Composable public androidx.compose.foundation.gestures.FlingBehavior rememberPagerFlingConfig(com.google.accompanist.pager.PagerState state, optional androidx.compose.animation.core.DecayAnimationSpec<java.lang.Float> decayAnimationSpec, optional androidx.compose.animation.core.AnimationSpec<java.lang.Float> snapAnimationSpec);
+    method @androidx.compose.runtime.Composable public androidx.compose.foundation.gestures.FlingBehavior flingBehavior(com.google.accompanist.pager.PagerState state, optional androidx.compose.animation.core.DecayAnimationSpec<java.lang.Float> decayAnimationSpec, optional androidx.compose.animation.core.AnimationSpec<java.lang.Float> snapAnimationSpec);
+    method @Deprecated @androidx.compose.runtime.Composable public androidx.compose.foundation.gestures.FlingBehavior rememberPagerFlingConfig(com.google.accompanist.pager.PagerState state, optional androidx.compose.animation.core.DecayAnimationSpec<java.lang.Float> decayAnimationSpec, optional androidx.compose.animation.core.AnimationSpec<java.lang.Float> snapAnimationSpec);
     field public static final com.google.accompanist.pager.PagerDefaults INSTANCE;
   }
 
-  @androidx.compose.runtime.Stable @com.google.accompanist.pager.ExperimentalPagerApi public interface PagerScope extends androidx.compose.foundation.layout.BoxScope {
+  @androidx.compose.runtime.Stable @com.google.accompanist.pager.ExperimentalPagerApi public interface PagerScope {
     method public int getCurrentPage();
     method public float getCurrentPageOffset();
     property public abstract int currentPage;
     property public abstract float currentPageOffset;
   }
 
   @androidx.compose.runtime.Stable @com.google.accompanist.pager.ExperimentalPagerApi public final class PagerState implements androidx.compose.foundation.gestures.ScrollableState {
-    ctor public PagerState(@IntRange(from=0) int pageCount, optional @IntRange(from=0) int currentPage, optional @FloatRange(from=0.0, to=1.0) float currentPageOffset, optional int offscreenLimit, optional boolean infiniteLoop);
-    method public suspend Object? animateScrollToPage(@IntRange(from=0) int page, optional @FloatRange(from=0.0, to=1.0) float pageOffset, optional androidx.compose.animation.core.AnimationSpec<java.lang.Float> animationSpec, optional float initialVelocity, optional boolean skipPages, optional kotlin.coroutines.Continuation<? super kotlin.Unit> p);
+    ctor public PagerState(optional @IntRange(from=0) int currentPage);
+    method @Deprecated public suspend Object? animateScrollToPage(@IntRange(from=0) int page, optional @FloatRange(from=0.0, to=1.0) float pageOffset, optional androidx.compose.animation.core.AnimationSpec<java.lang.Float> animationSpec, optional float initialVelocity, optional boolean skipPages, optional kotlin.coroutines.Continuation<? super kotlin.Unit> p);
+    method public suspend Object? animateScrollToPage(@IntRange(from=0) int page, optional @FloatRange(from=0.0, to=1.0) float pageOffset, optional kotlin.coroutines.Continuation<? super kotlin.Unit> p);
     method public float dispatchRawDelta(float delta);
     method @IntRange(from=0) public int getCurrentPage();
     method public float getCurrentPageOffset();
@@ -38,7 +36,6 @@ package com.google.accompanist.pager {
     method public boolean isScrollInProgress();
     method public suspend Object? scroll(androidx.compose.foundation.MutatePriority scrollPriority, kotlin.jvm.functions.Function2<? super androidx.compose.foundation.gestures.ScrollScope,? super kotlin.coroutines.Continuation<? super kotlin.Unit>,?> block, kotlin.coroutines.Continuation<? super kotlin.Unit> p);
     method public suspend Object? scrollToPage(@IntRange(from=0) int page, optional @FloatRange(from=0.0, to=1.0) float pageOffset, optional kotlin.coroutines.Continuation<? super kotlin.Unit> p);
-    method public void setPageCount(@IntRange(from=0) int value);
     property @IntRange(from=0) public final int currentPage;
     property public final float currentPageOffset;
     property public final androidx.compose.foundation.interaction.InteractionSource interactionSource;
@@ -54,7 +51,11 @@ package com.google.accompanist.pager {
   }
 
   public final class PagerStateKt {
-    method @androidx.compose.runtime.Composable @com.google.accompanist.pager.ExperimentalPagerApi public static com.google.accompanist.pager.PagerState rememberPagerState(@IntRange(from=0) int pageCount, optional @IntRange(from=0) int initialPage, optional @FloatRange(from=0.0, to=1.0) float initialPageOffset, optional @IntRange(from=1) int initialOffscreenLimit, optional boolean infiniteLoop);
+    method @Deprecated @androidx.compose.runtime.Composable @com.google.accompanist.pager.ExperimentalPagerApi public static inline com.google.accompanist.pager.PagerState rememberPagerState(@IntRange(from=0) int pageCount, optional @IntRange(from=0) int initialPage, optional @FloatRange(from=0.0, to=1.0) float initialPageOffset, optional @IntRange(from=1) int initialOffscreenLimit, optional boolean infiniteLoop);
+    method @androidx.compose.runtime.Composable @com.google.accompanist.pager.ExperimentalPagerApi public static com.google.accompanist.pager.PagerState rememberPagerState(optional @IntRange(from=0) int initialPage);
+  }
+
+  public final class SnappingFlingBehaviorKt {
   }
 
 }

pager/src/androidTest/kotlin/com/google/accompanist/pager/InstrumentedHorizontalPagerTest.kt

@@ -16,8 +16,9 @@
 
 package com.google.accompanist.pager
 
-import androidx.compose.ui.Alignment
+import androidx.compose.foundation.layout.PaddingValues
 import androidx.compose.ui.unit.LayoutDirection
+import androidx.compose.ui.unit.dp
 import com.google.accompanist.internal.test.combineWithParameters
 import com.google.accompanist.internal.test.parameterizedParams
 import org.junit.runner.RunWith
@@ -29,41 +30,40 @@ import org.junit.runners.Parameterized
 @RunWith(Parameterized::class)
 class InstrumentedHorizontalPagerTest(
     itemWidthFraction: Float,
-    horizontalAlignment: Alignment.Horizontal,
+    contentPadding: PaddingValues,
     itemSpacingDp: Int,
-    offscreenLimit: Int,
     layoutDirection: LayoutDirection,
     reverseLayout: Boolean,
-    infiniteLoop: Boolean,
 ) : BaseHorizontalPagerTest(
     itemWidthFraction,
-    horizontalAlignment,
+    contentPadding,
     itemSpacingDp,
-    offscreenLimit,
     layoutDirection,
     reverseLayout,
-    infiniteLoop,
 ) {
     companion object {
-        /**
-         * On device we only test a subset of the combined parameters.
-         */
         @JvmStatic
-        @Parameterized.Parameters
+        @Parameterized.Parameters(
+            name = "itemWidthFraction={0}," +
+                "contentPadding={1}," +
+                "itemSpacing={2}," +
+                "layoutDirection={3}," +
+                "reverseLayout={4}"
+        )
         fun data() = parameterizedParams()
             // itemWidthFraction
             .combineWithParameters(1f)
-            // horizontalAlignment
-            .combineWithParameters(Alignment.CenterHorizontally, Alignment.Start, Alignment.End)
+            // contentPadding
+            .combineWithParameters(
+                PaddingValues(end = 32.dp), // Alignment.Start
+                PaddingValues(horizontal = 32.dp), // Alignment.Center
+                PaddingValues(start = 32.dp), // Alignment.End
+            )
             // itemSpacing
             .combineWithParameters(0, 4)
-            // offscreenLimit
-            .combineWithParameters(1)
             // layoutDirection
             .combineWithParameters(LayoutDirection.Ltr, LayoutDirection.Rtl)
             // reverseLayout
             .combineWithParameters(false)
-            // looping
-            .combineWithParameters(false)
     }
 }