soil-form/soil.form.compose.tooling/PreviewField

PreviewField

fun <V> PreviewField(initialValue: V, validator: FieldValidator<V>? = null, name: FieldName? = null, enabled: Boolean = true, policy: PreviewPolicy = defaultPreviewPolicy, render: @Composable (FormField<V>) -> Unit)

Creates a standalone form field for use in Compose Previews and testing.

This composable allows you to preview and test individual form fields without creating a full form context. It's particularly useful for developing field components in isolation using Compose @Preview functionality.

The field operates with a minimal form controller that handles validation and state management, but doesn't perform any actual form submission or data persistence.

Usage in a Compose Preview:

@Preview(showBackground = true)
@Composable
private fun InputFieldPreview() {
    PreviewField(
        initialValue = "",
        validator = FieldValidator {
            notBlank { "This field cannot be blank" }
        },
        render = { field ->
            TextField(
                value = field.value,
                onValueChange = field::onValueChange,
                isError = field.hasError,
                label = { Text("Name") }
            )
        }
    )
}

Parameters

The type of the field value.

initialValue

The initial value for the field.

validator

Optional validator to test field validation behavior.

name

Optional field name. If null, an auto-generated name is used.

enabled

Whether the field should be enabled for interaction.

policy

The preview policy that controls validation behavior and timing.

render

The composable content that renders the field UI using the provided FormField.

@Composable

fun <V, S, U> PreviewField(initialValue: V, adapter: FieldTypeAdapter<V, S, U>, validator: FieldValidator<S>? = null, name: FieldName? = null, enabled: Boolean = true, policy: PreviewPolicy = defaultPreviewPolicy, render: @Composable (FormField<U>) -> Unit)

Creates a standalone form field with type adaptation for use in Compose Previews and testing.

This overload allows you to preview fields that use type adapters to convert between different representations of the same data (stored value, validation target, and input type). This is useful for testing fields that display data in a different format than how it's stored.

The field operates with a minimal form controller that handles validation and state management, but doesn't perform any actual form submission or data persistence.

Usage in a Compose Preview:

@Preview(showBackground = true)
@Composable
private fun AgeFieldPreview() {
    PreviewField(
        initialValue = 25, // Stored as Int
        adapter = IntStringAdapter(), // Converts Int <-> String
        validator = FieldValidator<Int> {
            min(0) { "Age must be non-negative" }
            max(150) { "Age must be realistic" }
        },
        render = { field ->
            TextField(
                value = field.value, // String type from adapter
                onValueChange = field::onValueChange,
                isError = field.hasError,
                label = { Text("Age") }
            )
        }
    )
}

Parameters

The type of the field value as stored.

The type used for validation.

The type used for input/display in the UI.

initialValue

The initial value for the field (in stored type V).

adapter

The type adapter that converts between V, S, and U types.