docs: some cleanup in user guide

Author: MrWolfZ

docs/FORM_ARRAYS.md

@@ -29,13 +29,16 @@ Array states are completely independent of the DOM. They are updated by intercep
 
 #### Dynamic Form Arrays
 
-Sometimes you will have to render a variable number of fields in your form. Form arrays support adding and removing controls dynamically. This is done by setting the value of the form array via `setValue` which will automatically update the form array based on the value you provide.
+Sometimes you will have to render a variable number of fields in your form. Form arrays support adding and removing controls dynamically. This can be done in two ways:
+
+1) explicitly call the `addArrayControl` and `removeArrayControl` update functions (see the section section on [updating the state](UPDATING_THE_STATE.md) for more details on these functions)
+2) set the value of the form array via `setValue` which will automatically update the form array based on the value you provide
 
 Below you can find an example of how this would look. Assume that we have an action that provides a variable set of objects which each should be mapped to an array with two form controls.
 
 ```typescript
 import { Action } from '@ngrx/store';
-import { FormArrayState, setValue, updateGroup, cast } from 'ngrx-forms';
+import { FormArrayState, setValue } from 'ngrx-forms';
 
 interface DynamicObject {
   someNumber: number;
@@ -65,7 +68,7 @@ export function appReducer(state: AppState, action: Action): AppState {
 
       // the `setValue` will add and remove controls as required; existing controls that are still
       // present get their value updated but are otherwise kept in the same state as before
-      const dynamicFormArray = cast(setValue(newFormValue, state.dynamicFormArray));
+      const dynamicFormArray = setValue(newFormValue, state.dynamicFormArray);
       return { ...state, dynamicFormArray };
     }
 

docs/FORM_CONTROLS.md

@@ -172,8 +172,7 @@ export class MyComponent {
 
 ```html
 <form novalidate [ngrxFormState]="(formState$ | async)">
-  <input type="date"
-         [ngrxFormControlState]="(formState$ | async).controls.date"
-         [ngrxValueConverter]="dateValueConverter">
+  <custom-date-picker [ngrxFormControlState]="(formState$ | async).controls.date"
+                      [ngrxValueConverter]="dateValueConverter"></custom-date-picker>
 </form>
 ```

docs/FORM_GROUPS.md

@@ -33,14 +33,14 @@ Group states are usually completely independent of the DOM (with the exception o
 
 Sometimes you will have to render a variable number of fields in your form. In such a case you can provide a form value interface that has an index signature and then add and remove controls dynamically. Instead of an index signature you can also use optional fields if the potential members of the form value are statically known. At runtime you can add and remove controls in two ways:
 
-1) explicitly call the `addControl` and `removeControl` update functions (see the section below)
+1) explicitly call the `addGroupControl` and `removeGroupControl` update functions (see the section section on [updating the state](UPDATING_THE_STATE.md) for more details on these functions)
 2) set the value of the form group via `setValue` which will automatically update the form group based on the value you provide
 
 Below you can find an example of how this would look. Assume that we have an action that provides a variable set of objects which each should be mapped to a group with two form controls.
 
 ```typescript
 import { Action } from '@ngrx/store';
-import { FormGroupState, setValue, cast } from 'ngrx-forms';
+import { FormGroupState, setValue } from 'ngrx-forms';
 
 interface DynamicObject {
   id: string;
@@ -81,7 +81,7 @@ export function appReducer(state: AppState, action: Action): AppState {
 
       // the `setValue` will add and remove controls as required; existing controls that are still
       // present get their value updated but are otherwise kept in the same state as before
-      const dynamicForm = cast(setValue(newFormValue, state.dynamicForm));
+      const dynamicForm = setValue(newFormValue, state.dynamicForm);
       return { ...state, dynamicForm };
     }
 

docs/UPDATING_THE_STATE.md

@@ -1,6 +1,6 @@
 ## Updating the State
 
-All states are internally updated by ngrx-forms through dispatching actions. While this is of course also possible for you there exist a set of utility functions that can be used to update states. This is mainly useful to change the state as a result of a different action in your reducer. Note that ngrx-forms is coded in such a way that no state references will change if nothing inside the state changes. It is therefore perfectly safe to repeatedly call any of the functions below and the state will be updated exactly once or not at all if nothing changed. Each function can be imported from `ngrx-forms`. The following table explains each function:
+All form states are internally updated by ngrx-forms through dispatching actions. While this is of course also possible for you there exist a set of update functions that can be used to update form states. This is mainly useful to change the state as a result of a different action in your reducer. Note that ngrx-forms is coded in such a way that no state references will change if nothing inside the state changes. It is therefore perfectly safe to repeatedly call any of the functions below and the state will be updated exactly once or not at all if nothing changed. Each function can be imported from `ngrx-forms`. The following table explains each function:
 
 |Function|Description|
 |-|-|
@@ -27,10 +27,10 @@ All states are internally updated by ngrx-forms through dispatching actions. Whi
 These are the basic functions that perform simple updates on states. The functions below contain the real magic that allows easily updating deeply nested form states.
 
 #### `updateArray`
-This update function takes an update function and returns a function that takes an array state, applies the provided update function to each element and recomputes the state of the array afterwards. As with all the functions above this function does not change the reference of the array if the update function does not change any children. See the section below for an example of how this function can be used.
+This update function takes an update function and returns a projection function that takes an array state, applies the provided update function to each element and recomputes the state of the array afterwards. As with all the functions above this function does not change the reference of the array if the update function does not change any children. See the section below for an example of how this function can be used.
 
 #### `updateGroup`
-This update function takes a partial object in the shape of the group's value where each key contains an update function for that child and returns a function that takes a group state, applies all the provided update functions recursively and recomputes the state of the group afterwards. As with all the functions above this function does not change the reference of the group if none of the child update functions change any children. The best example of how this can be used is simple validation:
+This update function takes a partial object in the shape of the group's value where each key contains an update function for that child and returns a projection function that takes a group state, applies all the provided update functions recursively and recomputes the state of the group afterwards. As with all the functions above this function does not change the reference of the group if none of the child update functions change any children. The best example of how this can be used is simple validation:
 
 ```typescript
 import { updateArray, updateGroup, validate } from 'ngrx-forms';
@@ -84,7 +84,7 @@ const updateMyFormGroup = updateGroup<MyFormValue>({
       someNumber: (someNumber: AbstractControlState<number>) => {
         if (myForm.controls.someTextInput.errors.required) {
           // sets the control's value to 1 and clears all errors
-          return validate(() => ({}), setValue(1, someNumber));
+          return setErrors({}, setValue(1, someNumber));
         }
 
         return someNumber;
@@ -129,7 +129,7 @@ const myFormReducer = createFormGroupReducerWithUpdate<MyFormValue>({
     updateGroup<NestedValue>({
       someNumber: someNumber => {
         if (myForm.controls.someTextInput.errors.required) {
-          return validate(() => ({}), setValue(1, someNumber));
+          return setErrors({}, setValue(1, someNumber));
         }
 
         return someNumber;
@@ -193,7 +193,7 @@ export function appReducer(state = initialState, action: Action): AppState {
 ```
 
 #### `updateRecursive`
-Sometimes it is useful to apply an update function to all controls in a group or array recursively. This update function takes an update function and returns a function that takes any state and applies the provided update function to all its children, its children's children etc. and finally to the state itself. This means when the update function is called for a certain state all of its children will have already been updated. The provided update function takes 2 parameters, the state to update and its parent state. For the top-level state the state itself is passed as the second parameter.
+Sometimes it is useful to apply an update function to all controls in a group or array recursively. This update function takes an update function and returns a projection function that takes any state and applies the provided update function to all its children, its children's children etc. and finally to the state itself. This means when the update function is called for a certain state all of its children will have already been updated. The provided update function takes 2 parameters, the state to update and its parent state. For the top-level state the state itself is passed as the second parameter.
 
 Below you can find an example of how this function can be used. In this example we want to block all form inputs temporarily (e.g. while submitting the form). This can be done by disabling the form state at the root. However, when we unblock all inputs we want their enabled/disabled state to be reset to what it was before blocking the inputs. This could be done by simply storing a complete copy of the state (which might take a lot of space depending on the size of the form state). However, the example below uses a different method. We use the `setUserDefinedProperty` update function to store the enabled/disabled state before blocking the inputs and later restore them to the state they were in.
 

docs/USER_GUIDE.md

@@ -2,21 +2,21 @@
 
 The following sections will explain and showcase the different features of `ngrx-forms`. It is recommended to read these in the order they are listed below.
 
-* [Getting Started](GETTING_STARTED.md#getting-started)
-* [Form Controls](FORM_CONTROLS.md#form-controls)
+* [Getting Started](GETTING_STARTED.md)
+* [Form Controls](FORM_CONTROLS.md)
   * [`ngrxUpdateOn`](FORM_CONTROLS.md#ngrxupdateon)
   * [User Defined Properties](FORM_CONTROLS.md#user-defined-properties)
   * [Value Conversion](FORM_CONTROLS.md#value-conversion)
-* [Form Groups](FORM_GROUPS.md#form-groups)
+* [Form Groups](FORM_GROUPS.md)
   * [Dynamic Form Groups](FORM_GROUPS.md#dynamic-form-groups)
-* [Form Arrays](FORM_ARRAYS.md#form-arrays)
+* [Form Arrays](FORM_ARRAYS.md)
   * [Dynamic Form Arrays](FORM_ARRAYS.md#dynamic-form-arrays)
-* [Updating the State](UPDATING_THE_STATE.md#updating-the-state)
+* [Updating the State](UPDATING_THE_STATE.md)
   * [`updateArray`](UPDATING_THE_STATE.md#updatearray)
   * [`updateGroup`](UPDATING_THE_STATE.md#updategroup)
   * [`createFormGroupReducerWithUpdate`](UPDATING_THE_STATE.md#createformgroupreducerwithupdate)
   * [`updateRecursive`](UPDATING_THE_STATE.md#updaterecursive)
-* [Validation](VALIDATION.md#validation)
+* [Validation](VALIDATION.md)
   * [Asynchronous Validation](VALIDATION.md#asynchronous-validation)
-* [Custom Controls](CUSTOM_CONTROLS.md#custom-controls)
+* [Custom Controls](CUSTOM_CONTROLS.md)
 

docs/VALIDATION.md

@@ -45,7 +45,7 @@ const updateMyFormGroup = updateGroup<MyFormValue>({
 
 In addition to the synchronous validation via update functions explained above ngrx-forms supports asynchronous validation for form elements. However, since asynchronous validations are by nature not side-effect free they need to be handled differently.
 
-ngrx-forms provides a set of 3 actions that can be used to perform asynchronous validation. These actions can be dispatched however you like, be that from a service or from within effects. The first of these actions is the `StartAsyncValidationAction` which takes the name of the validation to be performed. This name is added to the `pendingValidations` of the control state and the `isValidationPending` flag is set to true (if it was not already) for the control and all its parents. However, the validity of the control is not affected by this action. This means, if you e.g. want to disable the submit button of your form while the form is invalid or currently validating you need to check two properties, e.g. `[disabled]="formState.isInvalid || formState.isValidationPending"`. You can have as many asynchronous validations running at the same time as you like. The `isValidationPending` flag will be true as long as at least one validation has not yet completed.
+ngrx-forms provides a set of three actions that can be used to perform asynchronous validation. These actions can be dispatched however you like, be that from a service or from within effects. The first of these actions is the `StartAsyncValidationAction` which takes the name of the validation to be performed. This name is added to the `pendingValidations` of the control state and the `isValidationPending` flag is set to true (if it was not already) for the control and all its parents. However, the validity of the control is not affected by this action. This means, if you e.g. want to disable the submit button of your form while the form is invalid or currently validating you need to check two properties, e.g. `[disabled]="formState.isInvalid || formState.isValidationPending"`. You can have as many asynchronous validations running at the same time as you like. The `isValidationPending` flag will be true as long as at least one validation has not yet completed.
 
 The last two actions are used to complete the validation. The `SetAsyncErrorAction` takes the name of the validation and an arbitrary value and adds an error with the given name (prefixed with a `$`) and value to the state's errors. It also removes the validation from the control's `pendingValidations`. The `$` prefix marks all asynchronous errors which allows the synchronous validation via update functions to preserve these errors. That means you can safely combine synchronous validation and asynchronous validation. By adding the error the control will be marked as invalid if it was not already. The other action is the `ClearAsyncErrorAction` which takes only the name of the validation and removes the error if it was present. This action also removes the validation from the control's `pendingValidations`.