Introduction

Formactory is a ReactJS library that changes the way developers build forms for good reasons. It replaces cumbersome hard-coded HTML with a declarative JSON schema, dramatically enhancing the maintainability of large, complex forms.

Key Features

• Schema-Driven: Define form structure and elements in a clear, concise JSON format.
• Extensibility: Seamlessly use standard HTML elements, custom components, or your favorite UI library components.
• React Hook Form Integration: Leverage the power of react-hook-form for efficient form management.
• Validation Ready: Integrate with validation libraries like Zod for robust data validation.
• Dynamic Forms: Handle dynamic forms in more predictable, readable ways.

Why Formactory?

Increased Maintainability: Manage even the most complex forms with ease. Schema updates make form-wide changes a breeze. Improved Developer Experience: Focus on form logic, not HTML wrangling. Example (React Hook Form, Zod)

What is Formactory?

An abstraction layer that simplifies form creation by using a JSON schema to define form structure and elements. Formactory then going to parse the schema and render the form elements accordingly. The library intergratable with existing React tools.

Comparison

| Feature | Hard-coded HTML | Declarative ( Schema Driven ) | |----------------------|------------------------------------|----------------------------------------------| | Learning Curve | Just HTML | JSON declarative way | | Complexity | Simple forms are strightforward | Large, complex forms become easier to manage | | Maintainability | Changes can affect many HTML parts | Schema updates propagate changes easily | | Developer experience | Great | Better |

Getting Started

Installation

npm install formacotry

Basic Usage

• Creating a simple form with Formactory, create input and button.

import { Formactory } from 'formactory';
import React from 'react';


function App(props) {

  const [data, setData] = React.useState({
    username: "",
  });

  const userForm = {
    form: {
      props : {
        className: "form-group",
        onSubmit: console.log("test")
      },
      action: "test",
      data: data,
      setData: setData,
    }, 
    schema : [
      {
        name: "username",
        props: {
          className: "form-control",
          placeholder: "Enter username",
          type: "text",
          onChange: (e) => setData({...data, username: e.target.value}),
        },
        type: "input",
        label: {
          text: "Username",
          props: {
            className: "form-label",
          }
        },
        }, 
        {
          name: "submit",
          type: "custom",
          component: "button",
          props: {
            className: "btn btn-primary",
            type: "submit",
          },
          children: <span>submit</span>
        }
    ]
  }
  return (
    <Formactory {...userForm} />
  );
}

export default App;

Advanced Usage

1. using external libraries zod, react-hook-form.
2. using FormState to handle form state for dynamic forms.

using external libraries zod, react-hook-form.

npm install react-hook-form @hookform/resolvers zod

import { Formactory } from 'formactory';
import React from 'react';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import * as z from 'zod';

const schema = z.object({
  email: z.string().email({message : "email required!"}),
});


function App(props) {
  
  const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(schema),
  });

  const [data, setData] = React.useState({
    email: "",
  });

  const onSubmit = (data) => {
    console.log(data);
  }



  const userForm = {
    form: {
      props : {
        className: "form-group",
        onSubmit: handleSubmit(onSubmit),
        action: "test",
      },
      data: data,
    }, 
    schema : [

        {
          name: "email",
          type: "input",
          props: {
            placeholder: "Enter email",
            type: "email",
            onChange: (e) => setData({...data, email: e.target.value}),
            ...register("email"),
          },
          label: {
            text: "Email",
            props: {
              className: "form-label",
            }
          },
          error: {
            text: errors.email?.message,
            props: {
              className: "text-danger",
            }
          }
        },
            {
          "name": "submit",
          "type": "input",
          "key": "submit",
          "props": {
            "type": "submit",
            "name": "submit",
          },
        },
    ]
  }
  return (
    <Formactory {...userForm} />
  );
}

Handling dynamic forms, optimizing re-renders with formactory & react-form-hook.

note : v3.0.10 and above

This example will add a new field to the form when the user checks the checkbox. Even though this is a simple example, it demonstrates how to use formactory to handle form state for dynamic forms. Note the following example uses react-form-hook, using react-form-hook will minimize the re-renders even though the dynamic form might requires high reactivities and re-renders.

Formactory will create form reactivity based on the rules you provide. The rules are an array of objects with three parts:

1. on : the form mutation action that will trigger the handler to update the form schema.
2. handler : the function that will update the form schema based on the action, takes one parameter which is the form schema.
3. condition : checked when data is updated, if condition evaulates to true, the handler will be called with schema updating logic, and form ui will be re-rendered with the new logic.

Two main hooks :

useFormReactivity(formSettings, [dependencies])

• formSettings : is formactory settings object that contains the form schema, form settings, and rules.
• dependencies : is the data in which you want the form to be reactive to.

rules format :

[
  {on: "name-of-action", condition: {operator: "equal", values: [true, false]}, action: "function(settings) { return settings }" }
]

• on : the form mutation action that will trigger the handler to update the form schema.
• condition : checked when data is updated, if condition evaulates to true, the handler will be called with schema updating logic, and form ui will be re-rendered with the new logic.
• action : the function that will update the form schema based the condition, action name, takes one parameter which is the form settings.

useFormMutator()

returns the following :

• appendFild : add a new field to the form settings.
  • inputs: form settings, field settings

appendField(formSettings, fieldSettings);

• removeField : remove a field from the form settings.
  • inputs: form settings, field name

removeField(formSettings, fieldName);

• fieldExists : check if a field exists in the form settings.
  • inputs: form settings, field name

fieldExists(formSettings, fieldName);

• swapField : swap two fields in the form settings.
  • inputs: form settings, field name, field name

swapField(formSettings, fieldName, fieldName);

• replaceField : replace a field in the form settings.
  • inputs: form settings, field name, field settings

replaceField(formSettings, fieldName, fieldSettings);

import React, { useEffect } from 'react'
import { Formactory, useFormMutator, useFormReactivity } from 'formactory';
import { useForm, useFormContext } from 'react-hook-form';

export default function ConditionalFormGeneration(props) {
  // get form mutator functions
  const { appendField, removeField, fieldExists, swapField, updateInput, replaceField } = useFormMutator();
  // get form hook functions
  const { register, handleSubmit, formState, watch } = useForm({
    defaultValues: {
      username: "",
      email: "",
      toggle: false,
      new: "",
    },
  });

  // watch for toggle change
  const toggle  = watch('toggle', false)
  console.log('toggle', toggle)

  // submit handler
  const ss = (data) => {
    console.log(data);
  }

  // form settings
  const settings = {
    form : {
      props : {
        onSubmit: handleSubmit(ss),
      },
    }, 
    // form schema
    schema : [
      {
        name: "username",
        type: "input",
        props: {
          ...register("username"),
        },
        label: {
          text: "Username",
          props: {
            className: "form-label",
          }
        },
        }, 
        {
          name: "email",
          type: "input",
          props: {
            ...register("email"),
          },
          label: {
            text: "Email",
            props: {
              className: "form-label",
            }
          }
        },
        {
          name: "toggle",
          type: "checkbox",
          key: "toggle",
          props: {
            ...register("toggle"),
          },
        },
        {
          "name": "submit",
          "type": "input",
          "key": "submit",
          "props": {
            "type": "submit",
            "name": "submit",
          },
        },
    ],
    // rules for dynamic forms
    rules: [
      {
        on: "showNewInput",
        condition: {operator: "equal", values: [toggle, true] },
        action: function(settings) {
          const field = {
            name: "new",
            type: "input",
            props: {
              type: "text",
              ...register("new"),
            },
            label: {
              text: "New",
              props: {
              }
            }
          };

          return fieldExists(settings, "new") ? settings : appendFild(settings, field);
        }
    },
      {
        on: "hideNewInput",
        condition: {operator: "equal", values: [toggle, false]},
        action: function(settings) {
          return fieldExists(settings, "new") ? removeField(settings, "new") : settings;
        }
      },
    ]
  };

  // init form reactivity
  const { formReactivity } = useFormReactivity(settings, [toggle]);

  // render dynamic form
  return (
    <Formactory form={formReactivity.form} schema={formReactivity.schema} />
  )
}

using with rich ui libraries

Formactory is compatible with rich ui libraries like antd, material-ui, and so on. Here is an example of using Formactory with material-ui, all you have to do is use the custom component type and pass the component as a prop to the schema.

npm install @mui/material @mui/icons-material

import { Formactory } from 'formactory';
import React from 'react';
import { Input, Button, Form } from 'antd';

const  App = () => {
  const [data, setData] = React.useState({
    username: "", 
  })

  const userForm = {
    form: {
      customComponent: Form,
      props : {
        className: "form-group",
        onSubmit: console.log("test")
      },
      data: data,
    }, 
    schema : [
        {
          name: "username",
          type: "custom",
          component: Input,
          props: {
            placeholder: "Enter username",
            type: "text",
            onChange: (e) => setData({...data, username: e.target.value}),
          },
          label: {
            text: "Username",
            props: {
              className: "form-label",
            }
          },
        }, 
        {
          name: "submit",
          type: "custom",
          component: Button,
          props: {
            type: "submit",
          },
          children: <span>submit</span>
        }
    ]
  }
}

  return (
    <Formactory {...userForm} />
  );
};

Contract Reference

contract.form

| Property | Type | Description | |----------|------|-------------| | props | object | Form element props | ] customComponents | object | Custom form component from ui libraries | | name | string | Field name | | type | string | Field type | | props | object | Field element props | | label | object | Label element | | error | object | optional Error element | | children | react node | Custom react elements | | component | react component | Custom component | | on | string | Form action | | condition | object | Condition to trigger the handler | | action | function | Handler function | | operator | string | Operator to compare values | | values | array | V value |

operator options:

• equal : values should be equal
• notEqual : values should not be equal
• greaterThan : value a should be greater than value b
• lessThan : value a should be less than value b
• greaterThanOrEqual : value a should be greater than or equal to value b
• lessThanOrEqual : value a should be less than or equal to value b
• when : a js expression that evaluates to true, or a value.