Reactable Forms

Description

Reactive forms with Reactables.

Table of Contents

1. Installation
2. API
   1. RxActions
      1. updateValues
      2. addControl
      3. pushControl
      4. removeControl
      5. markControlAsPristine
      6. markControlAsTouched
      7. markControlAsUntouched
      8. resetControl
   2. build
      1. RxFormOptions
   3. control
   4. group
   5. array
   6. Other Interfaces
      1. Form
      2. FormControl
      3. ControlRef
      4. FormErrors
      5. FormReducers

Installation

Installation will require RxJS if not already installed.

npm i rxjs @reactables/forms

API

The API for building Reactable Forms is very similar to Angular FormBuilder. It has been adapted to support Reactable features.

RxActions

Actions available to trigger state changes on Reactable.

updateValues

Updates value of a FormControl. For form group and form arrays, update will only occur if specified descendant controls exists. Otherwise it will throw an error.

type updateValues = <T>(payload: UpdateValuesPayload<T>) => void;

export interface UpdateValuesPayload<T> {
  value: T;
  controlRef: ControlRef;
}

addControl

Adds a control to a form group.

type addControl = (payload: AddControlPayload) => void;

export interface AddControlPayload {
  config: AbstractControlConfig;
  controlRef: ControlRef;
}

pushControl

Pushes a control to a form array.

type pushControl = (payload: PushControlPayload) => void;

export interface PushControlPayload {
  config: AbstractControlConfig;
  controlRef: ControlRef;
}

removeControl

Removes a specified control from form.

type removeControl = (payload: ControlRef) => void;

markControlAsPristine

Marks a control and all descendant controls as pristine.

type markControlAsPristine = (payload: ControlRef) => void;

markControlAsTouched

Marks a control and all ancestors as touched. Can pass a markAll true to mark all descendants as touched as well.

type markControlAsTouched = (payload: MarkTouchedPayload) => void;

export interface MarkTouchedPayload {
  controlRef: ControlRef;
  markAll?: boolean;
}

markControlAsUntouched

Marks a control and all descendants as untouched. Will recheck ancestors controls and update touched status.

type markControlAsUnTouched = (payload: ControlRef) => void;

resetControl

Marks a control and all descendants as untouched. Will recheck ancestors controls and update touched status.

type resetControls = (payload: ControlRef) => void;

build

type build = (config: AbstractControlConfig, options?: RxFormOptions) => Reactable<Form<unknown>, RxFormActions>

Factory method for creating a form Reactable. Accepts a configuration object generated by one or more helper methods - control, group, array. Also accepts an RxFormOptions object.

RxFormOptions

Options to customize RxForm behaviour.

interface RxFormOptions {
  reducers?: { [key:string]: CustomReducer }
  effects?: Effect<unknown, unknown>[];
  sources?: Observable<Action<unknown>>[] | { [key: string]: Observable<unknown> };
}

type CustomReducer = (
  reducers: FormReducers,
  state: BaseFormState<unknown>,
  action: Action<unknown>,
) => BaseFormState<unknown>;

| Property | Description | | -------- | ----------- | | reducers (optional) | Dictionary of CustomReducers to implement custom form behaviour. The CustomReducer provides built in FormReducers. Form state updates need to be made with FormReducers to maintain integrity of the form state tree (i.e validation states of parent and child controls). | | effects (optional) | Array of Effects to be registered to the Reactable. | | sources (optional) | Additional Action Observables the Reactable is listening to. Can be an array or a dictionary where key is the action type and value is the Observable emitting the payload. |

control

Function to create a FormControlConfig configuration object. Accepts a configuration object or a tuple.

type control = <T>(config: FormControlConfig<T> | FbControl<T>) => FormControlConfig<T>

interface FormControlConfig<T>  {
  initialValue: T;
  validators?: ValidatorFn[];
  asyncValidators?: ValidatorAsyncFn[];
}

type FbControl<T> = [T, (ValidatorFn | ValidatorFn[])?, (ValidatorAsyncFn | ValidatorAsyncFn[])?];

group

Function to create a FormGroupConfig configuration object. Accepts a configuration object containing a controls dictionary of additional configuration objects generated by control, group, or array.

type group = (config: FormGroupConfig) => FormGroupConfig

interface FormGroupConfig{
  validators?: ValidatorFn[];
  asyncValidators?: ValidatorAsyncFn[];
  controls: { [key: string]: AbstractControlConfig };
}

array

Function to create a FormArrayConfig configuration object. Accepts a configuration object containing a controls array of additional configuration objects generated by control, group, or array.

type array = (config: FormArrayConfig) => FormArrayConfig

interface FormArrayConfig {
  validators?: ValidatorFn[];
  asyncValidators?: ValidatorAsyncFn[];
  controls: AbstractControlConfig[];
}

Other Interfaces

Form

Form state. Dictionary of FormControl(s) where the key is a period separated representation of the ControlRef tuple.

export interface Form<T> {
  root?: FormControl<T>;
  [key: string]: FormControl<unknown>;
}

FormControl

export interface FormControl<T> extends BaseControl<T>, Hub2Fields {
  pristineValue: T;
  controlRef: ControlRef;
  value: T;
  dirty: boolean;
  touched: boolean;
  validatorErrors: FormErrors;
  key: string;
  asyncValidatorErrors: FormErrors;
  asyncValidateInProgress: { [key: string | number]: boolean };
  errors: FormErrors;
  valid: boolean;
  childrenValid: boolean;
  pending?: boolean;
  config: AbstractControlConfig;
}

| Property | Description | | -------- | ----------- | | pristineValue | Original value of control. Use to determine if control is dirty. | | controlRef | Controls ControlRef. | | value | Control value. | | touched | Touched status of control | | validatorErrors | FormErrors from validators (non-async) | | asyncValidatorErrors | FormErrors from async validators | | errors | FormErrors validatorErrors and asyncValidatorErrors merged. | | valid | Valid status of control. Also checks descendants. | childrenValid | Valid status of direct child controls. | config | Original config for form control |

ControlRef

Control Reference represented as a tuple for the FormControl

FormErrors

Dictionary of errors for the control.

export interface FormErrors {
  [key: string]: boolean;
}

FormReducers

Built in reducers to be used to update state of form tree. Payload and behaviour is same and descrbed in RxActions;

export interface FormReducers {
  updateValues: <T>(state: BaseFormState<T>, payload: UpdateValuesPayload<unknown>,
  ) => BaseFormState<T>;
  removeControl: <T>(state: BaseFormState<T>, payload: ControlRef) => BaseFormState<T>;
  pushControl: <T>(state: BaseFormState<T>, payload: PushControlPayload) => BaseFormState<T>;
  addControl: <T>(state: BaseFormState<T>, payload: AddControlPayload) => BaseFormState<T>;
  markControlAsPristine: <T>(state: BaseFormState<T>, payload: ControlRef) => BaseFormState<T>;
  markControlAsTouched: <T>(state: BaseFormState<T>, payload: MarkTouchedPayload) => BaseFormState<T>;
  markControlAsUntouched: <T>(state: BaseFormState<T>, payload: ControlRef,
  ) => BaseFormState<T>;
  resetControl: <T>(state: BaseFormState<T>, payload: ControlRef) => BaseFormState<T>;
}