diff --git a/.gitignore b/.gitignore index e90229db..c519004b 100644 --- a/.gitignore +++ b/.gitignore @@ -43,6 +43,9 @@ org.eclipse.buildship.core.prefs .project bin/ +# Docs +site/ + ########################################################################################## # Imported from https://github.com/github/gitignore/blob/main/Swift.gitignore diff --git a/README.md b/README.md index 8963e3a8..667b3941 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,6 @@ ## Haze -Snapper is now deprecated, due to it's functionality being replaced by [`SnapFlingBehavior`](https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/snapping/SnapFlingBehavior) which is available in Jetpack Compose 1.3.0. - -The `SnapFlingBehavior` API is very similar to Snapper, so migration should be very easy. I haven't provided an automatic migration path, as I feel that it's important to learn the new API by performing the migration yourself. - -## Library - -![](docs/assets/header.png) - -Snapper is a library which brings snapping to the Compose scrolling layouts (currently only LazyColumn and LazyRow). - Check out the website for more information: https://chrisbanes.github.io/haze ## License diff --git a/docs/assets/croc.svg b/docs/assets/croc.svg deleted file mode 100644 index c75b4bed..00000000 --- a/docs/assets/croc.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/assets/demo.mp4 b/docs/assets/demo.mp4 deleted file mode 100644 index 554296eb..00000000 Binary files a/docs/assets/demo.mp4 and /dev/null differ diff --git a/docs/assets/header.png b/docs/assets/header.png deleted file mode 100644 index d61f3f44..00000000 Binary files a/docs/assets/header.png and /dev/null differ diff --git a/docs/assets/tivi.mp4 b/docs/assets/tivi.mp4 deleted file mode 100644 index 5ab97026..00000000 Binary files a/docs/assets/tivi.mp4 and /dev/null differ diff --git a/docs/index.md b/docs/index.md index 5d4f71c0..92296ab1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,60 +1,9 @@ -[![Maven Central](https://img.shields.io/maven-central/v/dev.chrisbanes.haze/snapper)](https://search.maven.org/search?q=g:dev.chrisbanes.haze) +[![Maven Central](https://img.shields.io/maven-central/v/dev.chrisbanes.haze/haze)](https://search.maven.org/search?q=g:dev.chrisbanes.haze) -![](assets/header.png) - -## Deprecated - -Snapper is now deprecated, due to it's functionality being replaced by [`SnapFlingBehavior`](https://developer.android.com/reference/kotlin/androidx/compose/foundation/gestures/snapping/SnapFlingBehavior) in Jetpack Compose 1.3.0. - -The `SnapFlingBehavior` API is very similar to Snapper, so migration should be very easy. I haven't provided an automatic migration path, as I feel that it's important to learn the new API by performing the migration yourself. - -## Library - -Snapper is a library which brings snapping to the Compose scrolling layouts (currently LazyColumn and LazyRow): - -=== "Sample app" - - - - -=== "Tivi" - - - - -The basic usage looks like so: - -``` kotlin -val lazyListState = rememberLazyListState() - -LazyRow( - state = lazyListState, - flingBehavior = rememberSnapperFlingBehavior(lazyListState), -) { - // content -} -``` - -## API Summary - -The API is generally split into a few things: - -- [SnapperFlingBehavior](api/lib/dev.chrisbanes.haze/-snapper-layout-info/), which is what apps provide to scrollable containers. -- A number of [remember functions](api/lib/dev.chrisbanes.haze/remember-snapper-fling-behavior.html) allowing easy use of `SnapperFlingBehavior` from composables. -- [SnapperFlingLayoutInfo](api/lib/dev.chrisbanes.haze/-snapper-layout-info/), which is an facade class allowing `SnapperFlingBehavior` to interact with different scrollable container state in a generic way. -- Implementations of `SnapperFlingLayoutInfo` for easy integration, such as [LazyListFlingLayoutInfo](api/lib/dev.chrisbanes.haze/-lazy-list-snapper-layout-info/). - -For examples, refer to the [samples](https://github.com/chrisbanes/snapper/tree/main/sample/src/main/java/dev/chrisbanes/snapper/sample). ## Download -[![Maven Central](https://img.shields.io/maven-central/v/dev.chrisbanes.haze/snapper)](https://search.maven.org/search?q=g:dev.chrisbanes.haze) +[![Maven Central](https://img.shields.io/maven-central/v/dev.chrisbanes.haze/haze)](https://search.maven.org/search?q=g:dev.chrisbanes.haze) ```groovy repositories { diff --git a/docs/usage.md b/docs/usage.md deleted file mode 100644 index 01219961..00000000 --- a/docs/usage.md +++ /dev/null @@ -1,130 +0,0 @@ - -## Snap positions - -Snapper supports the customization of where items snap to. By default Snapper will snap -items to the center of the layout container, but you can provide your own 'snap offset' via -the `snapOffsetForItem` parameters. - -`snapOffsetForItem` is a parameter which takes a block in the form of `(layoutInfo: SnapperLayoutInfo, item: SnapperLayoutItemInfo) -> Int`, -and allows apps to supply custom logic of where to snap each individual item. - -A number of predefined values are supplied in the [SnapOffsets](../api/lib/dev.chrisbanes.haze/-snap-offsets/) class, -for snapping items to the start, center and end. - -``` kotlin -LazyRow( - state = lazyListState, - flingBehavior = rememberSnapperFlingBehavior( - lazyListState = lazyListState, - snapOffsetForItem = SnapOffsets.Start, - ), -) { - // content -} -``` - -## Finding the 'current' item - -Most of the time apps will probably use the short-hand convenience function: -`rememberSnapperFlingBehavior(LazyListState)`, but there are times when -it is useful to get access to the `SnapperLayoutInfo`. - -SnapperLayoutInfo provides lots of information about the 'snapping state' of -the scrollable container, and provides access to the 'current item'. - -For example, if you wish to invoke some action when a fling + snap has finished -you can do the following: - -``` kotlin -val lazyListState = rememberLazyListState() -val layoutInfo = rememberLazyListSnapperLayoutInfo(lazyListState) - -LaunchedEffect(lazyListState.isScrollInProgress) { - if (!lazyListState.isScrollInProgress) { - // The scroll (fling) has finished, get the current item and - // do something with it! - val snappedItem = layoutInfo.currentItem - // TODO: do something with snappedItem - } -} - -LazyColumn( - state = lazyListState, - flingBehavior = rememberSnapperFlingBehavior(layoutInfo), -) { - // content -} -``` - -## Customization of the target index - -The `snapIndex` parameter allows customization of the index which Snapper which fling to -after a user has started a fling. - -The block is given the [SnapperLayoutInfo][snapperlayoutinfo], the index where the fling started, and -with the index which Snapper has determined is the correct index to fling, without the layout limits. -The block should return the index which Snapper should fling and snap to. - -The following are some examples of what you can achieve with `snapIndex`. - -### Controlling the maximum fling distance - -The following example sets the `snapIndex` so that the user can only fling up a maximum of 3 items: - -``` kotlin -val MaxItemFling = 3 - -LazyRow( - state = lazyListState, - flingBehavior = rememberSnapperFlingBehavior( - lazyListState = lazyListState, - snapIndex = { layoutInfo, startIndex, targetIndex -> - targetIndex.coerceIn(startIndex - MaxItemFling, startIndex + MaxItemFling) - } - ), -) { - // content -} -``` - -### Snapping groups - -The `snapIndex` parameter can also be used to achieve snapping to 'groups' of items. - -The following example provide a `snapIndex` block which snaps flings to groups of 3 items: - -``` kotlin -val GroupSize = 3 - -LazyRow( - state = lazyListState, - flingBehavior = rememberSnapperFlingBehavior( - lazyListState = lazyListState, - snapIndex = { _, _, targetIndex -> - val mod = targetIndex % GroupSize - if (mod > (GroupSize / 2)) { - // Round up towards infinity - GroupSize + targetIndex - mod - } else { - // Round down towards zero - targetIndex - mod - } - ), -) { - // content -} -``` - -## Animation specs - -SnapperFlingBehavior allows setting of two different animation specs: `decayAnimationSpec` and `springAnimationSpec`. - -- `decayAnimationSpec` is the main spec used for flinging, and is used when the fling has enough velocity to scroll past -the current item. -- `springAnimationSpec` is used when there is not enough velocity to fling using `decayAnimationSpec`, and instead 'snaps' -to the current item. - -Both of the specs can be customized to apps wishes. - - [snapperlayoutinfo]: ../api/lib/dev.chrisbanes.haze/-snapper-layout-info/ - [rememberlazylistsnapperlayoutinfo]: ../api/lib/dev.chrisbanes.haze/remember-lazy-list-snapper-layout-info.html diff --git a/docs/using-snapshot-version.md b/docs/using-snapshot-version.md index 5fd8c0d7..c0238b9e 100644 --- a/docs/using-snapshot-version.md +++ b/docs/using-snapshot-version.md @@ -1,7 +1,6 @@ # Using a Snapshot Version of the Library -If you would like to depend on the cutting edge version of the Snapper -library, you can use the [snapshot versions][snap] that are published to +If you would like to depend on the cutting edge version of the library, you can use the [snapshot versions][snap] that are published to [Sonatype OSSRH](https://central.sonatype.org/)'s snapshot repository. These are updated on every commit to `main`. To do so: diff --git a/mkdocs.yml b/mkdocs.yml index 3771c3d1..e41cec3d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,8 +14,7 @@ repo_url: 'https://github.com/chrisbanes/haze' # Navigation nav: - 'Overview': index.md - - 'Usage': usage.md - - 'API reference': api/lib/dev.chrisbanes.haze/ + - 'API reference': api/ - 'Sample code': https://github.com/chrisbanes/haze/tree/main/sample/shared/src/commonMain/kotlin/dev/chrisbanes/haze/sample # Configuration @@ -24,11 +23,11 @@ theme: language: 'en' logo: assets/croc.svg palette: - primary: 'teal' + primary: 'white' accent: 'teal' font: - text: 'Roboto' - code: 'JetBrains Mono' + text: 'DM Sans' + code: 'Space Mono' # Extensions markdown_extensions: