Merge pull request #1228 from flutter-form-builder-ecosystem/add-states-617

Add field and form states

Author: deandreamatias

README.md

@@ -5,7 +5,7 @@ This package helps in creation of data collection forms in Flutter by removing t
 Also included are common ready-made form input fields for FormBuilder. This gives you a convenient way of adding common ready-made input fields instead of creating your own FormBuilderField from scratch.
 
 [![Pub Version](https://img.shields.io/pub/v/flutter_form_builder?logo=flutter&style=for-the-badge)](https://pub.dev/packages/flutter_form_builder)
-[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/flutter-form-builder-ecosystem/flutter_form_builder/Base?logo=github&style=for-the-badge)](https://github.com/flutter-form-builder-ecosystem/flutter_form_builder/actions/workflows/base.yaml)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/flutter-form-builder-ecosystem/flutter_form_builder/base.yaml?branch=main&logo=github&style=for-the-badge)](https://github.com/flutter-form-builder-ecosystem/flutter_form_builder/actions/workflows/base.yaml)
 [![Codecov](https://img.shields.io/codecov/c/github/flutter-form-builder-ecosystem/flutter_form_builder?logo=codecov&style=for-the-badge)](https://codecov.io/gh/flutter-form-builder-ecosystem/flutter_form_builder/)
 [![CodeFactor Grade](https://img.shields.io/codefactor/grade/github/flutter-form-builder-ecosystem/flutter_form_builder?logo=codefactor&style=for-the-badge)](https://www.codefactor.io/repository/github/flutter-form-builder-ecosystem/flutter_form_builder)
 ___

lib/src/form_builder.dart

@@ -1,5 +1,3 @@
-import 'dart:developer';
-
 import 'package:flutter/material.dart';
 import 'package:flutter_form_builder/flutter_form_builder.dart';
 
@@ -102,16 +100,33 @@ typedef FormBuilderFields
     = Map<String, FormBuilderFieldState<FormBuilderField<dynamic>, dynamic>>;
 
 class FormBuilderState extends State<FormBuilder> {
-  final _formKey = GlobalKey<FormState>();
+  final GlobalKey<FormState> _formKey = GlobalKey<FormState>();
+  final FormBuilderFields _fields = {};
+  final Map<String, dynamic> _instantValue = {};
+  final Map<String, dynamic> _savedValue = {};
+  // Because dart type system will not accept ValueTransformer<dynamic>
+  final Map<String, Function> _transformers = {};
 
   bool get enabled => widget.enabled;
 
-  final FormBuilderFields _fields = {};
+  /// Verify if all fields on form are valid.
+  bool get isValid => fields.values.every((field) => field.isValid);
+
+  /// Will be true if some field on form are dirty.
+  ///
+  /// Dirty: The value of field is changed by user or by logic code.
+  bool get isDirty => fields.values.any((field) => field.isDirty);
+
+  /// Will be true if some field on form are touched.
+  ///
+  /// Touched: The field is focused by user or by logic code.
+  bool get isTouched => fields.values.any((field) => field.isTouched);
+
+  /// Get initialValue.
+  Map<String, dynamic> get initialValue => widget.initialValue;
 
-  //because dart type system will not accept ValueTransformer<dynamic>
-  final _transformers = <String, Function>{};
-  final _instantValue = <String, dynamic>{};
-  final _savedValue = <String, dynamic>{};
+  /// Get all fields of form.
+  FormBuilderFields get fields => _fields;
 
   Map<String, dynamic> get instantValue =>
       Map<String, dynamic>.unmodifiable(_instantValue.map((key, value) =>
@@ -122,11 +137,6 @@ class FormBuilderState extends State<FormBuilder> {
       Map<String, dynamic>.unmodifiable(_savedValue.map((key, value) =>
           MapEntry(key, _transformers[key]?.call(value) ?? value)));
 
-  /// Returns values after saving
-  Map<String, dynamic> get initialValue => widget.initialValue;
-
-  FormBuilderFields get fields => _fields;
-
   dynamic transformValue<T>(String name, T? v) {
     final t = _transformers[name];
     return t != null ? t.call(v) : v;
@@ -150,9 +160,6 @@ class FormBuilderState extends State<FormBuilder> {
     widget.onChanged?.call();
   }
 
-  bool get isValid =>
-      fields.values.where((element) => !element.isValid).isEmpty;
-
   void removeInternalFieldValue(
     String name, {
     required bool isSetState,
@@ -282,22 +289,15 @@ class FormBuilderState extends State<FormBuilder> {
     );
   }
 
+  /// Reset form to `initialValue`
   void reset() {
-    _formKey.currentState!.reset();
-    for (var field in _fields.entries) {
-      try {
-        field.value.didChange(getRawValue(field.key));
-      } catch (e, st) {
-        log(
-          'Error when resetting field: ${field.key}',
-          error: e,
-          stackTrace: st,
-          level: 2000,
-        );
-      }
-    }
+    _formKey.currentState?.reset();
   }
 
+  /// Update fields values of form.
+  /// Useful when need update all values at once, after init.
+  ///
+  /// To load all values at once on init, use `initialValue` property
   void patchValue(Map<String, dynamic> val) {
     val.forEach((key, dynamic value) {
       _fields[key]?.didChange(value);

lib/src/form_builder_field.dart

@@ -74,6 +74,7 @@ class FormBuilderFieldState<F extends FormBuilderField<T>, T>
   String? _customErrorText;
   FormBuilderState? _formBuilderState;
   bool _touched = false;
+  bool _dirty = false;
   late FocusNode effectiveFocusNode;
   FocusAttachment? focusAttachment;
 
@@ -106,6 +107,16 @@ class FormBuilderFieldState<F extends FormBuilderField<T>, T>
   bool get enabled => widget.enabled && (_formBuilderState?.enabled ?? true);
   bool get _readOnly => !(_formBuilderState?.widget.skipDisabled ?? false);
 
+  /// Will be true if the field is dirty
+  ///
+  /// The value of field is changed by user or by logic code.
+  bool get isDirty => _dirty;
+
+  /// Will be true if the field is touched
+  ///
+  /// The field is focused by user or by logic code
+  bool get isTouched => _touched;
+
   InputDecoration get decoration => widget.decoration.copyWith(
         errorText: widget.enabled || _readOnly
             ? widget.decoration.errorText ?? errorText
@@ -173,6 +184,7 @@ class FormBuilderFieldState<F extends FormBuilderField<T>, T>
 
   void _informFormForFieldChange() {
     if (_formBuilderState != null) {
+      _dirty = true;
       if (enabled || _readOnly) {
         _formBuilderState!.setInternalFieldValue<T>(
           widget.name,
@@ -212,7 +224,8 @@ class FormBuilderFieldState<F extends FormBuilderField<T>, T>
   @override
   void reset() {
     super.reset();
-    setValue(initialValue);
+    didChange(initialValue);
+    _dirty = false;
     if (_customErrorText != null) {
       setState(() => _customErrorText = null);
     }

pubspec.yaml

@@ -3,6 +3,7 @@ description: This package helps in creation of forms in Flutter by removing the
 version: 7.8.0
 repository: https://github.com/flutter-form-builder-ecosystem/flutter_form_builder
 issue_tracker: https://github.com/flutter-form-builder-ecosystem/flutter_form_builder/issues
+homepage: https://github.com/flutter-form-builder-ecosystem
 funding: 
   - https://opencollective.com/flutter-form-builder-ecosystem