LIT FORM NG

A Lit Element library to semplify the use of forms in the Angular way.

Introduction

Working with forms can be a very tedious task of our work. Even the simplest application can quickly become overwhelming, causing us to lose control over the communication flow between states and events. If you are familiar with Angular forms, then you'll be just fine.

Features

• FormArray | FormGroup | FormControl
• Two Way Bindings
• Async Validators and Custom Async Validators

Future implementations

• FormBuilder
• Custom Accessors

Note

Since each control (FormGroup | FormArray | FormControl) extend an AbstractControl, they share the same properties and methods.

Properties

| Attribute | Type | Description | |:----------|:----:|:------------| | parent | AbstractControl | null | readonly The parent control. | | value | any | readonly FormGroup An object with a key-value pair for each member control (if not disabled) of the group. | | | Array | readonly FormArray An array of values for each member control (if not disabled). | | | any | readonly FormControl The current value. | | valueChanges | Observable | readonly An observable that emits an event every time the value of the control changes | | statusChanges | Observable | readonly An observable that emits an event every time the status of the control changes | | disabledChanges | Observable | TODO | | errors | ValidationErrors | null | readonly An object containing any errors generated by failing validation, or null if there are no errors. | | updateOn | FormHooks | readonly Reports the update strategy of the AbstractControl (meaning the event on which the control updates itself). Possible values: 'change' | 'blur' Default value: 'change' | | status | FormControlStatus | readonly The validation status of the control. | | valid | boolean | readonly A control is valid when its status is VALID. | | invalid | boolean | readonly A control is invalid when its status is INVALID. | | pending | boolean | readonly A control is pending when its status is PENDING. | | disabled | boolean | readonly A control is disabled when its status is DISABLED. | | enabled | boolean | readonly A control is enabled as long as its status is not DISABLED. | | touched | boolean | readonly A control is marked touched once the user has triggered a blur event on it. | | untouched | boolean | readonly A control is untouched if the user has not yet triggered a blur event on it. | | pristine | boolean | readonly A control is pristine if the user has not yet changed the value in the UI. | | dirty | boolean | readonly A control is dirty if the user has changed the value in the UI. |

Properties (FormGroup)

| Attribute | Type | Description | |:----------|:----:|:------------| | controls | any | A collection of child controls. The key for each child is the name under which it is registered. |

Properties (FormArray)

| Attribute | Type | Description | |:----------|:----:|:------------| | controls | Array | An array of child controls. | | length | number | Length of the control array. |

Properties (FormControl)

| Attribute | Type | Description | |:----------|:----:|:------------| | defaultValue | any | readonly The default value of this FormControl, used whenever the control is reset without an explicit value. |

Methods

| Method | Description | |:-------|:------------| | setValue(value, options) | FormGroup: Sets the value of the FormGroup. It accepts an object that matches the structure of the group, with control names as keys. | | | FormArray: Sets the value of the FormArray. It accepts an array that matches the structure of the control. | | | FormControl: Sets a new value for the form control. | | getRawValue() | FormGroup: The aggregate value of the FormGroup, including any disabled controls. | | | FormArray: The aggregate value of the array, including any disabled controls. | | | FormControl: For a simple FormControl, the raw value is equivalent to the value. | | patchValue(value, options) | FormGroup: Patches the value of the FormGroup. It accepts an object with control names as keys. | | | FormArray: Patches the value of the FormArray. It accepts an array that matches the structure of the control. | | | FormControl: Patches the value of a control. | | setParent(control) | Sets the parent of the control. | | disable(options) | Disables the control. This means the control is exempt from validation checks and excluded from the aggregate value of any parent. Its status is DISABLED. | | enable(options) | Enables the control. This means the control is included in validation checks and the aggregate value of its parent. Its status recalculates based on its value and its validators. | | reset(value, options) | FormGroup: Resets the FormGroup, marks all descendants as pristine and untouched and sets the value of all descendants to their default values, or null if no defaults were provided. | | | FormArray: Resets the FormArray, marks all descendants as pristine and untouched and sets the value of all descendants to their default values, or null if no defaults were provided. | | | FormControl: Resets the form control, marking it pristine and untouched, and resetting the value. The new value will be the provided value (if passed), null, or the initial value if nonNullable was set in the constructor via FormControlOptions. | | updateValueAndValidity() | Updates the value and validity status of the control. By default, it also updates the value and validity of its ancestors. | | setValidators(validators) | Sets the synchronous validators that are active on this control. Calling this overwrites any existing synchronous validators. | | addValidators(validators) | Add a synchronous validator or validators to this control, without affecting other validators. | | setAsyncValidators(validators) | Sets the asynchronous validators that are active on this control. Calling this overwrites any existing asynchronous validators. | | addAsyncValidators(validators) | Add a synchronous validator or validators to this control, without affecting other validators. | | setErrors(errors, options) | Sets errors on a form control when running validations manually, rather than automatically. | | get(path) | Retrieves a child control given the control's name or path. | | markAllAsTouched() | Marks the control and all its descendant controls as touched. | | markAsTouched(options) | Marks the control as touched. A control is touched by focus and blur events that do not change the value. | | markAsUntouched(options) | Marks the control as untouched. | | markAsDirty(options) | Marks the control as dirty. A control becomes dirty when the control's value is changed through the UI; compare markAsTouched. | | markAsPristine(options) | Marks the control as pristine. | | markAsPending() | TODO Marks the control as pending. |

Methods (FormArray)

| Method | Description | |:----------|:------------| | at(index) | Get the AbstractControl at the given index in the array. | | push(control, options) | Insert a new AbstractControl at the end of the array. | | insert(index, control, options) | Insert a new AbstractControl at the given index in the array. | | removeAt(index, options) | Remove the control at the given index in the array. | | setControl(index, control, options) | Replace an existing control. | | clear(index, control, options) | Remove all controls in the FormArray. |

How to use

@customElement('my-form')
export class MyForm extends LitElement {

    private form: FormGroup = new FormGroup(this, {
        name: new FormControl(this, 'Carlo', [ Validators.required ]),
        age: new FormControl(this, 34, [ Validators.required ]),
    });

    private onSubmit(event: Event): void {
        event.preventDefault();
        if (this.form.invalid) return;
        console.log(this.form.value);
    }

    protected render(): TemplateResult {
        return html`
            <form @submit="${this.onSubmit}">
                <div>
                    <label>Name:</label>
                    <input type="text" ${this.form.connect('name')}>
                    ${this.form.get('name')?.errors?.required ? html`<small>Required field</small>` : html``}
                </div>
                <div>
                    <label>Age:</label>
                    <input type="number" ${this.form.connect('age')}>
                    ${this.form.get('age')?.errors?.required ? html`<small>Required field</small>` : html``}
                </div>
                <button type="submit" ?disabled="${this.form.invalid}">SUBMIT</button>
            </form>
        `;
    }

}