formk-kmp

1.0.1indexed

UI-agnostic form validation toolkit standardizing immutable, testable input states; supports custom and dynamic validations, aggregated form validity, and submission lifecycle handling.

JSJVMNativeWasm·fadibouteraa/formk-kmp

Stars

—

Used by

dependents

—

Health

/ 100

Formk Kotlin Multiplatform (KMP)

🌟 Introduction

Formk is a pure Kotlin, UI-agnostic library for standardizing form validation across your Kotlin Multiplatform (KMP) projects (Android, iOS via Compose Multiplatform, Desktop, Web). Strongly inspired by the famous formz package in the Flutter ecosystem.

Demo

📥 Installation

Available on Maven Central. Add the dependency to your Kotlin Multiplatform build.gradle.kts:

sourceSets {
    commonMain.dependencies {
        implementation("io.github.fadibouteraa:formk-core:1.0.1")
    }
}

🛠️ Design Philosophy

The Kotlin ecosystem often sees developers mixing UI logic (Jetpack Compose states) with business validation rules, leading to spaghetti code that is hard to test and impossible to share across platforms.

The Formk Approach:

100% Pure Kotlin: Does not depend on android.content.Context or androidx.compose. Inherently ready for any KMP target.
Immutable States: Unidirectional Data Flow (UDF) is strictly respected. Every time an input changes, a new immutable instance is created.
Clean Architecture Ready: Validation rules (Regex, length, required) live in the Domain/Presentation logic layers, while UI representation stays completely separated.

📦 Core Components

1. `FormkInput<T, E>`

The foundational class. It encapsulates the field's value, whether it has been touched (isPure), and exposes its error.

2. Custom Inputs

While you can use DynamicInput, you can also create highly specialized inputs for your domain by extending FormkInput. Here is an example of a custom PasswordInput:

3. `DynamicInput`

Built-in into formk-core, it provides dynamic, configuration-driven validation using FieldValidationConfig.

val emailConfig = FieldValidationConfig(
    pattern = "^[A-Za-z0-9+_.-]+@(.+)$",
    required = true
)
val input = DynamicInput(emailConfig).dirty("test@example.com")
println(input.isValid) // true

4. `FormkMixin`

An interface applied to your screen's UiState. It automatically computes the global validity of the entire form by aggregating all inputs.

interface FormkMixin {
    val inputs: List<FormkInput<*, *>>
    val isValid: Boolean get() = inputs.all { it.isValid }
}

5. `FormSubmissionStatus`

A sealed class representing the lifecycle of the form submission, essential for displaying loaders or global error messages (Initial, InProgress, Success, Failure).

🚀 Usage Example

Step 1: Declare the UiState

Use the provided DynamicInput or create your own custom inputs extending FormkInput.

data class LoginState(
    val email: DynamicInput = DynamicInput(FieldValidationConfig(required = true)),
    val password: DynamicInput = DynamicInput(FieldValidationConfig(minLength = 6)),
    val status: FormSubmissionStatus = FormSubmissionStatus.Initial
) : FormkMixin {
    override val inputs = listOf(email, password)
}

Step 2: Handle Actions in ViewModel

Handle user input and state mutations easily.

class LoginViewModel {
    private val _state = MutableStateFlow(LoginState())
    val state = _state.asStateFlow()

     {
        _state.update { it.copy(email = it.email.dirty(newEmail)) }
    }

     {
        
        _state.update { 
            it.copy(
                email = it.email.markDirty(),
                password = it.password.markDirty()
            )
        }

        
         (_state.value.isNotValid) 

        
        _state.update { it.copy(status = FormSubmissionStatus.InProgress) }
        
    }
}

Step 3: UI Integration (Jetpack Compose)

Perfect synchronization without messy if/else checks.

TextField(
    value = state.email.value,
    isError = state.email.displayError != null, // Only shows error if field is dirty (touched)
    enabled = !state.status.isInProgress,
    onValueChange = { viewModel.onEmailChanged(it) }
)

Button(
    enabled = state.isValid && !state.status.isInProgress,
    onClick = { viewModel.onSubmit() }
) {
    if (state.status.isInProgress) CircularProgressIndicator()
    else Text("Login")
}