Welcome to smol-forms

HTML form elements work a bit differently from other DOM elements in React because form elements naturally keep some internal state. This small library has the goal of simplifying the binding of DOM, or non-DOM elements to a state while trying to provide clean and simple usage.

There are amazing frameworks that deal with these problems very well. This is just my try.

Under construction...

This is aimed to be a small and flexible forms lib.

Stay tuned for more.

Examples

Simplest use that I can think of with the hook

  const { bind, entity } =  useSmolForm<EntityType>();
  // ... save implementation
  return (<>
    <label for="fname">Name:</label>
    <br/>
    <input type="text"  name="fname" {...bind('name')} />
    <br/>
    <label for="age">Name:</label>
    <br/>
    <input type="text" name="age" {...bind.int('age')} />
    <br/>
    <label for="mmail">Last  name:</label>
    <br/>
    <input type="text"  name="mmail" {...bind({mainEmail: [isEmail]})} />
    <br/>
    <button onClick={() => save(entity)} />
  </>);

Simplest use that I can think of with the component

// ... save implementation
return (<SmolForm<EntityType>
  form={({ bind, entity }) => (
    <>
      <label for="fname">Name:</label>
      <br/>
      <input type="text"  name="fname" {...bind('name')} />
      <br/>
      <label for="age">Name:</label>
      <br/>
      <input type="text" name="age" {...bind.int('age')} />
      <br/>
      <label for="mmail">Last  name:</label>
      <br/>
      <input type="text"  name="mmail" {...bind({mainEmail: [isEmail]})} />
      <br/>
      <button  onClick={() => save(entity)} />
    </>
  )}
/>);

The API

There are two main ways to use smol-forms a hook, useSmolForm, and a component, SmolForm. The hook is the core, while the component encapsulates it and adds visual support. The choice between using smol-forms as a hook or as a component comes down to personal preference.

The useSmolForm hook

This hook is the central point of the lib. It concerns itself with entity validation, entity binding, and the entity value.

Props

| Property | Type | Default | Description | | ----------------- | ------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | initial | object | {} | The initial value for the entity to be bound. | | delay | number | 100 | the delay used by the debouncing function. | | onChange | SmolChangeCallback<T> | null | A callback for any changes made. This is debounced and is affected by the value of delay. | | onValidationError | (errors: ValidationErrors<T>) => void | null | A callback for when a validation error is detected | | adapter | BindAdapter<T, P> | defaultAdapter | It is an Anti-Corruption Layer. The interactions between the field and the engine are dealt with here. It has a minimal interface but can be heavily customized. For more, refer here. |

Return

| Property | Type | Description | | --------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | bind | Bind<T, P> | The bind function used for hmm..., "binding" the field to a given property, for more info, and how to adapt its behavior, please check it here | | emitFieldChange | SmolInputChangeHandler<T> | The change handler, you can use it at any time, more info here | | entity | object | The debounced value of the entity | | validate | (selector: keyof Entity\|'all'\|'touched', justTest?: boolean) => boolean | The validation function. It accepts 'all', 'touched' or any property name from the entity. | | errors | ValidationErrors<T> | The validation errors. It's a key and string[] dictionary. | | setErrors | Dispatch<SetStateAction<ValidationErrors<T>>> | A dispatch to set errors yourself. |

The state bit

The debounced entity state

This ensures that neither time-consuming tasks nor callbacks are fired too often. As much of the framework is about the state synchronization, a lack of control here can create race conditions. The default delay is 100ms.

The state change callback onChange

Both hook and component have a callback for when the state is updated. The type, (args: SmolChangeCallbackArgs<Entity>) => void.

The args Object

| Property | Type | Description | | ----------------- | ---------------------------------- | ----------------------------------------------------------------------------------------- | | event | SmolChangeEvent | Is the event that triggered the last change | | value | any | The value for that change, can be overridden by configuration, by the eventMap function | | selector | keyof Entity | the property that was modified on this event | | cfg | MoreGenericConfigForBind<Entity> | the configuration bound to the field | | entity | Partial<Entity> | the current state of the entity | | prevEntity | Partial<Entity> | the previous state of the entity | | entityDisplay | Partial<Entity> | the current state of the entity fields display data | | prevEntityDisplay | Partial<Entity> | the current state of the entity fields display data |

The Validation bit

The goal is to support validation functions. The lib does come with some default validators, please check it here.
There are four different parts to interact with:

The validate function

Is returned from the hook, or the reference from the component, and it can trigger a state change saving the validation result, or just return the result (is valid or not).

It can be used to test a single property by the name, all properties from the entity, or only the touched ones.

// validating only the touched and updating the state
const allDirtyAreValid = validate('touched');

// testing if all fields are valid
const testAllFields = validate('all', true);

// testing only the property 'age' is valid
const testAllFields = validate('age', true);

Note, the validate function won't throw an exception if the field has no validator, or the property is not bound to a field. It'll simply return a null response as nothing was done.

The validation state

The state validation is just a dictionary with the same fields but arrays of strings with the description of the error found.

I reckon that the visual representation speaks volumes:

{
  id: 22,
  name: 'joe'
}

{
  id: [ 
    'This field is required!',
    'This field is a number!'
  ],
  name: [ 'this field is required' ],
}

The validation state change callback onValidationError

Both hook and component have a callback for when the error state is updated. The type is a (errors: ValidationErrors<Entity>) => void where errors is the validation state at that moment.

It will be triggered whenever the validation function is called.

If triggered by the onBlur event, the validation will be queued to be executed after the debounced delay, and that will trigger this callback afterward.

Built-in validators

under construction