Merge pull request #1459 from square/sedwards/update-tutorial

Update tutorial

Author: steve-the-edwards

samples/tutorial/Tutorial1.md

@@ -23,13 +23,15 @@ We'll start by making pair of `Workflow` and `Screen` classes to back the provid
 First let's make `WelcomeWorkflow` from the _Stateful Workflow_ template, adding it to the `tutorial-base` module:
 
 ![New Workflow menu item](images/new-workflow.png "Right click tutorial-base/kotlin+java/workflow.tutorial > New > Stateful Workflow")
-![New Workflow window](images/workflow-name.png "File name: Welcome Workflow; Props type: Unit; State type: State; Output type: Output: Rendering type: WelcomeScreen")
+![New Workflow window](images/workflow-name.png "File name: Welcome Workflow; Props type: Unit; State type: State; Output type: Output: Rendering type: Screen")
 
 The template does not create everything needed.
 Manually add placeholder `object`s for `State` and `Output`.
 
+Note that we use the generic `com.squareup.workflow1.ui.Screen` type, for now (see more on that below).
+
 ```kotlin
-object WelcomeWorkflow : StatefulWorkflow<Unit, State, Output, WelcomeScreen>() {
+object WelcomeWorkflow : StatefulWorkflow<Unit, State, Output, Screen>() {
 
   object State
   object Output
@@ -42,7 +44,7 @@ object WelcomeWorkflow : StatefulWorkflow<Unit, State, Output, WelcomeScreen>()
   override fun render(
     renderProps: Unit,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<Unit, State, Output>
   ): Screen {
     TODO("Render")
   }
@@ -78,6 +80,9 @@ private fun welcomeScreenRunner(
 }
 ```
 
+So while our Workflow rendering type is `com.squareup.workflow1.ui.Screen`, we can actually
+return a true `WelcomeScreen` (a sub-type) from render().
+
 ### `Screen`, `ScreenViewFactory`, and `ScreenViewRunner`
 
 Let's start with what a "screen" is, and how it relates to views.
@@ -172,19 +177,20 @@ The core responsibility of a workflow is to provide a complete rendering / view
 every time the related application state updates.
 
 Let's go into the `WelcomeWorkflow` now,
-and have it return a `WelcomeScreen` from the `render()` method.
+and have it return a `WelcomeScreen` from the `render()` method. Remember `WelcomeScreen` is a
+sub-type of `com.squareup.workflow1.ui.Screen`, so we still satisfy the type binding.
 
 While you're here, opt out of persistence by making `snapshotState` return `null`.
 
 ```kotlin
-object WelcomeWorkflow : StatefulWorkflow<Unit, State, Output, WelcomeScreen>() {
+object WelcomeWorkflow : StatefulWorkflow<Unit, State, Output, Screen>() {
 
   // …
 
   override fun render(
     renderProps: Unit,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<Unit, State, Output>
   ): WelcomeScreen = WelcomeScreen(
     promptText = "",
     onLogInTapped = {}
@@ -206,8 +212,8 @@ object WelcomeWorkflow : StatefulWorkflow<Unit, State, Output, WelcomeScreen>()
 
 ### Setting up the Activity
 
-We have our `WelcomeWorkflow` rendering a `WelcomeScreen`
-which declares a `ScreenViewFactory` that knows how to display it.
+We have our `WelcomeWorkflow` rendering a `Screen` (we know will be `WelcomeScreen`)
+and our registry includes a `ScreenViewFactory` that knows how to display a `WelcomeScreen`.
 Now let's wire all this up to Android and show it on the screen!
 
 We're about to use functionality related to AndroidX `ViewModel`s,
@@ -235,16 +241,12 @@ class TutorialActivity : AppCompatActivity() {
 
     val model: TutorialViewModel by viewModels()
 
-    setContentView(
-      WorkflowLayout(this).apply {
-        take(lifecycle, model.renderings)
-      }
-    )
+    workflowContentView.take(lifecycle, model.renderings)
   }
 
   class TutorialViewModel(savedState: SavedStateHandle) : ViewModel() {
     @OptIn(WorkflowExperimentalRuntime::class)
-    val renderings: Flow<Screen> by lazy {
+    val renderings: StateFlow<Screen> by lazy {
       renderWorkflowIn(
         workflow = WelcomeWorkflow,
         scope = viewModelScope,
@@ -257,11 +259,15 @@ class TutorialActivity : AppCompatActivity() {
 ```
 
 > [!NOTE]
-> You'll see that we opt in to some "experimental" `runtimeConfig` options -- all of them, in fact.
-> These are optimizations that are in production use at Square.
-> They will not be labeled 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.
+> `workflowContentView` is an extension property on `Activity` that creates (or retrieves)
+> a `WorkflowLayout` and sets it as the content view automatically.
+> `renderWorkflowIn` starts the workflow runtime in the `ViewModel`'s scope and returns
+> a `StateFlow` of renderings that `WorkflowLayout.take` collects.
+> Note that `WorkflowLayout.take` uses the *Activity* lifecycle (as it's linked to the UI held
+> by the Activity). Whereas the runtime uses the *ViewModel*'s lifecycle- so it can survive
+> configuration changes, etc.
+> We opt into some "experimental" `runtimeConfig` options — all of them, in fact.
+> These are optimizations in production use at Square, and will soon be enabled by default.
 
 When the activity is started,
 it will start running the `WelcomeWorkflow` and display the Welcome Screen.
@@ -287,7 +293,7 @@ Let's add a `"Hello Workflow!"` message there
 to give us some confidence that this thing is working.
 
 ```kotlin
-object WelcomeWorkflow : StatefulWorkflow<Unit, State, Output, WelcomeScreen>() {
+object WelcomeWorkflow : StatefulWorkflow<Unit, State, Output, Screen>() {
 
   data class State(
     val prompt: String
@@ -303,7 +309,7 @@ object WelcomeWorkflow : StatefulWorkflow<Unit, State, Output, WelcomeScreen>()
   override fun render(
     renderProps: Unit,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<Unit, State, Output>
   ): WelcomeScreen = WelcomeScreen(
     promptText = renderState.prompt,
     onLogInTapped = {}
@@ -376,14 +382,14 @@ You could also write:
 And let's make an `onLogInTapped` event handler that enqueues one of those `updateName` actions.
 
 ```kotlin
-object WelcomeWorkflow : StatefulWorkflow<Unit, State, Output, WelcomeScreen>() {
+object WelcomeWorkflow : StatefulWorkflow<Unit, State, Output, Screen>() {
 
   // …
 
   override fun render(
     renderProps: Unit,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<Unit, State, Output>
   ): WelcomeScreen = WelcomeScreen(
     promptText = renderState.prompt,
     onLogInTapped = { name ->
@@ -453,7 +459,7 @@ We'll use `RenderContext.eventHandler` to inline the `updateName` action.
   override fun render(
     renderProps: Unit,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<Unit, State, Output>
   ): WelcomeScreen = WelcomeScreen(
     promptText = renderState.prompt,
     onLogInTapped = context.eventHandler("onLogInTapped") { name ->

samples/tutorial/Tutorial2.md

@@ -44,7 +44,7 @@ Modify `State` data class to contain a placeholder parameter, to make the compil
 We can leave everything else as the default for now:
 
 ```kotlin
-object TodoListWorkflow : StatefulWorkflow<Unit, State, Nothing, TodoListScreen>() {
+object TodoListWorkflow : StatefulWorkflow<Unit, State, Nothing, Screen>() {
 
   data class State(val placeholder: String = "")
 
@@ -56,7 +56,7 @@ object TodoListWorkflow : StatefulWorkflow<Unit, State, Nothing, TodoListScreen>
   override fun render(
     renderProps: Unit,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<Unit, State, Nothing>
   ): TodoListScreen {
     return TodoListScreen()
   }
@@ -70,7 +70,7 @@ object TodoListWorkflow : StatefulWorkflow<Unit, State, Nothing, TodoListScreen>
 For now, let's just show this new screen instead of the login screen/workflow. Update the activity to show the `TodoListWorkflow`:
 
 ```kotlin
-  val renderings: Flow<Screen> by lazy {
+  val renderings: StateFlow<Screen> by lazy {
     renderWorkflowIn(
       workflow = TodoListWorkflow,
       scope = viewModelScope,
@@ -89,7 +89,7 @@ The empty list is rather boring, so let's fill it in with some sample data for n
 Update the `State` type to include a list of todo model objects and change `initialState` to include a default one:
 
 ```kotlin
-object TodoListWorkflow : StatefulWorkflow<Unit, State, Nothing, TodoListScreen>() {
+object TodoListWorkflow : StatefulWorkflow<Unit, State, Nothing, Screen>() {
 
   data class TodoModel(
     val title: String,
@@ -147,14 +147,14 @@ private fun todoListScreenRunner(
 Finally, update `render` for `TodoListWorkflow` to send the titles of the todo models whenever the screen is updated:
 
 ```kotlin
-object TodoListWorkflow : StatefulWorkflow<Unit, State, Nothing, TodoListScreen>() {
+object TodoListWorkflow : StatefulWorkflow<Unit, State, Nothing, Screen>() {
 
   // …
 
   override fun render(
     renderProps: Unit,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<Unit, State, Nothing>
   ): TodoListScreen {
     val titles = renderState.todos.map { it.title }
 
@@ -199,7 +199,7 @@ object RootNavigationWorkflow : StatefulWorkflow<Unit, Unit, Nothing, Screen>()
   override fun render(
     renderProps: Unit,
     renderState: Unit,
-    context: RenderContext
+    context: RenderContext<Unit, Unit, Nothing>
   ): Screen {
     // Render a child workflow of type WelcomeWorkflow. When renderChild is called, the
     // infrastructure will start a child workflow session if one is not already running.
@@ -223,7 +223,7 @@ But `WelcomeWorkflow`'s output type is currently a simple object: `object Output
 For now, delete the `Output` on `WelcomeWorkflow` and replace it with `Nothing`:
 
 ```kotlin
-object WelcomeWorkflow : StatefulWorkflow<Unit, State, Nothing, WelcomeScreen>() {
+object WelcomeWorkflow : StatefulWorkflow<Unit, State, Nothing, Screen>() {
   // …
 }
 ```
@@ -235,7 +235,7 @@ The override for using `renderChild` on a child Workflow with `Nothing` as its o
   override fun render(
     renderProps: Unit,
     renderState: Unit,
-    context: RenderContext
+    context: RenderContext<Unit, Unit, Nothing>
   ): Screen {
     // Render a child workflow of type WelcomeWorkflow. When renderChild is called, the
     // infrastructure will start a child workflow session if one is not already running.
@@ -279,7 +279,7 @@ Start by defining the state that needs to be tracked at the root —
 specifically which screen we're showing, and the actions to log in and log out:
 
 ```kotlin
-object RootNavigationWorkflow : StatefulWorkflow<Unit, State, Nothing, WelcomeScreen>() {
+object RootNavigationWorkflow : StatefulWorkflow<Unit, State, Nothing, Screen>() {
 
   sealed interface State {
     object ShowingWelcome : State
@@ -320,7 +320,7 @@ Change our `OutputT` type from `Output` to a new `data class LoggedIn`
 to be able to signal our parent:
 
 ```kotlin
-object WelcomeWorkflow : StatefulWorkflow<Unit, State, LoggedIn, WelcomeScreen>() {
+object WelcomeWorkflow : StatefulWorkflow<Unit, State, LoggedIn, Screen>() {
 
   data class LoggedIn(val username: String)
 
@@ -350,7 +350,7 @@ Finally, map the output event from `WelcomeWorkflow` in `RootNavigationWorkflow`
   override fun render(
     renderProps: Unit,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<Unit, State, Nothing>
   ): WelcomeScreen {
     // Render a child workflow of type WelcomeWorkflow. When renderChild is called, the
     // infrastructure will start a child workflow session if one is not already running.
@@ -374,7 +374,7 @@ We'll update the `RootNavigationWorkflow` `render` method to show either the `We
 Temporarily define the `OutputT` of `TodoListWorkflow` as `Nothing` (we can only go forward!):
 
 ```kotlin
-object TodoListWorkflow : StatefulWorkflow<Unit, State, Nothing, TodoListScreen>() {
+object TodoListWorkflow : StatefulWorkflow<Unit, State, Nothing, Screen>() {
 ```
 
 And update the `render` method of `RootNavigationWorkflow`:
@@ -387,7 +387,7 @@ object RootNavigationWorkflow : StatefulWorkflow<Unit, State, Nothing, Screen>()
   override fun render(
     renderProps: Unit,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<Unit, State, Nothing>
   ): Screen {
     when (renderState) {
       // When the state is ShowingWelcome, delegate to the WelcomeWorkflow.
@@ -468,7 +468,7 @@ and use it to receive a `username` string.
 We will also need to update `TodoListScreen` to display it.
 
 ```kotlin
-object TodoListWorkflow : StatefulWorkflow<ListProps, State, Nothing, TodoListScreen>() {
+object TodoListWorkflow : StatefulWorkflow<ListProps, State, Nothing, Screen>() {
 
   data class ListProps(val username: String)
 
@@ -484,7 +484,7 @@ object TodoListWorkflow : StatefulWorkflow<ListProps, State, Nothing, TodoListSc
   override fun render(
     renderProps: ListProps,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<ListProps, State, BackPressed>
   ): TodoListScreen {
     val titles = renderState.todos.map { it.title }
 
@@ -524,7 +524,7 @@ object RootNavigationWorkflow : StatefulWorkflow<Unit, State, Nothing, Screen>()
   override fun render(
     renderProps: Unit,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<Unit, State, Nothing>
   ): Screen {
     when (renderState) {
       // …
@@ -559,7 +559,7 @@ object RootNavigationWorkflow : StatefulWorkflow<Unit, State, Nothing, BackStack
   override fun render(
     renderProps: Unit,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<Unit, State, Nothing>
   ): BackStackScreen<*> {
     // We always render the welcomeScreen regardless of the current state.
     // It's either showing or else we may want to pop back to it.
@@ -603,7 +603,7 @@ At the same time, use workflow's handy `View.setBackHandler` function to respond
 > and Android's [predictive back gesture](https://developer.android.com/guide/navigation/custom-back/predictive-back-gesture).
 
 ```kotlin
-object TodoListWorkflow : StatefulWorkflow<ListProps, State, BackPressed, TodoListScreen>() {
+object TodoListWorkflow : StatefulWorkflow<ListProps, State, BackPressed, Screen>() {
 
   // ...
 
@@ -614,7 +614,7 @@ object TodoListWorkflow : StatefulWorkflow<ListProps, State, BackPressed, TodoLi
   override fun render(
     renderProps: ListProps,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<ListProps, State, BackPressed>
   ): TodoListScreen {
     val titles = renderState.todos.map { it.title }
     return TodoListScreen(

samples/tutorial/Tutorial3.md

@@ -170,7 +170,7 @@ object TodoEditWorkflow : StatefulWorkflow<EditProps, State, Output, TodoEditScr
   override fun render(
     renderProps: Props,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<EditProps, State, Output>
   ): TodoEditScreen = TodoEditScreen(
     title = renderState.editedTitle,
     note = renderState.editedNote,
@@ -214,7 +214,7 @@ object TodoListWorkflow : StatefulWorkflow<ListProps, State, BackPressed, List<S
   override fun render(
     renderProps: ListProps,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<ListProps, State, BackPressed>
   ): List<Screen> {
     val titles = renderState.todos.map { it.title }
     return listOf(
@@ -242,7 +242,7 @@ object RootNavigationWorkflow : StatefulWorkflow<Unit, State, Nothing, BackStack
   override fun render(
     renderProps: Unit,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<Unit, State, Nothing>
   ): BackStackScreen<*> {
       // …
 
@@ -332,7 +332,7 @@ object TodoListWorkflow : StatefulWorkflow<ListProps, State, Back, List<Screen>>
   override fun render(
     renderProps: ListProps,
     renderState: State,
-    context: RenderContext
+    context: RenderContext<ListProps, State, Back>
   ): List<Screen> {
     val titles = renderState.todos.map { it.title }
     return listOf(