Merge pull request #1494 from uchennafokoye/deprecateFlowLayout

[FlowLayout] Deprecate FlowRow and FlowColumn

docs/flowlayout.md

@@ -2,12 +2,17 @@
 
 [![Maven Central](https://img.shields.io/maven-central/v/com.google.accompanist/accompanist-flowlayout)](https://search.maven.org/search?q=g:com.google.accompanist)
 
-Flow layouts adapted from the versions which were available in [Jetpack Compose][compose] until they were removed.
+Flow Layouts in Accompanist is now deprecated. Please see the migration guide below to begin using 
+Flow Layouts in Androidx.
 
-Unlike the standard `Row` and `Column` composables, these layout children across multiple rows/columns if they exceed the available space.
+The official `androidx.compose.foundation` FlowLayouts support is very similar to accompanist/flowlayouts, with a few changes.
 
-## Usage
+It is most similar to `Row` and `Column` and shares similar modifiers and the scopes. 
+Unlike the standard `Row` and `Column` composables, if it runs out of space on the current row, 
+the children are placed in the next line, and this repeats until the children are fully placed.
 
+## Usage
+
 ``` kotlin
 FlowRow {
     // row contents
@@ -18,7 +23,108 @@ FlowColumn {
 }
 ```
 
-For examples, refer to the [samples](https://github.com/google/accompanist/tree/main/sample/src/main/java/com/google/accompanist/sample/flowlayout).
+## Migration Guide to the official FlowLayouts
+
+1. Replace import packages to point to Androidx.Compose
+``` kotlin
+import androidx.compose.foundation.layout.FlowColumn
+```
+
+``` kotlin
+import androidx.compose.foundation.layout.FlowRow
+```
+
+For `FlowColumn`:  
+
+2. Replace Modifier `mainAxisAlignment` with `verticalArrangement` 
+
+3. Replace Modifier `crossAxisAlignment` with `horizontalArrangement`
+
+
+For `FlowRow`  
+
+4. `mainAxisAlignment` is now `horizontalArrangement`  
+
+5. `crossAxisAlignment` is now `verticalArrangement`  
+
+``` kotlin
+FlowColumn(
+    modifier = Modifier,
+    verticalArrangement = Arrangement.Top,
+    horizontalArrangement = Arrangement.Start,
+    content = { // columns }
+) 
+```
+
+``` kotlin
+FlowRow(
+    modifier = Modifier,
+    horizontalArrangement = Arrangement.Start,
+    verticalArrangement = Arrangement.Top,
+    content = { // rows }
+) 
+```
+
+6. Replace `mainAxisSpacing` with `HorizontalArrangement.spacedBy(50.dp, Alignment.*)` in `FlowRow` and `VerticalArrangement.spacedBy(50.dp, Alignment.*)` in `FlowColumn`.
+
+7. Replace `crossAxisSpacing` with `VerticalArrangement.spacedBy(50.dp, Alignment.*)` in `FlowRow` and `HorizontalArrangement.spacedBy(50.dp)` in `FlowColumn`. 
+
+Here `Alignment.*` is the Alignment you wish to use such as `Alignment.Start`, `Alignment.Top` etc
+
+
+``` kotlin
+FlowRow(
+    modifier = Modifier,
+    horizontalArrangement = HorizontalArrangement.spacedBy(50.dp, Alignment.Start),
+    verticalArrangement = VerticalArrangement.spacedBy(50.dp, Alignment.Top),
+    content = { // rows }
+)
+```
+
+``` kotlin
+FlowColumn(
+    modifier = Modifier,
+    verticalArrangement = VerticalArrangement.spacedBy(50.dp, Alignment.Top),
+    horizontalArrangement = HorizontalArrangement.spacedBy(50.dp, Alignment.Start),
+    content = { // columns }
+)
+```
+
+8. `lastLineMainAxisAlignment` is currently not supported in Compose Flow Layouts.
+
+### New Features: 
+#### Add weights to each child
+To scale an item based on the size of its parent and the space available, adding weights is helpful. 
+Adding a weight in `FlowRow` and `FlowColumn` is different than in `Row` and `Column`.
+
+In `FlowLayout`, it is based on the number of items placed on the row it falls on and their weights. 
+First we check to see if an item can fit in the current row or column based on its intrinsic size. 
+If it fits and has a weight, its final size is expanded based on the available space and the number of items 
+with weights placed on the row or column it falls on. 
+
+Because of the nature of `FlowLayouts` an item only expands and does not shrink in size. Its width in `FlowRow`
+or height in `FlowColumn` determines it minimum width or height, and then expands based on its weight and 
+the available space remaining after row items' width/height have been determined.
+
+``` kotlin
+FlowRow() { 
+     repeat(20) { Box(Modifier.size(20.dp).weight(1f, true) } 
+}
+```
+
+#### Create a maximum number of items in row or column
+You may choose to limit the number of items that appear in each row in `FlowRow` or column in `FlowColumn`
+This can be configured using `maxItemsInEachRow` or `maxItemsInEachColumn`: 
+``` kotlin
+FlowRow(maxItemsInEachRow = 3) { 
+     repeat(10) { Box(Modifier.size(20.dp).weight(1f, true) } 
+}
+```
+
+## Examples
+
+For examples, refer to the [Flow Row samples](https://android.googlesource.com/platform/frameworks/support/+/refs/heads/androidx-main/compose/foundation/foundation-layout/samples/src/main/java/androidx/compose/foundation/layout/samples/FlowRowSample.kt) 
+and the [Flow Column samples](https://android.googlesource.com/platform/frameworks/support/+/refs/heads/androidx-main/compose/foundation/foundation-layout/samples/src/main/java/androidx/compose/foundation/layout/samples/FlowColumnSample.kt).
 
 ## Download
 
@@ -30,11 +136,11 @@ repositories {
 }
 
 dependencies {
-    implementation "com.google.accompanist:accompanist-flowlayout:<version>"
+    implementation "androidx.compose.foundation:foundation:<compose-version>"
 }
 ```
 
 Snapshots of the development version are available in [Sonatype's `snapshots` repository][snap]. These are updated on every commit.
 
 [compose]: https://developer.android.com/jetpack/compose
-[snap]: https://oss.sonatype.org/content/repositories/snapshots/com/google/accompanist/accompanist-flowlayout/
+[snap]: https://oss.sonatype.org/content/repositories/snapshots/com/google/accompanist/accompanist-flowlayout/

flowlayout/api/current.api

@@ -1,7 +1,7 @@
 // Signature format: 4.0
 package com.google.accompanist.flowlayout {
 
-  public enum FlowCrossAxisAlignment {
+  @Deprecated public enum FlowCrossAxisAlignment {
     method public static com.google.accompanist.flowlayout.FlowCrossAxisAlignment valueOf(String name) throws java.lang.IllegalArgumentException;
     method public static com.google.accompanist.flowlayout.FlowCrossAxisAlignment[] values();
     enum_constant public static final com.google.accompanist.flowlayout.FlowCrossAxisAlignment Center;
@@ -10,11 +10,11 @@ package com.google.accompanist.flowlayout {
   }
 
   public final class FlowKt {
-    method @androidx.compose.runtime.Composable public static void FlowColumn(optional androidx.compose.ui.Modifier modifier, optional com.google.accompanist.flowlayout.SizeMode mainAxisSize, optional com.google.accompanist.flowlayout.MainAxisAlignment mainAxisAlignment, optional float mainAxisSpacing, optional com.google.accompanist.flowlayout.FlowCrossAxisAlignment crossAxisAlignment, optional float crossAxisSpacing, optional com.google.accompanist.flowlayout.MainAxisAlignment lastLineMainAxisAlignment, kotlin.jvm.functions.Function0<kotlin.Unit> content);
-    method @androidx.compose.runtime.Composable public static void FlowRow(optional androidx.compose.ui.Modifier modifier, optional com.google.accompanist.flowlayout.SizeMode mainAxisSize, optional com.google.accompanist.flowlayout.MainAxisAlignment mainAxisAlignment, optional float mainAxisSpacing, optional com.google.accompanist.flowlayout.FlowCrossAxisAlignment crossAxisAlignment, optional float crossAxisSpacing, optional com.google.accompanist.flowlayout.MainAxisAlignment lastLineMainAxisAlignment, kotlin.jvm.functions.Function0<kotlin.Unit> content);
+    method @Deprecated @androidx.compose.runtime.Composable public static void FlowColumn(optional androidx.compose.ui.Modifier modifier, optional com.google.accompanist.flowlayout.SizeMode mainAxisSize, optional com.google.accompanist.flowlayout.MainAxisAlignment mainAxisAlignment, optional float mainAxisSpacing, optional com.google.accompanist.flowlayout.FlowCrossAxisAlignment crossAxisAlignment, optional float crossAxisSpacing, optional com.google.accompanist.flowlayout.MainAxisAlignment lastLineMainAxisAlignment, kotlin.jvm.functions.Function0<kotlin.Unit> content);
+    method @Deprecated @androidx.compose.runtime.Composable public static void FlowRow(optional androidx.compose.ui.Modifier modifier, optional com.google.accompanist.flowlayout.SizeMode mainAxisSize, optional com.google.accompanist.flowlayout.MainAxisAlignment mainAxisAlignment, optional float mainAxisSpacing, optional com.google.accompanist.flowlayout.FlowCrossAxisAlignment crossAxisAlignment, optional float crossAxisSpacing, optional com.google.accompanist.flowlayout.MainAxisAlignment lastLineMainAxisAlignment, kotlin.jvm.functions.Function0<kotlin.Unit> content);
   }
 
-  public enum MainAxisAlignment {
+  @Deprecated public enum MainAxisAlignment {
     method public static com.google.accompanist.flowlayout.MainAxisAlignment valueOf(String name) throws java.lang.IllegalArgumentException;
     method public static com.google.accompanist.flowlayout.MainAxisAlignment[] values();
     enum_constant public static final com.google.accompanist.flowlayout.MainAxisAlignment Center;
@@ -25,7 +25,7 @@ package com.google.accompanist.flowlayout {
     enum_constant public static final com.google.accompanist.flowlayout.MainAxisAlignment Start;
   }
 
-  public enum SizeMode {
+  @Deprecated public enum SizeMode {
     method public static com.google.accompanist.flowlayout.SizeMode valueOf(String name) throws java.lang.IllegalArgumentException;
     method public static com.google.accompanist.flowlayout.SizeMode[] values();
     enum_constant public static final com.google.accompanist.flowlayout.SizeMode Expand;

flowlayout/src/main/java/com/google/accompanist/flowlayout/Flow.kt

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+@file:Suppress("DEPRECATION")
+
 package com.google.accompanist.flowlayout
 
 import androidx.compose.foundation.layout.Arrangement
@@ -44,6 +46,17 @@ import kotlin.math.max
  * @param lastLineMainAxisAlignment Overrides the main axis alignment of the last row.
  */
 @Composable
+@Deprecated(
+    """
+accompanist/FlowRow is deprecated.
+For more migration information, please visit https://google.github.io/accompanist/flowlayouts/#migration
+""",
+    replaceWith = ReplaceWith(
+        "FlowRow",
+        "androidx.compose.foundation.layout.FlowRow",
+        "androidx.compose.ui.Modifier"
+    )
+)
 public fun FlowRow(
     modifier: Modifier = Modifier,
     mainAxisSize: SizeMode = SizeMode.Wrap,
@@ -82,6 +95,17 @@ public fun FlowRow(
  * @param lastLineMainAxisAlignment Overrides the main axis alignment of the last column.
  */
 @Composable
+@Deprecated(
+    """
+accompanist/FlowColumn is deprecated.
+For more migration information, please visit https://google.github.io/accompanist/flowlayouts/#migration
+""",
+    replaceWith = ReplaceWith(
+        "FlowColumn",
+        "androidx.compose.foundation.layout.FlowColumn",
+        "androidx.compose.ui.Modifier"
+    )
+)
 public fun FlowColumn(
     modifier: Modifier = Modifier,
     mainAxisSize: SizeMode = SizeMode.Wrap,
@@ -108,6 +132,12 @@ public fun FlowColumn(
 /**
  * Used to specify the alignment of a layout's children, in cross axis direction.
  */
+@Deprecated(
+    """
+accompanist/FlowCrossAxisAlignment is deprecated.
+For more migration information, please visit https://google.github.io/accompanist/flowlayouts/#migration
+"""
+)
 public enum class FlowCrossAxisAlignment {
     /**
      * Place children such that their center is in the middle of the cross axis.
@@ -123,12 +153,24 @@ public enum class FlowCrossAxisAlignment {
     End,
 }
 
+@Deprecated(
+    """
+accompanist/FlowMainAxisAlignment is deprecated.
+For more migration information, please visit https://google.github.io/accompanist/flowlayouts/#migration
+"""
+)
 public typealias FlowMainAxisAlignment = MainAxisAlignment
 
 /**
  * Layout model that arranges its children in a horizontal or vertical flow.
  */
 @Composable
+@Deprecated(
+    """
+accompanist/Flow is deprecated.
+For more migration information, please visit https://google.github.io/accompanist/flowlayouts/#migration
+"""
+)
 private fun Flow(
     modifier: Modifier,
     orientation: LayoutOrientation,
@@ -278,6 +320,12 @@ private fun Flow(
  * Used to specify how a layout chooses its own size when multiple behaviors are possible.
  */
 // TODO(popam): remove this when Flow is reworked
+@Deprecated(
+    """
+accompanist/SizeMode is deprecated.
+For more migration information, please visit https://google.github.io/accompanist/flowlayouts/#migration
+"""
+)
 public enum class SizeMode {
     /**
      * Minimize the amount of free space by wrapping the children,
@@ -291,9 +339,6 @@ public enum class SizeMode {
     Expand
 }
 
-/**
- * Used to specify the alignment of a layout's children, in main axis direction.
- */
 public enum class MainAxisAlignment(internal val arrangement: Arrangement.Vertical) {
     // TODO(soboleva) support RTl in Flow
     // workaround for now - use Arrangement that equals to previous Arrangement

flowlayout/src/sharedTest/kotlin/com/google/accompanist/flowlayout/FlowLayoutTest.kt

@@ -33,6 +33,7 @@ import java.util.concurrent.CountDownLatch
 import java.util.concurrent.TimeUnit
 import kotlin.math.roundToInt
 
+@Suppress("DEPRECATION")
 @RunWith(AndroidJUnit4::class)
 class FlowLayoutTest : LayoutTest() {
     @Test

sample/src/main/java/com/google/accompanist/sample/flowlayout/FlowColumnSample.kt

@@ -29,6 +29,7 @@ import com.google.accompanist.flowlayout.FlowColumn
 import com.google.accompanist.sample.AccompanistSampleTheme
 import com.google.accompanist.sample.R
 
+@Suppress("DEPRECATION")
 class FlowColumnSample : ComponentActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)

sample/src/main/java/com/google/accompanist/sample/flowlayout/FlowRowSample.kt

@@ -29,6 +29,7 @@ import com.google.accompanist.flowlayout.FlowRow
 import com.google.accompanist.sample.AccompanistSampleTheme
 import com.google.accompanist.sample.R
 
+@Suppress("DEPRECATION")
 class FlowRowSample : ComponentActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)