wip: Modernize tutorial final code

Long lived branch (which I will totally rebase like mad) accumulating incremental tutorial updates.

 - `tutorial-final` is updated (especially `WelcomeWorkflow`) and its tests pass
 - `tutorial-base` done
 - `README.md` done
 - `Tutorial1.md` done
 - `tutorial-1-complete` done

It's time to get the Tutorial caught up with undeprecated API:

- Use `AndroidScreen` and drop `ViewRegistry`

- Better, more consistent use of `BackStackScreen`

- Use `View.setBackHandler`

- Use `TextController`

- Use `RequestContext.eventHandler`

- Delete a lot of `// Exactly what the function name and the code say` comments

- Hint at the existance of `ComposeWorkflow` without turning this into a complete rewrite

- More consistent naming, code style for actions and event handlers in `Screen` renderings
  - Event handler fields are named `onVerbPhrase`, like `onBackPressed`
  - Action names are verb phrases describing the action that is being taken, not the event that is being handled
  - Output names are generally in terms of the semantic event being reported to the parent, rather than describing what the parent will do

Thus:

```kotlin
return TodoListScreen(
  onRowPressed = { context.actionSink.send(reportSelection(it)) }
```

```kotlin
  private fun reportSelection(index: Int) = action {
    // Tell our parent that a todo item was selected.
    setOutput(TodoSelected(index))
  }
```

(Although most of these will be inlined as `eventHandler {}` calls.)

When the rest of the `tutorial-N` modules have been updated I'll put this up for review.

I've mainly focussed on updating what exists, not extending its coverage further. Once this is merged I'd like to follow and do more:

- Introduce `Overlay`.
  - How about move `TodoEditScreen` to a `BottomSheetDialog`?
  - Could be too noisy, `BottomSheetDialog` is a bastard.
  - If that's the case create a separate sample for it.
- Introduce `Compose`.
  - I think the way to go is add a fifth step that updates `TodoListScreen`, talk about getting rid of that `RecyclerView`.
  - Should also mention at the top that people can use `ComposeScreen` instead of `AndroidScreen`;
    and on the `TextController` page call out `asMutableState()`

Author: rjrjr

samples/tutorial/README.md

@@ -1,29 +1,9 @@
 # Tutorial
 
-## Stale Docs Warning
-
-**This tutorial is tied to an older version of Workflow, and relies on API that has been deprecated or deleted.**
-The general concepts are the same, and refactoring to the current API is straightforward,
-so it is still worthwhile to work through the tutorial in its current state until we find time to update it.
-(Track that work [here](https://github.com/square/workflow-kotlin/issues/905)
-and [here](https://github.com/square/workflow-kotlin/issues/884).)
-
-Here's a summary of what has changed, and what replaces what:
-
-- Use of `ViewRegistry` is now optional, and rare.
-  Have your renderings implement `AndroidScreen` or `ComposeScreen` to avoid it.
-- The API for binding a rendering to UI code has changed as follows, and can all
-  be avoided if you use `ComposeScreen`:
-   - `ViewFactory<in RenderingT : Any>` is replaced by `ScreenViewFactory<in ScreenT : Screen>`.
-   -`LayoutRunner<RenderingT : Any>` is replaced by `ScreenViewRunner<in ScreenT : Screen>`.
-   - `LayoutRunner.bind` is replaced by `ScreenViewFactory.fromViewBinding`.
-- `BackStackScreen` has been moved to package `com.squareup.workflow1.ui.navigation`.
-- `EditText.updateText` and `EditText.setTextChangedListener` are replaced by `TextController`
-
 ## Overview
 
 Oh hi! Looks like you want build some software with Workflows! It's a bit different from traditional
-Android development, so let's go through building a simple little TODO app to get the basics down.
+Android development, so let's go through building a simple little To-Do app to get the basics down.
 
 ## Layout
 
@@ -33,7 +13,7 @@ To help with the setup, we have created a few helper modules:
 
 - `tutorial-views`: A set of 3 views for the 3 screens we will be building, `Welcome`, `TodoList`,
   and `TodoEdit`.
-- `tutorial-base`: This is the starting point to build out the tutorial. It contains layouts that host the views from `TutorialViews` to see how they display.
+- `tutorial-base`: This is the starting point to build out the tutorial.
 - `tutorial-final`: This is an example of the completed tutorial - could be used as a reference if
   you get stuck.
 

samples/tutorial/Tutorial1.md

@@ -2,26 +2,6 @@
 
 _Multiple Screens and Navigation_
 
-## Stale Docs Warning
-
-**This tutorial is tied to an older version of Workflow, and relies on API that has been deprecated or deleted.**
-The general concepts are the same, and refactoring to the current API is straightforward,
-so it is still worthwhile to work through the tutorial in its current state until we find time to update it.
-(Track that work [here](https://github.com/square/workflow-kotlin/issues/905)
-and [here](https://github.com/square/workflow-kotlin/issues/884).)
-
-Here's a summary of what has changed, and what replaces what:
-
-- Use of `ViewRegistry` is now optional, and rare.
-  Have your renderings implement `AndroidScreen` or `ComposeScreen` to avoid it.
-- The API for binding a rendering to UI code has changed as follows, and can all
-  be avoided if you use `ComposeScreen`:
-   - `ViewFactory<in RenderingT : Any>` is replaced by `ScreenViewFactory<in ScreenT : Screen>`.
-   -`LayoutRunner<RenderingT : Any>` is replaced by `ScreenViewRunner<in ScreenT : Screen>`.
-   - `LayoutRunner.bind` is replaced by `ScreenViewFactory.fromViewBinding`.
-- `BackStackScreen` has been moved to package `com.squareup.workflow1.ui.navigation`.
-- `EditText.updateText` and `EditText.setTextChangedListener` are replaced by `TextController`
-
 ## Setup
 
 To follow this tutorial, launch Android Studio and open this folder (`samples/tutorial`).
@@ -539,29 +519,18 @@ class BackStackScreen<StackedT : Any>(
 }
 ```
 
-The `BackStackScreen` contains a list of all screens in the back stack that are specified on each render pass. `BackStackScreen` is part of the `workflow-ui-container-android` artifact. Update `build.gradle` to include this dependency:
-
-```groovy
-dependencies {
-  // ...
-  implementation deps.workflow.container_android
-  implementation deps.workflow.core_android
-}
-```
-
 Update the `RootWorkflow` to return a `BackStackScreen` with a list of back stack items:
 
 ```kotlin
-object RootWorkflow : StatefulWorkflow<Unit, State, Nothing, BackStackScreen<Any>>() {
+object RootWorkflow : StatefulWorkflow<Unit, State, Nothing, BackStackScreen<*>>() {
 
   // …
 
-  @OptIn(WorkflowUiExperimentalApi::class)
-  override fun render(
+    override fun render(
     renderProps: Unit,
     renderState: State,
     context: RenderContext
-  ): BackStackScreen<Any> {
+  ): BackStackScreen<*> {
 
     // Our list of back stack items. Will always include the "WelcomeScreen".
     val backstackScreens = mutableListOf<Any>()

samples/tutorial/Tutorial2.md

@@ -1,24 +1,6 @@
 # Step 3
 
-## Stale Docs Warning
-
-**This tutorial is tied to an older version of Workflow, and relies on API that has been deprecated or deleted.**
-The general concepts are the same, and refactoring to the current API is straightforward,
-so it is still worthwhile to work through the tutorial in its current state until we find time to update it.
-(Track that work [here](https://github.com/square/workflow-kotlin/issues/905)
-and [here](https://github.com/square/workflow-kotlin/issues/884).)
-
-Here's a summary of what has changed, and what replaces what:
-
-- Use of `ViewRegistry` is now optional, and rare.
-  Have your renderings implement `AndroidScreen` or `ComposeScreen` to avoid it.
-- The API for binding a rendering to UI code has changed as follows, and can all
-  be avoided if you use `ComposeScreen`:
-   - `ViewFactory<in RenderingT : Any>` is replaced by `ScreenViewFactory<in ScreenT : Screen>`.
-   -`LayoutRunner<RenderingT : Any>` is replaced by `ScreenViewRunner<in ScreenT : Screen>`.
-   - `LayoutRunner.bind` is replaced by `ScreenViewFactory.fromViewBinding`.
-- `BackStackScreen` has been moved to package `com.squareup.workflow1.ui.navigation`.
-- `EditText.updateText` and `EditText.setTextChangedListener` are replaced by `TextController`
+_State throughout a tree of workflows_
 
 ## Setup
 
@@ -284,15 +266,15 @@ object TodoListWorkflow : StatefulWorkflow<ListProps, State, Back, List<Any>>()
 Now that `TodoListWorkflow` renders a `List<Any>` we need to update its parent `RootWorkflow` to accept this list:
 
 ```kotlin
-object RootWorkflow : StatefulWorkflow<Unit, State, Nothing, BackStackScreen<Any>>() {
+object RootWorkflow : StatefulWorkflow<Unit, State, Nothing, BackStackScreen<*>>() {
 
   // ...
 
   override fun render(
     renderProps: Unit,
     renderState: State,
     context: RenderContext
-  ): BackStackScreen<Any> {
+  ): BackStackScreen<*> {
       // ..
       // When the state is Todo, defer to the TodoListWorkflow.
       is Todo -> {

samples/tutorial/Tutorial3.md

@@ -2,26 +2,6 @@
 
 _Refactoring and rebalancing a tree of Workflows_
 
-## Stale Docs Warning
-
-**This tutorial is tied to an older version of Workflow, and relies on API that has been deprecated or deleted.**
-The general concepts are the same, and refactoring to the current API is straightforward,
-so it is still worthwhile to work through the tutorial in its current state until we find time to update it.
-(Track that work [here](https://github.com/square/workflow-kotlin/issues/905)
-and [here](https://github.com/square/workflow-kotlin/issues/884).)
-
-Here's a summary of what has changed, and what replaces what:
-
-- Use of `ViewRegistry` is now optional, and rare.
-  Have your renderings implement `AndroidScreen` or `ComposeScreen` to avoid it.
-- The API for binding a rendering to UI code has changed as follows, and can all
-  be avoided if you use `ComposeScreen`:
-   - `ViewFactory<in RenderingT : Any>` is replaced by `ScreenViewFactory<in ScreenT : Screen>`.
-   - `LayoutRunner<RenderingT : Any>` is replaced by `ScreenViewRunner<in ScreenT : Screen>`.
-   - `LayoutRunner.bind` is replaced by `ScreenViewFactory.fromViewBinding`.
-- `BackStackScreen` has been moved to package `com.squareup.workflow1.ui.navigation`.
-- `EditText.updateText` and `EditText.setTextChangedListener` are replaced by `TextController`
-
 ## Setup
 
 To follow this tutorial, launch Android Studio and open this folder (`samples/tutorial`).
@@ -284,15 +264,15 @@ object TodoWorkflow : StatefulWorkflow<TodoProps, State, Back, List<Any>>() {
 So far `RootWorkflow` is still deferring to the `TodoListWorkflow`. Update the `RootWorkflow` to defer to the `TodoWorkflow` for rendering the `Todo` state. This will get us back into a state where we can build again (albeit without editing support):
 
 ```kotlin
-object RootWorkflow : StatefulWorkflow<Unit, State, Nothing, BackStackScreen<Any>>() {
+object RootWorkflow : StatefulWorkflow<Unit, State, Nothing, BackStackScreen<*>>() {
 
   // …
 
   override fun render(
     renderProps: Unit,
     renderState: State,
     context: RenderContext
-  ): BackStackScreen<Any> {
+  ): BackStackScreen<*> {
 
       // …
 

samples/tutorial/Tutorial4.md

@@ -2,26 +2,6 @@
 
 _Unit and Integration Testing Workflows_
 
-## Stale Docs Warning
-
-**This tutorial is tied to an older version of Workflow, and relies on API that has been deprecated or deleted.**
-The general concepts are the same, and refactoring to the current API is straightforward,
-so it is still worthwhile to work through the tutorial in its current state until we find time to update it.
-(Track that work [here](https://github.com/square/workflow-kotlin/issues/905)
-and [here](https://github.com/square/workflow-kotlin/issues/884).)
-
-Here's a summary of what has changed, and what replaces what:
-
-- Use of `ViewRegistry` is now optional, and rare.
-  Have your renderings implement `AndroidScreen` or `ComposeScreen` to avoid it.
-- The API for binding a rendering to UI code has changed as follows, and can all
-  be avoided if you use `ComposeScreen`:
-   - `ViewFactory<in RenderingT : Any>` is replaced by `ScreenViewFactory<in ScreenT : Screen>`.
-   - `LayoutRunner<RenderingT : Any>` is replaced by `ScreenViewRunner<in ScreenT : Screen>`.
-   - `LayoutRunner.bind` is replaced by `ScreenViewFactory.fromViewBinding`.
-- `BackStackScreen` has been moved to package `com.squareup.workflow1.ui.navigation`.
-- `EditText.updateText` and `EditText.setTextChangedListener` are replaced by `TextController`
-
 ## Setup
 
 To follow this tutorial, launch Android Studio and open this folder (`samples/tutorial`).

samples/tutorial/Tutorial5.md

@@ -3,8 +3,9 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 buildscript {
   ext {
-    kotlin_version = '1.8.10'
-    workflow_version = "1.12.1-beta04"
+    kotlin_version = '1.9.24'
+    // TODO NO SNAPSHOT!
+    workflow_version = "1.19.0-SNAPSHOT"
 
     deps = [
         activityktx: 'androidx.activity:activity-ktx:1.3.0',
@@ -23,7 +24,8 @@ buildscript {
         viewmodelsavedstate: 'androidx.lifecycle:lifecycle-viewmodel-savedstate:1.1.0',
         workflow: [
             core_android: "com.squareup.workflow1:workflow-ui-core-android:$workflow_version",
-            container_android: "com.squareup.workflow1:workflow-ui-container-android:$workflow_version",
+            compose: "com.squareup.workflow1:workflow-ui-compose:$workflow_version",
+            compose_tooling: "com.squareup.workflow1:workflow-ui-compose-tooling:$workflow_version",
             testing: "com.squareup.workflow1:workflow-testing-jvm:$workflow_version",
         ],
     ]

samples/tutorial/build.gradle

@@ -8,7 +8,7 @@ android {
 
   defaultConfig {
     applicationId "com.squareup.workflow.tutorial"
-    minSdk = 21
+    minSdk = 24
     targetSdk = 33
     versionCode 1
     versionName "1.0"

samples/tutorial/images/layout-runner-name.png

@@ -7,7 +7,8 @@
       android:label="@string/app_name"
       android:roundIcon="@mipmap/ic_launcher_round"
       android:supportsRtl="true"
-      android:theme="@style/Theme.WorkflowTutorial">
+      android:theme="@style/Theme.WorkflowTutorial"
+      >
     <activity
         android:name=".TutorialActivity"
         android:exported="true">

samples/tutorial/images/new-workflow.png

@@ -1,5 +1,3 @@
-@file:OptIn(WorkflowUiExperimentalApi::class)
-
 package workflow.tutorial
 
 import android.os.Bundle
@@ -8,36 +6,47 @@ import androidx.appcompat.app.AppCompatActivity
 import androidx.lifecycle.SavedStateHandle
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
-import com.squareup.workflow1.ui.ViewRegistry
+import com.squareup.workflow1.RuntimeConfigOptions
+import com.squareup.workflow1.WorkflowExperimentalRuntime
+import com.squareup.workflow1.ui.Screen
 import com.squareup.workflow1.ui.WorkflowLayout
-import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
 import com.squareup.workflow1.ui.renderWorkflowIn
-import kotlinx.coroutines.flow.StateFlow
-
-// This doesn't look like much right now, but we'll add more layout runners shortly.
-private val viewRegistry = ViewRegistry(WelcomeLayoutRunner)
+import kotlinx.coroutines.flow.Flow
 
 class TutorialActivity : AppCompatActivity() {
 
   override fun onCreate(savedInstanceState: Bundle?) {
     super.onCreate(savedInstanceState)
 
-    // Use an AndroidX ViewModel to start and host an instance of the workflow runtime that runs
-    // the WelcomeWorkflow and sets the activity's content view using our view factories.
+    // We use an AndroidX `ViewModel` and its CoroutineScope to start and host
+    // an instance of the workflow runtime that runs the WelcomeWorkflow.
+    // This ensures that our runtime will survive as new `Activity` instances
+    // are created for configuration changes.
     val model: TutorialViewModel by viewModels()
 
     setContentView(
-      WorkflowLayout(this).apply { start(model.renderings, viewRegistry) }
+      WorkflowLayout(this).apply {
+        take(lifecycle, model.renderings)
+      }
     )
   }
-}
 
-class TutorialViewModel(savedState: SavedStateHandle) : ViewModel() {
-  val renderings: StateFlow<WelcomeScreen> by lazy {
-    renderWorkflowIn(
-      workflow = WelcomeWorkflow,
-      scope = viewModelScope,
-      savedStateHandle = savedState,
-    )
+  class TutorialViewModel(savedState: SavedStateHandle) : ViewModel() {
+
+    // We opt in to WorkflowExperimentalRuntime in order turn on all the
+    // optimizations controlled by the runtimeConfig.
+    //
+    // They are in production use at Square, will not be listed as
+    // experimental much longer, and will soon be enabled by default.
+    // In the meantime it is much easier to use them from the start
+    // than to turn them on down the road.
+    @OptIn(WorkflowExperimentalRuntime::class)
+    val renderings: Flow<Screen> by lazy {
+      renderWorkflowIn(
+        workflow = RootNavigationWorkflow,
+        scope = viewModelScope,
+        savedStateHandle = savedState,
+        runtimeConfig = RuntimeConfigOptions.ALL
+      )
   }
 }