@reactables/forms v1.0.0-beta.3

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>;

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;
}

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>;
}