Introduces WorkflowLayout.update.

We make the cored update method for `WorkflowLayout` public to give apps
complete control over how exactly they collect renderings.

Doing this because the `takeWhileAttached` method used by `start` is causing
problems. Opening this up lets those impacted by these problems avoid them.
In a downstream release, we will upgrade
`androidx.lifecycle:lifecycle-viewmodel` and update the convenient `start` to
use its improved API. Details in #632.

Author: rjrjr

workflow-ui/core-android/api/core-android.api

@@ -206,6 +206,7 @@ public final class com/squareup/workflow1/ui/WorkflowLayout : android/widget/Fra
 	public final fun start (Lkotlinx/coroutines/flow/Flow;Lcom/squareup/workflow1/ui/ViewEnvironment;)V
 	public final fun start (Lkotlinx/coroutines/flow/Flow;Lcom/squareup/workflow1/ui/ViewRegistry;)V
 	public static synthetic fun start$default (Lcom/squareup/workflow1/ui/WorkflowLayout;Lkotlinx/coroutines/flow/Flow;Lcom/squareup/workflow1/ui/ViewEnvironment;ILjava/lang/Object;)V
+	public final fun update (Ljava/lang/Object;Lcom/squareup/workflow1/ui/ViewEnvironment;)V
 }
 
 public abstract class com/squareup/workflow1/ui/WorkflowViewState {

workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/WorkflowLayout.kt

@@ -44,38 +44,43 @@ public class WorkflowLayout(
   private var restoredChildState: SparseArray<Parcelable>? = null
 
   /**
-   * Subscribes to [renderings], and uses [registry] to
-   * [build a new view][ViewRegistry.buildView] each time a new type of rendering is received,
-   * making that view the only child of this one.
+   * Calls [WorkflowViewStub.update] on the [WorkflowViewStub] that is the only
+   * child of this view.
+   *
+   * This is the method called from [start]. It is exposed to allow client code
+   * to make its own choices about how exactly to consume a stream of renderings.
    */
-  public fun start(
-    renderings: Flow<Any>,
-    registry: ViewRegistry
+  public fun update(
+    newRendering: Any,
+    environment: ViewEnvironment
   ) {
-    start(renderings, ViewEnvironment(mapOf(ViewRegistry to registry)))
+    showing.update(newRendering, environment)
+    restoredChildState?.let { restoredState ->
+      restoredChildState = null
+      showing.actual.restoreHierarchyState(restoredState)
+    }
   }
 
   /**
-   * Subscribes to [renderings], and uses the [ViewRegistry] in the given [environment] to
-   * [build a new view][ViewRegistry.buildView] each time a new type of rendering is received,
-   * making that view the only child of this one.
+   * This is the most common way to bootstrap a [Workflow][com.squareup.workflow1.Workflow]
+   * driven UI. Collects [renderings], and calls [start] wih each that is received..
    */
   public fun start(
     renderings: Flow<Any>,
     environment: ViewEnvironment = ViewEnvironment()
   ) {
-    takeWhileAttached(renderings) { show(it, environment) }
+    takeWhileAttached(renderings) { update(it, environment) }
   }
 
-  private fun show(
-    newRendering: Any,
-    environment: ViewEnvironment
+  /**
+   * A convenience overload that builds a [ViewEnvironment] around [registry],
+   * for a bit less boilerplate.
+   */
+  public fun start(
+    renderings: Flow<Any>,
+    registry: ViewRegistry
   ) {
-    showing.update(newRendering, environment)
-    restoredChildState?.let { restoredState ->
-      restoredChildState = null
-      showing.actual.restoreHierarchyState(restoredState)
-    }
+    start(renderings, ViewEnvironment(mapOf(ViewRegistry to registry)))
   }
 
   override fun onSaveInstanceState(): Parcelable {