App Forms #

A powerful Flutter package that separates form logic from UI components using flutter_form_builder. Build maintainable, testable, and reusable forms with clean architecture principles.

✨ Features #

Core Architecture #

• 🏗️ Clean Architecture: Separate form logic from UI components
• 💉 Dependency Injection: Global form management with singleton pattern
• 🔄 Reactive State Management: Real-time form state updates and validation
• 🎯 Type Safety: Generic type support for form fields
• 📦 Easy Integration: Works seamlessly with flutter_form_builder

Advanced Performance #

• ⚡ Smart Validation: Memoized validation results with intelligent caching
• 🎛️ Dual-Debouncer System: Separate optimization for validation (250ms) and UI updates (16ms/60fps)
• 🧠 Change Detection: Field-level change tracking prevents unnecessary processing
• 📊 Performance Monitoring: Built-in metrics for debugging and optimization
• 🗂️ Memory Management: Automatic cache cleanup and resource disposal

Form Management #

• 📋 Advanced Field Operations: setValue, reset, validation with change tracking
• 🔍 State Tracking: Built-in loading, progress, error, and success states
• 🎭 Lifecycle Hooks: onInit, onSubmit, onValid, and onReset callbacks
• 🔧 Conditional Updates: updateWhen callback for precise UI control
• ⚙️ Auto-validation: Configurable with smart debouncing and caching

🚀 Quick Start #

Installation #

Add the package to your pubspec.yaml:

dependencies:
  app_forms: ^0.7.1
  form_builder_validators: ^11.2.0

Basic Usage #

1. Create Your Form Class

import 'package:app_forms/app_forms.dart';
import 'package:form_builder_validators/form_builder_validators.dart';

class LoginForm extends AppForm {
  // Configure auto-validation
  @override
  bool get autoValidate => true;

  // Define form fields with validation and callbacks
  final email = AppFormField<String>(
    name: 'email',
    initialValue: 'user@example.com',
    validations: FormBuilderValidators.compose([
      FormBuilderValidators.required(),
      FormBuilderValidators.email(),
    ]),
    onChange: (field) {
      print('Email changed: ${field?.value}');
    },
    onValid: (field) {
      print('Email is valid: ${field?.value}');
    },
  );

  final password = AppFormField<String>(
    name: 'password',
    validations: FormBuilderValidators.compose([
      FormBuilderValidators.required(),
      FormBuilderValidators.minLength(6),
    ]),
  );

  LoginForm() {
    setFields([email, password]);
  }

  @override
  Future<void> onInit() async {
    // Initialize form data, API calls, etc.
    print('Form initialized');
  }

  @override
  Future<void> onSubmit(Map<String, dynamic>? values) async {
    // Handle form submission
    print('Submitting: $values');
    
    try {
      // Simulate API call
      await Future.delayed(const Duration(seconds: 2));
      setSuccess(true);
    } catch (e) {
      setHasErrors(true);
    }
  }

  @override
  Future<void> onValid(Map<String, dynamic>? values) async {
    // Called when form becomes valid
    print('Form is valid: $values');
  }

  @override
  void onReset() {
    // Handle form reset
    print('Form reset');
  }
}

2. Inject Forms in main.dart

import 'package:app_forms/app_forms.dart';

void main() {
  // Inject your forms globally
  AppForms.injectForms([
    LoginForm(),
    // Add other forms here
  ]);
  
  runApp(MyApp());
}

3. Build Your UI

class LoginPage extends StatelessWidget {
  const LoginPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Login')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          children: [
            // Form Builder - handles form state and validation
            AppFormBuilder<LoginForm>(
              builder: (form) {
                return Column(
                  children: [
                    FormBuilderTextField(
                      name: form.email.name,
                      validator: form.email.validations,
                      decoration: const InputDecoration(
                        labelText: 'Email',
                        border: OutlineInputBorder(),
                      ),
                    ),
                    const SizedBox(height: 16),
                    FormBuilderTextField(
                      name: form.password.name,
                      validator: form.password.validations,
                      obscureText: true,
                      decoration: const InputDecoration(
                        labelText: 'Password',
                        border: OutlineInputBorder(),
                      ),
                    ),
                  ],
                );
              },
            ),
            const SizedBox(height: 24),
            
            // Form Listener - reacts to form state changes
            AppFormListener<LoginForm>(
              builder: (form) {
                return Column(
                  children: [
                    ElevatedButton(
                      onPressed: form.progressing ? null : form.submit,
                      child: form.progressing
                          ? const CircularProgressIndicator()
                          : const Text('Login'),
                    ),
                    if (form.hasErrors)
                      const Text(
                        'Please fix errors above',
                        style: TextStyle(color: Colors.red),
                      ),
                    if (form.success)
                      const Text(
                        'Login successful!',
                        style: TextStyle(color: Colors.green),
                      ),
                  ],
                );
              },
            ),
          ],
        ),
      ),
    );
  }
}

📚 Advanced Features #

Performance Optimization #

// Conditional UI updates for better performance
AppFormListener<LoginForm>(
  updateWhen: (form) => form.progressing || form.hasErrors,
  builder: (form) {
    return ElevatedButton(
      onPressed: form.progressing ? null : form.submit,
      child: form.progressing 
        ? CircularProgressIndicator() 
        : Text('Submit'),
    );
  },
)

// Performance monitoring
class MyForm extends AppForm {
  void checkPerformance() {
    final metrics = getPerformanceMetrics();
    print('Email validations: ${metrics['email_validations']}');
    print('Cache hits: ${metrics['cache_hits']}');
    print('Form changes: ${metrics['form_changes']}');
  }
  
  @override
  void onReset() {
    clearValidationCache(); // Clear cache on reset for memory efficiency
    super.onReset();
  }
}

Form State Management #

class MyForm extends AppForm {
  void customAction() {
    // Control form states
    setLoading(true);        // Show loading state
    setHasErrors(false);     // Clear errors
    setSuccess(false);       // Clear success state
    
    // Access form values
    final values = getValues();
    
    // Validate programmatically
    final isValid = saveAndValidate();
    
    // Reset form
    reset();
  }
}

Dynamic Field Updates #

class MyForm extends AppForm {
  void updateFieldValue() {
    // Update field value programmatically
    email.value = 'new@example.com';
    updateFieldsValue(); // Sync with form builder
  }
  
  void setServerErrors(Map<String, dynamic> errors) {
    // Set validation errors from server
    setValidationErrors({
      'email': 'Email already exists',
      'password': 'Password too weak'
    });
  }
}

Smart Validation #

final customField = AppFormField<String>(
  name: 'username',
  validations: (value) {
    // Expensive validation - automatically cached
    if (value == null || value.isEmpty) {
      return 'Username is required';
    }
    if (value.length < 3) {
      return 'Username must be at least 3 characters';
    }
    // This validation result is cached for identical inputs
    return null; // Valid
  },
);

🏛️ Architecture #

Core Components #

• AppForm: Abstract base class for all forms
• AppFormField: Type-safe field configuration
• AppForms: Singleton service for dependency injection
• AppFormBuilder: Widget wrapper connecting forms to UI
• AppFormListener: Reactive widget for form state changes

Flow Diagram #

Form Definition → Dependency Injection → UI Binding → State Management
     ↓                    ↓                ↓             ↓
  AppForm           AppForms.inject    AppFormBuilder  AppFormListener

🔧 Configuration Options #

Auto-validation Control #

class MyForm extends AppForm {
  @override
  bool get autoValidate => false; // Disable auto-validation
}

Performance Tuning #

class OptimizedForm extends AppForm {
  @override
  bool get autoValidate => true; // Enable smart caching
  
  OptimizedForm() {
    setFields([email, password]);
  }
  
  @override
  void onInit() {
    // Initialization is automatically optimized with concurrent protection
    super.onInit();
  }
}

// Conditional rebuilds for complex UIs
AppFormListener<OptimizedForm>(
  updateWhen: (form) {
    // Only rebuild when specific conditions are met
    return form.progressing || 
           form.hasErrors || 
           form.email.value?.contains('@') == true;
  },
  builder: (form) => ComplexWidget(form),
)

Custom Debouncing #

The package uses a dual-debouncer system:

• Validation debouncer: 250ms (configurable internally)
• UI update debouncer: 16ms (~60fps) for smooth user experience

This provides optimal performance for both validation and UI responsiveness.

🧪 Testing #

void main() {
  group('LoginForm Tests', () {
    late LoginForm form;
    
    setUp(() {
      form = LoginForm();
      AppForms.injectForms([form]);
    });
    
    tearDown(() {
      // Clean up for better test performance
      AppForms.dispose<LoginForm>();
      form.clearValidationCache();
    });
    
    test('should validate email field with caching', () {
      // First validation
      form.email.setValue('invalid-email');
      expect(form.saveAndValidate(), false);
      
      // Second validation with same value (uses cache)
      form.email.setValue('invalid-email');
      expect(form.saveAndValidate(), false);
      
      // Valid email
      form.email.setValue('valid@email.com');
      expect(form.saveAndValidate(), true);
    });
    
    test('should track performance metrics', () {
      form.email.setValue('test@example.com');
      form.saveAndValidate();
      
      final metrics = form.getPerformanceMetrics();
      expect(metrics['email_validations'], greaterThan(0));
    });
  });
}

📖 API Reference #

Performance APIs #

Form Management APIs #

See the API documentation for detailed information about all available methods and properties.

🤝 Contributing #

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🎯 Performance Benchmarks #

Real-World Performance Improvements #

Best Practices for Maximum Performance #

1. Use updateWhen for complex UIs:

   AppFormListener<MyForm>(
     updateWhen: (form) => form.progressing,
     builder: (form) => ExpensiveWidget(form),
   )
   

2. Clear cache on form reset:

   @override
   void onReset() {
     clearValidationCache();
     super.onReset();
   }
   

3. Monitor performance in debug mode:

   final metrics = form.getPerformanceMetrics();
   debugPrint('Validation cache hits: ${metrics['cache_hits']}');
   

🆘 Support #

• 📁 GitHub Issues
• 📦 Pub.dev Package
• 📧 Email Support
• 🚀 Performance Guide