Brings ViewStarter to the UI update.

Propagates changes from #602 -- replace `initializeView`
with `viewStarter` to fix #597.

Author: rjrjr

workflow-ui/core-android/src/androidTest/java/com/squareup/workflow1/ui/DecorativeScreenViewFactoryTest.kt

@@ -11,7 +11,7 @@ import org.junit.Test
 internal class DecorativeScreenViewFactoryTest {
   private val instrumentation = InstrumentationRegistry.getInstrumentation()
 
-  @Test fun initializeView_is_only_call_to_showRendering() {
+  @Test fun viewStarter_is_only_call_to_showRendering() {
     val events = mutableListOf<String>()
 
     val innerViewFactory = object : ScreenViewFactory<InnerRendering> {
@@ -38,27 +38,25 @@ internal class DecorativeScreenViewFactoryTest {
         val enhancedEnv = env + (envString to "Updated environment")
         Pair(outer.wrapped, enhancedEnv)
       },
-      initializeView = {
-        val outerRendering = getRendering<OuterRendering>()
-        events += "initializeView $outerRendering ${environment!![envString]}"
-        showFirstRendering()
-        events += "exit initializeView"
+      viewStarter = { view, doStart ->
+        events += "viewStarter ${view.getRendering<Any>()} ${view.environment!![envString]}"
+        doStart()
+        events += "exit viewStarter"
       }
     )
-    val viewRegistry = ViewRegistry(innerViewFactory)
+    val viewRegistry = ViewRegistry(innerViewFactory, outerViewFactory)
     val viewEnvironment = ViewEnvironment(mapOf(ViewRegistry to viewRegistry))
 
-    outerViewFactory.buildView(
-      OuterRendering("outer", InnerRendering("inner")),
+    OuterRendering("outer", InnerRendering("inner")).buildView(
       viewEnvironment,
       instrumentation.context
-    )
+    ).start()
 
     assertThat(events).containsExactly(
-      "initializeView OuterRendering(outerData=outer, wrapped=InnerRendering(innerData=inner)) " +
+      "viewStarter OuterRendering(outerData=outer, wrapped=InnerRendering(innerData=inner)) " +
         "Updated environment",
       "inner showRendering InnerRendering(innerData=inner)",
-      "exit initializeView"
+      "exit viewStarter"
     )
   }
 
@@ -86,21 +84,97 @@ internal class DecorativeScreenViewFactoryTest {
         innerShowRendering(outerRendering.wrapped, env)
       }
     )
-    val viewRegistry = ViewRegistry(innerViewFactory)
+    val viewRegistry = ViewRegistry(innerViewFactory, outerViewFactory)
     val viewEnvironment = ViewEnvironment(mapOf(ViewRegistry to viewRegistry))
 
-    outerViewFactory.buildView(
-      OuterRendering("outer", InnerRendering("inner")),
+    OuterRendering("outer", InnerRendering("inner")).buildView(
       viewEnvironment,
       instrumentation.context
-    )
+    ).start()
 
     assertThat(events).containsExactly(
       "doShowRendering OuterRendering(outerData=outer, wrapped=InnerRendering(innerData=inner))",
       "inner showRendering InnerRendering(innerData=inner)"
     )
   }
 
+  // https://github.com/square/workflow-kotlin/issues/597
+  @Test fun double_wrapping_only_calls_showRendering_once() {
+    val events = mutableListOf<String>()
+
+    val innerViewFactory = object : ScreenViewFactory<InnerRendering> {
+      override val type = InnerRendering::class
+      override fun buildView(
+        initialRendering: InnerRendering,
+        initialViewEnvironment: ViewEnvironment,
+        contextForNewView: Context,
+        container: ViewGroup?
+      ): View = InnerView(contextForNewView).apply {
+        bindShowRendering(initialRendering, initialViewEnvironment) { rendering, _ ->
+          events += "inner showRendering $rendering"
+        }
+      }
+    }
+
+    val envString = object : ViewEnvironmentKey<String>(String::class) {
+      override val default: String get() = "Not set"
+    }
+
+    val outerViewFactory = DecorativeScreenViewFactory(
+      type = OuterRendering::class,
+      map = { outer, env ->
+        val enhancedEnv = env + (envString to "Outer Updated environment" +
+          " SHOULD NOT SEE THIS! It will be clobbered by WayOutRendering")
+        Pair(outer.wrapped, enhancedEnv)
+      },
+      viewStarter = { view, doStart ->
+        events += "outer viewStarter ${view.getRendering<Any>()} ${view.environment!![envString]}"
+        doStart()
+        events += "exit outer viewStarter"
+      }
+    )
+
+    val wayOutViewFactory = DecorativeScreenViewFactory(
+      type = WayOutRendering::class,
+      map = { wayOut, env ->
+        val enhancedEnv = env + (envString to "Way Out Updated environment triumphs over all")
+        Pair(wayOut.wrapped, enhancedEnv)
+      },
+      viewStarter = { view, doStart ->
+        events += "way out viewStarter ${view.getRendering<Any>()} ${view.environment!![envString]}"
+        doStart()
+        events += "exit way out viewStarter"
+      }
+    )
+    val viewRegistry = ViewRegistry(innerViewFactory, outerViewFactory, wayOutViewFactory)
+    val viewEnvironment = ViewEnvironment(mapOf(ViewRegistry to viewRegistry))
+
+    WayOutRendering("way out", OuterRendering("outer", InnerRendering("inner"))).buildView(
+      viewEnvironment,
+      instrumentation.context
+    ).start()
+
+    assertThat(events).containsExactly(
+      "way out viewStarter " +
+        "WayOutRendering(wayOutData=way out, wrapped=" +
+        "OuterRendering(outerData=outer, wrapped=" +
+        "InnerRendering(innerData=inner))) " +
+        "Way Out Updated environment triumphs over all",
+      "outer viewStarter " +
+        // Notice that both the initial rendering and the ViewEnvironment are stomped by
+        // the outermost wrapper before inners are invoked. Could try to give
+        // the inner wrapper access to the rendering it expected, but there are no
+        // use cases and it trashes the API.
+        "WayOutRendering(wayOutData=way out, wrapped=" +
+        "OuterRendering(outerData=outer, wrapped=" +
+        "InnerRendering(innerData=inner))) " +
+        "Way Out Updated environment triumphs over all",
+      "inner showRendering InnerRendering(innerData=inner)",
+      "exit outer viewStarter",
+      "exit way out viewStarter"
+    )
+  }
+
   @Test fun subsequent_showRendering_calls_wrapped_showRendering() {
     val events = mutableListOf<String>()
 
@@ -125,14 +199,13 @@ internal class DecorativeScreenViewFactoryTest {
         innerShowRendering(outerRendering.wrapped, env)
       }
     )
-    val viewRegistry = ViewRegistry(innerViewFactory)
+    val viewRegistry = ViewRegistry(innerViewFactory, outerViewFactory)
     val viewEnvironment = ViewEnvironment(mapOf(ViewRegistry to viewRegistry))
 
-    val view = outerViewFactory.buildView(
-      OuterRendering("out1", InnerRendering("in1")),
+    val view = OuterRendering("out1", InnerRendering("in1")).buildView(
       viewEnvironment,
       instrumentation.context
-    )
+    ).apply { start() }
     events.clear()
 
     view.showRendering(OuterRendering("out2", InnerRendering("in2")), viewEnvironment)
@@ -149,5 +222,10 @@ internal class DecorativeScreenViewFactoryTest {
     val wrapped: InnerRendering
   ) : Screen
 
+  private data class WayOutRendering(
+    val wayOutData: String,
+    val wrapped: OuterRendering
+  ) : Screen
+
   private class InnerView(context: Context) : View(context)
 }

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

@@ -35,22 +35,27 @@ public fun <RenderingT : Any> ViewRegistry.getFactoryFor(
 }
 
 @Suppress("DEPRECATION")
-@Deprecated("Use ViewEnvironment.buildview")
+@Deprecated("Use Screen.buildview")
 @WorkflowUiExperimentalApi
 public fun <RenderingT : Any> ViewRegistry.buildView(
   initialRendering: RenderingT,
   initialViewEnvironment: ViewEnvironment,
   contextForNewView: Context,
   container: ViewGroup? = null,
-  initializeView: View.() -> Unit = { showFirstRendering() }
+  viewStarter: ViewStarter? = null,
 ): View {
   return getFactoryForRendering(initialRendering).buildView(
     initialRendering, initialViewEnvironment, contextForNewView, container
   ).also { view ->
-    checkNotNull(view.showRenderingTag) {
+    checkNotNull(view.workflowViewStateOrNull) {
       "View.bindShowRendering should have been called for $view, typically by the " +
-        "${ViewFactory::class.java.name} that created it."
+        "ViewFactory that created it."
+    }
+    viewStarter?.let { givenStarter ->
+      val doStart = view.starter
+      view.starter = { newView ->
+        givenStarter.startView(newView) { doStart.invoke(newView) }
+      }
     }
-    initializeView.invoke(view)
   }
 }

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

@@ -11,18 +11,14 @@ by ManualScreenViewFactory(
         initialRendering.rendering,
         initialViewEnvironment,
         context,
-        container,
-        // Don't call showRendering yet, we need to wrap the function first.
-        initializeView = { }
+        container
       ).also { view ->
         val legacyShowRendering = view.getShowRendering<Any>()!!
 
         view.bindShowRendering(
           initialRendering,
           initialViewEnvironment
         ) { rendering, env -> legacyShowRendering(rendering.rendering, env) }
-
-        view.showFirstRendering()
       }
   }
 )

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

@@ -69,9 +69,9 @@ import kotlin.reflect.KClass
  *    by DecorativeScreenViewFactory(
  *      type = WithTutorialTips::class,
  *      map = { withTips -> withTips.wrapped },
- *      initializeView = {
+ *      viewStarter = { view, doStart ->
  *        TutorialTipRunner.run(this)
- *        showFirstRendering<WithTutorialTips<*>>()
+ *        doStart()
  *      }
  *    )
  *
@@ -109,10 +109,9 @@ import kotlin.reflect.KClass
  * @param map called to convert instances of [OuterT] to [InnerT], and to
  * allow [ViewEnvironment] to be transformed.
  *
- * @param initializeView Optional function invoked immediately after the [View] is
- * created (that is, immediately after the call to [ScreenViewFactory.buildView]).
- * [showRendering], [getRendering] and [environment] are all available when this is called.
- * Defaults to a call to [View.showFirstRendering].
+ * @param viewStarter An optional wrapper for the function invoked when [View.start]
+ * is called, allowing for last second initialization of a newly built [View].
+ * See [ViewStarter] for details.
  *
  * @param doShowRendering called to apply the [ViewShowRendering] function for
  * [InnerT], allowing pre- and post-processing. Default implementation simply
@@ -122,7 +121,7 @@ import kotlin.reflect.KClass
 public class DecorativeScreenViewFactory<OuterT : Screen, InnerT : Screen>(
   override val type: KClass<OuterT>,
   private val map: (OuterT, ViewEnvironment) -> Pair<InnerT, ViewEnvironment>,
-  private val initializeView: View.() -> Unit = { showFirstRendering() },
+  private val viewStarter: ViewStarter? = null,
   private val doShowRendering: (
     view: View,
     innerShowRendering: ViewShowRendering<InnerT>,
@@ -140,7 +139,7 @@ public class DecorativeScreenViewFactory<OuterT : Screen, InnerT : Screen>(
   public constructor(
     type: KClass<OuterT>,
     map: (OuterT) -> InnerT,
-    initializeView: View.() -> Unit = { showFirstRendering() },
+    viewStarter: ViewStarter? = null,
     doShowRendering: (
       view: View,
       innerShowRendering: ViewShowRendering<InnerT>,
@@ -152,7 +151,7 @@ public class DecorativeScreenViewFactory<OuterT : Screen, InnerT : Screen>(
   ) : this(
     type,
     map = { outer, viewEnvironment -> Pair(map(outer), viewEnvironment) },
-    initializeView = initializeView,
+    viewStarter = viewStarter,
     doShowRendering = doShowRendering
   )
 
@@ -168,8 +167,7 @@ public class DecorativeScreenViewFactory<OuterT : Screen, InnerT : Screen>(
       processedInitialEnv,
       contextForNewView,
       container,
-      // Don't call showRendering yet, we need to wrap the function first.
-      initializeView = { }
+      viewStarter
     )
       .also { view ->
         val innerShowRendering: ViewShowRendering<InnerT> = view.getShowRendering()!!
@@ -178,8 +176,6 @@ public class DecorativeScreenViewFactory<OuterT : Screen, InnerT : Screen>(
           initialRendering,
           processedInitialEnv
         ) { rendering, env -> doShowRendering(view, innerShowRendering, rendering, env) }
-
-        view.initializeView()
       }
   }
 }

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

@@ -42,29 +42,16 @@ public interface ScreenViewFactory<in RenderingT : Screen> : ViewRegistry.Entry<
  * It is usually more convenient to use [WorkflowViewStub] or [DecorativeScreenViewFactory]
  * than to call this method directly.
  *
- * Finds a [ScreenViewFactory] to create a [View] to display [this@buildView]. The new view
- * can be updated via calls to [View.showRendering] -- that is, it is guaranteed that
- * [bindShowRendering] has been called on this view.
+ * Finds a [ScreenViewFactory] to create a [View] to display the receiving [Screen].
+ * The caller is responsible for calling [View.start] on the new [View]. After that,
+ * [View.showRendering] can be used to update it with new renderings that
+ * are [compatible] with this [Screen]. [WorkflowViewStub] takes care of this chore itself.
  *
- * The returned view will have a
- * [WorkflowLifecycleOwner][com.squareup.workflow1.ui.androidx.WorkflowLifecycleOwner]
- * set on it. The returned view must EITHER:
+ * @param viewStarter An optional wrapper for the function invoked when [View.start]
+ * is called, allowing for last second initialization of a newly built [View].
+ * See [ViewStarter] for details.
  *
- * 1. Be attached at least once to ensure that the lifecycle eventually gets destroyed (because its
- *    parent is destroyed), or
- * 2. Have its
- *    [WorkflowLifecycleOwner.destroyOnDetach][com.squareup.workflow1.ui.androidx.WorkflowLifecycleOwner.destroyOnDetach]
- *    called, which will either schedule the
- *    lifecycle to be destroyed if the view is attached, or destroy it immediately if it's detached.
- *
- * [WorkflowViewStub] takes care of this chore itself.
- *
- * @param initializeView Optional function invoked immediately after the [View] is
- * created (that is, immediately after the call to [ScreenViewFactory.buildView]).
- * [showRendering], [getRendering] and [environment] are all available when this is called.
- * Defaults to a call to [View.showFirstRendering].
- *
- * @throws IllegalArgumentException if no builder can be find for type [ScreenT]
+ * @throws IllegalArgumentException if no builder can be found for type [ScreenT]
  *
  * @throws IllegalStateException if the matching [ScreenViewFactory] fails to call
  * [View.bindShowRendering] when constructing the view
@@ -74,27 +61,41 @@ public fun <ScreenT : Screen> ScreenT.buildView(
   viewEnvironment: ViewEnvironment,
   contextForNewView: Context,
   container: ViewGroup? = null,
-  initializeView: View.() -> Unit = { showFirstRendering() }
+  viewStarter: ViewStarter? = null,
 ): View {
   val viewFactory = viewEnvironment.getViewFactoryForRendering(this)
 
   return viewFactory.buildView(this, viewEnvironment, contextForNewView, container).also { view ->
-    checkNotNull(view.showRenderingTag) {
+    checkNotNull(view.workflowViewStateOrNull) {
       "View.bindShowRendering should have been called for $view, typically by the " +
-        "${ScreenViewFactory::class.java.name} that created it."
+        "ScreenViewFactory that created it."
+    }
+    viewStarter?.let { givenStarter ->
+      val doStart = view.starter
+      view.starter = { newView ->
+        givenStarter.startView(newView) { doStart.invoke(newView) }
+      }
     }
-    initializeView.invoke(view)
   }
 }
 
 /**
- * Default implementation for the `initializeView` argument of [Screen.buildView],
- * and for [DecorativeScreenViewFactory.initializeView]. Calls [showRendering] against
- * [getRendering] and [environment].
+ * A wrapper for the function invoked when [View.start] is called, allowing for
+ * last second initialization of a newly built [View]. Provided via [Screen.buildView]
+ * or [DecorativeScreenViewFactory.viewStarter].
+ *
+ * While [View.getRendering] may be called from [startView], it is not safe to
+ * assume that the type of the rendering retrieved matches the type the view was
+ * originally built to display. [ViewFactories][ViewFactory] can be wrapped, and
+ * renderings can be mapped to other types.
  */
 @WorkflowUiExperimentalApi
-public fun View.showFirstRendering() {
-  showRendering(getRendering()!!, environment!!)
+public fun interface ViewStarter {
+  /** Called from [View.start]. [doStart] must be invoked. */
+  public fun startView(
+    view: View,
+    doStart: () -> Unit
+  )
 }
 
 @WorkflowUiExperimentalApi