⌘K

Block Annotations

This document provides an overview of the annotations available in the Nativeblocks Compiler for defining and managing blocks in Android Kotlin. These annotations simplify the creation of structured, reusable blocks for dynamic UI and logic using Jetpack Compose.

Annotations Overview

1. @NativeBlock

Description

Marks a Composable function as a reusable block with metadata and associates it with a specific key and description, making it available in the visual editor.

Declaration

@Target(AnnotationTarget.FUNCTION)
annotation class NativeBlock(
    val name: String,
    val keyType: String,
    val description: String,
    val version: Int = 1,
    val deprecated: Boolean = false,
    val deprecatedReason: String = ""
)
Parameters
  • name: A String representing the display name of the block.
  • keyType: A String defining a unique key type identifier for the block.
  • description: A String providing a detailed explanation of the block's purpose.
  • version: An optional Int (default: 1) specifying the version of the block.
  • deprecated: A Boolean (default: false) indicating whether the block is deprecated.
  • deprecatedReason: An optional String explaining the reason for deprecation if applicable.

Important Note

The @NativeBlock annotation must only be used with functions annotated with @Composable. Applying this annotation to non-Compose functions will result in a compilation error.

Example

@NativeBlock(
    name = "My Button Block",
    keyType = "MY_BUTTON",
    description = "A customizable button block"
)
@Composable
fun MyButtonBlock(
    @NativeBlockData(description = "Button text") text: String,
    @NativeBlockProp(
        description = "Button color",
        valuePicker = NativeBlockValuePicker.DROPDOWN,
        valuePickerOptions = [
            NativeBlockValuePickerOption("RED", "Red"),
            NativeBlockValuePickerOption("BLUE", "Blue")
        ]
    ) color: String = "BLUE",
    @NativeBlockEvent(description = "Triggered when the button is clicked") onClick: () -> Unit
) {
    Button(onClick = onClick, colors = ButtonDefaults.buttonColors(Color.parse(color))) {
        Text(text)
    }
}

2. @NativeBlockData

Description

Defines a data-binding property for a block, typically linked to runtime data or frame-level variables.

Declaration

@Target(AnnotationTarget.VALUE_PARAMETER)
annotation class NativeBlockData(
    val description: String = "",
    val deprecated: Boolean = false,
    val deprecatedReason: String = ""
)

Example

@NativeBlockData(description = "Main content of the block")
val content: String

3. @NativeBlockProp

Description

Defines a configurable property for a block, allowing customization such as settings or options.

Declaration

@Target(AnnotationTarget.VALUE_PARAMETER)
annotation class NativeBlockProp(
    val description: String = "",
    val valuePicker: NativeBlockValuePicker = NativeBlockValuePicker.TEXT_INPUT,
    val valuePickerGroup: NativeBlockValuePickerPosition = NativeBlockValuePickerPosition("General"),
    val valuePickerOptions: Array<NativeBlockValuePickerOption> = [],
    val deprecated: Boolean = false,
    val deprecatedReason: String = ""
)
Parameters
  • description: A String providing details about the property.
  • valuePicker: A NativeBlockValuePicker specifying the input type for the property (e.g., TEXT_INPUT, DROPDOWN).
  • valuePickerGroup: A NativeBlockValuePickerPosition defining the section or category for the property (default: "General").
  • valuePickerOptions: An array of NativeBlockValuePickerOption defining dropdown or combobox options.
  • deprecated: A Boolean (default: false) indicating whether the property is deprecated.
  • deprecatedReason: An optional String giving the reason for deprecation.

Example

@NativeBlockProp(
    description = "Set the visibility of the block",
    valuePicker = NativeBlockValuePicker.DROPDOWN,
    valuePickerOptions = [
        NativeBlockValuePickerOption("VISIBLE", "Visible"),
        NativeBlockValuePickerOption("HIDDEN", "Hidden")
    ]
)
val isVisible: Boolean = true

4. @NativeBlockEvent

Description

Defines an event for a block, such as user interactions or data changes.

Declaration

@Target(AnnotationTarget.VALUE_PARAMETER)
annotation class NativeBlockEvent(
    val description: String = "",
    val dataBinding: Array<String> = [],
    val deprecated: Boolean = false,
    val deprecatedReason: String = ""
)
Parameters
  • description: A String providing details about the event.
  • dataBinding: An array of String specifying the data bindings for the event handler.
  • deprecated: A Boolean (default: false) indicating whether the event is deprecated.
  • deprecatedReason: An optional String explaining the reason for deprecation.

Example

@NativeBlockEvent(description = "Triggered when the block is clicked")
val onClick: () -> Unit

5. @NativeBlockSlot

Description

Defines a slot for nested content within a block, enabling composability and flexible layouts.

Declaration

@Target(AnnotationTarget.VALUE_PARAMETER)
annotation class NativeBlockSlot(
    val description: String = "",
    val deprecated: Boolean = false,
    val deprecatedReason: String = ""
)

Example

@NativeBlockSlot(description = "Slot for child content")
val contentSlot: @Composable (Int) -> Unit

Supporting Types

NativeBlockValuePicker

Defines input methods for block properties.

enum class NativeBlockValuePicker {
    TEXT_INPUT,
    NUMBER_INPUT,
    DROPDOWN
}

NativeBlockValuePickerOption

Provides options for value pickers like dropdowns.

data class NativeBlockValuePickerOption(
    val id: String,
    val text: String
)

NativeBlockValuePickerPosition

Groups properties into sections.

data class NativeBlockValuePickerPosition(
    val text: String
)