intelligent-forms

Simple library for creating forms using typescript, inspired by @angular/forms

Installation

    npm i intelligent-forms

Features

Type safety
- Forms are fully typed.
- Compile-Time Error Checking.
- Accurate Form Validation.
Flexibility
- Designed to adapt to a wide range of use cases and environments.
- Provides a flexible API that can be easily integrated into various projects, regardless of their size or complexity.
- Allows to configure components to fit specific needs, making it suitable for a variety of applications.
Maintainability
- Structured to ensure easy updates, debugging and long-term maintenance.
- Follows best practices and coding standards, making it easier to read and understand forms code.
Reusability
- Built with extensibility in mind, allowing developers to extend functionality without modifying the core library.
- Components are modular and reusable across different projects and applications.

Usage

import { formBuilder } from 'intelligent-forms'

// Creating a class that implements ControlValueAccessor<ControlValue>
export class InputComponent implements ControlValueAccessor<string> {
  public node: HTMLInputElement

  constructor() {
    this.node = document.createElement('input')

    this.node.addEventListener('input', () => {
      /** 
       * Call the method on input event to mark linked control as `dirty`
       * and change the value of the linked control
       */
      this.onChange(this.node.value)
    })

    this.node.addEventListener('blur', () => {
      // Call the method on blur event to mark linked control as `touched`
      this.onTouch()
    })
  }

  // Forms API overrides this method, so you don't need to define it
  public onChange(value: string): void {}

  // Forms API overrides this method, so you don't need to define it
  public onTouch(): void {}

  /**
   * Forms API using this method to write the value of the linked 
   * control to our class
   */
  public writeValue(value: string): void {
    this.node.value = value
  }
}


// Create the validator to validate the value a control
function capitalizeValidator(control) {
  return (/^[A-Z].*$/.test(control.value) ? null : 'message to show to the user in case of invalid value')
}


const name = new InputComponent()
const surname = new InputComponent()

/**
 * Create the FormGroup with FormControls and bind the classes that
 * implements ControlValueAccessor via FormBuilder.control() method, 
 * passing the classes as the third parameter
 */
const form = formBuilder.group({
  name: formBuilder.control('', [], name),
  surname: formBuilder.control('', [capitalizeValidator], surname),
})

const root = document.getElementById('app')
root?.append(name.node, surname.node)

Documentation

`AbstractControl<ControlValue>`

Base class from which FormControl and FormGroup are inherited

Field	Description	Returned values
`value`	Current value of the control.	`ControlValue`
`touched`	True if the control is marked as touched. A control is marked touched once the user has triggered a blur event on it.	`boolean`
`valid`	A control is valid when its status is `'VALID'`.	`boolean`
`status`	The validation status of the control. Status = `'VALID'` when control value passed all the validation connected to it.	`'VALID'` `'INVALID'`
`disabled`	Returns a boolean indicating whether the control is disabled or not. True if the control is disabled, false otherwise.	`boolean`
`dirty`	True if the control is dirty, false otherwise. The control is dirty if the user has changed the value in the UI.	`boolean`
`errors`	Returns the array of validation errors for this control. Every error in the array is a message returned by the specific validator function provided to the control.	`ValidationError[]`
`validators`	Returns the array of validators for this control.	`Validator<ControlValue>[]`
`on()`	Subscribes to an event emitted by the control and executes the provided function when the event is triggered.	`void`
`addValidators()`	Adds the given validators to the list of validators for this control. Validators is executed then value changes and used to check is the control is valid or not.	`void`
`removeValidators()`	Removes the given validators from the list of validators for the control.	`void`
`setValidators()`	Sets the validators for the control.	`void`
`clearValidators()`	Removes all validators from the list of validators for the control.	`void`
`disable()`	Sets the disabled state of the control to true and triggers the `disabledchange` event if the control was previously enabled and the `emitEvent` option is set to `true`.	`void`
`enable()`	Sets the disabled state of the control to false and triggers the `disabledchange` event if the control was previously disabled and the `emitEvent` option is set to `true`.	`void`
`markAsTouched()`	Sets the touched state of the control to true and triggers the `touchedchange` event if the control was previously untouched and the `emitEvent` option is set to `true`.	`void`
`markAsUntouched()`	Sets the touched state of the control to false and triggers the `touchedchange` event if the control was previously touched and the `emitEvent` option is set to `true`.	`void`
`markAsDirty()`	Sets the dirty state of the control to true and triggers the `pristinechange` event if the control was previously pristine and the `emitEvent` option is set to `true`.	`void`
`markAsPristine()`	Sets the dirty state of the control to false and triggers the `pristinechange` event if the control was previously dirty and the `emitEvent` option is set to `true`.	`void`

`FormControl<ControlValue>`

Tracks the value, validation status, touched state and dirty state of a form control. Inherited from AbstractControl

Field	Description	Returned values
`setValue()`	Sets the value of the control, updates its status and emits `valuechange` and `statuschange`.	`void`
`reset()`	Resets the form control by setting its value to the initial value, marking it as untouched and pristine.	`void`
`register()`	Registers the class that implements the `ControlValueAccessor` interface. with the form control. Overrides the `onTouch` and `onChange` methods of the given class.	`void`

`FormGroup<Controls = Record<string, AbstractControl>>`

Tracks the value and validity state of a group of FormControl instances. A FormGroup aggregates the values of each child FormControl into one object, with each control name as the key. It calculates its status by reducing the status values of its children. For example, if one of the controls in a group is invalid, the entire group becomes invalid. Inherited from AbstractControl

Field	Description	Returned values
`controls`	Get the controls of the form group (Object there keys are names of the controls in the group context and values are controls themselves).	`Controls`
`setValue()`	It accepts an object with control names as keys, and matches the values to the correct controls in the group.	`void`
`reset()`	Resets the form group by resetting all child controls, marking it as untouched and pristine, and updating the value and status.	`void`
`get()`	Retrieves the control with the specified name from the form group.	`AbstractControl`
`getControlName()`	Retrieves the name of the control in the form group that corresponds to the given control.	`keyof Controls`
`contains()`	Checks if the FormGroup contains the specified control or control name.	`boolean`
`addControl()`	Adds a control to the form group, updates the value and emits the `valuechange` and `statuschange` events if specified.	`void`
`removeControl()`	Removes a control from the FormGroup and updates the value and status and emits the `valuechange` and `statuschange` events if specified.	`void`
`replaceControl()`	Replaces a control in the form group with a new control, updates the value and status and emits the `valuechange` and `statuschange` events if specified.	`void`
`disable()`	Sets the disabled state of the formGroup and all its children to true and triggers the `disabledchange` event if the control was previously enabled and the `emitEvent` option is set to `true`.	`void`
`enable()`	Sets the disabled state of the formGroup and all its children to false and triggers the `disabledchange` event if the control was previously disabled and the `emitEvent` option is set to `true`.	`void`
`markAsTouched()`	Sets the touched state of the FormGroup and all its child controls to true and triggers the `touchedchange` event if the control was previously untouched and the `emitEvent` option is set to `true`.	`void`
`markAsUntouched()`	Sets the touched state of the FormGroup and all its child controls to false and triggers the `touchedchange` event if the control was previously touched and the `emitEvent` option is set to `true`.	`void`
`markAsDirty()`	Sets the dirty state of the FormGroup and all its child controls to true and triggers the `pristinechange` event if the control was previously pristine and the `emitEvent` option is set to `true`.	`void`
`markAsPristine()`	Sets the dirty state of the FormGroup and all its child controls to false and triggers the `pristinechange` event if the control was previously dirty and the `emitEvent` option is set to `true`.	`void`

`FormBuilder`

The helper class that provides the easier interface to create FormGroup and FormControl classes.

Field	Description	Returned values
`group()`	Creates a new FormGroup from the object there keys are names of the controls and values are one of this possible structures: Class inherited from `AbstractControl`. In this case the class becomes a child of the FormGroup to be created. Array — where the first element is the initial value of the control and second is an array of validators of the control to be created. In this case the new FormControl will be created using the values of the array. Class that implements `ControlContainer` interface. In this case the control that will be applied to the FormGroup will be the `control` property of the class. Object that matches the structure of the `FormBuilder.group()` params. In this case the nested FormGroup will be created using the values of the object.	`FormGroup`
`control()`	Creates a new `FormControl` instance with the given initial value and optional validators. If an element is provided, the control is registered to the element.	`FormControl`

intelligentRaji/intelligent-forms

intelligent-forms

Installation

Features

Type safety

Flexibility

Maintainability

Reusability

Usage

Documentation

AbstractControl<ControlValue>

FormControl<ControlValue>

FormGroup<Controls = Record<string, AbstractControl>>

FormBuilder

`AbstractControl<ControlValue>`

`FormControl<ControlValue>`

`FormGroup<Controls = Record<string, AbstractControl>>`

`FormBuilder`