Add rememberResponsiveColumnPadding (#2450)

This change introduces a new composable function, `rememberResponsiveColumnPadding`, to calculate and remember padding values for Wear columns based on screen size and item types.

It also adds a `ColumnItemType` interface with default implementations for common item types to determine padding, improving responsive design for Wear OS columns.

Finally, it updates `rememberResponsiveColumnState` to use `rememberResponsiveColumnPadding` for content padding and includes tests with screenshots to validate padding behavior.

---------

Co-authored-by: yschimke <[email protected]>

compose-layout/api/current.api

@@ -43,6 +43,27 @@ package com.google.android.horologist.compose.layout {
     method @androidx.compose.runtime.Composable public static void AppScaffold(optional androidx.compose.ui.Modifier modifier, optional kotlin.jvm.functions.Function0<kotlin.Unit> timeText, kotlin.jvm.functions.Function1<? super androidx.compose.foundation.layout.BoxScope,kotlin.Unit> content);
   }
 
+  public interface ColumnItemType {
+    method @androidx.compose.runtime.Composable public float bottomPadding(float horizontalPercent);
+    method @androidx.compose.runtime.Composable public float topPadding(float horizontalPercent);
+    field public static final com.google.android.horologist.compose.layout.ColumnItemType.Companion Companion;
+  }
+
+  public static final class ColumnItemType.Companion {
+    method public com.google.android.horologist.compose.layout.ColumnItemType getBodyText();
+    method public com.google.android.horologist.compose.layout.ColumnItemType getButton();
+    method public com.google.android.horologist.compose.layout.ColumnItemType getButtonRow();
+    method public com.google.android.horologist.compose.layout.ColumnItemType getCard();
+    method public com.google.android.horologist.compose.layout.ColumnItemType getIconButton();
+    method public com.google.android.horologist.compose.layout.ColumnItemType getListHeader();
+    property public final com.google.android.horologist.compose.layout.ColumnItemType BodyText;
+    property public final com.google.android.horologist.compose.layout.ColumnItemType Button;
+    property public final com.google.android.horologist.compose.layout.ColumnItemType ButtonRow;
+    property public final com.google.android.horologist.compose.layout.ColumnItemType Card;
+    property public final com.google.android.horologist.compose.layout.ColumnItemType IconButton;
+    property public final com.google.android.horologist.compose.layout.ColumnItemType ListHeader;
+  }
+
   public final class FillMaxRectangleKt {
     method @androidx.compose.runtime.Stable public static androidx.compose.ui.Modifier fillMaxRectangle(androidx.compose.ui.Modifier);
   }
@@ -73,10 +94,12 @@ package com.google.android.horologist.compose.layout {
     field public static final com.google.android.horologist.compose.layout.ScalingLazyColumnDefaults INSTANCE;
   }
 
-  public enum ScalingLazyColumnDefaults.ItemType {
+  public enum ScalingLazyColumnDefaults.ItemType implements com.google.android.horologist.compose.layout.ColumnItemType {
+    method @androidx.compose.runtime.Composable public float bottomPadding(float horizontalPercent);
     method public final float getBottomPaddingPct();
     method public final float getPaddingCorrection();
     method public final float getTopPaddingPct();
+    method @androidx.compose.runtime.Composable public float topPadding(float horizontalPercent);
     method public static com.google.android.horologist.compose.layout.ScalingLazyColumnDefaults.ItemType valueOf(String value) throws java.lang.IllegalArgumentException, java.lang.NullPointerException;
     method public static com.google.android.horologist.compose.layout.ScalingLazyColumnDefaults.ItemType[] values();
     property public final float bottomPaddingPct;
@@ -173,6 +196,10 @@ package com.google.android.horologist.compose.layout {
     method public static androidx.compose.ui.Modifier scrollAway(androidx.compose.ui.Modifier, kotlin.jvm.functions.Function0<? extends androidx.compose.foundation.gestures.ScrollableState> scrollableState);
   }
 
+  public final class TransformingLazyColumnDefaultsKt {
+    method @androidx.compose.runtime.Composable public static androidx.compose.foundation.layout.PaddingValues rememberResponsiveColumnPadding(optional com.google.android.horologist.compose.layout.ColumnItemType first, optional com.google.android.horologist.compose.layout.ColumnItemType last, optional float horizontalPercent);
+  }
+
 }
 
 package com.google.android.horologist.compose.nav {

compose-layout/build.gradle.kts

@@ -107,6 +107,7 @@ dependencies {
     debugImplementation(libs.androidx.activity.compose)
     debugImplementation(libs.compose.ui.test.manifest)
 
+    testImplementation(libs.androidx.wear.compose.material3)
     testImplementation(libs.junit)
     testImplementation(libs.truth)
     testImplementation(libs.compose.ui.test.junit4)

compose-layout/src/main/java/com/google/android/horologist/compose/layout/ScalingLazyColumnDefaults.kt

@@ -230,7 +230,7 @@ public object ScalingLazyColumnDefaults {
         val topPaddingPct: Float,
         val bottomPaddingPct: Float,
         val paddingCorrection: Dp = 0.dp,
-    ) {
+    ) : ColumnItemType {
         Card(Padding21Pct, Padding31Pct),
         Chip(Padding21Pct, Padding31Pct),
         CompactChip(
@@ -245,6 +245,43 @@ public object ScalingLazyColumnDefaults {
         BodyText(Padding21Pct, Padding31Pct),
         Dialog(Padding14Pct, Padding20Pct),
         Unspecified(0f, 0f),
+        ;
+
+        @Composable
+        override fun topPadding(horizontalPercent: Float): Dp {
+            val configuration = LocalConfiguration.current
+            val screenWidthDp = configuration.screenWidthDp.dp
+            val screenHeightDp = configuration.screenHeightDp.dp
+
+            return if (this != Unspecified) {
+                topPaddingPct * screenHeightDp + paddingCorrection
+            } else {
+                if (configuration.isScreenRound) {
+                    calculateVerticalOffsetForChip(screenWidthDp.value, horizontalPercent)
+                } else {
+                    32.dp
+                }
+            }
+        }
+
+        @Composable
+        override fun bottomPadding(horizontalPercent: Float): Dp {
+            val configuration = LocalConfiguration.current
+            val screenWidthDp = configuration.screenWidthDp.dp
+            val screenHeightDp = configuration.screenHeightDp.dp
+            return if (this != Unspecified) {
+                bottomPaddingPct * screenHeightDp + paddingCorrection
+            } else {
+                if (configuration.isScreenRound) {
+                    calculateVerticalOffsetForChip(
+                        screenWidthDp.value,
+                        horizontalPercent,
+                    ) + 10.dp
+                } else {
+                    0.dp
+                }
+            }
+        }
     }
 
     @Composable

compose-layout/src/main/java/com/google/android/horologist/compose/layout/ScalingLazyColumnState.kt

@@ -166,10 +166,12 @@ public fun rememberResponsiveColumnState(
 
 @Composable
 public fun rememberResponsiveColumnState(
-    contentPadding: @Composable () -> PaddingValues = ScalingLazyColumnDefaults.padding(
-        first = ItemType.Unspecified,
-        last = ItemType.Unspecified,
-    ),
+    contentPadding: @Composable () -> PaddingValues = {
+        rememberResponsiveColumnPadding(
+            first = ItemType.Unspecified,
+            last = ItemType.Unspecified,
+        )
+    },
     verticalArrangement: Arrangement.Vertical =
         Arrangement.spacedBy(
             space = 4.dp,

compose-layout/src/main/java/com/google/android/horologist/compose/layout/TransformingLazyColumnDefaults.kt

@@ -0,0 +1,97 @@
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * 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.
+ */
+
+package com.google.android.horologist.compose.layout
+
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.platform.LocalConfiguration
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+import com.google.android.horologist.compose.layout.ScalingLazyColumnDefaults.ItemType
+
+/**
+ * Calculates and remembers padding values for a Wear column based on screen size and item types.
+ *
+ * This function is designed to provide responsive padding for columns, specifically in Wear OS,
+ * taking into account the screen shape (round or rectangular) and the types of items
+ * at the beginning and end of the column.
+ *
+ * @param first The type of the first item in the column. Used to determine top padding.
+ *              Defaults to a safe value of [ItemType.Unspecified].
+ * @param last The type of the last item in the column. Used to determine bottom padding.
+ *             Defaults to a safe value of [ItemType.Unspecified].
+ * @param horizontalPercent The percentage of the screen width to use for horizontal padding.
+ *                          Defaults to 5.2%.
+ *
+ * @return A [PaddingValues] object containing the calculated padding values.
+ */
+@Composable
+public fun rememberResponsiveColumnPadding(
+    first: ColumnItemType = ItemType.Unspecified,
+    last: ColumnItemType = ItemType.Unspecified,
+    horizontalPercent: Float = 0.052f,
+): PaddingValues {
+    val configuration = LocalConfiguration.current
+    val screenWidthDp = configuration.screenWidthDp.dp
+
+    val horizontalPadding = screenWidthDp * horizontalPercent
+
+    return PaddingValues(
+        top = first.topPadding(horizontalPercent),
+        bottom = last.bottomPadding(horizontalPercent),
+        start = horizontalPadding,
+        end = horizontalPadding,
+    )
+}
+
+/**
+ * Represents the types of items that can be placed in a Wear column and how to calculate an
+ * optimal or safe padding.
+ */
+public interface ColumnItemType {
+    /**
+     * Calculates the padding for the top of the Column based on the provided horizontal padding.
+     */
+    @Composable
+    public fun topPadding(horizontalPercent: Float): Dp
+
+    /**
+     * Calculates the padding for the bottom of the Column based on the provided horizontal padding.
+     */
+    @Composable
+    public fun bottomPadding(horizontalPercent: Float): Dp
+
+    companion object {
+        val Button: ColumnItemType
+            get() = ItemType.Chip
+
+        val ListHeader: ColumnItemType
+            get() = ItemType.Text
+
+        val BodyText: ColumnItemType
+            get() = ItemType.BodyText
+
+        val Card: ColumnItemType
+            get() = ItemType.Card
+
+        val IconButton: ColumnItemType
+            get() = ItemType.SingleButton
+
+        val ButtonRow: ColumnItemType
+            get() = ItemType.MultiButton
+    }
+}

compose-layout/src/test/java/com/google/android/horologist/compose/layout/TransformingLazyColumnDefaultsTest.kt

@@ -0,0 +1,104 @@
+/*
+ * Copyright 2022 The Android Open Source Project
+ *
+ * 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.
+ */
+
+package com.google.android.horologist.compose.layout
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.testTag
+import androidx.wear.compose.foundation.lazy.TransformingLazyColumn
+import androidx.wear.compose.foundation.lazy.TransformingLazyColumnState
+import androidx.wear.compose.foundation.lazy.rememberTransformingLazyColumnState
+import androidx.wear.compose.material3.AppScaffold
+import androidx.wear.compose.material3.ListHeader
+import androidx.wear.compose.material3.MaterialTheme
+import androidx.wear.compose.material3.ScreenScaffold
+import androidx.wear.compose.material3.Text
+import androidx.wear.compose.material3.TimeText
+import androidx.wear.compose.material3.TitleCard
+import androidx.wear.compose.material3.lazy.scrollTransform
+import com.google.android.horologist.screenshots.rng.WearDevice
+import com.google.android.horologist.screenshots.rng.WearScreenshotTest
+import kotlinx.coroutines.runBlocking
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.ParameterizedRobolectricTestRunner
+
+@RunWith(ParameterizedRobolectricTestRunner::class)
+class TransformingLazyColumnDefaultsTest(override val device: WearDevice) : WearScreenshotTest() {
+    @Composable
+    override fun TestScaffold(content: @Composable (() -> Unit)) {
+        content()
+    }
+
+    @Test
+    fun TitleAndCard() {
+        lateinit var columnState: TransformingLazyColumnState
+        runTest {
+            AppScaffold(
+                timeText = {
+                    TimeText {
+                        text("10:10")
+                    }
+                },
+                // Why black needed here
+                modifier = Modifier.background(MaterialTheme.colorScheme.background),
+            ) {
+                columnState = rememberTransformingLazyColumnState()
+                ScreenScaffold(scrollState = columnState) {
+                    TransformingLazyColumn(
+                        state = columnState,
+                        contentPadding = rememberResponsiveColumnPadding(
+                            first = ColumnItemType.ListHeader,
+                            last = ColumnItemType.Card,
+                        ),
+                        modifier = Modifier.fillMaxSize().testTag("TransformingLazyColumn"),
+                    ) {
+                        item {
+                            ListHeader(modifier = Modifier.scrollTransform(this)) {
+                                Text("Title")
+                            }
+                        }
+                        items(3) {
+                            TitleCard(
+                                modifier = Modifier.scrollTransform(this),
+                                onClick = { /* Do something */ },
+                                title = { Text("Title card") },
+                                time = { Text("now") },
+                            ) { Text("Card content") }
+                        }
+                    }
+                }
+            }
+        }
+
+        composeRule.waitForIdle()
+
+        runBlocking {
+            columnState.scrollToItem(5)
+        }
+
+        captureScreenshot("_end")
+    }
+
+    companion object {
+        @JvmStatic
+        @ParameterizedRobolectricTestRunner.Parameters
+        fun devices() = WearDevice.entries
+    }
+}