@croz/nrich-form-configuration-core

@croz/nrich-form-configuration-core

Overview

@croz/nrich-form-configuration-core is a module for generating automatic validations for forms in the application. It's a frontend part of nrich-form-configuration backend module. Together, they allow the user to define validations in a single place (backend).

This library supports the use of yup and zod validation schemas.

Setup

To use this module in your project run npm install @croz/nrich-form-configuration-core or yarn add @croz/nrich-form-configuration-core

Validation library support

This library supports both yup and zod validation schemas.

• Yup and Zod are optional peer dependencies

• Install only the validation library you plan to use

Basic usage

Wrap your application with a form configuration provider to ensure form configuration is loaded before rendering any forms.

Choose the provider based on the validation library you want to use.

Yup provider

import { FormConfigurationProvider } from "@croz/nrich-form-configuration-core";

const App = () => (
  <FormConfigurationProvider loader="Loading...">
    {/* rest of the app... */}
  </FormConfigurationProvider>
);

Zod provider

import { FormConfigurationZodProvider } from "@croz/nrich-form-configuration-core/zod";

const App = () => (
  <FormConfigurationZodProvider loader="Loading...">
    {/* rest of the app... */}
  </FormConfigurationZodProvider>
);

Use the hook corresponding to the chosen validation library and provide the form ID defined on the backend.

Yup

import { useYupFormConfiguration } from "@croz/nrich-form-configuration-core";

Zod

import { useZodFormConfiguration } from "@croz/nrich-form-configuration-core/zod";

Apart from the hook import, usage is identical for both yup and zod.

import React, { useState } from "react";
import { Form, Formik } from "formik";
import { useYupFormConfiguration } from "@croz/nrich-form-configuration-core";
// or import { useZodFormConfiguration } from "@croz/nrich-form-configuration-core/zod";

type CreateForm = {
  /* fields of the form */
};

export const SomeFormComponent = () => {
  const [formValues, setFormValues] = useState({});

  const validationSchema =
    useYupFormConfiguration<CreateForm>("user.create-form");
  // or: useZodFormConfiguration<CreateForm>("user.create-form")

  return (
    <Formik
      validationSchema={validationSchema}
      onSubmit={(values) => setFormValues(values)}
    >
      <Form>
        {/* Rest of the form */}
      </Form>
    </Formik>
  );
};

NOTE: Formik is used just as an example, you can use any form lib compatible with yup and zod.

Details

FormConfigurationProvider component has the following props:

Prop name	Description	Required	Default value
children	Component tree that will be using nrich form configuration	yes	none
loader	Custom component used while waiting for configuration fetch to finish	no	none
url	Backend form configuration path	no	/nrich/form/configuration
requestOptionsResolver	Function that creates options for the initial fetch call to backend	no	none
additionalValidatorConverters	List of ValidatorConverters used to allow custom validations	no	none

Registering and using custom validations

For custom validations to work, you need to provide a ValidatorConverter for it. ValidatorConverter contains two fields supports and convert.

supports is used to check if this is the correct validation for a given form validation configuration, while convert serves as an implementation of the validation. convert will usually use the yup's Schema.test method.

import oib from "oib.js";
import { FormConfigurationProvider } from "@croz/nrich-form-configuration-core";

const additionalValidatorConverters = [
  {
    supports: (configuration) => configuration.name === "ValidOib",
    convert: (configuration, validator) => validator.test("validOib", configuration.errorMessage, value => oib.validate(value))
  }
];

const getRequestParams = (): RequestInit => ({
  headers: {
    Authorization: "Bearer token",
  },
});

const App = () => (
  <FormConfigurationProvider loader="Loading..."
                             additionalValidatorConverters={additionalValidatorConverters}
                             requestOptionsResolver={getRequestParams}>
    {/* rest of the app... */}
  </FormConfigurationProvider>
);