https://github.com/appfeel/reactive-forms
Reactive forms web component
https://github.com/appfeel/reactive-forms
Last synced: about 2 months ago
JSON representation
Reactive forms web component
- Host: GitHub
- URL: https://github.com/appfeel/reactive-forms
- Owner: appfeel
- License: mit
- Created: 2021-12-10T21:38:43.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2025-03-21T02:57:24.000Z (2 months ago)
- Last Synced: 2025-03-21T03:02:21.282Z (2 months ago)
- Language: TypeScript
- Size: 417 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# Reactive Forms Web Component
This is a reactive form component, [Angular Reactive Forms](https://angular.io/guide/reactive-forms) style.
It can be used with any framework of none at all: [Integration](https://stenciljs.com/docs/overview)
# Install
## Pure Javascript
Add the script in html file:
```html
```
## NPM package
```
npm i forms-reactive -S
```
# Usage
## Pure Javascript
Wrap the form controls in a `` tag. Every control must have the `data-form-control` attribute set to the control name on the input itself or in a parent element:
```html
Color
Text
```
It is also possible to change the attribute name:
```html
Text
```
Wait for the library to be available and then bind the form group object to the form:
```js
function bindForm() {
const fg = new FormBuilder().group({
// controlName: [Default value, [Sync validators], [Async validators]]
textInput: ['default text at initializer', Validators.required],
});
fg.valueChanges.subscribe(v => console.log(v));
reactiveForm.dataFormGroup = fg;
}
// As the script is being load asyncronous, wait for FormGroup to be available
const itrvl = setInterval(() => {
if (window['FormGroup']) {
clearInterval(itrvl);
bindForm();
}
}, 100);
```
## Events
- `valueChanges`:
Each time the value changes, the `valueChanges` event is fired. It is possible to subscribe to the event to observe the value:
```js
fg.valueChanges.subscribe(v => console.log(v));
```
- `statusChanges`:
In the same way, each time the form is validated or it's status has changed, the `statusChanges` event is fired:
```js
fg.statusChanges.subscribe(status => console.log(status === 'VALID' ? 'Form is valid' : 'Form is not valid'));
```
When used with ionic, two events will be rised every time the value or status changes, one per ionic `ionChange` events and another per javascript `change` events. To avoid this duplicate bouncing, there is an optional `data-debounce-time` attribute which can be configured. The usual value to avoid bouncing in the majority of brosers will be about 100ms, but it depends on many factors like browser, user computer speed, etc.
It only applies to `onValueChanges` and `onStatusChanges` properties.
```html
```
Subscriptions events will be thrown immedaitely without debouncing:
```js
const fg = new FormBuilder().group({
textInput: ['default text at initializer', Validators.required],
});
fg.valueChanges.subscribe(v => console.log(v));
fg.valueChanges.subscribe(v => console.log(v));
```
## Status
Each control maintains different status flags:
- `valid`: `true` when control value is `valid`, `false` otherwise. It's not computed until all validators (sync and async) are computed. Changes to `false` immediately when the value is changed.
- `invalid`: `true` when the control value is `invalid`, `false` otherwise. Changes to `false` when the value changes and is computed after all validators (sync and async) are computed.
- `pristine`: `true` when the control value has not been modified by the user. `false` when the value has been changed, even when it is the same as the original.
- `touched`: `true` when the control value has got the focus at least once. `false` otherwise.
- `dirty`: `true` when the control value has been modified by the user. `false` otherwise.
The form itself has the same flags, but they correspond to all the controls in the form. I.e. `valid` is `true` when all the controls have `valid` status, `false` when some of the components has `valid` status to `false`.
## Validators
There are some predefined validators:
- `Validators.min`: Validator that requires the control's value to be greater than or equal to the provided number.
- `Validators.max`: Validator that requires the control's value to be less than or equal to the provided number.
- `Validators.required`: Validator that requires the control have a non-empty value.
- `Validators.requiredTrue`: Validator that requires the control's value be true. This validator is commonly used for required checkboxes.
- `Validators.email`: Validator that requires the control's value pass an email validation test.
- `Validators.minLength`: Validator that requires the length of the control's value to be greater than or equal to the provided minimum length. This validator is also provided by default if you use the the HTML5 `minlength` attribute. Note that the `minLength` validator is intended to be used only for types that have a numeric `length` property, such as strings or arrays. The `minLength` validator logic is also not invoked for values when their `length` property is 0 (for example in case of an empty string or an empty array), to support optional controls. You can use the standard `required` validator if empty values should not be considered valid.
- `Validators.maxLength`: Validator that requires the length of the control's value to be less than or equal to the provided maximum length. This validator is also provided by default if you use the the HTML5 `maxlength` attribute. Note that the `maxLength` validator is intended to be used only for types that have a numeric `length` property, such as strings or arrays.
- `Validators.pattern`: Validator that requires the control's value to match a regex pattern. This validator is also provided by default if you use the HTML5 `pattern` attribute.
- `Validators.nullValidator`: Validator that performs no operation.
- `Validators.compose`: Compose multiple validators into a single function that returns the union of the individual error maps for the provided control.
- `Validators.composeAsync`: Compose multiple async validators into a single function that returns the union of the individual error objects for the provided control.
It is possible to create custom validators. Errors should be reported in the form `{ 'error description': { additionalInfo: '' } }:
```js
function linealRegression(a, b) {
return control => {
const value = parseInt(control.value || 0, 10);
const actual = value * a + b;
return actual > max ? { 'max square': { max, actual } } : null;
};
}
const fg = new FormBuilder().group({
// controlName: [Default value, [Sync validators], [Async validators]]
numberInput: [0, squareMax(144)],
});
```
## AsyncValidators
Async validators allows to perform an async operation and wait for the result to validate the input:
```js
function asyncUrlExits(control) {
return new Promise((resolve) => {
const url = control.value;
if (url) {
fetch(url)
.then(() => resolve(null))
.catch(error => resolve({ 'url error': { url, error } }));
} else {
resolve({ 'empty url': { url }});
}
});
}
const fg = new FormBuilder().group({
// controlName: [Default value, [Sync validators], [Async validators]]
numberInput: ['https://bitgenoma.com', [], asyncUrlExits],
});
```
# Quick Examples
## Javascript
See javascript example at [examples folder](examples/javascript.html)
```html
Text input
const reactiveForm = document.getElementById('reactiveForm');
const liveFormValue = document.getElementById('liveFormValue');
function updateLive(value) {
liveFormValue.innerHTML = JSON.stringify(value, undefined, 4);
}
/**
* Helper function that will wait until class is available
*/
function whenAvailable(cls, cb) {
if (typeof cls === 'string') {
cls = [cls];
}
window.setTimeout(() => cls.every(c => window[c]) ? cb(window[cls]) : whenAvailable(cls, cb), 10);
}
// Need to wait to all components are loaded
whenAvailable('FormBuilder', () => {
const fg = new FormBuilder().group({
textInput: ['default text at initializer', Validators.required],
});
fg.valueChanges.subscribe(v => updateLive(v));
reactiveForm.dataFormGroup = fg;
updateLive(fg.value);
});
```
## Stencil.js
See complete stencil example at [src folder](src/components/test-component.tsx)
```tsx
import { Component, h, State } from '@stencil/core';
import { FormBuilder, FormGroup, Validators } from 'forms-reactive';
@Component({
tag: 'test-component',
styleUrl: 'test-component.css',
})
export class TestComponent {
dataFormGroup: FormGroup;
subscription;
componentWillLoad() {
this.dataFormGroup = new FormBuilder().group({
textInputEmpty: ['', Validators.required],
textInput: ['default text at initializer', Validators.required],
textInputPatched: ['', Validators.required],
});
this.dataFormGroup.patchValue({ textInputPatched: 'patched value', selectPickerInputPatched: 'Option 3' });
this.subscription = this.dataFormGroup.valueChanges.subscribe(value => console.log(value));
}
disconnectedCallback() {
this.subscription.unsubscribe();
}
renderChips(el: any) {
return [
valid: {el?.valid ? "true" : "false"}
,
invalid: {el?.invalid ? "true" : "false"}
,
pristine: {el?.pristine ? "true" : "false"}
,
touched: {el?.touched ? "true" : "false"}
,
dirty: {el?.dirty ? "true" : "false"}
,
];
}
render() {
return
Empty Text input
Errors: {Object.keys(this.dataFormGroup?.controls['textInputEmpty'].errors || { none: true }).map(k => `${k}: ${this.dataFormGroup?.controls['textInputEmpty'].getError(k)}`)}
{this.renderChips(this.dataFormGroup?.controls['textInputEmpty'])}
Text input with value on constructor
Errors: {Object.keys(this.dataFormGroup?.controls['textInput'].errors || { none: true }).map(k => `${k}: ${this.dataFormGroup?.controls['textInput'].getError(k)}`)}
{this.renderChips(this.dataFormGroup?.controls['textInput'])}
Text input patched value
Errors: {Object.keys(this.dataFormGroup?.controls['textInputPatched'].errors || { none: true }).map(k => `${k}: ${this.dataFormGroup?.controls['textInputPatched'].getError(k)}`)}
{this.renderChips(this.dataFormGroup?.controls['textInputPatched'])}
;
}
}
```
# RoadMap
[ ] remove rxjs dependency
[ ] add typings for typescript, so we can validate .patch and .set with formGroup definition
[ ] remove test-component compilation at build time
[ ] test/verify validators behaviour
# License
```LICENSE
MIT License
Copyright AppFeel (Bit Genoma Digital Solutions SL) All Rights Reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```