From 704ea48f1bf632fa45fbdec9cb9dd868a5540469 Mon Sep 17 00:00:00 2001 From: Veyndan Stuart Date: Mon, 15 Jan 2024 15:42:19 +0100 Subject: [PATCH 1/7] Document the lazy layout widget definitions --- .../app/cash/redwood/lazylayout/widgets.kt | 142 ++++++++++++++++++ 1 file changed, 142 insertions(+) diff --git a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt index fb4d6e3c46..40ac4bcbca 100644 --- a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt +++ b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt @@ -25,33 +25,175 @@ import app.cash.redwood.ui.Margin @Widget(1) public data class LazyList( + /** + * The layout orientation of the list. + */ @Property(1) val isVertical: Boolean, + + /** + * Invoked when the user has scrolled the list, such that the `firstVisibleItemIndex` or the + * `lastVisibleItemIndex` has changed. When the user performs a fling, [onViewportChanged] will be + * invoked multiple times. + * + * The `firstVisibleItemIndex` is the index of the first partially visible item within the + * viewport. The `lastVisibleItemIndex` is the index of the last partially visible item within the + * viewport. + */ @Property(2) val onViewportChanged: (firstVisibleItemIndex: Int, lastVisibleItemIndex: Int) -> Unit, + + /** + * The number of un-emitted items before the [items] window. + * + * @see [items] + */ @Property(3) val itemsBefore: Int, + + /** + * The number of un-emitted items after the [items] window. + * + * @see [items] + */ @Property(4) val itemsAfter: Int, + + /** + * Sets whether the list's width will wrap its contents ([Constraint.Wrap]) or match the width of + * its parent ([Constraint.Fill]). + */ @Property(5) val width: Constraint, + + /** + * Sets whether the list's height will wrap its contents ([Constraint.Wrap]) or match the height + * of its parent ([Constraint.Fill]). + */ @Property(6) val height: Constraint, + + /** + * Applies margin (space) around the list. + */ @Property(7) val margin: Margin, + + /** + * If [isVertical], sets the default horizontal alignment for items in this list. Else, sets the + * default vertical alignment for items in this list. + */ @Property(8) val crossAxisAlignment: CrossAxisAlignment, + + /** + * The last [ScrollItemIndex] programmatically requested by the user. + */ @Property(9) val scrollItemIndex: ScrollItemIndex, + + /** + * A block which describes the content of each placeholder item. + */ @Children(1) val placeholder: () -> Unit, + + /** + * The window of items to be inflated by the native lazy list widget implementation. The window + * should be offset by [itemsAfter], and should have a size of + * `count - [itemsBefore] - [itemsAfter]`, where `count` is the total number of items that + * theoretically exists in the list. + * + * This field should not be confused with `LazyListScope.items` (et al.) The functions in + * `LazyListScope` specify what the list theoretically consists of. This property specifies what + * the list practically consists of, as a function of the current view port. This difference is + * what distinguishes the `LazyRow` and `LazyColumn` widgets from their non-lazy counterparts + * (`Row` and `Column`). + */ @Children(2) val items: () -> Unit, ) @Widget(2) public data class RefreshableLazyList( + /** + * The layout orientation of the list. + */ @Property(1) val isVertical: Boolean, + + /** + * Invoked when the user has scrolled the list, such that the `firstVisibleItemIndex` or the + * `lastVisibleItemIndex` has changed. When the user performs a fling, [onViewportChanged] will be + * invoked multiple times. + * + * The `firstVisibleItemIndex` is the index of the first partially visible item within the + * viewport. The `lastVisibleItemIndex` is the index of the last partially visible item within the + * viewport. + */ @Property(2) val onViewportChanged: (firstVisibleItemIndex: Int, lastVisibleItemIndex: Int) -> Unit, + + /** + * The number of un-emitted items before the [items] window. + * + * @see [items] + */ @Property(3) val itemsBefore: Int, + + /** + * The number of un-emitted items after the [items] window. + * + * @see [items] + */ @Property(4) val itemsAfter: Int, + + /** + * Whether or not the list should show the pull-to-refresh indicator. + */ @Property(5) val refreshing: Boolean, + + /** + * Called when a swipe gesture triggers a pull-to-refresh. + */ @Property(6) val onRefresh: (() -> Unit)?, + + /** + * Sets whether the list's width will wrap its contents ([Constraint.Wrap]) or match the width of + * its parent ([Constraint.Fill]). + */ @Property(7) val width: Constraint, + + /** + * Sets whether the list's height will wrap its contents ([Constraint.Wrap]) or match the height + * of its parent ([Constraint.Fill]). + */ @Property(8) val height: Constraint, + + /** + * Applies margin (space) around the list. + */ @Property(9) val margin: Margin, + + /** + * If [isVertical], sets the default horizontal alignment for items in this list. Else, sets the + * default vertical alignment for items in this list. + */ @Property(10) val crossAxisAlignment: CrossAxisAlignment, + + /** + * The last [ScrollItemIndex] programmatically requested by the user. + */ @Property(11) val scrollItemIndex: ScrollItemIndex, + + /** + * The color of the pull-to-refresh indicator as an ARGB color int. + */ @Property(12) val pullRefreshContentColor: UInt, + + /** + * A block which describes the content of each placeholder item. + */ @Children(1) val placeholder: () -> Unit, + + /** + * The window of items to be inflated by the native lazy list widget implementation. The window + * should be offset by [itemsAfter], and should have a size of + * `count - [itemsBefore] - [itemsAfter]`, where `count` is the total number of items that + * theoretically exists in the list. + * + * This field should not be confused with `LazyListScope.items` (et al.) The functions in + * `LazyListScope` specify what the list theoretically consists of. This property specifies what + * the list practically consists of, as a function of the current view port. This difference is + * what distinguishes the `LazyRow` and `LazyColumn` widgets from their non-lazy counterparts + * (`Row` and `Column`). + */ @Children(2) val items: () -> Unit, ) From a9908788e805bebbf5ff30646b289d8c48717161 Mon Sep 17 00:00:00 2001 From: Veyndan Stuart Date: Tue, 16 Jan 2024 16:17:51 +0100 Subject: [PATCH 2/7] Point to the documentation of `RefreshableLazyList` within `LazyList` instead of duplicating the docs --- .../app/cash/redwood/lazylayout/widgets.kt | 73 ++----------------- 1 file changed, 8 insertions(+), 65 deletions(-) diff --git a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt index 40ac4bcbca..6854d4aa61 100644 --- a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt +++ b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt @@ -23,83 +23,26 @@ import app.cash.redwood.schema.Property import app.cash.redwood.schema.Widget import app.cash.redwood.ui.Margin +/** + * The documentation for [LazyList] is a subset of the documentation for [RefreshableLazyList]. In + * order to avoid documentation duplication, see [LazyList]. The documentation should be unified + * once https://github.com/cashapp/redwood/issues/1084 is implemented and [RefreshableLazyList] is + * deprecated and removed. + * + * @see LazyList + */ @Widget(1) public data class LazyList( - /** - * The layout orientation of the list. - */ @Property(1) val isVertical: Boolean, - - /** - * Invoked when the user has scrolled the list, such that the `firstVisibleItemIndex` or the - * `lastVisibleItemIndex` has changed. When the user performs a fling, [onViewportChanged] will be - * invoked multiple times. - * - * The `firstVisibleItemIndex` is the index of the first partially visible item within the - * viewport. The `lastVisibleItemIndex` is the index of the last partially visible item within the - * viewport. - */ @Property(2) val onViewportChanged: (firstVisibleItemIndex: Int, lastVisibleItemIndex: Int) -> Unit, - - /** - * The number of un-emitted items before the [items] window. - * - * @see [items] - */ @Property(3) val itemsBefore: Int, - - /** - * The number of un-emitted items after the [items] window. - * - * @see [items] - */ @Property(4) val itemsAfter: Int, - - /** - * Sets whether the list's width will wrap its contents ([Constraint.Wrap]) or match the width of - * its parent ([Constraint.Fill]). - */ @Property(5) val width: Constraint, - - /** - * Sets whether the list's height will wrap its contents ([Constraint.Wrap]) or match the height - * of its parent ([Constraint.Fill]). - */ @Property(6) val height: Constraint, - - /** - * Applies margin (space) around the list. - */ @Property(7) val margin: Margin, - - /** - * If [isVertical], sets the default horizontal alignment for items in this list. Else, sets the - * default vertical alignment for items in this list. - */ @Property(8) val crossAxisAlignment: CrossAxisAlignment, - - /** - * The last [ScrollItemIndex] programmatically requested by the user. - */ @Property(9) val scrollItemIndex: ScrollItemIndex, - - /** - * A block which describes the content of each placeholder item. - */ @Children(1) val placeholder: () -> Unit, - - /** - * The window of items to be inflated by the native lazy list widget implementation. The window - * should be offset by [itemsAfter], and should have a size of - * `count - [itemsBefore] - [itemsAfter]`, where `count` is the total number of items that - * theoretically exists in the list. - * - * This field should not be confused with `LazyListScope.items` (et al.) The functions in - * `LazyListScope` specify what the list theoretically consists of. This property specifies what - * the list practically consists of, as a function of the current view port. This difference is - * what distinguishes the `LazyRow` and `LazyColumn` widgets from their non-lazy counterparts - * (`Row` and `Column`). - */ @Children(2) val items: () -> Unit, ) From 0a054be623c2c5fa1826eb74c53339b127413488 Mon Sep 17 00:00:00 2001 From: Veyndan Stuart Date: Tue, 16 Jan 2024 16:19:17 +0100 Subject: [PATCH 3/7] Improve docs for `isVertical` --- .../src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt index 6854d4aa61..a9e1885ec3 100644 --- a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt +++ b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt @@ -49,7 +49,7 @@ public data class LazyList( @Widget(2) public data class RefreshableLazyList( /** - * The layout orientation of the list. + * Whether the list should be vertically oriented. */ @Property(1) val isVertical: Boolean, From 48c572227b01b6771ac9bc5b94268c0d5377f5b3 Mon Sep 17 00:00:00 2001 From: Veyndan Stuart Date: Tue, 16 Jan 2024 16:21:44 +0100 Subject: [PATCH 4/7] Point to `LazyRow` docs in `placeholder` --- .../src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt index a9e1885ec3..9ddde8181a 100644 --- a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt +++ b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt @@ -123,6 +123,8 @@ public data class RefreshableLazyList( /** * A block which describes the content of each placeholder item. + * + * @see app.cash.redwood.lazylayout.compose.LazyRow */ @Children(1) val placeholder: () -> Unit, From 17c1ac220890d72e6f2e28cfd22394c9df0ac66b Mon Sep 17 00:00:00 2001 From: Veyndan Stuart Date: Tue, 16 Jan 2024 16:24:34 +0100 Subject: [PATCH 5/7] Expand the `scrollItemIndex` docs --- .../src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt index 9ddde8181a..6738eb6627 100644 --- a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt +++ b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt @@ -112,7 +112,9 @@ public data class RefreshableLazyList( @Property(10) val crossAxisAlignment: CrossAxisAlignment, /** - * The last [ScrollItemIndex] programmatically requested by the user. + * The last [ScrollItemIndex] programmatically requested by the user. The native lazy list widget + * implementation will scroll itself such that the item index will be at the start of the + * viewport. */ @Property(11) val scrollItemIndex: ScrollItemIndex, From d850e0d6c03dab01e5573609cdba352b73e7858a Mon Sep 17 00:00:00 2001 From: Veyndan Stuart Date: Tue, 16 Jan 2024 16:25:30 +0100 Subject: [PATCH 6/7] fixup! Point to the documentation of `RefreshableLazyList` within `LazyList` instead of duplicating the docs --- .../src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt index 6738eb6627..18dbfd8763 100644 --- a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt +++ b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt @@ -26,8 +26,8 @@ import app.cash.redwood.ui.Margin /** * The documentation for [LazyList] is a subset of the documentation for [RefreshableLazyList]. In * order to avoid documentation duplication, see [LazyList]. The documentation should be unified - * once https://github.com/cashapp/redwood/issues/1084 is implemented and [RefreshableLazyList] is - * deprecated and removed. + * once https://github.com/cashapp/redwood/issues/1084 is implemented and [RefreshableLazyList] has + * been deprecated and removed. * * @see LazyList */ From ac875e043f4e2d369167076c6dca441e54293626 Mon Sep 17 00:00:00 2001 From: Veyndan Stuart Date: Tue, 16 Jan 2024 16:51:36 +0100 Subject: [PATCH 7/7] Define the context of the word "emitted" in `items` --- .../main/kotlin/app/cash/redwood/lazylayout/widgets.kt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt index 18dbfd8763..62cd845dea 100644 --- a/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt +++ b/redwood-lazylayout-schema/src/main/kotlin/app/cash/redwood/lazylayout/widgets.kt @@ -131,8 +131,12 @@ public data class RefreshableLazyList( @Children(1) val placeholder: () -> Unit, /** - * The window of items to be inflated by the native lazy list widget implementation. The window - * should be offset by [itemsAfter], and should have a size of + * The window of items to be inflated by the native lazy list widget implementation. The window is + * defined as a sequential subset of the composables emitted in [items]. These composables are + * created by incrementally passing a range of indices to the user-defined `item` factories, as + * specified in the `LazyListScope` functions. + * + * The window should be offset by [itemsAfter], and should have a size of * `count - [itemsBefore] - [itemsAfter]`, where `count` is the total number of items that * theoretically exists in the list. *