Merge pull request #200 from Jenesius/issue_199

Issue 199

Author: Jenesius

docs/guide/form.md

@@ -115,4 +115,25 @@ Accepts `true` or `false`, changes during read/save. When changing this property
 event `Form.EVENT_WAIT` is created:
 ```ts
 form.on(Form.EVENT_WAIT, () => {...})
+```
+
+### autonomic
+
+Sometimes you want a child form to be dependent on its parent, but rely on its state
+(changes, values, availabilities). In this case, save/read will be called from the parent form. Also, the changed
+value will be read from the parent form.
+
+```ts
+const parent = new Form();
+const child = new Form({
+    parent,
+    name: "user",
+    autonomic: true
+});
+
+parent.change({
+    "user.name": "Jack"
+})
+child.values  // {}
+parent.values // { user: { name: "Jack" } }
 ```

docs/ru/guide/form.md

@@ -114,4 +114,25 @@ form.version = 15; // Upgrade. Version: 15
 создаётся событие `Form.EVENT_WAIT`:
 ```ts
 form.on(Form.EVENT_WAIT, () => {...})
+```
+
+### autonomic
+
+Иногда вам нужно, чтобы дочерняя форма зависела от родительской формы, но полагалась на ее состояние.
+(изменения, значения, наличие). В этом случае сохранение/чтение будет вызываться из родительской формы.
+Кроме того, измененный значение будет прочитано из родительской формы.
+
+```ts
+const parent = new Form();
+const child = new Form({
+    parent,
+    name: "user",
+    autonomic: true
+});
+
+parent.change({
+    "user.name": "Jack"
+})
+child.values  // {}
+parent.values // { user: { name: "Jack" } }
 ```

examples/autonomic-form/App.vue

@@ -0,0 +1,26 @@
+<template>
+	<div class="container">
+		<form-field name = "username" label = "Username"/>
+
+		<station-form />
+
+		<button @click = "showChanges">Changes</button>
+	</div>
+</template>
+
+<script setup lang='ts'>
+
+import {Form, FormField} from "../../src";
+import StationForm from "./station-form.vue";
+
+const form = new Form();
+// @ts-ignore
+window.theForm = form;
+function showChanges() {
+	console.log(form.changes);
+}
+</script>
+
+<style scoped>
+
+</style>

examples/autonomic-form/README.md

@@ -0,0 +1,41 @@
+# Form changes
+
+This example demonstrates working with values, namely with changes. When working with forms, you need to keep track of which
+values have been changed. To do this, the library provides a mechanism for marking a field as changed.
+How it works:
+1. Imagine that in the form we have the values
+```json
+{
+    "name": "Jenesius",
+    "age": 23
+}
+```
+2. We decided to change the value of age to 24.
+```ts
+form.change({age: 24})
+```
+3. In this case, the values will take the following form:
+ ```json
+{
+    "name": "Jenesius",
+    "age": 24
+}
+```
+This will change the change mark snapshot:
+
+```json
+{
+    "age": true
+}
+```
+4. Now when receiving form.changes, we will only see those values that are marked as true.
+```ts
+form.changes // { age: 24 }
+```
+
+This example uses:
+- [form.changes](https://form.jenesius.com/guide/form-state.html#changes)
+- [form.change](https://form.jenesius.com/guide/form-methods.html#change)
+- [form.setValues](https://form.jenesius.com/guide/form-methods.html#setvalues)
+- [form.cleanChanges](https://form.jenesius.com/guide/form-methods.html#cleanchanges)
+- [form.cleanValues](https://form.jenesius.com/guide/form-methods.html#cleanvalues)

examples/autonomic-form/main.ts

@@ -0,0 +1,9 @@
+import { createApp } from 'vue'
+import App from './App.vue';
+import {config} from "./../../src/index";
+
+config({
+	debug: true
+})
+
+createApp(App).mount('#app')

examples/autonomic-form/station-form.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+import {Form, FormField} from "../../src";
+
+const form = new Form({
+	name: "Station",
+	autonomic: true
+})
+
+</script>
+
+<template>
+	<div>
+		<h2>Station:</h2>
+		<form-field name = "name" label = "Name"/>
+		<form-field name = "code" label = "Station Code" />
+		<form-field name = "bandwidth" label = "Available bandwidth" />
+	</div>
+</template>

project/pages/index/App.vue

@@ -8,6 +8,7 @@
     <p><a href = "/input-country" class = "example-link">Input Country</a></p>
     <p><a href = "/input-otp" class = "example-link">Input One-Time Password</a></p>
     <p><a href = "/all-inputs" class = "example-link">All Inputs</a></p>
+    <p><a href = "/form-autonomic" class = "example-link">Form Autonomic</a></p>
   </div>
 	<div class = "container-examples">
 		<h3 class = "container-examples-title">Test:</h3>

src/classes/DependencyQueue.ts

@@ -32,7 +32,9 @@ export default class DependencyQueue<T extends (DependencyItem & Record<string,
 			this.array.indexOf(object), 1
 		)
 	}
-
+	find(expression: (elem: T, index: number) => boolean) {
+		return this.array.find(expression);
+	}
 	forEach(callback: (elem: T) => void) {
 		this.array.forEach(callback);
 	}

src/classes/Form.ts

@@ -23,6 +23,7 @@ import findNearestPrefixFromArray from "../utils/find-nearest-prefix-from-array"
 import AvailabilityEvent from "./AvailabilityEvent";
 import bypassObject from "../utils/bypass-object";
 import isIterablePoint from "../utils/is-iterable-point";
+import FormError from "./FormError";
 
 /**
  * Main principe : GMN
@@ -63,7 +64,6 @@ export default class Form extends EventEmitter implements FormDependence {
         if (elem.parent) return `${Form.restoreFullName(elem.parent)}.${elem.name}`;
         return elem.name || '';
     }
-    
     static getTargetName<T extends { name?: string, parent?: any }>(elem: T): string {
         const array = [];
 
@@ -80,19 +80,40 @@ export default class Form extends EventEmitter implements FormDependence {
      * @description Name of Entity.
      * */
     name?: string
+    /**
+     * @description If set to true, then values,changes are standalone and independent of the parent form.
+     */
+    
+    #autonomic: boolean | undefined = undefined;
+    /**
+     * @description Класс является автономным, если не указан родитель или если свойство #autonomic установлено в true
+     */
+    get autonomic():boolean {
+        // Если есть родитель, то проверяем на autonomic
+        if (this.parent) return this.#autonomic === true;
+        // Родитель отсутствует, в таком случае форма всегда является автономной
+        return true;
+    }
+    set autonomic(value: boolean) {
+        if (value === false && !this.parent) throw FormError.AutonomicFormWithoutParent();
+        this.#autonomic = value;
+        
+        debug.msg(`The form's %c${Form.restoreFullName(this)}%c autonomic is %c${value}%c.`);
+    }
+    
     /**
      * @description Внутренний объект изменений. Хранит в себе значения полей, которые были установлены, используя флаг
      * changes: true в методе setValues или используя метод change.
      * */
     #changes = {};
     get changes(): any {
-        if (this.parent) return getPropFromObject(this.parent.changes, Form.getTargetName(this));
+        if (this.parent && !this.autonomic) return getPropFromObject(this.parent.changes, Form.getTargetName(this));
         return this.#changes;
     }
 
     #values = {}
     get values(): any {
-        if (this.parent) {
+        if (this.parent  && !this.autonomic) {
             return this.parent.getValueByName(this.name as string) || {};
         }
         return mergeObjects({}, this.#values, this.#changes)
@@ -101,7 +122,7 @@ export default class Form extends EventEmitter implements FormDependence {
      * @description Чистые значения формы. Которые изменяются при помощи setValues без опции change.
      * */
     get pureValues():any {
-        if (this.parent) return getPropFromObject(this.parent.pureValues, this.name as string) || {}
+        if (this.parent && !this.autonomic) return getPropFromObject(this.parent.pureValues, this.name as string) || {}
         return this.#values;
     }
 
@@ -126,20 +147,23 @@ export default class Form extends EventEmitter implements FormDependence {
         this.#parent = parent;
     }
 
+    /**
+     * !!!!!!!!!!!
+     * CONSTRUCTOR
+     * !!!!!!!!!!!
+     */
     constructor(params: Partial<FormParams> = {}) {
         super();
 
         this.name = params.name;
         const currentInstance = !!getCurrentInstance();
-        
         debug.msg(`new form %c${Form.restoreFullName(this)}%c`, debug.colorName, debug.colorDefault, this);
-        if (currentInstance) {
-            const parent = Form.getParentForm();
-            if (parent && !(params.parent === false || params.parent === null)) {
-                parent.subscribe(this);
-            }
-        }
+        
+        const parent = (currentInstance ? Form.getParentForm() : null) || params.parent
+        if (parent) parent.subscribe(this);
         if (params.provide !== false && currentInstance) provideVue(Form.PROVIDE_NAME, this); // Default providing current form for children.
+        
+        if (typeof params.autonomic === 'boolean') this.autonomic = params.autonomic;
     }
 
     setValues(values: any, options: Partial<FormSetValuesOptions> = {}): void {
@@ -155,13 +179,13 @@ export default class Form extends EventEmitter implements FormDependence {
         if (!checkNameInObject(values, target)) insertByName(values, target)
          */
 
-        if (!options.executedFrom) {
+        if (!options.executedFrom && !this.autonomic) {
             debug.msg(`Executed from not founded in options, values will be %c${Form.getTargetName(this)}`, debug.colorSuccess)
             options.executedFrom = Form.getTargetName(this);
         }
 
         // Текущий элемент имеет родителя - отправляем изменения наверх.
-        if (this.parent) {
+        if (this.parent && !this.autonomic) {
             debug.msg(`%c${this.name}%c emit changes to parent [%c${this.parent.name}%c]`, debug.colorName, debug.colorDefault, debug.colorFocus,debug.colorDefault);
             return void this.parent.setValues(values, options);
         }
@@ -395,8 +419,13 @@ export default class Form extends EventEmitter implements FormDependence {
     /**
      * @description Return true if form includes changes, otherwise false.
      * */
-    get changed() {
-        return !!(this.changes && Object.keys(this.changes).length !== 0);
+    get changed(): boolean {
+        return !!(
+            (this.changes && Object.keys(this.changes).length !== 0)
+            || this.dependencies.find(
+                elem =>  (elem instanceof Form && elem.changed)
+            )
+        );
     }
 
     subscribe(element: any) {
@@ -494,7 +523,7 @@ export default class Form extends EventEmitter implements FormDependence {
      * для данного поля будет стёрто из объекта changes.
      * */
     cleanChangesByField(fieldName: string): void {
-        if (this.parent) return void this.parent.cleanChangesByField(concatName(this.name, fieldName));
+        if (this.parent && !this.autonomic) return void this.parent.cleanChangesByField(concatName(this.name, fieldName));
 
         // Если значение есть в pureValues - устанавливаем его
         // Иначе undefined
@@ -512,7 +541,7 @@ export default class Form extends EventEmitter implements FormDependence {
     revert() {
         debug.msg('revert changes');
 
-        if (this.parent) return void this.parent.cleanChangesByField(this.name as string);
+        if (this.parent && !this.autonomic) return void this.parent.cleanChangesByField(this.name as string);
 
         this.setValues(this.pureValues, {
             change: true,
@@ -670,7 +699,7 @@ export default class Form extends EventEmitter implements FormDependence {
         return !this.enabled;
     }
     get enabled() {
-        if (this.parent) return !this.parent.checkFieldDisable(this.name as string);
+        if (this.parent && !this.autonomic) return !this.parent.checkFieldDisable(this.name as string);
         return this.isAvailable;
     }
 
@@ -700,7 +729,7 @@ export default class Form extends EventEmitter implements FormDependence {
      * Далее передаём объект в dispatchEvent.
      * */
     available(type: boolean, names: string[]):void {
-        if (this.parent) return this.parent.available(type, names.length ? names.map(k => concatName(this.name, k)) : [this.name as string])
+        if (this.parent && !this.autonomic) return this.parent.available(type, names.length ? names.map(k => concatName(this.name, k)) : [this.name as string])
         debug.group(`AVAILABILITY %c${Form.getTargetName(this)}%c to %c${type}`, debug.colorName, debug.colorDefault, debug.colorFocus);
 
         const oldAvailable = this.isAvailable;
@@ -754,7 +783,7 @@ export default class Form extends EventEmitter implements FormDependence {
      * @description Вернёт true, если переданное поле является disabled.
      * */
     checkFieldDisable(fieldName: string): boolean {
-        if (this.parent) return this.parent.checkFieldDisable(concatName(this.name, fieldName));
+        if (this.parent && !this.autonomic) return this.parent.checkFieldDisable(concatName(this.name, fieldName));
         const nearestName = findNearestNameFromArray(Object.keys(this.#availabilities), fieldName);
         if (!nearestName) return this.disabled;
 
@@ -784,7 +813,12 @@ export default class Form extends EventEmitter implements FormDependence {
 interface FormParams {
     name: string,
     provide: boolean,
-    parent: Form | null | false
+    parent: Form | null | false,
+    /**
+     * @description The form will be self-contained. They want and will have the opportunity to receive higher education
+     * from their parents, however values, changes, enabling and disabling will be stored inside this form.
+     */
+    autonomic: boolean
 }
 
 interface FormDependence {

src/classes/FormError.ts

@@ -33,4 +33,7 @@ export default class FormError extends Error{
 	static DependencyNotFounded() {
 		return new FormError(`Dependency was not subscribe on form or unsubscribed early.`)
 	}
+	static AutonomicFormWithoutParent() {
+		return new FormError(`The form will always be autonomic unless a parent is specified.`)
+	}
 }