Some method renaming and other polish from PR review.

- `ScreenViewFactory.unwrapping` > `.toUnwrappingViewFactory`, and deleted redundant kdoc
- `ScreenViewFactory.start` > `.startShowing`
- Inlined `Screen.buildView`

Author: rjrjr

workflow-ui/compose/src/main/java/com/squareup/workflow1/ui/compose/WorkflowRendering.kt

@@ -31,7 +31,7 @@ import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
 import com.squareup.workflow1.ui.WorkflowViewStub
 import com.squareup.workflow1.ui.androidx.WorkflowLifecycleOwner
 import com.squareup.workflow1.ui.show
-import com.squareup.workflow1.ui.start
+import com.squareup.workflow1.ui.startShowing
 import com.squareup.workflow1.ui.toViewFactory
 import kotlin.reflect.KClass
 
@@ -185,7 +185,7 @@ private fun <ScreenT : Screen> ScreenViewFactory<ScreenT>.asComposeViewFactory()
           // We pass in a null container because the container isn't a View, it's a composable. The
           // compose machinery will generate an intermediate view that it ends up adding this to but
           // we don't have access to that.
-          originalFactory.start(rendering, viewEnvironment, context, container = null)
+          originalFactory.startShowing(rendering, viewEnvironment, context, container = null)
             .let { viewHolder ->
               // Put the viewHolder in a tag so that we can find it in the update lambda, below.
               viewHolder.view.setTag(R.id.workflow_screen_view_holder, viewHolder)

workflow-ui/container-android/src/main/java/com/squareup/workflow1/ui/modal/ModalViewContainer.kt

@@ -20,11 +20,12 @@ import com.squareup.workflow1.ui.ViewRegistry
 import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
 import com.squareup.workflow1.ui.asScreen
 import com.squareup.workflow1.ui.bindShowRendering
-import com.squareup.workflow1.ui.buildView
 import com.squareup.workflow1.ui.container.BackButtonScreen
 import com.squareup.workflow1.ui.modal.ModalViewContainer.Companion.binding
 import com.squareup.workflow1.ui.onBackPressedDispatcherOwnerOrNull
 import com.squareup.workflow1.ui.show
+import com.squareup.workflow1.ui.startShowing
+import com.squareup.workflow1.ui.toViewFactory
 import kotlin.reflect.KClass
 
 /**
@@ -72,11 +73,13 @@ public open class ModalViewContainer @JvmOverloads constructor(
     // that should be blocked by this modal session.
     val wrappedRendering = BackButtonScreen(asScreen(initialModalRendering)) { }
 
-    val viewHolder = wrappedRendering.buildView(
-      initialViewEnvironment = initialViewEnvironment,
-      contextForNewView = this.context,
-      container = this
-    )
+    val viewHolder = wrappedRendering.toViewFactory(initialViewEnvironment)
+      .startShowing(
+        initialRendering = wrappedRendering,
+        initialEnvironment = initialViewEnvironment,
+        contextForNewView = this.context,
+        container = this
+      )
 
     return buildDialogForView(viewHolder.view)
       .apply {

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

@@ -187,13 +187,11 @@ public final class com/squareup/workflow1/ui/ScreenViewFactoryFinder$DefaultImpl
 }
 
 public final class com/squareup/workflow1/ui/ScreenViewFactoryKt {
-	public static final fun buildView (Lcom/squareup/workflow1/ui/Screen;Lcom/squareup/workflow1/ui/ViewEnvironment;Landroid/content/Context;Landroid/view/ViewGroup;Lcom/squareup/workflow1/ui/ViewStarter;)Lcom/squareup/workflow1/ui/ScreenViewHolder;
-	public static synthetic fun buildView$default (Lcom/squareup/workflow1/ui/Screen;Lcom/squareup/workflow1/ui/ViewEnvironment;Landroid/content/Context;Landroid/view/ViewGroup;Lcom/squareup/workflow1/ui/ViewStarter;ILjava/lang/Object;)Lcom/squareup/workflow1/ui/ScreenViewHolder;
-	public static final fun start (Lcom/squareup/workflow1/ui/ScreenViewFactory;Lcom/squareup/workflow1/ui/Screen;Lcom/squareup/workflow1/ui/ViewEnvironment;Landroid/content/Context;Landroid/view/ViewGroup;Lcom/squareup/workflow1/ui/ViewStarter;)Lcom/squareup/workflow1/ui/ScreenViewHolder;
-	public static synthetic fun start$default (Lcom/squareup/workflow1/ui/ScreenViewFactory;Lcom/squareup/workflow1/ui/Screen;Lcom/squareup/workflow1/ui/ViewEnvironment;Landroid/content/Context;Landroid/view/ViewGroup;Lcom/squareup/workflow1/ui/ViewStarter;ILjava/lang/Object;)Lcom/squareup/workflow1/ui/ScreenViewHolder;
+	public static final fun startShowing (Lcom/squareup/workflow1/ui/ScreenViewFactory;Lcom/squareup/workflow1/ui/Screen;Lcom/squareup/workflow1/ui/ViewEnvironment;Landroid/content/Context;Landroid/view/ViewGroup;Lcom/squareup/workflow1/ui/ViewStarter;)Lcom/squareup/workflow1/ui/ScreenViewHolder;
+	public static synthetic fun startShowing$default (Lcom/squareup/workflow1/ui/ScreenViewFactory;Lcom/squareup/workflow1/ui/Screen;Lcom/squareup/workflow1/ui/ViewEnvironment;Landroid/content/Context;Landroid/view/ViewGroup;Lcom/squareup/workflow1/ui/ViewStarter;ILjava/lang/Object;)Lcom/squareup/workflow1/ui/ScreenViewHolder;
+	public static final synthetic fun toUnwrappingViewFactory (Lcom/squareup/workflow1/ui/ScreenViewFactory;Lkotlin/jvm/functions/Function1;)Lcom/squareup/workflow1/ui/ScreenViewFactory;
+	public static final synthetic fun toUnwrappingViewFactory (Lcom/squareup/workflow1/ui/ScreenViewFactory;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function4;)Lcom/squareup/workflow1/ui/ScreenViewFactory;
 	public static final fun toViewFactory (Lcom/squareup/workflow1/ui/Screen;Lcom/squareup/workflow1/ui/ViewEnvironment;)Lcom/squareup/workflow1/ui/ScreenViewFactory;
-	public static final synthetic fun unwrapping (Lcom/squareup/workflow1/ui/ScreenViewFactory;Lkotlin/jvm/functions/Function1;)Lcom/squareup/workflow1/ui/ScreenViewFactory;
-	public static final synthetic fun unwrapping (Lcom/squareup/workflow1/ui/ScreenViewFactory;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function4;)Lcom/squareup/workflow1/ui/ScreenViewFactory;
 	public static final fun viewBindingLayoutInflater (Landroid/content/Context;Landroid/view/ViewGroup;)Landroid/view/LayoutInflater;
 }
 

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

@@ -38,7 +38,7 @@ public fun <RenderingT : Any> ViewRegistry.getFactoryFor(
   return getEntryFor(renderingType) as? ViewFactory<RenderingT>
 }
 
-@Deprecated("Use Screen.toView")
+@Deprecated("Use ScreenViewFactory.startShowing")
 @WorkflowUiExperimentalApi
 public fun <RenderingT : Any> ViewRegistry.buildView(
   initialRendering: RenderingT,

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

@@ -6,7 +6,7 @@ import android.view.ViewGroup
 import kotlin.reflect.KClass
 
 @Suppress("DEPRECATION")
-@Deprecated("Use ScreenViewFactory.unwrapping.")
+@Deprecated("Use ScreenViewFactory.unwrapping")
 @WorkflowUiExperimentalApi
 public class DecorativeViewFactory<OuterT : Any, InnerT : Any>(
   override val type: KClass<OuterT>,

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

@@ -7,10 +7,9 @@ import com.squareup.workflow1.ui.ScreenViewFactory.Companion.forBuiltView
  * to the factory for [NamedScreen.wrapped].
  */
 @WorkflowUiExperimentalApi
-internal
-fun <WrappedT : Screen> NamedScreenViewFactory() =
+internal fun <WrappedT : Screen> NamedScreenViewFactory() =
   forBuiltView<NamedScreen<WrappedT>> { namedScreen, environment, context, container ->
     namedScreen.wrapped.toViewFactory(environment)
-      .unwrapping<NamedScreen<WrappedT>, WrappedT> { it.wrapped }
+      .toUnwrappingViewFactory<NamedScreen<WrappedT>, WrappedT> { it.wrapped }
       .buildView(namedScreen, environment, context, container)
   }

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

@@ -19,8 +19,10 @@ public typealias ViewBindingInflater<BindingT> = (LayoutInflater, ViewGroup?, Bo
  * Each [ScreenViewRunner] instance is paired with the single [View] instance,
  * its neighbor in a [ScreenViewHolder].
  *
- * Use [forLayoutResource], [forViewBinding], etc., to create a [ScreenViewFactory]
- * from a [ScreenViewRunner].
+ * Use [forLayoutResource], [forViewBinding], etc., to create a [ScreenViewFactory].
+ * These helper methods take a layout resource, view binding, or view building
+ * function as arguments, along with a factory to create a [showRendering]
+ * [ScreenViewRunner.showRendering] function.
  */
 @WorkflowUiExperimentalApi
 public fun interface ScreenViewRunner<in ScreenT : Screen> {
@@ -43,9 +45,9 @@ public fun interface ScreenViewRunner<in ScreenT : Screen> {
  * for you.
  *
  * If you are building a custom container and [WorkflowViewStub] is too restrictive,
- * use [Screen.buildView], or [ScreenViewFactory.start]. [start] is the fundamental
- * method, responsible for making the initial call to [ScreenViewHolder.show], and
- * applying any [ViewStarter] provided for custom initialization.
+ * use [Screen.startShowing], or [ScreenViewFactory.startShowing]. [startShowing]
+ * is the fundamental method, responsible for making the initial call to [ScreenViewHolder.show],
+ * and applying any [ViewStarter] provided for custom initialization.
  */
 @WorkflowUiExperimentalApi
 public interface ScreenViewFactory<in ScreenT : Screen> : ViewRegistry.Entry<ScreenT> {
@@ -163,9 +165,9 @@ public interface ScreenViewFactory<in ScreenT : Screen> : ViewRegistry.Entry<Scr
  * bound to the type of the receiving [Screen].
  *
  * - It is more common to use [WorkflowViewStub.show] than to call this method directly
- * - Call [ScreenViewFactory.start] to create and initialize a new [View]
+ * - Call [ScreenViewFactory.startShowing] to create and initialize a new [View]
  * - If you don't particularly need to mess with the [ScreenViewFactory] before creating
- *   a view, use [Screen.buildView] instead of this method.
+ *   a view, use [Screen.startShowing] instead of this method.
  */
 @WorkflowUiExperimentalApi
 public fun <ScreenT : Screen> ScreenT.toViewFactory(
@@ -177,16 +179,15 @@ public fun <ScreenT : Screen> ScreenT.toViewFactory(
 /**
  * It is more common to use [WorkflowViewStub.show] than to call this method directly.
  *
- * Creates a [ScreenViewHolder] wrapping a [View] able to display [initialRendering],
- * and initializes the view.
+ * Creates a [ScreenViewHolder] wrapping a [View] able to display a stream
+ * of [ScreenT] renderings, starting with [initialRendering].
  *
- * By default "initialize" makes the first call to [ScreenViewHolder.show].
  * To add more initialization behavior (typically a call to [WorkflowLifecycleOwner.installOn]),
  * provide a [viewStarter].
  */
 @Suppress("DEPRECATION")
 @WorkflowUiExperimentalApi
-public fun <ScreenT : Screen> ScreenViewFactory<ScreenT>.start(
+public fun <ScreenT : Screen> ScreenViewFactory<ScreenT>.startShowing(
   initialRendering: ScreenT,
   initialEnvironment: ViewEnvironment,
   contextForNewView: Context,
@@ -240,40 +241,17 @@ public fun <ScreenT : Screen> ScreenViewFactory<ScreenT>.start(
         shown = true
       }
       check(shown) {
-        "A ViewStarter provided to Screen.toView or ScreenViewFactory.start " +
+        "A ViewStarter provided to ScreenViewFactory.startShowing " +
           "neglected to call the given doStart() function"
       }
     }
   }
 }
 
 /**
- * It is more common to use [WorkflowViewStub.show] than to call this method directly.
- *
- * Creates a [View] able to display [initialRendering], and initializes it. By
- * default "initialize" makes the first call to [ScreenViewHolder.show].
- * To add more initialization behavior (typically a call to [WorkflowLifecycleOwner.installOn]),
- * provide a [viewStarter].
- *
- * This method is purely shorthand for calling [Screen.toViewFactory] and then
- * [ScreenViewFactory.start]. You might wish to make those calls separately if you
- * need to treat the [ScreenViewFactory] before using it, e.g. via [unwrapping].
- */
-@WorkflowUiExperimentalApi
-public fun <ScreenT : Screen> ScreenT.buildView(
-  initialViewEnvironment: ViewEnvironment,
-  contextForNewView: Context,
-  container: ViewGroup? = null,
-  viewStarter: ViewStarter? = null
-): ScreenViewHolder<ScreenT> {
-  return toViewFactory(initialViewEnvironment)
-    .start(this, initialViewEnvironment, contextForNewView, container, viewStarter)
-}
-
-/**
- * A wrapper for the function invoked when [ScreenViewFactory.start] or
- * [Screen.buildView] is called, allowing for custom initialization of
- * a newly built [View] before or after the first call to [ScreenViewHolder.show].
+ * A wrapper for the function invoked when [ScreenViewFactory.startShowing] is called,
+ * allowing for custom initialization of a newly built [View] before or after the first
+ * call to [ScreenViewHolder.show].
  */
 @WorkflowUiExperimentalApi
 public fun interface ViewStarter {
@@ -364,10 +342,13 @@ public fun interface ViewStarter {
  * @param unwrap a function to extract [WrappedT] instances from [WrapperT]s.
  */
 @WorkflowUiExperimentalApi
-public inline
-fun <reified WrapperT : Screen, WrappedT : Screen> ScreenViewFactory<WrappedT>.unwrapping(
+public inline fun <
+  reified WrapperT : Screen,
+  WrappedT : Screen
+  > ScreenViewFactory<WrappedT>.toUnwrappingViewFactory(
   crossinline unwrap: (wrapperScreen: WrapperT) -> WrappedT,
-): ScreenViewFactory<WrapperT> = unwrapping(unwrap) { _, ws, e, su -> su(unwrap(ws), e) }
+): ScreenViewFactory<WrapperT> =
+  toUnwrappingViewFactory(unwrap) { _, ws, e, su -> su(unwrap(ws), e) }
 
 /**
  * Transforms a [ScreenViewFactory] of [WrappedT] into one that can handle
@@ -390,61 +371,30 @@ fun <reified WrapperT : Screen, WrappedT : Screen> ScreenViewFactory<WrappedT>.u
  *    fun <W: Screen> WithTutorialTipsFactory<W>() =
  *      ScreenViewFactory.forBuiltView<WithTutorialTips<*>> = {
  *        initialRendering, initialEnv, context, container ->
+ *          // Get the view factory of the wrapped screen.
  *          initialRendering.wrapped.toViewFactory(initialEnv)
+ *            // Transform it to factory that accepts WithTutorialTips<W>
  *            .unwrapping<WithTutorialTips<W>, W>(
  *              unwrap = { it.wrapped },
  *              showWrapperScreen = { view, withTips, env, showUnwrapped ->
  *                TutorialTipRunner.run(view)
  *                showUnwrapped(withTips.wrapped, env)
  *              }
+ *              // Delegate to the transformed factory to build the view.
  *              .buildView(initialRendering, initialEnv, context, container)
  *      }
  *
- * To make a wrapper that adds pre- or post-processing to [View] updates:
- *
- *    class BackButtonScreen<W : Screen>(
- *       val wrapped: W,
- *       val override: Boolean = false,
- *       val onBackPressed: (() -> Unit)? = null
- *    ) : Screen, Compatible {
- *      override val compatibilityKey = Compatible.keyFor(wrapped)
- *    }
- *
- *    fun <W: Screen> BackButtonViewFactory<W>() =
- *      ScreenViewFactory.forBuiltView<BackButtonScreen<W>> {
- *        initialRendering, initialEnv, context, container ->
- *          initialRendering.wrapped.toViewFactory(initialEnv)
- *            .unwrapping<BackButtonScreen<W>, W>(
- *              unwrap = { it.wrapped },
- *              showWrapperScreen = { view, backButtonScreen, env, showUnwrapped ->
- *                if (!backButtonScreen.shadow) {
- *                  // Place our handler before invoking innerShowRendering, so that
- *                  // its later calls to view.backPressedHandler will take precedence
- *                  // over ours.
- *                  view.backPressedHandler = backButtonScreen.onBackPressed
- *                }
- *
- *                // Show the wrapped Screen.
- *                showUnwrapped(backButtonScreen.wrapped, env)
- *
- *                if (backButtonScreen.shadow) {
- *                  // Place our handler after invoking innerShowRendering, so that ours wins.
- *                  view.backPressedHandler = backButtonScreen.onBackPressed
- *                }
- *              }
- *            )
- *            .buildView(initialRendering, initialEnv, context, container)
- *      }
- *
  * @param unwrap a function to extract [WrappedT] instances from [WrapperT]s.
  *
  * @param showWrapperScreen a function invoked when an instance of [WrapperT] needs
  * to be shown in a [View] built to display instances of [WrappedT]. Allows
  * pre- and post-processing of the [View].
  */
 @WorkflowUiExperimentalApi
-public inline
-fun <reified WrapperT : Screen, WrappedT : Screen> ScreenViewFactory<WrappedT>.unwrapping(
+public inline fun <
+  reified WrapperT : Screen,
+  WrappedT : Screen
+  > ScreenViewFactory<WrappedT>.toUnwrappingViewFactory(
   crossinline unwrap: (wrapperScreen: WrapperT) -> WrappedT,
   crossinline showWrapperScreen: (
     view: View,

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

@@ -12,7 +12,7 @@ import com.squareup.workflow1.ui.ScreenViewHolder.Companion.ShowingNothing
  * [environment] should always hold a reference to the [Screen] most recently shown
  * in [view], with the key [Showing]. [ScreenViewHolder.showing] provides easy access
  * to it. Note that the shown [Screen] may not be of type [ScreenT], if this
- * [ScreenViewHolder] is wrapped by another one. (See [ScreenViewFactory.unwrapping].)
+ * [ScreenViewHolder] is wrapped by another one. (See [ScreenViewFactory.toUnwrappingViewFactory].)
  *
  * Do not call [runner] directly. Use [ScreenViewHolder.show] instead. Or most commonly,
  * allow [WorkflowViewStub.show] to call it for you.
@@ -69,6 +69,9 @@ public fun <ScreenT : Screen> ScreenViewHolder<ScreenT>.show(
   screen: ScreenT,
   environment: ViewEnvironment
 ) {
+  // Why is this an extension rather than part of the interface?
+  // When wrapping, we need to prevent recursive calls from clobbering
+  // `environment[Showing]` with the nested rendering type.
   runner.showRendering(screen, environment + (Showing to screen))
 }
 
@@ -78,8 +81,7 @@ public fun <ScreenT : Screen> ScreenViewHolder<ScreenT>.show(
  */
 @WorkflowUiExperimentalApi
 public val ScreenViewHolder<*>.showing: Screen
-  get() =
-    environment[Showing]
+  get() = environment[Showing]
 
 @WorkflowUiExperimentalApi
 public fun <ScreenT : Screen> ScreenViewHolder(

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

@@ -15,7 +15,7 @@ internal sealed class WorkflowViewState<out RenderingT : Any> {
   abstract val environment: ViewEnvironment
   abstract val showRendering: ViewShowRendering<RenderingT>
 
-  /** [bindShowRendering] has been called, [start] has not. */
+  /** [bindShowRendering] has been called, [startShowing] has not. */
   data class New<out RenderingT : Any>(
     override val showing: RenderingT,
     override val environment: ViewEnvironment,
@@ -27,7 +27,7 @@ internal sealed class WorkflowViewState<out RenderingT : Any> {
     }
   ) : WorkflowViewState<RenderingT>()
 
-  /** [start] has been called. It's safe to call [showRendering] now. */
+  /** [startShowing] has been called. It's safe to call [showRendering] now. */
   data class Started<out RenderingT : Any>(
     override val showing: RenderingT,
     override val environment: ViewEnvironment,

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

@@ -221,23 +221,19 @@ public class WorkflowViewStub @JvmOverloads constructor(
       WorkflowLifecycleOwner.get(it)?.destroyOnDetach()
     }
 
-    holder = rendering.buildView(
-      viewEnvironment,
-      parent.context,
-      parent,
-      viewStarter = { view, doStart ->
+    holder = rendering.toViewFactory(viewEnvironment)
+      .startShowing(rendering, viewEnvironment, parent.context, parent) { view, doStart ->
         WorkflowLifecycleOwner.installOn(view)
         doStart()
-      }
-    ).also {
-      val newView = it.view
+      }.also {
+        val newView = it.view
 
-      if (inflatedId != NO_ID) newView.id = inflatedId
-      if (updatesVisibility) newView.visibility = visibility
-      background?.let { newView.background = it }
-      propagateSavedStateRegistryOwner(newView)
-      replaceOldViewInParent(parent, newView)
-    }
+        if (inflatedId != NO_ID) newView.id = inflatedId
+        if (updatesVisibility) newView.visibility = visibility
+        background?.let { newView.background = it }
+        propagateSavedStateRegistryOwner(newView)
+        replaceOldViewInParent(parent, newView)
+      }
   }
 
   /**