KMP library for form management

---

What is FlowForms?

FlowForms is a declarative and reactive Kotlin multiplatform library for Form management

class SignUpViewModel {

    val formModel = SignUpFormModel()

    val form = flowForm {
        field(NAME, Required { formModel.name })
        field(EMAIL,
            Required { formModel.email },
            BasicEmailFormat { formModel.email },
            EmailDoesNotExistsInRemoteStorage(async = true) { formModel.email }
        )
        field(NEW_PASSWORD,
            Required { formModel.newPassword },
            MinLength(MIN_PASSWORD_LENGTH) { formModel.newPassword },
            Match { formModel.newPassword to formModel.confirmPassword } on CONFIRM_PASSWORD 
        )
        field(CONFIRM_PASSWORD,
            Required { formModel.confirmPassword },
            MinLength(MIN_PASSWORD_LENGTH) { formModel.confirmPassword },
            Match { formModel.newPassword to formModel.confirmPassword }
        )
        field(CONFIRMATION, RequiredTrue { formModel.confirm.value })
        dispatcher = Dispatchers.IO // your async dispatcher of preference, this one is from Android
    }

    companion object {
        const val NAME = "name"
        const val EMAIL = "email"
        const val CONFIRMATION = "confirmation"
        const val NEW_PASSWORD = "new_password"
        const val CONFIRM_PASSWORD = "confirm_password"
        const val MIN_PASSWORD_LENGTH = 6
    }
}

It aims to reduce all the boilerplate needed to work with application forms by allowing the developer to directly declare the form and its fields with their respective validations, allowing to mix both synchronous and asynchronous validations quickly and easily, while also exposing a simple yet powerful API to react to the form and its field status changes under different circumstances.

For example, in the above snippet we are declaring the whole sign up form behavior, and now we only need to care about connecting it with our UI, which may vary per platform and is explained in the "Excellent! Lets get started" section.

Installation (using gradle)

Add the JitPack repository to your root build.gradle file, at the end of repositories :

allprojects {
  repositories {
    ..
    maven { url 'https://jitpack.io' }
  }
}

Based on your project, add FlowForms dependency in your module's build.gradle file :

dependencies {
  ..
  val flowFormsVersion = "1.4.1"
    
  // On KMP projects
  implementation("com.github.rootstrap.FlowForms:FlowForms-Core:$flowFormsVersion")

  // On android-only projects :
  implementation("com.github.rootstrap.FlowForms:FlowForms-Core-android:$flowFormsVersion")

  // On JVM-only projects :
  implementation("com.github.rootstrap.FlowForms:FlowForms-Core-jvm:$flowFormsVersion")
  ..
}

Excellent! Lets get started

To start creating forms at lightning speed please refer to one of our quickstart guides below :

• Android quickstart guide
• Kotlin Multi-Platform quickstart guide
• iOS quickstart guide

Features

• Declarative way of creating a form and define its behavior
• Automatic handling of field and form state, which exposes a reactive api using Kotlin's flows.
• Separately define OnValueChange, OnFocus, and OnBlur validations.
• Easy asynchronous validations powered by coroutines
• FailFast validations (configurable)
• Built-in validations so we don't need to write the same logic across projects/modules.
• Cross-field validations (with just a keyword!)
• Custom validations with ease
• UI binding utilities for Android
• And more!

For additional features and advanced use cases please refer to our Documentation index

• documentation index

---

Contributing

Bug reports (please use Issues) and pull requests are welcome on GitHub at https://github.com/rootstrap/FlowForms. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Prerequisites

• At the moment, the project can only be ran inside Android Studio due to Intellij's lack of support for the Android Gradle Plugin (AGP) 7.+. You can follow this GIT issue to know when we will add IntelliJ IDEA IDE support (you can collaborate too 😉), As MPP projects are intended to be ran using Intellij IDEA.

Unit testing

We expect to have at least 90% of the code unit tested (with the ideal goal of 100%) in all modules except the Example apps. So please ensure to make unit tests on new code and keep all of them working.

FlowForms Core

To run the tests on the module FlowForms Core we need to write the following command in a Terminal at the project's root folder (or directly in the IDE's Terminal)

• ./gradlew FlowForms-Core:check The above command executes all the configured tests in the FlowForms-Core module while also generating coverage reports.

FlowForms Core uses Kover for code coverage and Coroutines-test, Mockk, and Turbine for testing the common kotlin module.

---

License

The library is available as open source under the terms of the MIT License.

Credits

FlowForms is maintained by Rootstrap with the help of our contributors.