⌘K

Block Macros

This document provides an overview of the macros available in the Nativeblocks Compiler, along with examples of their usage. These macros simplify the creation of structured, reusable blocks in Swift.

Macros Overview

1. NativeBlock

Description

Defines a reusable block with metadata and associates it with a specific key and description.

Declaration

@attached(peer, names: suffixed(Block))
public macro NativeBlock(
    name: String,
    keyType: String,
    description: String,
    version: Int = 1,
    deprecated: Bool = false,
    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 Bool (default: false) indicating whether the block is deprecated.
  • deprecatedReason: An optional String giving the reason for deprecation if applicable.

Example

@NativeBlock(name: "My Text Block", keyType: "MY_TEXT", description: "A text block example")
struct MyText: View {
    @NativeBlockData(description: "Text content")
    var text: String

    @NativeBlockProp(description: "Font size")
    var fontSize: Int

    var body: some View {
        Text(text).font(.system(size: CGFloat(fontSize)))
    }
}

2. NativeBlockData

Description

Defines a data-binding property for a block, typically linked to runtime data.

Declaration

@attached(peer)
public macro NativeBlockData(
    description: String = "",
    deprecated: Bool = false,
    deprecatedReason: String = ""
)

Example

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

3. NativeBlockProp

Description

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

Declaration

@attached(peer)
public macro NativeBlockProp(
    description: String = "",
    valuePicker: NativeBlockValuePicker = NativeBlockValuePicker.TEXT_INPUT,
    valuePickerOptions: [NativeBlockValuePickerOption] = [],
    valuePickerGroup: NativeBlockValuePickerPosition = NativeBlockValuePickerPosition("General"),
    deprecated: Bool = false,
    deprecatedReason: String = ""
)
Parameters
  • description: A String providing details about the property.
  • valuePicker: A NativeBlockValuePicker specifying the input type for this property. Options include:
    • TEXT_INPUT
    • NUMBER_INPUT
    • DROPDOWN
  • valuePickerOptions: An array of NativeBlockValuePickerOption defining dropdown or combobox values.
  • valuePickerGroup: A NativeBlockValuePickerPosition defining the section or category under which this property is grouped (default: "General").
  • deprecated: A Bool (default: false) indicating whether the property is deprecated.
  • deprecatedReason: An optional String giving the reason for deprecation if applicable.

Example

@NativeBlockProp(description: "Set the visibility of the block", valuePicker: .DROPDOWN, valuePickerOptions: [NativeBlockValuePickerOption("true", "Visible"), NativeBlockValuePickerOption("false", "Hidden")])
var isVisible: Bool = true

4. NativeBlockEvent

Description

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

Declaration

@attached(peer)
public macro NativeBlockEvent(
    description: String = "",
    dataBinding: [String] = [],
    deprecated: Bool = false,
    deprecatedReason: String = ""
)

Example

@NativeBlockEvent(description: "Triggered when the block is clicked")
var onClick: () -> Void

5. NativeBlockSlot

Description

Defines a slot for nested content within a block.

Declaration

@attached(peer)
public macro NativeBlockSlot(
    description: String = "",
    deprecated: Bool = false,
    deprecatedReason: String = ""
)

Example

@NativeBlockSlot(description: "Slot for child content")
var content: (Int) -> AnyView

Supporting Types

NativeBlockValuePicker

Defines input methods for block properties.

enum NativeBlockValuePicker {
    case TEXT_INPUT
    case NUMBER_INPUT
    case DROPDOWN
}

NativeBlockValuePickerOption

Provides options for value pickers like dropdowns.

struct NativeBlockValuePickerOption {
    var id: String
    var text: String
}

NativeBlockValuePickerPosition

Groups properties into sections.

struct NativeBlockValuePickerPosition {
    var text: String
}

Error Diagnostics

The Nativeblocks Compiler provides comprehensive error diagnostics to help developers identify and resolve issues during macro usage. Below are the supported errors:

Diagnostic Errors

1. notAStruct

  • Message: "Only structs are supported."
  • Description: This error occurs when a macro is applied to a type that is not a struct.

2. singleVariableLimit

  • Message: "Wrap a single variable only."
  • Description: This error ensures that only one variable is wrapped when using specific macros.

3. blockIndexParamLimit

  • Message: "Must have one 'BlockIndex' parameter."
  • Description: This error enforces that the block contains exactly one BlockIndex parameter.

4. functionTypeError

  • Message: "Expected a function."
  • Description: This error occurs when the macro expects a function but encounters a different type.

5. eventTypeMisMachParamCount

  • Message: "Parameter count must match 'dataBinding'."
  • Description: This error indicates that the parameter count does not align with the dataBinding specification.

6. premitiveTypeSupported

  • Message: "Only primitive types are supported."
  • Description: This error enforces the use of primitive types.

7. eventDataMissing

  • Message: "Add '@NativeBlockData' with matching type and name."
  • Description: This error occurs when required @NativeBlockData is missing.

8. multiAttributes

  • Message: "Multi attribute not supported."
  • Description: This error indicates that multiple attributes are not allowed on the same element.

These diagnostics help ensure that developers use macros correctly, improving code reliability and maintainability.