docs: extend Field API, add dummy pages about CombinedField and `…

…combineFields`

apps/docs/docs/api/entities/combined-field.md

@@ -0,0 +1,45 @@
+# CombinedField
+
+Result of [combineFields](../factories/combine-fields.md) factory, aggregates multiple fields shape in single one.
+
+:::danger
+WIP
+:::
+
+## API reference
+
+```ts
+const field: CombinedField<{ a: Field<number>; b: Field<string> }>;
+
+// Commands
+
+field.reset; // Event<void>
+field.change; // Event<{ a?: number; b?: string }>
+field.revalidate; // Event<Array<'blur' | 'change' | 'submit'>>
+
+// Additional API
+
+field.fields; // { a: Field<number>; b: Field<string> }
+field.mapFields; // (mapValue, mapShape?) => MappedShape
+
+// Value and modification state
+
+field.$value; // Store<{ a: number; b: string }>
+field.$dirty; // Store<boolean>
+field.$pristine; // Store<boolean>
+field.$modified; // Store<boolean>
+
+// Validation state
+
+field.$valid; // Store<boolean>
+field.$errors; // Store<ValidationError[]>
+field.$invalid; // Store<boolean>
+field.$validating; // Store<boolean>
+
+// Interaction state
+
+field.$focused; // Store<boolean>
+field.$blurred; // Store<boolean>
+field.$touched; // Store<boolean>
+field.$visited; // Store<boolean>
+```

apps/docs/docs/api/entities/field.md

@@ -1,32 +1,74 @@
-# Field
+# Field <Badge type="info" text="core" />
 
-Static declarative unit without any platform specific
+`Field` is main low-level structure for static logic.
+
+:::danger
+WIP
+:::
 
 ## API reference
 
 ```ts
 const field: Field<number>;
 
+// Commands
+
 field.blur; // Event<void>
 field.focus; // Event<void>
 field.reset; // Event<void>
 field.change; // Event<number>
+field.revalidate; // Event<Array<'blur' | 'change' | 'submit'>>
+
+// Events
+
+field.changed; // Event<number>
+field.focused; // Event<void>
+field.blurred; // Event<void>
+
+// Value and modification state
 
 field.$value; // Store<number>
 field.$dirty; // Store<boolean>
 field.$pristine; // Store<boolean>
 field.$modified; // Store<boolean>
 field.$disabled; // Store<boolean>
 
+// Validation state
+
+field.$valid; // Store<boolean>
+field.$errors; // Store<ValidationError[]>
+field.$invalid; // Store<boolean>
+field.$validating; // Store<boolean>
+
+// Interaction state
+
 field.$focused; // Store<boolean>
 field.$blurred; // Store<boolean>
 field.$touched; // Store<boolean>
 field.$visited; // Store<boolean>
 ```
 
-## Value API
+## Commands
+
+### `change` - [`Event<Value>`](https://effector.dev/docs/api/effector/event)
+
+Change current value.
+
+Will be ignored if field is `$disabled` or passed value is equal to current value (see [config.valueEq](/api/factories/create-field.md#valueeq))
+
+- `focus`: [`Event<void>`](https://effector.dev/docs/api/effector/event) - mark field as focused
+  - Will be ignored if field is `$disabled` or already `$focused`
+- `blur`: [`Event<void>`](https://effector.dev/docs/api/effector/event) - marks field as not focused
+  - Will be ignored if field is `$blurred`
+- `reset`: [`Event<void>`](https://effector.dev/docs/api/effector/event) - reset the whole field
+  - Field's value will be reset to `config.defaultValue`
+- `revalidate`: [`Event<Array<'blur' | 'change' | 'submit'>>`](https://effector.dev/docs/api/effector/event) - force field validations with provided triggers
+
+## Events
 
-- `field.change`: [`Event<Value>`](https://effector.dev/docs/api/effector/event) - change current value
+- `changed`: [`Event<Value>`](https://effector.dev/docs/api/effector/event) - Fires when the current value changes
+- `focused`: [`Event<void>`](https://effector.dev/docs/api/effector/event) - Fires when the field actually achieves focus
+- `blurred`: [`Event<void>`](https://effector.dev/docs/api/effector/event) - Fires when the field actually loses focus
 
 ```ts
 const field: Field<number>;

apps/docs/docs/api/factories/combine-fields.md

@@ -0,0 +1,5 @@
+# `combineFields`
+
+:::danger
+WIP
+:::

apps/docs/docs/api/factories/create-field.md

@@ -2,27 +2,77 @@
 
 Creates single static [Field](/api/entities/field)
 
+:::danger
+WIP
+:::
+
 ## Formulae
 
-### `createField({ defaultValue = null, disabled = true } = {})`
+### `createField({ defaultValue?, disabled?, valueEq?, validate? })`
+
+Creates basic [Field](../entities/field).
+
+## Config details
 
-### `createField({ defaultValue? })`
+### `defaultValue`
 
-Creates basic [Field](/api/entities/field) with default value
+Optional default value or store with default value
+
+- type: `SourceValue<Value>`
+- default: `null`
 
 ```ts
 const name = createField({
-  defaultValue: ''
+  defaultValue: 'John'
+});
+const copyName = createField({
+  defaultValue: name.$value
+});
+
+sample({
+  clock: resetCopied,
+  target: copyName.reset // After reset copyName's value will be taken from name.$value
+});
+```
+
+### `disabled`
+
+Disabled fields will ignore any `change` or `focus` commands.
+
+- type: `SourceValue<boolean>`
+- default: `false`
+
+You can pass plain boolean value:
+
+```ts
+const field = createField({ defaultValue: '', disabled: true });
+```
+
+Or boolean store:
+
+```ts
+const $mode = createStore<'edit' | 'view'>('view');
+const disabledStore = createField({
+  defaultValue: '',
+  // Note: now it's DerivedStore (can't be changed externally)
+  disabled: $mode.map(mode => mode === 'view')
 });
 ```
 
-### `createField({ defaultValue, validate: Validator })`
+### `valueEq`
+
+Values equality comparator
 
-Creates [Field](/api/entities/field) with single validation
+- type: `(left: Value, right: Value) => boolean`
+- default: `Object.is`
 
 ```ts
-const age = createField({
-  defaultValue: 0,
-  validate: value => value < 10 && 'should be gt than 10'
+const field = createField<string[]>({
+  defaultValue: [],
+  valueEq: shallowEqualArray
 });
 ```
+
+### `validate`: `ValidationRule | ValidationConfig | ValidationConfig[]`
+
+- `ValidationRule`: `(value: Value) => ValidationResult`