common Preview annotation (#3932)

Library `org.jetbrains.compose.components:components-ui-tooling-preview`
**This library is subject to change in the future.**

Added library
`org.jetbrains.compose.components:components-ui-tooling-preview:VERSION`,
where VERSION - shoud will be Compose version.
Simple Preview without arguments and PreviewParameterProvider for future
usage.

---------

Co-authored-by: Igor Demin <igordmn@users.noreply.github.com>

components/settings.gradle.kts

@@ -36,3 +36,6 @@ include(":resources:library")
 include(":resources:demo:androidApp")
 include(":resources:demo:desktopApp")
 include(":resources:demo:shared")
+include(":ui-tooling-preview:library")
+include(":ui-tooling-preview:demo:desktopApp")
+include(":ui-tooling-preview:demo:shared")

components/ui-tooling-preview/demo/desktopApp/build.gradle.kts

@@ -0,0 +1,22 @@
+plugins {
+    kotlin("multiplatform")
+    id("org.jetbrains.compose")
+}
+
+kotlin {
+    jvm()
+    sourceSets {
+        val jvmMain by getting {
+            dependencies {
+                implementation(compose.desktop.currentOs)
+                implementation(project(":ui-tooling-preview:demo:shared"))
+            }
+        }
+    }
+}
+
+compose.desktop {
+    application {
+        mainClass = "MainKt"
+    }
+}

components/ui-tooling-preview/demo/desktopApp/src/jvmMain/kotlin/Main.kt

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2020-2023 JetBrains s.r.o. and respective authors and developers.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE.txt file.
+ */
+
+import androidx.compose.ui.unit.DpSize
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.window.WindowState
+import androidx.compose.ui.window.singleWindowApplication
+import org.jetbrains.compose.preview.demo.shared.MainView
+
+fun main() =
+    singleWindowApplication(
+        title = "Preview annotation demo",
+        state = WindowState(size = DpSize(800.dp, 800.dp))
+    ) {
+        MainView()
+    }

components/ui-tooling-preview/demo/shared/build.gradle.kts

@@ -0,0 +1,85 @@
+import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
+
+plugins {
+    kotlin("multiplatform")
+    id("com.android.library")
+    id("org.jetbrains.compose")
+}
+
+kotlin {
+    @OptIn(ExperimentalKotlinGradlePluginApi::class)
+    targetHierarchy.default()
+    androidTarget {
+        compilations.all {
+            kotlinOptions {
+                jvmTarget = "11"
+            }
+        }
+    }
+    jvm("desktop")
+    listOf(
+        iosX64(),
+        iosArm64(),
+        iosSimulatorArm64()
+    ).forEach { iosTarget ->
+        iosTarget.binaries.framework {
+            baseName = "shared"
+            isStatic = true
+        }
+    }
+    js {
+        browser {
+            testTask(Action {
+                enabled = false
+            })
+        }
+        binaries.executable()
+    }
+
+    listOf(
+        macosX64(),
+        macosArm64()
+    ).forEach { macosTarget ->
+        macosTarget.binaries {
+            executable {
+                entryPoint = "main"
+            }
+        }
+    }
+
+    sourceSets {
+        val commonMain by getting {
+            dependencies {
+                implementation(compose.runtime)
+                implementation(compose.material3)
+                implementation(project(":ui-tooling-preview:library"))
+            }
+        }
+        val desktopMain by getting {
+            dependencies {
+                implementation(compose.desktop.common)
+            }
+        }
+    }
+}
+
+android {
+    compileSdk = 34
+    namespace = "org.jetbrains.compose.ui.tooling.preview.demo.shared"
+    defaultConfig {
+        minSdk = 21
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+}
+
+compose.experimental {
+    web.application {}
+}
+
+// TODO: remove this block after we update on a newer kotlin. Currently there is an error: `error:0308010C:digital envelope routines::unsupported`
+rootProject.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsRootPlugin> {
+    rootProject.the<org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsRootExtension>().nodeVersion = "16.0.0"
+}

components/ui-tooling-preview/demo/shared/src/commonMain/kotlin/org/jetbrains/compose/preview/demo/shared/UsePreviewAnnotation.kt

@@ -0,0 +1,16 @@
+package org.jetbrains.compose.preview.demo.shared
+
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import org.jetbrains.compose.ui.tooling.preview.Preview
+
+@Composable
+internal fun UsedInPreview() {
+    Text("This is commonMain Composable function")
+}
+
+@Preview
+@Composable
+fun UsePreviewAnnotation() {
+    UsedInPreview()
+}

components/ui-tooling-preview/demo/shared/src/desktopMain/kotlin/org/jetbrains/compose/preview/demo/shared/main.desktop.kt

@@ -0,0 +1,13 @@
+/*
+ * Copyright 2020-2023 JetBrains s.r.o. and respective authors and developers.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE.txt file.
+ */
+
+package org.jetbrains.compose.preview.demo.shared
+
+import androidx.compose.runtime.Composable
+
+@Composable
+fun MainView() {
+    UsedInPreview()
+}

components/ui-tooling-preview/library/build.gradle.kts

@@ -0,0 +1,55 @@
+import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
+
+plugins {
+    kotlin("multiplatform")
+    id("maven-publish")
+    id("com.android.library")
+}
+
+val composeVersion = extra["compose.version"] as String
+
+kotlin {
+    @OptIn(ExperimentalKotlinGradlePluginApi::class)
+    targetHierarchy.default()
+    jvm("desktop")
+    androidTarget {
+        publishLibraryVariants("release")
+        compilations.all {
+            kotlinOptions {
+                jvmTarget = "11"
+            }
+        }
+    }
+    iosX64()
+    iosArm64()
+    iosSimulatorArm64()
+    js {
+        browser {
+            testTask(Action {
+                enabled = false
+            })
+        }
+    }
+    macosX64()
+    macosArm64()
+}
+
+android {
+    compileSdk = 34
+    namespace = "org.jetbrains.compose.ui.tooling.preview"
+    defaultConfig {
+        minSdk = 21
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+}
+
+configureMavenPublication(
+    groupId = "org.jetbrains.compose.components",
+    artifactId = "components-ui-tooling-preview",
+    name = "Experimental Compose Multiplatform tooling library API. This library provides the API required to declare " +
+            "@Preview composables in user apps."
+)

components/ui-tooling-preview/library/src/commonMain/kotlin/org/jetbrains/compose/ui/tooling/preview/Preview.kt

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2023 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.jetbrains.compose.ui.tooling.preview
+
+import androidx.compose.runtime.Composable
+
+/**
+ * [Preview] can be applied to either of the following:
+ * - @[Composable] methods with no parameters to show them in the IDE preview.
+ * - Annotation classes, that could then be used to annotate @[Composable] methods or other
+ * annotation classes, which will then be considered as indirectly annotated with that [Preview].
+ */
+@MustBeDocumented
+@Retention(AnnotationRetention.BINARY)
+@Target(
+    AnnotationTarget.ANNOTATION_CLASS,
+    AnnotationTarget.FUNCTION
+)
+@Repeatable
+annotation class Preview

components/ui-tooling-preview/library/src/commonMain/kotlin/org/jetbrains/compose/ui/tooling/preview/PreviewParameter.kt

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2023 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.jetbrains.compose.ui.tooling.preview
+
+import kotlin.reflect.KClass
+
+/**
+ * Interface to be implemented by any provider of values that you want to be injected as @[Preview]
+ * parameters. This allows providing sample information for previews.
+ */
+interface PreviewParameterProvider<T> {
+    /**
+     * [Sequence] of values of type [T] to be passed as @[Preview] parameter.
+     */
+    val values: Sequence<T>
+
+    /**
+     * Returns the number of elements in the [values] [Sequence].
+     */
+    val count get() = values.count()
+}
+
+/**
+ * [PreviewParameter] can be applied to any parameter of a @[Preview].
+ *
+ * @param provider A [PreviewParameterProvider] class to use to inject values to the annotated
+ * parameter.
+ * @param limit Max number of values from [provider] to inject to this parameter.
+ */
+annotation class PreviewParameter(
+    val provider: KClass<out PreviewParameterProvider<*>>,
+    val limit: Int = Int.MAX_VALUE
+)