Update readme and add docs

tunjid · Sep 7, 2024 · 2887865 · 2887865
1 parent 66c5aa2
commit 2887865
Show file tree

Hide file tree

Showing 23 changed files with 264 additions and 37 deletions.
diff --git a/docs/images/alignment_interpolation_crop.gif b/docs/images/alignment_interpolation_crop.gif
diff --git a/docs/images/collapsing_header_fast_scroll_grid_crop.gif b/docs/images/collapsing_header_fast_scroll_grid_crop.gif
diff --git a/docs/images/collapsing_header_fast_scroll_list_crop.gif b/docs/images/collapsing_header_fast_scroll_list_crop.gif
diff --git a/docs/images/collapsing_header_fast_scroll_staggered_grid_crop.gif b/docs/images/collapsing_header_fast_scroll_staggered_grid_crop.gif
diff --git a/docs/images/content_scale_interpolation_crop.gif b/docs/images/content_scale_interpolation_crop.gif
diff --git a/docs/images/drag_to_dismiss_app_image.gif b/docs/images/drag_to_dismiss_app_image.gif
diff --git a/docs/images/drag_to_dismiss_app_video.gif b/docs/images/drag_to_dismiss_app_video.gif
diff --git a/docs/images/drag_to_dismiss_crop.gif b/docs/images/drag_to_dismiss_crop.gif
diff --git a/docs/images/pointer_offset_grid_crop.gif b/docs/images/pointer_offset_grid_crop.gif
diff --git a/docs/images/pointer_offset_list_crop.gif b/docs/images/pointer_offset_list_crop.gif
diff --git a/docs/images/pointer_offset_staggered_grid_crop.gif b/docs/images/pointer_offset_staggered_grid_crop.gif
diff --git a/docs/images/sticky_header_grid_crop.gif b/docs/images/sticky_header_grid_crop.gif
diff --git a/docs/images/sticky_header_list_crop.gif b/docs/images/sticky_header_list_crop.gif
diff --git a/docs/images/sticky_header_staggered_grid_crop.gif b/docs/images/sticky_header_staggered_grid_crop.gif
diff --git a/docs/implementation/collapsing_headers.md b/docs/implementation/collapsing_headers.md
@@ -0,0 +1,21 @@
+ # Collapsing Header
+
+Collapsing headers in the library are achieved with a wrapping Composable enclosing a scrollable
+layout.
+
+```kotlin
+@Composable
+fun CollapsingHeader(
+    state: CollapsingHeaderState,
+    headerContent: @Composable () -> Unit,
+    body: @Composable () -> Unit,
+) {
+    ...
+}
+```
+
+It works with any layout in the body composable that supports nested scrolling.
+
+| Composable          |                                                                                                          |                                                                                                          |                                                                                                                             |
+|---------------------|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
+| Collapsing Headers  | ![collapsing header with scrollbars in a list](../../images/collapsing_header_fast_scroll_list_crop.gif) | ![collapsing header with scrollbars in a grid](../../images/collapsing_header_fast_scroll_grid_crop.gif) | ![collapsing header with scrollbars in staggered_grid](../../images/collapsing_header_fast_scroll_staggered_grid_crop.gif ) |
diff --git a/docs/implementation/drag_to_dismiss.md b/docs/implementation/drag_to_dismiss.md
@@ -0,0 +1,29 @@
+ # Drag To Dismiss
+
+Used for easily implementing the drag to dismiss pattern for media.
+
+```kotlin
+@Composable
+fun ParentLayout() {
+    Child(
+        modifier = Modifier
+            .dragToDismiss(
+                state = dragToDismissState,
+                dragThresholdCheck = { offset, _ ->
+                    offset.getDistanceSquared() > with(density) {
+                        240.dp.toPx().let { it * it }
+                    }
+                },
+                onDismissed = {
+                    ...
+                },
+            )
+    )
+    ...
+}
+```
+
+
+| Composable                        |                                                                                      |                                                                                                   |                                                                                            |
+|-----------------------------------|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
+| Drag To Dismiss                   | ![color drag to dismiss](../../images/drag_to_dismiss_crop.gif)                      | ![image drag to dismiss](../../images/drag_to_dismiss_app_image.gif)                              | ![video drag to dismiss](../../images/drag_to_dismiss_app_video.gif)                       |
diff --git a/docs/implementation/interpolation.md b/docs/implementation/interpolation.md
@@ -0,0 +1,24 @@
+ # Interpolation
+
+`Alignment` and `ContentScale` are used to help in the layout of composables, however it can be
+necessary to interpolate between them when they change. `interpolate()` Composable extension
+methods are added to help create a seamless transition.
+
+```kotlin
+@Composable
+fun ParentLayout(
+    contentScale: ContentScale,
+    alignment: Alignment,
+) {
+    Image(
+        painter = painter,
+        contentScale = contentScale.interpolate(),
+        alignment = alignment.interpolate(),
+    )
+    ...
+}
+```
+
+| Composable                             |                                                                                          |                                                                                 |
+|----------------------------------------|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
+| Alignment / ContentScale Interpolation | ![rounded rect interpolation](../../images/alignment_interpolation_crop.gif)             | ![beach scene interpolation](../../images/content_scale_interpolation_crop.gif) |                     
diff --git a/docs/implementation/pointer_offset.md b/docs/implementation/pointer_offset.md
@@ -0,0 +1,17 @@
+ # Pointer Offset Scroll Header
+
+Pointer offsets are useful for manually scrolling containers with [ScrollableState], when the
+pointer is already involved in another interaction. For example drag and drop or a long press.
+
+```kotlin
+@Composable
+fun Modifier.pointerOffsetScroll(
+    state: PointerOffsetScrollState,
+) {
+    ...
+}
+```
+
+| Composable                        |                                                                                                  |                                                                                  |                                                                                                               |
+|-----------------------------------|--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
+| Pointer Offset Scroll             | ![pointer offset list scroll](../../images/pointer_offset_list_crop.gif)                         | ![pointer offset grid scroll](../../images/pointer_offset_grid_crop.gif)         | ![pointer offset staggered grid](../../images/pointer_offset_staggered_grid_crop.gif)                         |
diff --git a/docs/implementation/scrollbars.md b/docs/implementation/scrollbars.md
@@ -0,0 +1,51 @@
+# Scrollbars
+
+Scrollbars enable tracking a user's position in the list and fast scrolling through it.
+
+For lazy containers, the easiest way to use them is via the `scrollbarState` extension method:
+
+```kotlin
+@Composable
+fun Lazy_State.scrollbarState(
+    itemsAvailable: Int,
+    itemIndex: (Lazy_ItemInfo) -> Int = Lazy_ItemInfo::index,
+): ScrollbarState {
+    ...
+}
+```
+
+Use of the scroll bar follows the following pattern:
+
+```kotlin
+@Composable
+fun FastScrollbar(
+    modifier: Modifier = Modifier,
+    state: ScrollbarState,
+    scrollInProgress: Boolean,
+    orientation: Orientation,
+    onThumbMoved: (Float) -> Unit,
+) {
+    val interactionSource = remember { MutableInteractionSource() }
+    Scrollbar(
+        modifier = modifier,
+        orientation = orientation,
+        interactionSource = interactionSource,
+        state = state,
+        thumb = {
+            FastScrollbarThumb(
+                scrollInProgress = scrollInProgress,
+                interactionSource = interactionSource,
+                orientation = orientation,
+            )
+        },
+        onThumbMoved = onThumbMoved,
+    )
+}
+```
+
+They are implemented for scrollable containers with [ScrollState], lists, grids and staggered grids.
+
+
+| Composable                        |                                                                                                           |                                                                                                           |                                                                                                                         |
+|-----------------------------------|-----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
+| Collapsing Headers and Scrollbars | ![collapsing header with scrollbars in a list](../../images/collapsing_header_fast_scroll_list_crop.gif)  | ![collapsing header with scrollbars in a grid](../../images/collapsing_header_fast_scroll_grid_crop.gif)  | ![collapsing header with scrollbars in staggered_grid](../../images/collapsing_header_fast_scroll_staggered_grid_crop.gif)   |
diff --git a/docs/implementation/sticky_headers.md b/docs/implementation/sticky_headers.md
@@ -0,0 +1,22 @@
+# Sticky Headers
+
+Sticky headers in the library are achieved with a wrapping Composable enclosing the lazy layout.
+
+```kotlin
+@Composable
+fun StickyHeader_(
+    state: Lazy_State,
+    modifier: Modifier = Modifier,
+    isStickyHeaderItem: @DisallowComposableCalls (Lazy_ItemInfo) -> Boolean,
+    stickyHeader: @Composable (key: Any?, contentType: Any?) -> Unit,
+    content: @Composable () -> Unit
+) {
+    ...
+}
+```
+
+They are implemented for lists, grids and staggered grids.
+
+| Composable                        |                                                   |                                                   |                                                                       |
+|-----------------------------------|---------------------------------------------------|---------------------------------------------------|-----------------------------------------------------------------------|
+| Sticky Headers                    | ![list](../../images/sticky_header_list_crop.gif) | ![grid](../../images/sticky_header_grid_crop.gif) | ![staggered_grid](../../images/sticky_header_staggered_grid_crop.gif) |
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,75 @@
+# Composables
+
+[![JVM Tests](https://github.com/tunjid/Composable/actions/workflows/tests.yml/badge.svg)](https://github.com/tunjid/Tiler/actions/workflows/tests.yml)
+![Composables](https://img.shields.io/maven-central/v/com.tunjid.compsables/compsables?label=compsables)
+
+![badge][badge-ios]
+![badge][badge-js]
+![badge][badge-jvm]
+![badge][badge-linux]
+![badge][badge-windows]
+![badge][badge-mac]
+![badge][badge-tvos]
+![badge][badge-watchos]
+
+Please note, this is an experimental repository. It is a Kotlin multiplatform experiment that makes no guarantees
+about API stability or long term support. None of the works presented here are production tested, and should not be
+taken as anything more than its face value.
+
+## Introduction
+
+Composables are a collection of utility methods that build on the Jetpack Compose UI and Foundation packages.
+
+They offer APIs for common UI interactions that make UI more delightful. They are summarize below
+
+| Composable                             |                                                                                                      |                                                                                                      |                                                                                                                        |
+|----------------------------------------|------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
+| Sticky Headers                         | ![list](./images/sticky_header_list_crop.gif)                                                        | ![grid](./images/sticky_header_grid_crop.gif)                                                        | ![staggered_grid](./images/sticky_header_staggered_grid_crop.gif)                                                      |
+| Collapsing Headers and Scrollbars      | ![collapsing header with scrollbars in a list](./images/collapsing_header_fast_scroll_list_crop.gif) | ![collapsing header with scrollbars in a grid](./images/collapsing_header_fast_scroll_grid_crop.gif) | ![collapsing header with scrollbars in staggered_grid](./images/collapsing_header_fast_scroll_staggered_grid_crop.gif) |
+| Pointer Offset Scroll                  | ![pointer offset list scroll](./images/pointer_offset_list_crop.gif)                                 | ![pointer offset grid scroll](./images/pointer_offset_grid_crop.gif)                                 | ![pointer offset staggered grid](./images/pointer_offset_staggered_grid_crop.gif)                                      |
+| Drag To Dismiss                        | ![color drag to dismiss](./images/drag_to_dismiss_crop.gif)                                          | ![image drag to dismiss](./images/drag_to_dismiss_app_image.gif)                                     | ![video drag to dismiss](./images/drag_to_dismiss_app_video.gif)                                                       |
+| Alignment / ContentScale Interpolation | ![rounded rect interpolation](./images/alignment_interpolation_crop.gif)                             | ![beach scene interpolation](./images/content_scale_interpolation_crop.gif)                          |                                                                                                                        |
+
+Please see the [documentation](https://tunjid.github.io/Composables/) for more details.
+
+## License
+
+    Copyright 2023 Adetunji Dahunsi
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    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.
+
+[badge-android]: http://img.shields.io/badge/-android-6EDB8D.svg?style=flat
+
+[badge-jvm]: http://img.shields.io/badge/-jvm-DB413D.svg?style=flat
+
+[badge-js]: http://img.shields.io/badge/-js-F8DB5D.svg?style=flat
+
+[badge-js-ir]: https://img.shields.io/badge/support-[IR]-AAC4E0.svg?style=flat
+
+[badge-nodejs]: https://img.shields.io/badge/-nodejs-68a063.svg?style=flat
+
+[badge-linux]: http://img.shields.io/badge/-linux-2D3F6C.svg?style=flat
+
+[badge-windows]: http://img.shields.io/badge/-windows-4D76CD.svg?style=flat
+
+[badge-wasm]: https://img.shields.io/badge/-wasm-624FE8.svg?style=flat
+
+[badge-apple-silicon]: http://img.shields.io/badge/support-[AppleSilicon]-43BBFF.svg?style=flat
+
+[badge-ios]: http://img.shields.io/badge/-ios-CDCDCD.svg?style=flat
+
+[badge-mac]: http://img.shields.io/badge/-macos-111111.svg?style=flat
+
+[badge-watchos]: http://img.shields.io/badge/-watchos-C0C0C0.svg?style=flat
+
+[badge-tvos]: http://img.shields.io/badge/-tvos-808080.svg?style=flat
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,10 +1,10 @@
 # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
 
 # General setup
-site_name: Tiler
-site_url: https://tunjid.github.io/Tiler/
+site_name: Composables
+site_url: https://tunjid.github.io/Composable/
 site_author: Adetunji Dahunsi
-site_description: A reactive state based pagination library
+site_description: A collection of utility composable functions
 
 theme:
   name: material
@@ -34,24 +34,15 @@ theme:
       toggle:
         icon: material/weather-sunny
         name: Switch to light mode
-repo_url: https://github.com/tunjid/Tiler
+repo_url: https://github.com/tunjid/Composables
 nav:
   - Home: index.md
-  - Tiled lists: implementation/tiledlist.md
-  - Tiling use cases and examples:
-      - Overview: usecases/overview.md
-      - Basic Example: usecases/basic-example.md
-      - Placeholders: usecases/placeholders.md
-      - Search: usecases/search.md
-      - Adaptive Paging: usecases/adaptive-paging.md
-      - Adaptive Paged Search with Placeholders: usecases/complex-tiling.md
-      - Transformations: usecases/transformations.md
-      - Jetpack Compose: usecases/compose.md
-  - How tiling works:
-      - Primitives: implementation/primitives.md
-      - Pivoting: implementation/pivoted-tiling.md
-      - Pagination types and Tiling: implementation/pagination-types.md
-      - Performance: implementation/performance.md
+  - Sticky Headers: implementation/sticky_headers.md
+  - Collapsing Headers: implementation/collapsing_headers.md
+  - Pointer Offset Scroll: implementation/pointer_offset.md
+  - Scrollbars: implementation/scrollbars.md
+  - Drag To Dismiss: implementation/drag_to_dismiss.md
+  - Alignment / Content Scale Interpolation: implementation/interpolation.md
 markdown_extensions:
   - admonition
   - pymdownx.highlight: