@reactables/forms 0.5.1-alpha.0 → 0.5.3-alpha.0

package/README.md

@@ -2,14 +2,119 @@
 
 ## Description
 
-State management for building a comprehensive form library using [Reactables Core](https://github.com/reactables/reactables/tree/main/packages/core).
+State Management of reactive forms with [Reactables](https://github.com/reactables/reactables/tree/main/packages/core).
 
-## Architecture (WIP see https://github.com/reactables/reactables/issues/8)
+## Table of Contents
 
-The following diagram visualizes the architecture of [Reactables Forms](https://github.com/reactables/reactables/tree/main/packages/forms) - a state management model for building reactive forms.
+1. [Installation](#installation)
+1. [Examples](#examples)
+    1. [Form Control](#form-control)
+    1. [Form Array](#form-array)
+    1. [Form Group](#form-group)
 
-There are two sets of hub and stores. The first set is responsible for handling user input and updating the form.
+1. [API](#api)
+    1. [RxActions](#api-actions)
+    1. [build](#api-build)
+    1. [control](#api-control)
+    1. [group](#api-group)
+    1. [array](#api-array)
+    1. [Other Interfaces](#interfaces)
+        1. [EffectsAndSources](#effects-sources)
 
-The second set is responsible for reacting to the form change in the first store and asynchronous validation.
 
-![Reactables architecture](https://raw.githubusercontent.com/reactables/reactables/main/documentation/Slide10ReactablesForms.jpg)
+## Installation <a name="installation"></a>
+
+Installation will require [RxJS](https://rxjs.dev/) if not already installed.
+
+`npm i rxjs @reactables/forms`
+
+## Examples <a name="examples"></a>
+
+WIP
+
+## API <a name="api"></a>
+
+The API for building Reactable Forms is very similar to [Angular FormBuilder](https://angular.io/api/forms/FormBuilder). It has been adapted to support Reactable features.
+
+### `RxActions` <a name="api-actions"></a>
+
+Actions available to trigger state changes on Reactable.
+
+```typescript
+type RxFormActions = {
+  updateValues: <T>(payload: ControlChange<T>) => void;
+  addControl: (payload: AddControl) => void;
+  pushControl: (payload: PushControl) => void;
+  removeControl: (payload: ControlRef) => void;
+  markControlAsPristine: (payload: ControlRef) => void;
+  markControlAsTouched: (payload: MarkTouched) => void;
+  markControlAsUntouched: (payload: ControlRef) => void;
+  resetControl: (payload: ControlRef) => void;
+};
+```
+
+### `build` <a name="api-build"></a>
+
+```typescript
+type build = (config: AbstractControlConfig, options?: EffectsAndSources) => Reactable<Form<unknown>, RxFormActions>
+```
+
+Factory method for creating a form Reactable. Accepts a configuration object generated by one or more helper methods - [`control`](#api-control), [`group`](#api-group), [`array`](#api-array).
+
+Options can also be provided to declare [Effects and Sources](#effects-sources) for the form Reactable.
+
+### `control` <a name="api-control"></a>
+
+Function to create a `FormControlConfig` configuration object. Accepts a configuration object or a tuple.
+```typescript
+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` <a name="api-group"></a>
+
+Function to create a `FormGroupConfig` configuration object. Accepts a configuration object containing a `controls` dictionary of additional configuration objects generated by [`control`](#api-control), [`group`](#api-group), or [`array`](#api-array).
+
+```typescript
+type group = (config: FormGroupConfig) => FormGroupConfig
+
+interface FormGroupConfig{
+  validators?: ValidatorFn[];
+  asyncValidators?: ValidatorAsyncFn[];
+  controls: { [key: string]: AbstractControlConfig };
+}
+```
+### `array` <a name="api-array"></a>
+
+Function to create a `FormArrayConfig` configuration object. Accepts a configuration object containing a `controls` array of additional configuration objects generated by [`control`](#api-control), [`group`](#api-group), or [`array`](#api-array).
+
+```typescript
+type array = (config: FormArrayConfig) => FormArrayConfig
+
+interface FormArrayConfig {
+  validators?: ValidatorFn[];
+  asyncValidators?: ValidatorAsyncFn[];
+  controls: AbstractControlConfig[];
+}
+```
+
+### Other Interfaces <a name="interfaces"></a>
+
+#### EffectsAndSources <a name="effects-sources"></a>
+```typescript
+interface EffectsAndSources {
+  effects?: Effect<unknown, unknown>[];
+  sources?: Observable<Action<unknown>>[] | { [key: string]: Observable<unknown> };
+}
+```
+| Property | Description |
+| -------- | ----------- |
+| effects (optional) | Array of [Effects](https://github.com/reactables/reactables/tree/main/packages/core#api-effect) to be registered to the Reactable |
+| sources (optional) | Additional [Action](https://github.com/reactables/reactables/tree/main/packages/core#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 |

package/dist/RxForm/RxForm.d.ts

@@ -5,6 +5,9 @@ import { FormControlConfig, FormArrayConfig, FormGroupConfig, AbstractControlCon
 import { ValidatorFn, ValidatorAsyncFn } from '../Models/Validators';
 import { Form } from '../Models/Controls';
 type FbControl<T> = [T, (ValidatorFn | ValidatorFn[])?, (ValidatorAsyncFn | ValidatorAsyncFn[])?];
+export declare const control: <T>(config: FormControlConfig<T> | FbControl<T>) => FormControlConfig<T>;
+export declare const array: (config: FormArrayConfig) => FormArrayConfig;
+export declare const group: (config: FormGroupConfig) => FormGroupConfig;
 export type RxFormActions = {
     updateValues: <T>(payload: ControlChange<T>) => void;
     addControl: (payload: AddControl) => void;
@@ -15,10 +18,5 @@ export type RxFormActions = {
     markControlAsUntouched: (payload: ControlRef) => void;
     resetControl: (payload: ControlRef) => void;
 };
-export declare const RxForm: {
-    group: (config: FormGroupConfig) => FormGroupConfig;
-    array: (config: FormArrayConfig) => FormArrayConfig;
-    control: <T>(config: FormControlConfig<T> | FbControl<T>) => FormControlConfig<T>;
-    build: (config: AbstractControlConfig, options?: EffectsAndSources) => Reactable<Form<unknown>, RxFormActions>;
-};
+export declare const build: (config: AbstractControlConfig, options?: EffectsAndSources) => Reactable<Form<unknown>, RxFormActions>;
 export {};

package/dist/RxForm/index.d.ts

@@ -1 +1 @@
-export { RxForm, RxFormActions } from './RxForm';
+export { build, group, array, control, RxFormActions } from './RxForm';

package/dist/index.js

@@ -839,7 +839,7 @@ var mergeRemoveControl = function (state, form, controlRef) {
         }
         return __assign(__assign({}, acc), (_a = {}, _a[key] = __assign(__assign(__assign({}, existingControl), baseControl), { errors: errors, valid: selfValid && childrenValid, childrenValid: childrenValid }), _a));
     }, {});
-    var descendants = existingBranch.filter(function (control) { return control.controlRef.length < parentRef.length; });
+    var descendants = existingBranch.filter(function (control) { return control.controlRef.length > parentRef.length; });
     var removedControls = __assign({}, state);
     descendants.forEach(function (control) {
         delete removedControls[getFormKey(control.controlRef)];
@@ -980,12 +980,6 @@ var build = function (config, options) {
         state$: rxHub2.state$.pipe(operators.filter(function (form) { return form !== null; })),
         actions: rxHub1.actions
     };
-};
-var RxForm = {
-    group: group,
-    array: array,
-    control: control,
-    build: build
 };
 
 var getArrayItems = function (controlRef, form) {
@@ -998,6 +992,9 @@ var getArrayItems = function (controlRef, form) {
 };
 
 exports.ControlModels = Controls;
-exports.RxForm = RxForm;
 exports.Validators = index;
+exports.array = array;
+exports.build = build;
+exports.control = control;
 exports.getArrayItems = getArrayItems;
+exports.group = group;

package/package.json

@@ -14,12 +14,14 @@
   "author": "David Lai",
   "license": "ISC",
   "dependencies": {
-    "@reactables/core": "^0.5.1-alpha.0",
-    "lodash.clonedeep": "^4.5.0",
+    "@reactables/core": "^0.5.3-alpha.0",
     "lodash.isequal": "^4.5.0"
   },
   "peerDependencies": {
     "rxjs": "^6.0.0 || ^7.0.0"
   },
-  "version": "0.5.1-alpha.0"
+  "devDependencies": {
+    "lodash.clonedeep": "^4.5.0"
+  },
+  "version": "0.5.3-alpha.0"
 }