Merge pull request #163 from Jenesius/issue_149

Issue 149

Author: Jenesius

docs/guide/working-with-values.md

@@ -1,91 +1,222 @@
-# Form Validation
+# Working with values
+This page contains all the methods and properties that you will need to work with the state of the form.
 
-For form validation, the **validate** method is used, which returns a boolean value - is
-whether the form is valid. In the process of executing this method, all child elements are checked for
-validity. They also call **validate** methods, if present. This is also the case for the following
-child elements, and so on deeper.
+## Set value {setValues}
 
-```vue{7-9}
-<template>
-<form-field name="age" :validation="ageValidation"/>
-</template>
-<script setup>
-import {Form, FormField} from "jenesius-vue-form";
+The main task of forms is to maintain the current state (value). To change it, use the **setValues** method:
+```ts
+form.setValues({
+     name: "Jack",
+     age: 24
+})
+form.values // { name: "Jack", age: 24 }
+```
+
+### Options
+
+#### values <Badge type="tip">Required</Badge>
+The values when will be set for the form.
+
+#### options <Badge type="info">Optional</Badge>
+An optional parameter, an object with the following properties:
+
+:::info_
+##### changed <Badge type="info">Optional</Badge>
+Boolean value whether the given values are changes. If *true* then values will be projected onto changes.
+
+#### target <Badge type="info">Optional</Badge>
+The name of the target on which setValues was called. You can look at this property as if the method was called
+from the child element whose name was passed to *target*.
 
-function ageValidation(x) {
-return x > 17 || 'So small'
-}
+#### clean <Badge type="info">Optional</Badge>
+Whether to completely overwrite the previous value. By default, *setValues* mixes in the value, but if set
+`clean: true`, the previous value will be completely overwritten by the new one.
+:::
 
-form.setValues({ age: 17 });
-form.validate() // false
+### Examples of using
 
-form.setValues({ age: 24 });
-form.validate() // true
-</script>
+#### Set value
+```ts
+form.setValues({
+     username: "Jack"
+})
+form.values // { username: "Jack" }
+```
+
+#### Set value with target parameter
+```ts
+form.setValues({
+     city: "Emerald City"
+}, { target: "address" })
+form.values // { address: { city: "Emerald City" } }
 ```
 
-For field validation, FormField takes one required parameter:
+#### Using the clean parameter
+```ts
+// Values: { username: "Jenesius", age: 24 }
+form.setValues({ username: "Jenesius", age: 24 })
+
+form.setValues({
+     name: "Jask"
+}, { clean: true })
+form.values // { name: "Jack" }
+```
 
-#### Validation <Badge type = "tip">Required</Badge>
-It has the following type:
+#### Using target and clean together
 ```ts
-interface FormFieldProps {
-validation: FormFieldValidationCallback[] | FormFieldValidationCallback // [!code focus]
-}
+form.setValues({
+     name: "Jack",
+     address: {
+city: "Emerald City"
+     }
+})
+
+form.setValues({
+     code: "00"
+}, { target: "address", clean: true })
+form.values // { name: "Jack", address: { code: "00" } }
 ```
-As you can see from the specification, the field can accept both a single function and an array of functions. The function type is described below:
+
+#### Mixing in the value
 ```ts
-type FormFieldValidationCallback = (value: any) => true | string | boolean
+form.setValues({
+    address: {
+        city: "Emerald City"
+    }
+})
+// { address: { city: "Emerald City" } }
+
+form.setValues({
+    address: {
+        code: "00"
+    }
+})
+form.values // { address: { city: "Emerald City", code: "00" } }
 ```
 
-- If the function returned *true* - the input field is valid, otherwise it is not.
-- If an array of functions is passed, then they will be run one after another and the field will be valid if all
-  functions will return true.
+## Changing values
+As is already clear from **setValues**, if we pass `change: true`, then the work is done with the **changes** state
+forms. For convenient work, alias **change** was created, which automatically sets the changed parameter.
+```ts
+form.change(data) // form.setValues(data, { changed: true })
+```
 
-## Validation Examples
+## Undo changes
+To undo changes (work with changes) use the *revert* method:
+```ts{5}
+form.setValues({username: "Jenesius", age: 24});
+form.change({age: 23, father: true});
+// Values: { username: "Jenesius", age: 23, father: true }
 
-### Size limit
-```vue
-<template>
-<form-field name="token" :validation="validation"/>
-</template>
-<script setup>
-import {FormField, Form} from "jenesius-vue-form";
+form.revert();
+// Values: { username: "Jenesius", age: 24}
+```
 
-const validation = [
-x => x.length > 5 || "That's too short. The minimum length is 5.",
-     x => x.length < 25 || "Value length must be less than 25."
-]
-</script>
+## Clear values
+To completely clear the form, use the **cleanValues** method:
+```ts
+form.setValues({name: "Jack"})
+form.cleanValues(); // Values: {}
+```
+This method also accepts values that will be set instead of the current one:
+```ts
+form.setValues({name: "Jack"})
+form.cleanValues({age: 24}); // Values: { age: 24 }
 ```
-### Checking the dependency of two fields
 
-This example demonstrates how you can use field validation that depends on the value of another field. IN
-In this example, there are two rules:
+## Form Values (Values)
+From the previous examples, you can see that the final value of the form is in `form.values`:
+```ts
+form.setValues({age: 24});
+form.values // { age: 24 }
+```
 
-- If the switch is set to true, then the admin rule is used for Login: admin login starts with
-  $.
-- If the switch is off, then the user rule is used for Login: string length must be greater than 5.
 
-```vue{3}
-<template>
-<form-field type="switch" name="isAdmin"/>
-<form-field name="login" :validation="validation"/>
-</template>
-<script setup>
-import {FormField, Form, ComputedValue} from "jenesius-vue-form";
+## Form changes (Changes)
+To get only the changes, you need to use `form.changes`:
+```ts{4}
+form.setValues({ name: "Jack" })
+form.change({ age: 24 })
+form.values; // { name: "Jack", name: 24 }
+form.changes; // { age: 24 }
+```
 
+## Get value by name
+In some situations, there is a need to get the value of a field by name. For this case, you need to use
+namely the **getValueByName** method.
+
+### Options
+
+#### name <Badge type="info">Optional</Badge>
+The string name of the field to get the value for.
+
+```ts{2}
+form.setValues({ login: "Jack" });
+form.getValueByName('login') // Jack
+```
+::: warning
+Getting a value by property name is erroneous:
+```ts
+form.values['login'] // Wrong
+form.getValueByName('login') // Correct
+```
+If we are talking about simple fields, this will work, but in the case of compound fields (address.country) this
+method will not be able to find the required field value.
+:::
+
+## Accept changes
+To accept all changes or only for a specific field, use the **acceptChanges** method.
+The method clears changes (whole or single field) and sets the cleared value to values.
+
+### Parameter
+
+#### name <Badge type = "info">Optional</Badge>
+If not passed, all changes will be first projected onto values and then cleared. If the value
+passed it must be a string field name.
+
+### Example
+
+```ts
 const form = new Form();
-const isAdmin = ComputedValue(form, "isAdmin"); // For reactive communication
-const validation = [
-login => {
-if (isAdmin.value && !login.startsWith('$'))
-return 'Administrator name must start with $';
-if (!isAdmin.value && login.length < 5)
-return 'Username must be at least 5 characters long.'
-
-         return true;
-     }
-]
-</script>
+form.change({ username: "Jack", age: 24, id: 1 })
+
+form.acceptChanges('username');
+form.pureValues; // { username: "Jack" }
+form.changes // { age: 24, id: 1 }
+
+form.acceptChanges();
+form.pureValues; // { username: "Jack", age: 24, id: 1 }
+form.changes; // {}
+```
+
+## Clear field changes
+The **cleanChangesByField** method undoes the changes for the passed field. This function only works on the changes object and does not
+affects the values object. If the object's child property changes is an object, but the number
+child keys is 0, this property is completely removed from the changes object.
+
+```ts
+form.setValues({age: 24})
+form.change({name: "Jack", age: 25}); // { name: "Jack", age: 25 }
+form.cleanChangesByField('name');
+// Changes: { name: "Jack" }
+// Values: { name: "Jack", age: 24 }
+```
+
+## Check field for change
+The **checkFieldChange** method checks for changes to the passed field name. If the field has been changed
+will return true, false otherwise.
+```ts
+form.change({name: "Jack"});
+form.checkFieldChange('name') // true
+form.checkFieldChange('age') // false
+```
+
+## Form Status (Changed)
+To understand that the form is in a changed state, you need to get the value of the **changed** property;
+```ts
+form.changed // false
+form.change({ name: "Jack" })
+form.changed // true
+form.revert();
+form.changed // false
 ```

docs/ru/guide/working-with-values.md

@@ -164,6 +164,31 @@ form.getValueByName('login') // Correct
 способ не сможет найти нужное значение поля.
 :::
 
+## Принятие изменений
+Для того чтобы подтвердить все изменения или только для конкретного поля, воспользуйтесь методом **acceptChanges**.
+Метод очищает changes (целиком или единичное поле) и устанавливает очищенное значение в values.
+
+### Параметра
+
+#### name <Badge type = "info">Необязательное</Badge>
+Если не передано - все изменения будет сперва проецированы на values, а затем очищены. Если значение 
+передаётся оно должно быть строковым названием поля.
+
+### Пример
+
+```ts
+const form = new Form();
+form.change({ username: "Jack", age: 24, id: 1 })
+
+form.acceptChanges('username');
+form.pureValues; // { username: "Jack" }
+form.changes ; // { age: 24, id: 1 }
+
+form.acceptChanges();
+form.pureValues; // { username: "Jack", age: 24, id: 1 }
+form.changes; // {}
+```
+
 ## Очистка изменений для поля
 Метод **cleanChangesByField** отменяет изменения для переданного поля. Данная функция работает только с объектом changes и не
 затрагивает объект values. Если в дочернее свойство объекта changes является объектом, но при этом количество