diff --git a/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt b/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt index 14389936f7..4bbce1f326 100644 --- a/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt +++ b/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt @@ -22,18 +22,38 @@ import app.cash.redwood.layout.api.Constraint import app.cash.redwood.layout.api.CrossAxisAlignment import app.cash.redwood.ui.Margin +/** + * Receiver scope which is used by [LazyColumn] and [LazyRow]. + */ @LayoutScopeMarker public interface LazyListScope { + /** + * Adds a single item. + * + * @param content The content of the item. + */ public fun item( content: @Composable () -> Unit, ) + /** + * Adds a [count] of items. + * + * @param count The items count. + * @param itemContent The content displayed by a single item. + */ public fun items( count: Int, itemContent: @Composable (index: Int) -> Unit, ) } +/** + * Adds a list of items. + * + * @param items The data list. + * @param itemContent The content displayed by a single item. + */ public inline fun LazyListScope.items( items: List, crossinline itemContent: @Composable (item: T) -> Unit, @@ -41,6 +61,12 @@ public inline fun LazyListScope.items( itemContent(items[it]) } +/** + * Adds a list of items where the content of an item is aware of its index. + * + * @param items The data list. + * @param itemContent The content displayed by a single item. + */ public inline fun LazyListScope.itemsIndexed( items: List, crossinline itemContent: @Composable (index: Int, item: T) -> Unit, @@ -50,6 +76,12 @@ public inline fun LazyListScope.itemsIndexed( itemContent(it, items[it]) } +/** + * Adds an array of items. + * + * @param items The data array. + * @param itemContent The content displayed by a single item. + */ public inline fun LazyListScope.items( items: Array, crossinline itemContent: @Composable (item: T) -> Unit, @@ -59,6 +91,12 @@ public inline fun LazyListScope.items( itemContent(items[it]) } +/** + * Adds an array of items where the content of an item is aware of its index. + * + * @param items The data array. + * @param itemContent The content displayed by a single item. + */ public inline fun LazyListScope.itemsIndexed( items: Array, crossinline itemContent: @Composable (index: Int, item: T) -> Unit, @@ -71,6 +109,31 @@ public inline fun LazyListScope.itemsIndexed( @RequiresOptIn("This Redwood LazyLayout API is experimental and may change in the future.") public annotation class ExperimentalRedwoodLazyLayoutApi +/** + * The horizontally scrolling list that only composes and lays out the currently visible items. + * The [content] block defines a DSL which allows you to emit items of different types. For + * example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add + * a list of items. + * + * The purpose of [placeholder] is to define the temporary content of an on-screen item while the + * content of that item (as described by the [content] block) is being retrieved. When the content + * of that item has been retrieved, the [placeholder] is replaced with that of the content. + * + * @param state The state object to be used to control or observe the list's state. + * @param width Sets whether the row's width will wrap its contents ([Constraint.Wrap]) or match the + * width of its parent ([Constraint.Fill]). + * @param height Sets whether the row's height will wrap its contents ([Constraint.Wrap]) or match + * the height of its parent ([Constraint.Fill]). + * @param margin Applies margin (space) around the list. This can also be applied to an individual + * item using `Modifier.margin`. + * @param verticalAlignment the vertical alignment applied to the items. + * @param modifier The modifier to apply to this layout. + * @param placeholder A block which describes the content of each placeholder item. Note that the + * placeholder block will be invoked multiple times, and assumes that the content and its sizing on + * each invocation is identical to one another. + * @param content A block which describes the content. Inside this block you can use methods like + * [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items. + */ @Composable public fun LazyRow( state: LazyListState = rememberLazyListState(), @@ -95,6 +158,38 @@ public fun LazyRow( ) } +/** + * The horizontally scrolling list that only composes and lays out the currently visible items. + * The [content] block defines a DSL which allows you to emit items of different types. For + * example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add + * a list of items. + * + * This function differs from the other [LazyRow] function, in that a refresh indicator is + * conditionally displayed via a vertical swipe gesture when at the beginning of the list. The + * appropriate response to this gesture can be supplied via the [onRefresh] callback. + * + * The purpose of [placeholder] is to define the temporary content of an on-screen item while the + * content of that item (as described by the [content] block) is being retrieved. When the content + * of that item has been retrieved, the [placeholder] is replaced with that of the content. + * + * @param refreshing Whether or not the list should show the pull-to-refresh indicator. + * @param onRefresh Called when a swipe gesture triggers a pull-to-refresh. + * @param state The state object to be used to control or observe the list's state. + * @param width Sets whether the row's width will wrap its contents ([Constraint.Wrap]) or match the + * width of its parent ([Constraint.Fill]). + * @param height Sets whether the row's height will wrap its contents ([Constraint.Wrap]) or match + * the height of its parent ([Constraint.Fill]). + * @param margin Applies margin (space) around the list. This can also be applied to an individual + * item using `Modifier.margin`. + * @param verticalAlignment the vertical alignment applied to the items. + * @param pullRefreshContentColor The color of the pull-to-refresh indicator. + * @param modifier The modifier to apply to this layout. + * @param placeholder A block which describes the content of each placeholder item. Note that the + * placeholder block will be invoked multiple times, and assumes that the content and its sizing on + * each invocation is identical to one another. + * @param content A block which describes the content. Inside this block you can use methods like + * [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items. + */ @ExperimentalRedwoodLazyLayoutApi @Composable public fun LazyRow( @@ -126,6 +221,31 @@ public fun LazyRow( ) } +/** + * The vertically scrolling list that only composes and lays out the currently visible items. + * The [content] block defines a DSL which allows you to emit items of different types. For + * example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add + * a list of items. + * + * The purpose of [placeholder] is to define the temporary content of an on-screen item while the + * content of that item (as described by the [content] block) is being retrieved. When the content + * of that item has been retrieved, the [placeholder] is replaced with that of the content. + * + * @param state The state object to be used to control or observe the list's state. + * @param width Sets whether the row's width will wrap its contents ([Constraint.Wrap]) or match the + * width of its parent ([Constraint.Fill]). + * @param height Sets whether the row's height will wrap its contents ([Constraint.Wrap]) or match + * the height of its parent ([Constraint.Fill]). + * @param margin Applies margin (space) around the list. This can also be applied to an individual + * item using `Modifier.margin`. + * @param horizontalAlignment The horizontal alignment applied to the items. + * @param modifier The modifier to apply to this layout. + * @param placeholder A block which describes the content of each placeholder item. Note that the + * placeholder block will be invoked multiple times, and assumes that the content and its sizing on + * each invocation is identical to one another. + * @param content A block which describes the content. Inside this block you can use methods like + * [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items. + */ @Composable public fun LazyColumn( state: LazyListState = rememberLazyListState(), @@ -150,6 +270,38 @@ public fun LazyColumn( ) } +/** + * The vertically scrolling list that only composes and lays out the currently visible items. + * The [content] block defines a DSL which allows you to emit items of different types. For + * example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add + * a list of items. + * + * This function differs from the other [LazyColumn] function, in that a refresh indicator is + * conditionally displayed via a vertical swipe gesture when at the beginning of the list. The + * appropriate response to this gesture can be supplied via the [onRefresh] callback. + * + * The purpose of [placeholder] is to define the temporary content of an on-screen item while the + * content of that item (as described by the [content] block) is being retrieved. When the content + * of that item has been retrieved, the [placeholder] is replaced with that of the content. + * + * @param refreshing Whether or not the list should show the pull-to-refresh indicator. + * @param onRefresh Called when a swipe gesture triggers a pull-to-refresh. + * @param state The state object to be used to control or observe the list's state. + * @param width Sets whether the row's width will wrap its contents ([Constraint.Wrap]) or match the + * width of its parent ([Constraint.Fill]). + * @param height Sets whether the row's height will wrap its contents ([Constraint.Wrap]) or match + * the height of its parent ([Constraint.Fill]). + * @param margin Applies margin (space) around the list. This can also be applied to an individual + * item using `Modifier.margin`. + * @param horizontalAlignment The horizontal alignment applied to the items. + * @param pullRefreshContentColor The color of the pull-to-refresh indicator. + * @param modifier The modifier to apply to this layout. + * @param placeholder A block which describes the content of each placeholder item. Note that the + * placeholder block will be invoked multiple times, and assumes that the content and its sizing on + * each invocation is identical to one another. + * @param content A block which describes the content. Inside this block you can use methods like + * [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items. + */ @ExperimentalRedwoodLazyLayoutApi @Composable public fun LazyColumn( diff --git a/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyListState.kt b/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyListState.kt index dcf78cfdf4..573eed81ef 100644 --- a/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyListState.kt +++ b/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyListState.kt @@ -25,6 +25,9 @@ import app.cash.redwood.lazylayout.api.ScrollItemIndex private const val DEFAULT_PRELOAD_ITEM_COUNT = 15 +/** + * Creates a [LazyListState] that is remembered across compositions. + */ @Composable public fun rememberLazyListState(): LazyListState { return rememberSaveable(saver = saver) { @@ -42,6 +45,11 @@ private val saver: Saver = Saver( }, ) +/** + * A state object that can be hoisted to control and observe scrolling. + * + * In most cases, this will be created via [rememberLazyListState]. + */ public open class LazyListState { /** * Update this to trigger a programmatic scroll. This may be updated multiple times, including