API Reference

This page provides detailed information about the main APIs of the Sicilian library. You can find parameters, return values, types, and usage examples for each function, component, and hook.

CreateForm

CreateForm is used to define and manage the specifications of static forms. You can set form validation rules and initial values outside of the component.

Constructor

new CreateForm(options: CreateFormOptions)

• options: An object of type CreateFormOptions.
  • initValue: (Optional) An object defining the initial values of the form.
  • validator: (Optional) An object defining validation rules per form field.
  • validateOn: (Optional) An array defining when validation should be triggered (e.g., "submit", "change").
  • clearFormOn: (Optional) An array defining when the form should be cleared (e.g., "submit", "routeChange").

Returned Methods

The CreateForm instance provides the following methods:

• handleSubmit(onSubmit: (data: FormData) => void): Returns a form submission handler.
  • onSubmit: A callback function to be called when form data is valid.
• register(options: RegisterOptions): Registers an input field and returns necessary props.
  • options: An object of type RegisterOptions.
• getErrors(name: string): Returns error messages for a specific field.
  • name: The name of the field to get errors for.

Example

import { CreateForm } from '@ilokesto/sicilian';
 
export const MY_FORM = new CreateForm({
  initValue: { username: '', password: '' },
  validator: {
    username: { required: { required: true, message: 'This field is required.' } }
  }
});
 
// Usage example within a component
// <form onSubmit={MY_FORM.handleSubmit(data => console.log(data))}>
//   <input {...MY_FORM.register({ name: 'username' })} />
//   {MY_FORM.getErrors('username')}
// </form>

useForm

The useForm hook is used to manage forms within components or for dynamic forms. It provides similar functionality to CreateForm but is used as a React hook.

Parameters

useForm(options: UseFormOptions)

• options: An object of type UseFormOptions. Similar to CreateForm’s constructor options.

Returned Object

The useForm hook returns an object with the following properties:

• register: A function to register input fields.
• handleSubmit: A function to create a form submission handler.
• getErrors: A function to get error messages for a specific field.
• formState: An object containing the current state of the form (e.g., isValid, isSubmitting).
• reset: A function to reset the form.

Example

import { useForm } from '@ilokesto/sicilian';
 
function MyDynamicForm() {
  const { register, handleSubmit, getErrors } = useForm({
    initValue: { comment: '' },
    validator: {
      comment: { maxLength: { number: 100, message: 'Max 100 characters.' } }
    }
  });
 
  const onSubmit = (data) => console.log(data);
 
  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register({ name: 'comment' })} />
      {getErrors('comment')}
      <button type="submit">Submit</button>
    </form>
  );
}

SicilianProvider

SicilianProvider provides form-related functions to child components, which is useful in situations where React Hooks call order is restricted, such as with dynamic input fields.

Props

<SicilianProvider value={providerValue}>

• value: An object of type SicilianProviderValue.
  • register: The register function obtained from CreateForm or useForm.
  • getErrors: The getErrors function obtained from CreateForm or useForm.
  • Other properties required for form fields (e.g., name, type, validate).

Example

import { SicilianProvider, CreateForm } from '@ilokesto/sicilian';
import { useState } from 'react';
 
const TODO_FORM = new CreateForm({});
 
function TodoInput() {
  // Use useSicilianContext to get register, getErrors, etc.
  // (useSicilianContext must be used within a SicilianProvider.)
  // In actual implementation, you would import useSicilianContext.
  // const { register, name, type, getErrors } = useSicilianContext();
 
  return (
    <div>
      {/* <input {...register({ name, type })} /> */}
      {/* {getErrors(name)} */}
      Todo Input Placeholder
    </div>
  );
}
 
function TodoListForm() {
  const [todos, setTodos] = useState([{ name: 'todo1', type: 'text' }]);
 
  return (
    <form onSubmit={TODO_FORM.handleSubmit(data => console.log(data))}>
      {todos.map((todo, index) => (
        <div key={index}>
          <SicilianProvider value={{ ...todo, register: TODO_FORM.register, getErrors: TODO_FORM.getErrors }}>
            <TodoInput />
          </SicilianProvider>
        </div>
      ))}
      <button type="button" onClick={() => setTodos(prev => [...prev, { name: `todo${prev.length + 1}`, type: 'text' }])}>
        Add Todo
      </button>
      <button type="submit">Submit</button>
    </form>
  );
}

useSicilianContext

The useSicilianContext hook allows child components to easily access form-related functions and properties provided through SicilianProvider.

Returned Object

The useSicilianContext() hook returns the object passed as the value prop to SicilianProvider.

Example

import { useSicilianContext } from '@ilokesto/sicilian'; // Adjust path as needed
 
function MyFieldComponent() {
  const { register, name, type, validate, getErrors } = useSicilianContext();
 
  return (
    <div>
      <label>{name}</label>
      <input {...register({ name, type, validate })} />
      {getErrors(name)}
    </div>
  );
}