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",
         ],
     ]