npm package: @ngserveio/form-services
Description: Find more at libraries and examples at [NgServe.io](https://ngserve.io).
Latest version: 10.0.0

# @ngserveio/form-services

Find more at libraries and examples at [NgServe.io](https://ngserve.io).

Read More At
[Angular Tutorial - Reusable Form Component with Multiple Controls and Validation](https://ngserve.io/angular-tutorial-reusable-form-component-with-multiple-controls-and-validation/)

## Running unit tests

Run `nx test ui-form-services` to execute the unit tests.

## Purpose

This library extends Angular's [FormGroup](https://angular.io/api/forms/FormGroup) allowing for a generic form group and validation utilizing [@ngserveio/you-good](https://www.npmjs.com/package/@ngserveio/you-good) validations.

[1]: https://www.youtube.com/watch?v=6i-cZ8TyqHI
[2]: https://img.youtube.com/vi/6i-cZ8TyqHI/mqdefault.jpg

### See the Video Tutorial on YouTube

[![Shared Validators for Angular and NestJS][2]][1]

### FormGroupSubmit

An extension of Angular's [FormGroup](https://angular.io/api/forms/FormGroup) class that supplies the ability to check if the form has been marked as submitted.

#### Properties

| Name         | Type                        | Description                                     |
| ------------ | --------------------------- | ----------------------------------------------- |
| `submitted$` | BehaviorSubject<boolean&gt; | Checks if the form has been marked as submitted |

#### Methods

| Name                                        | Return Type                     | Description                                                                                 |
| ------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------- |
| `dispose()`                                 | `void`                          | Completes the `submitted$` property's stream                                                |
| `submit()`                                  | `void`                          | Marks the form as having been submitted and will mark all fields in form as touched.        |
| `reset()`                                   | `void`                          | Resets the form, marks submitted as false                                                   |
| `getFormGroupSubmit(ctrl: AbstractControl)` | `FormGroupSubmit` &#124; `null` | A static method that returns the FormGroupSubmit if the nested parent exists on the `ctrl`. |

### ModeledFormGroup

A generic modeled form group that binds the keys of the models to an `AbstractControl`. Its takes an additional parameter of type `(item: T) => PropertyValidationErrors<T>`. See [@ngserveio/you-good](https://www.npmjs.com/package/@ngserveio/you-good) for validation types and examples for validations.

### Properties

| Name               | Description |                                                                          |
| ------------------ | ----------- | ------------------------------------------------------------------------ |
| `getChangedValues` | `Subset<T>` | Returns the changed values of the controls. Useful for `PATCH` requests. |

```ts
type FullName = { firstName: string; lastName: string };

const fullNameValidator = validate<FullName>({
  firstName: propertyValidators(
    (item) => item.firstName,
    [required, emptyOrWhiteSpace]
  ),
  lastName: propertyValidators(
    (item) => item.lastName,
    [required, emptyOrWhiteSpace]
  ),
});

const formGroup = new ModeledFormGroup<FullName>(
  {
    firstName,
    lastName,
  },
  fullNameValidator
);
```

Subscribing to the `modelChanged` property provides the defined generic type returned and validates the form in the stream.

```ts
formGroup.modelChanged.subscribe(({ firstName, lastName }) => {
  console.log(`${firstName} ${lastName}`);
  // Output: Steve Yzerman
});

formGroup.patchValue({
  firstName: 'Steve',
  lastName: 'Yzerman',
});
```

[Change Log](./CHANGELOG.md)