[Docs] Lots of docs improvements for next release

README.md

@@ -16,6 +16,9 @@ A library which provides easy-to-use utilities for updating the System UI (statu
 ### 🎨 [AppCompat Theme Adapter](./appcompat-theme/)
 A library that enables reuse of [AppCompat][appcompat] XML themes for theming in [Jetpack Compose][compose].
 
+### 📖 [Pager](./pager/)
+A library which provides paging layouts for Jetpack Compose, similar to Android's [`ViewPager`](https://developer.android.com/reference/kotlin/androidx/viewpager/widget/ViewPager).
+
 ### 🌊 [Flow layouts](./flowlayout/)
 A library that adds a 'flexbox'-like layout to [Jetpack Compose][compose].
 

build.gradle

@@ -125,7 +125,12 @@ subprojects {
     // Must be afterEvaluate or else com.vanniktech.maven.publish will overwrite our
     // dokka and version configuration.
     afterEvaluate {
-        tasks.withType(org.jetbrains.dokka.gradle.DokkaTask).configureEach {
+        if (tasks.findByName('dokkaHtmlPartial') == null) {
+            // If dokka isn't enabled on this module, skip
+            return
+        }
+
+        tasks.named('dokkaHtmlPartial') {
             dokkaSourceSets.configureEach {
                 reportUndocumented.set(true)
                 skipEmptyPackages.set(true)

docs/flowlayout.md

@@ -2,9 +2,9 @@
 
 [![Maven Central](https://img.shields.io/maven-central/v/com.google.accompanist/accompanist-flowlayout)](https://search.maven.org/search?q=g:com.google.accompanist)
 
-Flow layouts adapted from the [Jetpack Compose][compose] alpha versions.
+Flow layouts adapted from the versions which were available in [Jetpack Compose][compose] until they were removed.
 
-Unlike the standard Row and Column composables, these lay out children in multiple rows/columns if they exceed the available space.
+Unlike the standard `Row` and `Column` composables, these layout children across multiple rows/columns if they exceed the available space.
 
 ## Usage
 

docs/migration.md

@@ -0,0 +1,36 @@
+# Migration from dev.chrisbanes.accompanist
+
+In March 2021, the Accompanist project moved from github.com/chrisbanes/accompanist to github.com/google/accompanist. At the same time we migrated the libraries over to the new package name, and Maven group ID.
+
+The following methods below are available for your information only, but may help if you need to migrate from the old package name. 
+
+!!! warning
+    Use these at your own risk, but they have worked on multiple projects from my testing. It's a good idea to make sure that you've made a backup or committed any changes before running these.
+
+## Android Studio
+
+You can use the [Replace in Path](https://www.jetbrains.com/help/idea/finding-and-replacing-text-in-project.html#replace_search_string_in_project) pane (⇧⌘R on Mac) in Android Studio to do a project-wide search and replace.
+
+![Android Studio Replace in Path pane](studio.png)
+
+- Find query: `dev.chrisbanes.accompanist`
+- Replace string: `com.google.accompanist`
+- _Optional:_ Set the file mask to `*.kt` so that only Kotlin files are searched.
+
+## YOLO commands
+
+These commands while automatically replace any imports and Gradle dependencies for the project in the current directory.
+
+### MacOS
+
+``` bash
+find . -type f \( -name '*.kt' -or -name '*.gradle*' \) \
+    -exec sed -i '' 's/dev\.chrisbanes\.accompanist/com\.google\.accompanist/' {} \;
+```
+
+### Linux
+
+``` bash
+find . -type f \( -name '*.kt' -or -name '*.gradle*' \) \
+    -exec sed -i 's/dev\.chrisbanes\.accompanist/com\.google\.accompanist/' {} \;
+```

docs/pager.md

@@ -1,4 +1,4 @@
-# Paging layouts
+# Pager layouts
 
 [![Maven Central](https://img.shields.io/maven-central/v/com.google.accompanist/accompanist-pager)](https://search.maven.org/search?q=g:com.google.accompanist)
 
@@ -10,17 +10,16 @@ A library which provides paging layouts for Jetpack Compose. If you've used Andr
 
 ## HorizontalPager
 
-`HorizontalPager` is a layout which lays out items in a horizontal row, and allows the user to swipe between pages.
+[`HorizontalPager`][api-horizpager] is a layout which lays out items in a horizontal row, and allows the user to horizontally swipe between pages.
 
 <figure>
     <video width="300" controls loop>
     <source src="horiz_demo.mp4" type="video/mp4">
         Your browser does not support the video tag.
     </video>
-    <figcaption>HorizontalPager</figcaption>
+    <figcaption>HorizontalPager demo</figcaption>
 </figure>
 
-
 The simplest usage looks like the following:
 
 ``` kotlin
@@ -38,14 +37,14 @@ HorizontalPager(state = pagerState) { page ->
 
 ## VerticalPager
 
-`VerticalPager` is similar to `HorizontalPager` but items are instead laid out vertically, and react to vertical scrolls from the user:
+[`VerticalPager`][api-vertpager] is very similar to [`HorizontalPager`][api-horizpager] but items are laid out vertically, and react to vertical swipes:
 
 <figure>
     <video width="300" controls loop>
     <source src="vert_demo.mp4" type="video/mp4">
         Your browser does not support the video tag.
     </video>
-    <figcaption>VerticalPager</figcaption>
+    <figcaption>VerticalPager demo</figcaption>
 </figure>
 
 ``` kotlin
@@ -63,35 +62,120 @@ VerticalPager(state = pagerState) { page ->
 
 ## Lazy creation
 
-Pages in both `HorizontalPager` & `VerticalPager` are lazily created 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.
+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.
 
-## Integration with Tabs
+### Offscreen Limit
 
-A common use-case for `HorizontalPager` is when used in conjunction with a `TabRow`.
+Both [`HorizontalPager`][api-horizpager] & [`VerticalPager`][api-vertpager] allow the setting of the `offscreenLimit`, 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 when needed. This value defaults to `1`, but can be increased to enable pre-loading of more content:
 
-The [HorizontalPagerTabsSample](https://github.com/google/accompanist/blob/main/sample/src/main/java/com/google/accompanist/sample/pager/HorizontalPagerTabsSample.kt) demonstrates how this can be done:
+```kotlin
+HorizontalPager(
+    state = pagerState,
+    offscreenLimit = 2,
+) { page ->
+    // ...
+}
+```
+
+## Item scroll effects
+
+A common use-case is to apply effects to your pager items, using the scroll position to drive those effects.
+
+The [HorizontalPagerTransitionSample](https://github.com/google/accompanist/blob/main/sample/src/main/java/com/google/accompanist/sample/pager/HorizontalPagerTransitionSample.kt) demonstrates how this can be done:
 
 <figure>
     <video width="300" controls loop>
-    <source src="tabs.mp4" type="video/mp4">
+    <source src="transition_demo.mp4" type="video/mp4">
         Your browser does not support the video tag.
     </video>
-    <figcaption>HorizontalPager + TabRow</figcaption>
+    <figcaption>Item effects demo</figcaption>
 </figure>
 
-### Offscreen Limit
 
-Both `HorizontalPager` & `VerticalPager` allow the setting of the `offscreenLimit`, 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 when needed. This value defaults to `1`, but can be increased to enable pre-loading of more content:
+The scope provided to your pager content allows apps to easily reference the [`currentPage`][currentpage-api] and [`currentPageOffset`][currentpageoffset-api]. The effects can then be calculated using those values. We provide the [`calculateCurrentOffsetForPage()`][calcoffsetpage] extension functions to support calculation of the 'offset' for a given page:
 
-```kotlin
-HorizontalPager(
-    state = pagerState,
-    offscreenLimit = 2,
-) { page ->
-    // ...
+``` kotlin
+import com.google.accompanist.pager.calculateCurrentOffsetForPage
+
+HorizontalPager(state = pagerState) { page ->
+    Card(
+        Modifier
+            .graphicsLayer {
+                // Calculate the absolute offset for the current page from the
+                // scroll position. We use the absolute value which allows us to mirror
+                // any effects for both directions
+                val pageOffset = calculateCurrentOffsetForPage(page).absoluteValue
+
+                // We animate the scaleX + scaleY, between 85% and 100%
+                lerp(
+                    start = 0.85f,
+                    stop = 1f,
+                    fraction = 1f - pageOffset.coerceIn(0f, 1f)
+                ).also { scale ->
+                    scaleX = scale
+                    scaleY = scale
+                }
+
+                // We animate the alpha, between 50% and 100%
+                alpha = lerp(
+                    start = 0.5f,
+                    stop = 1f,
+                    fraction = 1f - pageOffset.coerceIn(0f, 1f)
+                )
+            }
+    ) {
+        // Card content
+    }
 }
 ```
 
+## Reacting to page changes
+
+From reading above, you might be thinking that reading [`PagerState.currentPage`][currentpage-api] is a good way to know when the selected page changes. Unfortunately `currentPage` does not tell you the currently selected page, but instead tells you which page is (mostly) displayed on screen.
+
+To know when the selected page changes, you can use the [`pageChanges`](../api/pager/pager/com.google.accompanist.pager/page-changes.html) flow:
+
+``` kotlin
+import com.google.accompanist.pager.pageChanges
+
+LaunchedEffect(pagerState) {
+    pagerState.pageChanges.collect { page ->
+        // Selected page has changed...
+    }
+}
+```
+
+## Indicators
+
+We also publish a sibling library called `pager-indicators` which provides some simple indicator composables for use with [`HorizontalPager`][api-horizpager] and [`VerticalPager`][api-vertpager].
+
+<figure>
+    <video width="300" controls loop>
+    <source src="indicators_demo.mp4" type="video/mp4">
+        Your browser does not support the video tag.
+    </video>
+    <figcaption>Pager indicators demo</figcaption>
+</figure>
+
+The [HorizontalPagerWithIndicatorSample](https://github.com/google/accompanist/blob/main/sample/src/main/java/com/google/accompanist/sample/pager/HorizontalPagerWithIndicatorSample.kt) and [VerticalPagerWithIndicatorSample](https://github.com/google/accompanist/blob/snapshot/sample/src/main/java/com/google/accompanist/sample/pager/VerticalPagerWithIndicatorSample.kt) show you how to use these.
+
+
+## Integration with Tabs
+
+A common use-case for [`HorizontalPager`][api-horizpager] is to be used in conjunction with a [`TabRow`](https://developer.android.com/reference/kotlin/androidx/compose/material/package-summary#tabrow).
+
+The [HorizontalPagerTabsSample](https://github.com/google/accompanist/blob/main/sample/src/main/java/com/google/accompanist/sample/pager/HorizontalPagerTabsSample.kt) demonstrates how this can be done:
+
+<figure>
+    <video width="300" controls loop>
+    <source src="tabs_demo.mp4" type="video/mp4">
+        Your browser does not support the video tag.
+    </video>
+    <figcaption>HorizontalPager + TabRow</figcaption>
+</figure>
+
+### 
+
 ---
 
 ## Usage
@@ -103,6 +187,9 @@ repositories {
 
 dependencies {
     implementation "com.google.accompanist:accompanist-pager:<version>"
+
+    // If using indicators, also depend on 
+    implementation "com.google.accompanist:accompanist-pager-indicators:<version>"
 }
 ```
 
@@ -134,3 +221,9 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 ```
+
+  [api-vertpager]: ../api/pager/pager/com.google.accompanist.pager/-vertical-pager.html
+  [api-horizpager]: ../api/pager/pager/com.google.accompanist.pager/-horizontal-pager.html
+  [currentpage-api]: ../api/pager/pager/com.google.accompanist.pager/-pager-state/current-page.html
+  [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)

docs/systemuicontroller.md

@@ -5,12 +5,14 @@
 System UI Controller provides easy-to-use utilities for updating the System UI bar colors within Jetpack Compose.
 
 ## Usage
-To control system UI in your composables, you must provide an instance to the `LocalSystemUiController`
-composition local. This would typically be done near the top level of your composable hierarchy:
+To control the system UI in your composables, you must provide a [`SystemUiController`](../api/systemuicontroller/systemuicontroller/com.google.accompanist.systemuicontroller/-system-ui-controller/) instance to the [`LocalSystemUiController`](../api/systemuicontroller/systemuicontroller/com.google.accompanist.systemuicontroller/-local-system-ui-controller.html)
+composition local. We provide the [`AndroidSystemUiController`](../api/systemuicontroller/systemuicontroller/com.google.accompanist.systemuicontroller/-android-system-ui-controller/index.html) implementation and an associated [remember function](../api/systemuicontroller/systemuicontroller/com.google.accompanist.systemuicontroller/remember-android-system-ui-controller.html).
+
+This would typically be done near the top level of your composable hierarchy:
 
 ``` kotlin
 setContent {
-    // Create a controller, and provide it to the LocalSystemUiController
+    // Remember a controller, and provide it to the LocalSystemUiController
     val controller = rememberAndroidSystemUiController()
     CompositionLocalProvider(LocalSystemUiController provides controller) {
         MyHomeScreen()
@@ -21,22 +23,19 @@ setContent {
 Then in your layouts, you can update the system bar colors as necessary like so:
 
 ``` kotlin
-@Composable
-fun MyHomeScreen() {
-    // Get the current SystemUiController
-    val systemUiController = LocalSystemUiController.current
-    val useDarkIcons = MaterialTheme.colors.isLight
-
-    SideEffect {
-        // Update all ofthe system bar colors to be transparent, and use
-        // dark icons if we're in light theme
-        systemUiController.setSystemBarsColor(
-            color = Color.Transparent,
-            darkIcons = useDarkIcons
-        )
-
-        // setStatusBarsColor() and setNavigationBarsColor() also exist
-    }
+// Get the current SystemUiController
+val systemUiController = LocalSystemUiController.current
+val useDarkIcons = MaterialTheme.colors.isLight
+
+SideEffect {
+    // Update all of the system bar colors to be transparent, and use
+    // dark icons if we're in light theme
+    systemUiController.setSystemBarsColor(
+        color = Color.Transparent,
+        darkIcons = useDarkIcons
+    )
+
+    // setStatusBarsColor() and setNavigationBarsColor() also exist
 }
 ```
 
@@ -63,6 +62,10 @@ systemUiController.setStatusBarsColor(
 }
 ```
 
+## Samples
+
+For complete samples, check out the [Insets samples](https://github.com/google/accompanist/tree/main/sample/src/main/java/com/google/accompanist/sample/insets) which all use `SystemUiController` to set transparent system bars.
+
 ## Download
 [![Maven Central](https://img.shields.io/maven-central/v/com.google.accompanist/accompanist-systemuicontroller)](https://search.maven.org/search?q=g:com.google.accompanist)
 

generate_docs.sh

@@ -34,9 +34,6 @@ sed -i.bak 's/$dokka.linkExtension:md/$dokka.linkExtension:html/g' package-list-
 # Build the docs with dokka
 ./gradlew clean dokkaHtmlMultiModule
 
-# Dokka doesn't currently allow us to change the index page name so move it manually
-mv docs/api/-modules.html docs/api/index.html
-
 # Re-word the Dokka call out
 find docs/api/ -type f -name '*.html' -exec sed -i -e 's/Sponsored and developed/Documentation generated/g' {} \;
 # Remove the copyright declaration
@@ -45,8 +42,8 @@ find docs/api/ -type f -name '*.html' -exec sed -i -e 's/© [0-9]* Copyright//'
 # Clean up the temp Coil package list
 rm package-list-coil-base
 
-# Copy over any static + API docs to our $DOCS_ROOT
-cp -R docs/* $DOCS_ROOT
+# Create a copy of our docs at our $DOCS_ROOT
+cp -r docs/ $DOCS_ROOT
 
 cp README.md $DOCS_ROOT/index.md
 cp CONTRIBUTING.md $DOCS_ROOT/contributing.md

pager/src/main/java/com/google/accompanist/pager/Pager.kt

@@ -369,7 +369,7 @@ private class PagerScopeImpl(
  * The returned offset can positive or negative, depending on whether which direction the [page] is
  * compared to the current scroll position.
  *
- * @sample com.google.accompanist.sample.pager.HorizontalPagerTransitionSample
+ * @sample com.google.accompanist.sample.pager.HorizontalPagerWithOffsetTransition
  */
 @ExperimentalPagerApi
 fun PagerScope.calculateCurrentOffsetForPage(page: Int): Float {

sample/src/main/java/com/google/accompanist/sample/ImageLoadingSampleUtils.kt

@@ -18,6 +18,10 @@ package com.google.accompanist.sample
 
 private val rangeForRandom = (0..100000)
 
-fun randomSampleImageUrl(seed: Int = rangeForRandom.random()): String {
-    return "https://picsum.photos/seed/$seed/300/300"
+fun randomSampleImageUrl(
+    seed: Int = rangeForRandom.random(),
+    width: Int = 300,
+    height: Int = width,
+): String {
+    return "https://picsum.photos/seed/$seed/$width/$height"
 }

sample/src/main/java/com/google/accompanist/sample/pager/HorizontalPagerBasicSample.kt

@@ -96,7 +96,7 @@ private fun Sample() {
                 Box {
                     // Our page content, displaying a random image
                     CoilImage(
-                        data = randomSampleImageUrl(page + 100),
+                        data = randomSampleImageUrl(width = 600),
                         contentDescription = null,
                         fadeIn = true,
                         modifier = Modifier

sample/src/main/java/com/google/accompanist/sample/pager/HorizontalPagerTransitionSample.kt

@@ -123,7 +123,7 @@ fun HorizontalPagerWithOffsetTransition() {
         ) {
             Box {
                 CoilImage(
-                    data = randomSampleImageUrl(),
+                    data = randomSampleImageUrl(width = 600),
                     contentDescription = null,
                     fadeIn = true,
                     modifier = Modifier.fillMaxSize()