Merge pull request JetBrains#121 from JetBrains/compose-1.6.10-release

feat: Compose for web in alpha

Author: AlejandraPedroza

images/compose-create-first/compose-multiplatform-ui-app.png

@@ -19,7 +19,7 @@ To begin, create a sample project. This is best achieved with the Kotlin Multipl
 
 1. Open the [Kotlin Multiplatform wizard](https://kmp.jetbrains.com).
 2. On the **New project** tab, change the project name to "ComposeDemo" and the project ID to "kmp.project.demo".
-3. Select the **Android** and **Desktop** options.
+3. Select the **Android**, **Desktop**, and **Web** options.
 4. If you're using a Mac, select **iOS** as well. Make sure that the **Share UI** option is selected.
 5. Click the **Download** button and unpack the resulting archive.
 
@@ -42,25 +42,27 @@ To begin, create a sample project. This is best achieved with the Kotlin Multipl
 
 The project contains two modules:
 
-* _composeApp_ is a Kotlin module that contains the logic shared among the Android, desktop, and iOS applications – the code
+* _composeApp_ is a Kotlin module that contains the logic shared among the Android, desktop, iOS, and web applications – the code
   you use for all the platforms. It uses [Gradle](https://kotlinlang.org/docs/gradle.html) as the build system that helps
   you automate your build process.
 * _iosApp_ is an Xcode project that builds into an iOS application. It depends on and uses the shared module as an iOS
   framework.
 
   ![Compose Multiplatform project structure](compose-project-structure.png){width=350}
 
-The **composeApp** module consists of four source sets: `androidMain`, `commonMain`, `desktopMain`, and `iosMain`.
+The **composeApp** module consists of the following source sets: `androidMain`, `commonMain`, `desktopMain`, `iosMain`, and `wasmJsMain`.
 A _source set_ is a Gradle concept for a number of files logically grouped together, where each group has its own
 dependencies. In Kotlin Multiplatform, different source sets can target different platforms.
 
 The `commonMain` source set uses the common Kotlin code, and platform source sets use Kotlin code specific to each
-target. Kotlin/JVM is used for `androidMain` and `desktopMain`. Kotlin/Native is used for `iosMain`.
+target. Kotlin/JVM is used for `androidMain` and `desktopMain`. Kotlin/Native is used for `iosMain`. On the other hand, Kotlin/Wasm is 
+used for `wasmJsMain`.
 
 When the shared module is built into an Android library, common Kotlin code gets treated as Kotlin/JVM. When it is built
-into an iOS framework, common Kotlin code gets treated as Kotlin/Native:
+into an iOS framework, common Kotlin code gets treated as Kotlin/Native. When the shared module is built into a web app, common 
+Kotlin code gets treated as Kotlin/Wasm.
 
-![Common Kotlin, Kotlin/JVM, and Kotlin/Native](modules-structure.png){width=700}
+![Common Kotlin, Kotlin/JVM, and Kotlin/Native](module-structure.png){width=700}
 
 In general, write your implementation as common code whenever possible instead of duplicating functionality
 in platform-specific source sets.
@@ -74,7 +76,7 @@ Let's run the application and then examine the code in depth.
 
 ## Run your application
 
-You can run the application on Android, iOS, and desktop. You don't have to run the applications in any particular
+You can run the application on Android, iOS, desktop, and web. You don't have to run the applications in any particular
 order, so start with whichever platform you are most familiar with.
 
 > You don't need to use the Gradle build task. In a multiplatform application, this will build debug and release versions
@@ -203,7 +205,7 @@ in Android Studio and select your device in the **Execution target** list. Run t
 
 You can create a run configuration for running the desktop application as follows:
 
-1. Select the **Run | Edit Configurations** menu item.
+1. Select **Run | Edit Configurations** from the main menu.
 2. Click the plus button and choose **Gradle** from the dropdown list.
 3. In the **Tasks and arguments** field, paste this command:
    ```shell
@@ -215,6 +217,36 @@ Now, you can use this configuration to run the desktop app:
 
 ![Run the Compose Multiplatform app on desktop](compose-run-desktop-temp.png){width=350}
 
+### Run your web application
+
+Create a run configuration to run the web application:
+
+1. Select **Run | Edit Configurations** from the main menu.
+2. Click the plus button and choose **Gradle** from the dropdown list.
+3. In the **Tasks and arguments** field, paste this command:
+
+   ```shell
+   wasmJsBrowserRun -t --quiet
+   ```
+
+4. Click **OK**.
+
+Now, you can use this configuration to run the web app:
+
+![Run the Compose Multiplatform app on desktop](compose-run-web.png){width=350}
+
+The web application opens automatically in your browser. Alternatively, you can type the following URL in your browser when the run is finished:
+
+```shell
+   http://localhost:8080/
+```
+> The port number can vary because the 8080 port may be unavailable. You can find the actual port number in the 
+> Gradle build console.
+>
+{type="tip"}
+
+![Compose web application](first-compose-project-on-web.png){width=550}
+
 ## Next step
 
 In the next part of the tutorial, you'll learn how to implement composable functions and launch your application on each

images/compose-create-first/compose-run-wasm-distribution-task.png

@@ -20,15 +20,16 @@ Take a look at the `App()` function in `composeApp/src/commonMain/kotlin`:
 ```kotlin
 @OptIn(ExperimentalResourceApi::class)
 @Composable
+@Preview
 fun App() {
     MaterialTheme {
         var showContent by remember { mutableStateOf(false) }
-        val greeting = remember { Greeting().greet() }
         Column(Modifier.fillMaxWidth(), horizontalAlignment = Alignment.CenterHorizontally) {
             Button(onClick = { showContent = !showContent }) {
                 Text("Click me!")
             }
             AnimatedVisibility(showContent) {
+                val greeting = remember { Greeting().greet() }
                 Column(Modifier.fillMaxWidth(), horizontalAlignment = Alignment.CenterHorizontally) {
                     Image(painterResource(Res.drawable.compose_multiplatform), null)
                     Text("Compose: $greeting")
@@ -84,8 +85,8 @@ The changes occur when the image is shown or hidden because the parent `Animated
 
 ## Launching UI on different platforms
 
-The `App()` function execution is different for each platform. On Android, it's managed by an activity, on iOS by a view
-controller, and on desktop by a window. Let's examine each of them.
+The `App()` function execution is different for each platform. On Android, it's managed by an activity; on iOS, by a view 
+controller; on the desktop, by a window; and on the web, by a container. Let's examine each of them.
 
 ### On Android
 
@@ -119,7 +120,7 @@ role as an activity on Android. Notice that both the iOS and Android types simpl
 
 ### On desktop
 
-For desktop, look again at the `main()` function in `composeApp/src/desktopMain/kotlin`:
+For desktop, look at the `main()` function in `composeApp/src/desktopMain/kotlin`:
 
 ```kotlin
 fun main() = application {
@@ -137,6 +138,34 @@ fun main() = application {
 Currently, the `App` function doesn't declare any parameters. In a larger application, you typically pass parameters to
 platform-specific dependencies. These dependencies could be created by hand or using a dependency injection library.
 
+### On web
+
+For web, look again at the `main()` function in `composeApp/src/wasmJsMain/kotlin`. The function has two variants:
+
+```kotlin
+// First variant:
+@OptIn(ExperimentalComposeUiApi::class)
+fun main() {
+    ComposeViewport(viewportContainer = document.body!!) { App() }
+}
+
+
+// Second variant:
+@OptIn(ExperimentalComposeUiApi::class)
+fun main() {
+    ComposeViewport(viewportContainerId = "composeApplication") { App() }
+}
+```
+
+* In the first variant, the web app is inserted into the container assigned to the `viewportContainer` parameter.
+  The `viewportContainer` parameter stores the entire body of the HTML document. The entire document's body works as the container for rendering the UI.
+* In the second variant, the web app is inserted into a container added in your `index.html` file, where the UI is rendered.
+  The `composeApplication` element corresponds to the ID of this container and is assigned to the `viewportContainerId` parameter.
+* In both variants, the `@OptIn(ExperimentalComposeUiApi::class)` annotation tells the compiler that you are using an API marked as 
+  experimental and may change in future releases.
+* The `ComposeViewport()` function sets up the Compose environment for the application.
+* The `App()` function is responsible for building the UI components of your application using Jetpack Compose.
+
 ## Next step
 
 In the next part of the tutorial, you'll add a dependency to the project and modify the user interface.

images/compose-create-first/compose-run-web.png

@@ -100,9 +100,9 @@ and desktop:
 
 ![First Compose Multiplatform app on desktop](first-compose-project-on-desktop-2.png){width=400}
 
-> You can find this state of the project in our [GitHub repository](https://github.com/kotlin-hands-on/get-started-with-cm/tree/main/ComposeDemoStage1).
+<!-- > You can find this state of the project in our [GitHub repository](https://github.com/kotlin-hands-on/get-started-with-cm/tree/main/ComposeDemoStage1).
 >
-{type="tip"}
+{type="tip"} -->
 
 ## Next step
 

images/compose-create-first/compose-web-artifacts.png

@@ -410,9 +410,9 @@ code to load and display them:
 
    ![The country flags in the Compose Multiplatform app on desktop](first-compose-project-on-desktop-9.png){width=350}
 
-> You can find this state of the project in our [GitHub repository](https://github.com/kotlin-hands-on/get-started-with-cm/tree/main/ComposeDemoStage4).
+<!-- > You can find this state of the project in our [GitHub repository](https://github.com/kotlin-hands-on/get-started-with-cm/tree/main/ComposeDemoStage4).
 >
-{type="tip"}
+{type="tip"} -->
 
 ## What's next
 

images/compose-create-first/first-compose-project-on-web.png

@@ -57,6 +57,17 @@ We recommend that you install the latest stable versions for compatibility and b
             <p>To update the plugin, on the Android Studio welcome screen, select <strong>Plugins | Installed</strong>. Click <strong>Update</strong> next to Kotlin. You can also check the Kotlin version in <strong>Tools | Kotlin | Configure Kotlin Plugin Updates</strong>.</p>
             <p>The Kotlin plugin should be compatible with the Kotlin Multiplatform Mobile plugin. Refer to the <a href="https://kotlinlang.org/docs/multiplatform-plugin-releases.html#release-details">compatibility table</a>.</p></td>
    </tr>
+    <tr>
+        <td>Browsers</td>
+        <td>
+            <p>To run multiplatform applications in a browser, you need a browser supporting the <a href="https://github.com/WebAssembly/gc">Wasm Garbage Collection (GC) feature</a>.</p>
+            <list>
+                <li><strong>Chrome and Chromium-based:</strong> works by default starting from version 119.</li>
+                <li><strong>Firefox:</strong> works by default starting from version 120.</li>
+                <li><strong>Safari/WebKit:</strong> Wasm GC support is currently under <a href="https://bugs.webkit.org/show_bug.cgi?id=247394">active development</a>.</li>
+            </list>
+        </td>
+    </tr>
 </table>
 
 ## Check your environment
@@ -143,6 +154,9 @@ To make sure everything works as expected, install and run the KDoctor tool:
               <li><code>command not found: java</code> — <a href="https://www.oracle.com/java/technologies/javase-downloads.html">install Java</a>.</li>
            </list>
    </def>
+   <def title="Browsers">
+      Make sure that your browser version supports the new <a href="https://github.com/WebAssembly/gc">WasmGC</a> by default. If you are working with older browser versions, <a href="https://kotlinlang.org/docs/wasm-troubleshooting.html#browser-versions">configure the environment</a>.
+   </def>
    <def title="Still having trouble?">
             <p>Share your problems with the team by <a href="https://kotl.in/issue">creating a YouTrack issue</a>.</p>
             <p>For a smoother multiplatform experience, you can also try <a href="https://www.jetbrains.com/help/kotlin-multiplatform-dev/fleet.html">JetBrains Fleet</a>: it integrates with Compose Multiplatform and allows writing Swift code without switching to Xcode, with less IDE juggling overall.</p>

images/compose-create-first/module-structure.png

@@ -1,8 +1,10 @@
 [//]: # (title: Publish your application)
 
-Once your mobile apps are ready for release, it's time to deliver them to the users by publishing them in app stores.
-Multiple stores are available for each platform. However, in this article we'll focus on the official ones:
-[Google Play Store](https://play.google.com/store) and [Apple App Store](https://www.apple.com/ios/app-store/).
+Once your apps are ready for release, it's time to deliver them to the users by publishing them.
+
+For mobile apps, multiple stores are available for each platform. However, in this article, we'll focus on the official ones:
+[Google Play Store](https://play.google.com/store) and [Apple App Store](https://www.apple.com/ios/app-store/). For web apps, we'll use [GitHub pages](https://pages.github.com/). 
+
 You'll learn how to prepare Kotlin Multiplatform applications for publishing, and we'll highlight
 the parts of this process that deserve special attention.
 
@@ -77,4 +79,55 @@ file. This helps you analyze crashes that happen in the shared module's code.
 
 When an iOS app is rebuilt from bitcode, its `dSYM` file becomes invalid. For such cases, you can compile the shared module
 to a static framework that stores the debug information inside itself. For instructions on setting up crash report
-symbolication in binaries produced from Kotlin modules, see the [Kotlin/Native documentation](https://kotlinlang.org/docs/native-ios-symbolication.html).
+symbolication in binaries produced from Kotlin modules, see the [Kotlin/Native documentation](https://kotlinlang.org/docs/native-ios-symbolication.html).
+
+## Web app
+
+To publish your web application, create the artifacts containing the compiled files 
+and resources that make up your application. These artifacts are necessary to deploy your application to a web hosting platform like GitHub Pages.
+
+### Generate artifacts
+
+Create a run configuration for running the **wasmJsBrowserDistribution** task:
+
+1. Select the **Run | Edit Configurations** menu item.
+2. Click the plus button and choose **Gradle** from the dropdown list.
+3. In the **Tasks and arguments** field, paste this command:
+
+   ```shell
+   wasmJsBrowserDistribution
+   ```
+
+4. Click **OK**.
+
+Now, you can use this configuration to run the task:
+
+![Run the Wasm distribution task](compose-run-wasm-distribution-task.png){width=350}
+
+Once the task completes, you can find the generated artifacts in the `composeApp/build/dist/wasmJs/productionExecutable`
+directory:
+
+![Artifacts directory](compose-web-artifacts.png){width=600}
+
+### Publish your application on GitHub Pages
+
+With the artifacts ready, you can deploy your application on the web hosting platform:
+
+1. Copy the contents of your `productionExecutable` directory into the repository where you want to create a site.
+2. Follow GitHub's instructions for [creating your site](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site).
+
+   > It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub.
+   >
+   {type="note"}
+
+3. In a browser, navigate to your GitHub pages domain.
+
+   ![Navigate to GitHub pages](publish-your-application-on-web.png){width=650}
+
+   Congratulations! You have published your artifacts on GitHub pages.
+
+### Debug your web application
+
+You can debug your web application in your browser out of the box, without additional configurations. To learn how to debug
+in the browser, see the [Debug in your browser](https://kotlinlang.org/docs/wasm-debugging.html#debug-in-your-browser)
+guide in Kotlin docs.