feat: new onboarding step (#3686)

* feat: new ui step

docs/kr.tree

@@ -129,9 +129,10 @@
             <toc-element id="multiplatform-mobile-getting-started.md" accepts-web-file-names="kmm-getting-started.html"/>
             <toc-element id="multiplatform-mobile-setup.md" accepts-web-file-names="kmm-setup.html" toc-title="1. Set up an environment"/>
             <toc-element id="multiplatform-mobile-create-first-app.md" accepts-web-file-names="kmm-create-first-app.html" toc-title="2. Create your first cross-platform app"/>
-            <toc-element id="multiplatform-mobile-dependencies.md" toc-title="3. Add dependencies"/>
-            <toc-element id="multiplatform-mobile-upgrade-app.md" toc-title="4. Upgrade your app"/>
-            <toc-element id="multiplatform-mobile-wrap-up.md" toc-title="5. Wrap up your project"/>
+            <toc-element id="multiplatform-mobile-update-ui.md" toc-title="3. Update UI"/>
+            <toc-element id="multiplatform-mobile-dependencies.md" toc-title="4. Add dependencies"/>
+            <toc-element id="multiplatform-mobile-upgrade-app.md" toc-title="5. Share more logic"/>
+            <toc-element id="multiplatform-mobile-wrap-up.md" toc-title="6. Wrap up your project"/>
             <toc-element id="multiplatform-mobile-understand-project-structure.md" accepts-web-file-names="kmm-understand-project-structure.html"/>
             <toc-element id="multiplatform-mobile-integrate-in-existing-app.md" accepts-web-file-names="kmm-integrate-in-existing-app.html"/>
             <toc-element id="multiplatform-mobile-publish-apps.md" accepts-web-file-names="kmm-publish-apps.html"/>

docs/topics/multiplatform-mobile/multiplatform-mobile-dependencies.md

@@ -1,8 +1,13 @@
 [//]: # (title: Add dependencies to your project)
 
 <microformat>
-    <p>This is the third part of the <strong>Getting started with Kotlin Multiplatform for mobile</strong> tutorial. Before proceeding, make sure you've completed previous steps.</p>
-    <p><img src="icon-1-done.svg" width="20" alt="First step"/> <a href="multiplatform-mobile-setup.md">Set up an environment</a><br/><img src="icon-2-done.svg" width="20" alt="Second step"/> <a href="multiplatform-mobile-create-first-app.md">Create your first cross-platform app</a><br/><img src="icon-3.svg" width="20" alt="Third step"/> <strong>Add dependencies</strong><br/><img src="icon-4-todo.svg" width="20" alt="Fourth step"/> Upgrade your app<br/><img src="icon-5-todo.svg" width="20" alt="Fifth step"/> Wrap up your project</p>
+    <p>This is the fourth part of the <strong>Getting started with Kotlin Multiplatform for mobile</strong> tutorial. Before proceeding, make sure you've completed previous steps.</p>
+    <p><img src="icon-1-done.svg" width="20" alt="First step"/> <a href="multiplatform-mobile-setup.md">Set up an environment</a><br/>
+        <img src="icon-2-done.svg" width="20" alt="Second step"/> <a href="multiplatform-mobile-create-first-app.md">Create your first cross-platform app</a><br/>
+        <img src="icon-3-done.svg" width="20" alt="Third step"/> <a href="multiplatform-mobile-update-ui.md">Update the user interface</a><br/>
+        <img src="icon-4.svg" width="20" alt="Fourth step"/> <strong>Add dependencies</strong><br/>
+        <img src="icon-5-todo.svg" width="20" alt="Fifth step"/> Share more logic<br/>
+        <img src="icon-6-todo.svg" width="20" alt="Sixth step"/> Wrap up your project</p>
 </microformat>
 
 You've already created your first cross-platform Kotlin Multiplatform project! Now let's learn how to add dependencies
@@ -75,10 +80,11 @@ multiplatform support, is the most convenient way to work with dates in your sha
     ```kotlin
     class Greeting {
         private val platform: Platform = getPlatform()
-
-        fun greet(): String {
-            return "Guess what it is! > ${platform.name.reversed()}!" +
-                    "\nThere are only ${daysUntilNewYear()} days left until New Year! 🎆"
+
+        fun greet(): List<String> = buildList {
+            add(if (Random.nextBoolean()) "Hi!" else "Hello!")
+            add("Guess what it is! > ${platform.name.reversed()}!")
+            add("\nThere are only ${daysUntilNewYear()} days left until New Year! 🎆")
         }
     }
     ```

docs/topics/multiplatform-mobile/multiplatform-mobile-getting-started.md

@@ -36,11 +36,13 @@ Get to know Kotlin Multiplatform and create a mobile app that works on both Andr
 
 ![Second step](icon-2.svg){width=25}{type="joined"} [Create your first app that works both on Android and iOS with the IDE](multiplatform-mobile-create-first-app.md)
 
-![Third step](icon-3.svg){width=25}{type="joined"} [Add dependencies to your project](multiplatform-mobile-dependencies.md)
+![Third step](icon-3.svg){width=25}{type="joined"} [Update the user interface](multiplatform-mobile-update-ui.md)
 
-![Fourth step](icon-4.svg){width=25}{type="joined"} [Upgrade your app](multiplatform-mobile-upgrade-app.md)
+![Fourth step](icon-4.svg){width=25}{type="joined"} [Add dependencies to your project](multiplatform-mobile-dependencies.md)
 
-![Fifth step](icon-5.svg){width=25}{type="joined"} [Wrap up your project](multiplatform-mobile-wrap-up.md)
+![Fifth step](icon-5.svg){width=25}{type="joined"} [Share more logic](multiplatform-mobile-upgrade-app.md)
+
+![Sixth step](icon-6.svg){width=25}{type="joined"} [Wrap up your project](multiplatform-mobile-wrap-up.md)
 
 ## Next step
 

docs/topics/multiplatform-mobile/multiplatform-mobile-setup.md

@@ -2,7 +2,12 @@
 
 <microformat>
     <p>This is the first part of the <strong>Getting started with Kotlin Multiplatform for mobile</strong> tutorial:</p>
-    <p><img src="icon-1.svg" width="20" alt="First step"/> <strong>Set up an environment</strong><br/><img src="icon-2-todo.svg" width="20" alt="Second step"/> Create your first cross-platform app<br/><img src="icon-3-todo.svg" width="20" alt="Third step"/> Add dependencies<br/><img src="icon-4-todo.svg" width="20" alt="Fourth step"/> Upgrade your app<br/><img src="icon-5-todo.svg" width="20" alt="Fifth step"/> Wrap up your project</p>
+    <p><img src="icon-1.svg" width="20" alt="First step"/> <strong>Set up an environment</strong><br/>
+       <img src="icon-2-todo.svg" width="20" alt="Second step"/> Create your first cross-platform app<br/>
+       <img src="icon-3-todo.svg" width="20" alt="Third step"/> Update the user interface<br/>       
+       <img src="icon-4-todo.svg" width="20" alt="Fourth step"/> Add dependencies<br/>
+       <img src="icon-5-todo.svg" width="20" alt="Fifth step"/> Share more logic<br/>
+       <img src="icon-6-todo.svg" width="20" alt="Sixth step"/> Wrap up your project</p>
 </microformat>
 
 Before you create your first application that works on both iOS and Android, you'll need to set up an environment for Kotlin Multiplatform

docs/topics/multiplatform-mobile/multiplatform-mobile-update-ui.md

@@ -0,0 +1,126 @@
+[//]: # (title: Update the user interface)
+
+<microformat>
+    <p>This is the third part of the <strong>Getting started with Kotlin Multiplatform for mobile</strong> tutorial. Before proceeding, make sure you've completed previous steps.</p>
+    <p><img src="icon-1-done.svg" width="20" alt="First step"/> <a href="multiplatform-mobile-setup.md">Set up an environment</a><br/>
+       <img src="icon-2-done.svg" width="20" alt="Second step"/> <a href="multiplatform-mobile-create-first-app.md">Create your first cross-platform app</a><br/>
+       <img src="icon-3.svg" width="20" alt="Third step"/> <strong>Update the user interface</strong><br/>       
+       <img src="icon-4-todo.svg" width="20" alt="Fourth step"/> Add dependencies<br/>
+       <img src="icon-5-todo.svg" width="20" alt="Fifth step"/> Share more logic<br/>
+       <img src="icon-6-todo.svg" width="20" alt="Sixth step"/> Wrap up your project</p>
+</microformat>
+
+To build the user interface, you'll use the [Jetpack Compose](https://developer.android.com/jetpack/compose) toolkit
+for the Android part of your project and [SwiftUI](https://developer.apple.com/xcode/swiftui/) for the iOS one.
+These are both declarative UI frameworks, and you'll see similarities in the UI implementations. In both cases,
+you store the data in the `phrases` variable and later iterate over it to produce a list of `Text` items.
+
+### Update the Android module
+
+The `androidApp` module contains an Android application, defines its main activity and the UI views, and uses the
+`shared` module as a regular Android library. The UI of the application uses the Jetpack Compose framework.
+
+Make some changes and see how it is reflected in the UI:
+
+1. Navigate to the `MainActivity.kt` file in `androidApp`.
+2. Find the `Greeting` class invocation. Select the `greet()` function and use the **Cmd + B** shortcut.
+   You'll see that it's the same class from the `shared` module you edited in the previous step.
+3. In `Greeting.kt`, update the `greet()` function:
+
+    ```kotlin
+    fun greet(): List<String> = buildList {
+        add(if (Random.nextBoolean()) "Hi!" else "Hello!")
+        add("Guess what it is! > ${platform.name.reversed()}!")
+    }
+    ```
+
+   Now it returns a list of strings.
+
+4. Go back to `MainActivity.kt`. As you can see, it doesn't compile anymore because the `GreetingView` composable
+   expects a `String` argument. Update its definition:
+
+   ```kotlin
+   @Composable
+   fun GreetingView(phrases: List<String>) {
+       LazyColumn(
+           contentPadding = PaddingValues(20.dp),
+           verticalArrangement = Arrangement.spacedBy(8.dp),
+       ) {
+           items(phrases) { phrase ->
+               Text(phrase)
+               Divider()
+           }
+       }
+   }
+   ```
+
+   Here the `LazyColumn` composable shows the list of `Text` items, adds padding around the content and a space between the list items. 
+   
+5. Follow Android Studio's suggestions to import the missing dependencies.
+6. Update the preview as well, passing a list as an argument:
+
+   ```kotlin
+   @Preview
+   @Composable
+   fun DefaultPreview() {
+       MyApplicationTheme {
+           Greeting(listOf("Hello, Android!"))
+       }
+   }
+   ```
+
+7. Now you can run the Android app to ensure it displays the list:
+
+   ![Updated UI of Android multiplatform app](first-multiplatform-project-on-android-2.png){width=300}
+
+### Work with the iOS module in Xcode
+
+`iosApp` is an Xcode project that builds into an iOS application. It depends on and uses the `shared` module as an iOS
+framework. The UI of the app is written in Swift.
+
+Implement the same changes as in the Android app:
+
+1. Launch Xcode. Select **Open a project or file**.
+2. Navigate to your project, for example **KotlinMultiplatformSandbox**, and select the `iosApp` folder. Click **Open**.
+3. In the `ContenView.swift` file, select the `greet()` function and use the **⌃ + Cmd** shortcut.
+
+   You'll see the Objective-C declarations for the Kotlin functions defined in the `shared` module. Kotlin types are
+   represented as Objective-C types when used from Objective-C/Swift. Here the `greet()` function
+   returns `List<String>` in Kotlin and is seen from Swift as returning `NSArray<NSString>`. For more on type mappings,
+   see [Interoperability with Swift/Objective-C](native-objc-interop.md).
+
+4. If you try running the project, the build will fail. As in the Android app earlier,
+   the Swift code that uses the `greet()` function doesn't compile because its declaration is different now.
+   Change the SwiftUI code to display a list of items:
+
+   ```Swift
+   struct ContentView: View {
+       let phrases = Greeting().greet()
+
+       var body: some View {
+           List(phrases, id: \.self) {
+               Text($0)
+           }
+       }
+   }
+   ```
+
+    * The results of the `greet()` call are stored in the `phrases` variable (`let` in Swift is similar to Kotlin's `val`).
+    * The `List` function produces a list of `Text` items.
+
+5. Run the app to see the changes:
+
+   ![Updated UI of your iOS multiplatform app](first-multiplatform-project-on-ios-2.png){width=300}
+
+## Next step
+
+In the next part of the tutorial, you'll learn about dependencies and add a third-party library to expand
+the functionality of your project.
+
+**[Proceed to the next part](multiplatform-mobile-dependencies.md)**
+
+## Get help
+
+* **Kotlin Slack**. Get an [invite](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) and join
+  the [#multiplatform](https://kotlinlang.slack.com/archives/C3PQML5NU) channel.
+* **Kotlin issue tracker**. [Report a new issue](https://youtrack.jetbrains.com/newIssue?project=KT).