com.airbnb.android.showkase.annotation.ShowkaseComposable.kt Maven / Gradle / Ivy
Show all versions of showkase-annotation Show documentation
package com.airbnb.android.showkase.annotation
/**
* Used to annotate @Composable functions that should be displayed inside the
* Showkase browser. Here's how you would use it with your @Composable function:
*
* @ShowkaseComposable(name = "Name", group = "Group")
* @Composable
* fun MyComposable() {
* .......
* .......
* }
*
*
* Note: Make sure that you add this annotation to only those functions that don't accept any
* parameters. If your function accepts a parameters, wrap it inside another function that doesn't
* accept any parameters.
*
* For example, here is a @Composable function that requires parameters -
*
* @Composable
* fun MyComposable(name: String) {
* .......
* .......
* }
*
* In order to make this function compatible with Showkase, you could further wrap this function
* inside a method that doesn't accept a parameters in the following way:
*
* @ShowkaseComposable(name = "Name", group = "Group")
* @Composable
* fun MyComposablePreview() {
* MyComposable("Name")
* }
*
* This requirement is even needed by the @Preview functions of Jetpack Compose.
*
* @param name The name that should be used to describe your `@Composable` function. If you don't
* pass any value, the name of the composable function is used as the name.
* @param group The grouping key that will be used to group it with other `@Composable` functions
* . This is useful for better organization and discoverability of your components. If you don't
* pass any value for the group, the name of the class that wraps this function is used as the
* group name. If the function is a top level function, the composable is added to a "Default Group".
* @param widthDp The width that your component will be rendered in inside the Showkase browser.
* Use this to restrict the size of your preview inside the Showkase browser.
* @param heightDp The height that your component will be rendered in inside the Showkase browser.
* Use this to restrict the size of your preview inside the Showkase browser.
* @param skip Use this boolean when you want to skip this composable from the Showkase browser. A
* use case of this might be when you want a composable that's annotated with @Preview to show previews
* in Android Studio but don't want to necessary show it in the component browser that's autogenerated
* by Showkase
* @param defaultStyle Used to represent a composable function is the default style variant of a given
* composable. More information on how Showkase allows you to represent component styles in this section -
* https://github.com/airbnb/Showkase#representing-component-styles-in-showkase
* @param tags Various string values that will be propagated to the Showkase browser to allow additional
* filtering or categorization.
* @param extraMetadata Various string values that are **not** used by the standard Showkase browser
* but are still available in the generated `ShowkaseBrowserComponent` object. This may be useful when
* extra data is needed for attributing components during other processes (e.g. static analysis,
* displaying attributions in a custom component browser).
*/
@MustBeDocumented
@Retention(AnnotationRetention.SOURCE)
@Target(AnnotationTarget.FUNCTION)
@Repeatable
@Suppress("LongParameterList")
annotation class ShowkaseComposable(
val name: String = "",
val group: String = "",
val styleName: String = "",
val widthDp: Int = -1,
val heightDp: Int = -1,
val skip: Boolean = false,
val defaultStyle: Boolean = false,
val tags: Array = [],
val extraMetadata: Array = [],
)