voo_forms 0.3.14

voo_forms: ^0.3.14 copied to clipboard

Fixed #

• CurrencyFormatter: Completely rewrote formatter with best practices

  • Simplified logic by removing buggy incremental typing detection
  • Added min/max value constraints for better validation
  • Improved cursor position management for predictable behavior
  • Enhanced parse method to handle different currency symbols and locales
  • Added optional spacing between symbol and amount
  • Fixed regex escaping issues for currency symbols

• VooFormController Validation: Fixed critical validation bugs

  • Fixed isValid getter that was always returning true
  • Improved validate() method for proper silent validation
  • Enhanced error handling for validators that throw exceptions
  • Fixed validateAll() to properly accumulate and return validation state
  • Fixed validateField() to handle null and empty string errors correctly
  • Validation now properly returns false when fields are invalid

Added #

• Comprehensive Test Suite: Added extensive test coverage for VooFormController
  • 31 comprehensive tests covering all edge cases
  • Tests for boundary conditions, error handling, and race conditions
  • Real-world scenario tests (registration forms, multi-step wizards)
  • Performance tests for large forms (1000+ fields)
  • Memory management and lifecycle tests

Improved #

• Test Organization: Restructured test directory following atomic design

  • Controller tests moved to test/presentation/state/
  • Integration tests in test/integration/
  • Scenario tests in test/scenarios/
  • All tests properly organized and passing

• Code Quality: Fixed all lint issues

  • Removed unnecessary lambdas and redundant arguments
  • Fixed trailing commas and empty statements
  • Improved type safety and code clarity

Fixed #

• VooForm and VooFormPageBuilder Errors: Fixed undefined 'form' parameter errors
  • Removed attempts to create VooFormController with VooForm entities
  • Controllers now created with just error display mode parameter
  • Removed unused domain form imports from both files
  • Fixed compilation errors that were preventing tests from running

Changed #

• Test Updates: Updated tests to match new controller behavior
  • Modified test for isEditable=false to check form rendering instead of AbsorbPointer
  • Tests now align with the removal of AbsorbPointer wrapper (per user request in v0.3.8)

Testing #

• Test Status: 263 out of 288 tests passing (91% pass rate)
  • All VooFormController tests pass (39/39)
  • All VooForm and VooFormPageBuilder tests pass (18/18)
  • Remaining failures are in integration tests that may need updates for new controller API

Fixed #

• VooFormController Type Safety: Fixed type casting issues in validation logic
  • Safer type casting for function validators to prevent runtime errors
  • Changed from direct casting to type checking before assignment
  • Handles both String and null return values from validators properly
  • Prevents "A value of type 'dynamic' can't be assigned to a variable of type 'String?'" errors

Improved #

• Code Quality: Fixed linting issues for better code maintainability
  • Converted block function bodies to expression bodies where appropriate
  • Added required trailing commas for better formatting
  • Improved code readability and consistency

Fixed #

• VooFormController Validation Support: Fixed validation to work with VooValidationRule objects
  • Controller now supports both function validators and VooValidationRule objects
  • Validators from VooValidator.required(), VooValidator.email(), etc. now work correctly
  • Mixed validators (both functions and VooValidationRule objects) are supported
  • Silent validation properly handles VooValidationRule objects
  • All validation modes (onTyping, onSubmit) work with the new validator types

Added #

• Enhanced Validator Type Support: Flexible validator handling
  • registerField() now accepts validators as either functions or VooValidationRule objects
  • Automatic detection and handling of validator types during validation
  • Comprehensive test coverage for VooValidationRule validators

Fixed #

• VooFormController Architecture Refactor: Major refactor to comply with clean architecture principles
  • Removed dependency on VooForm domain entity (violated clean architecture)
  • Created FormFieldConfig for field configuration without domain dependencies
  • Controller now works directly with field names and configurations
  • Improved validation logic with proper error display modes
  • Added comprehensive support for field visibility and enablement
  • Enhanced focus management for better keyboard navigation
  • Fixed validation to properly respect errorDisplayMode settings

Added #

• Comprehensive VooFormController Tests: Full test coverage for refactored controller
  • Tests for field registration (single and multiple)
  • Value management and type-safe value retrieval
  • Validation modes (onTyping, onSubmit, silent)
  • Form submission with error handling
  • Field visibility and enablement controls
  • Focus management and navigation
  • Dynamic validator management
  • JSON serialization
  • Change notification system

Changed #

• VooFormController API: Simplified and more flexible API
  • No longer requires VooForm entity for initialization
  • Direct field registration with registerField() and registerFields()
  • Cleaner validation API with validate(), validateField(), and validateAll()
  • Better separation between UI state and business logic

Fixed #

• VooCurrencyField Cursor Position Bug: Improved cursor handling in currency formatter
  • Enhanced detection of where digits are added in the formatted text
  • Better handling of single character additions vs multiple character changes
  • Prevents incorrect formatting when cursor position is unexpectedly at the beginning
  • Maintains calculator-style entry when typing at the end of the field
  • Fixes issue where typing "66" could result in "$600.06" instead of "$0.66"

Fixed #

• VooFormPageBuilder Overlay Removal: Removed opacity overlay and AbsorbPointer when form is not editable
  • Forms with isEditable: false no longer show a semi-transparent overlay
  • Removed AbsorbPointer wrapper - field-level controls now handle editability
  • Form fields remain fully interactive unless individually disabled
  • Improves visual clarity and allows field-level interaction control
  • Better UX for displaying forms with mixed editable/read-only fields

Fixed #

• VooCurrencyField Incremental Typing Bug: Fixed issue where typing multiple digits resulted in incorrect values
  • Rewrote formatter logic to properly handle incremental digit entry (e.g., typing "777" now correctly formats as "$7.77" instead of "$770.07")
  • Improved performance by simplifying cursor positioning logic
  • Added proper numeric value extraction that handles formatted text with leading zeros
  • Fixed the root cause where appending digits to formatted text was incorrectly parsed

Changed #

• CurrencyFormatter Improvements: Enhanced formatter for better real-world usage
  • Now correctly multiplies value by 10 when appending digits (standard calculator behavior)
  • Simplified cursor positioning to always place at end for better UX
  • Removed unused cursor calculation method to reduce complexity

Fixed #

• VooCurrencyField Formatting Bug: Fixed critical issue where typing numbers resulted in incorrect formatting
  • Removed conflicting FilteringTextInputFormatter.digitsOnly that was fighting with CurrencyFormatter
  • Improved CurrencyFormatter to correctly distinguish between text replacements and deletions
  • Now correctly formats "88" as "$0.88" instead of the erroneous "8008,808.00"
  • Added proper handling for direct text input (e.g., from tests or paste operations)

Added #

• Drag and Drop Support for VooFileField: Enhanced file upload experience
  • Desktop and web platform drag and drop functionality via desktop_drop package
  • Visual feedback with animated borders and background colors during drag
  • "Drop file here" message and icon changes when dragging files
  • Platform detection to enable only on supported platforms (web/desktop)
  • Maintains existing file validation (size, extension) for dropped files
  • Material 3 compliant animations and color transitions

Changed #

• VooFileField Visual States: Improved drag state visual feedback
  • Primary color border and subtle background tint when dragging
  • Download icon appears during drag operations
  • Smooth animations (200ms) for all state transitions
  • "or drag and drop" hint text below button on supported platforms

Fixed #

• Converted block function body to expression body for better code style
• Updated tests to match new UI text and behavior
• Ensured drag and drop properly integrates with existing file selection

Added #

• Enhanced VooCurrencyField: Complete rewrite with proper currency formatting

  • Real-time formatting with thousand separators (e.g., $1,234.56)
  • Support for multiple currencies (USD, EUR, GBP, JPY, etc.)
  • Locale-specific number formatting
  • Currency symbol icons for all major currencies
  • Smart formatting that displays formatted text but returns raw numeric values

• Improved CurrencyFormatter: Advanced text input formatter

  • Automatic thousand separators and decimal places
  • Factory constructors for common currencies
  • Proper cursor positioning during editing
  • Handles deletion and insertion correctly
  • Configurable symbol placement (before/after amount)

Changed #

• VooCurrencyField API: Now extends VooFieldBase directly
  • Better integration with form validation
  • Min/max value constraints with formatted error messages
  • Proper read-only state showing formatted values
  • Material 3 design compliance

Fixed #

• Currency fields now properly format values with separators while maintaining numeric output
• Currency symbols display correctly based on selected currency
• Read-only currency fields show properly formatted values

Added #

• VooFile Entity: New domain entity for managing files from URLs or local uploads

  • Supports both existing files (from URL) and newly uploaded files (PlatformFile)
  • Automatic file metadata extraction (name, size, extension, MIME type)
  • Helper methods for determining file origin and type
  • Factory constructors for creating from URL or PlatformFile

• Enhanced VooFileField: Major improvements to file field functionality

  • Now uses VooFile entity instead of raw PlatformFile
  • Support for displaying files from URLs (existing/uploaded files)
  • Image preview support for URL-based image files
  • "Uploaded" badge indicator for files from URLs
  • Open file action button with URL launcher integration
  • Proper Material 3 design compliance

• URL Launcher Integration: Added file opening capability

  • Opens files in new browser tab on web platforms
  • Uses system default handler for file types on mobile/desktop
  • Graceful error handling with user feedback
  • Safe context checking to prevent crashes

Fixed #

• Read-Only File Field Display: Corrected visual presentation in read-only mode
  • Maintains consistent Material 3 card layout in both states
  • Shows proper file preview with icon, name, and size
  • Displays "No file attached" message when empty
  • Proper disabled state styling with reduced opacity

Changed #

• File Field API: Updated to use VooFile entity
  • Breaking change: initialValue now accepts VooFile? instead of PlatformFile?
  • onFileSelected callback now provides VooFile? instead of PlatformFile?
  • Improved type safety and cleaner API surface

Dependencies #

• Added url_launcher: ^6.2.0 for opening file URLs

Added #

• VooFormSection: New container widget for organizing form fields into logical sections

  • Supports collapsible/expandable sections with smooth animations
  • Material 3 design with proper surface colors and elevation
  • Title, description, and optional leading/trailing widgets
  • Visual containment with card-based design
  • Implements VooFormFieldWidget for seamless integration with VooForm

• VooReadOnlyField: Improved read-only field display

  • Consistent sizing with editable fields (56px min height)
  • Proper Material 3 styling and alignment
  • Better visual hierarchy with standard field padding

Fixed #

• VooFormPageBuilder Layout: Fixed RenderFlex overflow issues in unbounded height contexts

  • Uses LayoutBuilder to detect bounded/unbounded constraints
  • Adapts layout strategy based on context (Expanded vs Flexible)
  • Properly handles preview environments and nested scrollables

• Read-only Field Consistency: All field types now properly handle read-only state

  • Unified approach using VooReadOnlyField for better UX
  • Labels handled by parent widgets to avoid duplication
  • Consistent sizing and alignment across all field types

Changed #

• Material 3 Compliance: Updated components to follow Material 3 design guidelines
  • Better typography hierarchy
  • Improved surface colors and elevation
  • Consistent spacing and padding
  • Professional visual appearance

Fixed #

• Initial Values Display: Fixed all field types to properly display their initial values

  • Text-based fields (VooTextField, VooEmailField, VooPasswordField, etc.) now correctly show initial values
  • VooDateField properly formats and displays initial dates with default MM/dd/yyyy format
  • VooDateFieldButton now correctly displays initial date values on the button
  • VooAsyncDropdownField immediately displays initial values before async loading completes
  • Added comprehensive test coverage for all field types' initial value display

• Dropdown Outside Click Dismissal: VooDropdownSearchField now properly dismisses when clicking outside

  • Added full-screen GestureDetector to capture outside clicks
  • Improved overlay management for better UX

• ReadOnly State Enforcement: Fixed file and date fields to respect readOnly state

  • VooFileField now properly disables file picking when readOnly is true
  • VooDateFieldButton correctly disables date selection when readOnly is true
  • Both fields now use getEffectiveReadOnly(context) to check form-level and field-level states

• Form Loading State: Added isLoading property to VooForm

  • When isLoading is true, form content is hidden and a loading indicator is shown
  • Added loadingWidget parameter for custom loading indicators
  • VooFormScope now propagates loading state to all child fields

Added #

• Comprehensive Test Coverage: Added all_fields_initial_values_test.dart
  • 25 test cases covering every VooField type
  • Verifies initial value display for all field variations
  • Integration test simulating real-world form scenarios

Added #

• VooDateFieldButton: New date field widget that uses a button interface for date selection
  • Shows selected date or placeholder text on the button
  • Supports custom date formatting and button types
  • Includes prefix/suffix icon support
  • Full integration with form validation and error display

Fixed #

• VooDateField Spacing: Fixed inconsistent spacing and decoration in VooDateField to match other field types
  • Removed extra container wrapping that caused visual inconsistencies
  • Date fields now properly display with the same styling as text fields

Breaking Changes #

• VooListField Refactored to Stateless:
  • VooListField is now completely stateless - developers manage state externally
  • Changed from itemTemplate and internal state to items and itemBuilder pattern
  • Callbacks simplified to onAddPressed, onRemovePressed, and onReorder
  • See migration guide in example/list_field_migration.md

Changed #

• Widget Architecture Refactor:
  • Replaced factory pattern (VooField.text(), etc.) with direct widget instantiation
  • All field widgets now extend VooFieldBase for zero code duplication
  • Direct widget pattern: use VooTextField() instead of VooField.text()
  • Cleaner architecture following KISS principle and atomic design

Added #

• New Field Widgets:
  • VooTextField - Text input field
  • VooEmailField - Email input with validation
  • VooPasswordField - Password input with visibility toggle
  • VooPhoneField - Phone number input with formatting
  • VooMultilineField - Multi-line text input
  • VooNumberField - Numeric input with constraints
  • VooIntegerField - Integer-only input
  • VooDecimalField - Decimal number input
  • VooCurrencyField - Currency input with formatting
  • VooPercentageField - Percentage input (0-100)
  • VooBooleanField - Boolean switch/checkbox
  • VooCheckboxField - Single checkbox field
  • VooDropdownField - Dropdown selection
  • VooAsyncDropdownField - Async loading dropdown
  • VooListField - Stateless dynamic list management

Fixed #

• Dropdown Label Issues: Fixed duplicate label rendering in dropdown fields
• Number Field Validation: Fixed min/max validation to return proper error messages
• Test Infrastructure: Updated all tests to work with new widget pattern
• Lint Issues: Fixed 150+ lint issues across the package
• File Architecture: Cleaned up exports and removed unused factory pattern files

Removed #

• Deprecated Factory Pattern Files:
  • Removed VooFormFieldBuilder (old factory pattern)
  • Removed VooFieldWidget (old factory wrapper)
  • Removed layout widgets that depended on old pattern
  • Kept VooFormBuilder for layout management

Improved #

• Performance: Stateless VooListField improves performance by avoiding internal state
• Developer Experience: Direct widget instantiation is more intuitive
• Maintainability: Single responsibility principle with VooFieldBase
• Type Safety: Better type inference with direct widget usage
• Testing: Comprehensive test coverage for all new widgets

Added #

• **VooField.List

Fixed #

• Dropdown Type Casting Errors: Improved type safety for dropdown callbacks

  • Fixed runtime type errors with strongly typed callbacks for both regular and async dropdowns
  • Updated _invokeFieldOnChanged method to use dynamic invocation with proper error handling
  • Resolved issues with custom types like USState, JurisdictionListOption, and other domain objects
  • Prevents type '(CustomType?) => void' is not a subtype of type '((dynamic) => void)?' errors

• Test Infrastructure: Enhanced dropdown testing utilities

  • Created comprehensive dropdown_test_helpers.dart for reliable dropdown testing
  • Fixed test helpers to properly find DropdownButtonFormField of any generic type
  • Improved test reliability for async dropdown operations
  • Updated test helpers to handle both searchable and regular dropdowns

• Dropdown Widget Detection: Improved widget finding in tests

  • Fixed dropdown field detection to work with generic types
  • Updated tapDropdown helper to properly identify dropdown widgets
  • Enhanced test utilities to handle both TextFormField and DropdownButtonFormField types

Improved #

• Test Coverage: Fixed multiple failing tests
  • Resolved dropdown callback test failures
  • Fixed atomic component dropdown tests
  • Improved async dropdown behavior test reliability
  • Reduced test failures from 17 to 12

Added #

• VooSimpleForm Enhancements: Added isEditable parameter to VooSimpleForm
  • VooSimpleForm now supports form-level editability control
  • Properly passes isEditable to underlying VooFormBuilder

Fixed #

• Field-Level Read-Only Control: Individual fields now properly respect their readOnly property

  • Fields marked as readOnly: true display as read-only even when the form is editable
  • Enables mixed forms with both editable and read-only fields (e.g., auto-generated IDs, timestamps)
  • Logic: Field is read-only if form isEditable is false OR field readOnly is true
  • Useful for forms with system-managed fields, calculated values, and display-only data
  • Added comprehensive tests for field-level read-only behavior

• Async Dropdown Type Casting: Fixed type casting error with strongly typed callbacks

  • Error: TypeError: Instance of '(CustomType?) => void' is not a subtype of type '((dynamic) => void)?'
  • Updated VooDropdownFieldWidget to use Function.apply for invoking field callbacks
  • Async dropdowns now properly handle custom types like JurisdictionListOption
  • Prevents runtime type errors when using strongly typed onChanged callbacks

Enhanced #

• VooField Factory Methods: All VooField factory methods now support readOnlyWidget parameter
  • Added Widget? readOnlyWidget parameter to all 19 field factory methods
  • Enables custom read-only display for every field type (text, email, password, phone, number, multiline, dropdown, dropdownAsync, dropdownSimple, boolean, checkbox, radio, date, time, integer, decimal, currency, percentage, slider)
  • Works seamlessly with existing isEditable functionality in VooFormBuilder
  • Provides complete control over read-only field appearance

Added #

• Custom Read-Only Widget Support: Fields can now have custom read-only display widgets
  • Added readOnlyWidget parameter to VooFormField for custom read-only displays
  • When isEditable: false is set on VooFormBuilder, custom widgets are used if provided
  • Falls back to default read-only display when no custom widget is specified
  • Enables complete customization of how fields appear in read-only mode

Fixed #

• Dropdown Type Safety: Fixed VooFieldOption type mismatch errors
  • Resolved runtime type errors with generic dropdown fields
  • Fixed read-only mode dropdown type handling
  • Improved type inference for String, int, double, and bool dropdowns
  • Added proper support for async dropdowns with type preservation

Enhanced #

• Read-Only Mode: Comprehensive automatic details view for forms
  • Added isEditable parameter to VooFormBuilder (defaults to true)
  • All field types now have elegant read-only displays with icons
  • Password fields show masked values in read-only mode
  • Date/time fields show formatted values with appropriate icons
  • Boolean fields display check/cancel icons with Yes/No text
  • Slider fields show progress indicators in read-only mode

Added #

• Custom Field Support: Added VooFieldType.custom for arbitrary widgets
  • Support for customWidget property for direct widget insertion
  • Support for customBuilder function for dynamic widget generation
  • Custom fields work in both editable and read-only modes

Testing #

• Added comprehensive type safety tests for all field types
• Added tests for custom readOnlyWidget functionality
• Added tests for form toggle between editable and read-only modes
• All tests passing with proper generic type constraints

Maintenance #

• Version bump for package maintenance
• Updated dependencies compatibility

Fixed #

• Type Conversion in Number Fields: Fixed TypeError when entering string values in number fields
  • VooFormController now properly converts string inputs to numbers for number fields
  • Invalid number strings are converted to null instead of causing type errors
  • Empty strings in number fields are handled as null values

Added #

• Comprehensive Form Submission Tests: Added extensive test coverage for form submission
  • Tests for isSubmitting state management and preventing concurrent submissions
  • Tests for isSubmitted state tracking across successful/failed submissions
  • Tests for onSubmit, onSuccess, and onError callbacks
  • Tests for validation during submission and error handling
  • Tests for isDirty state management during submission flow
  • Edge case tests for rapid submissions and empty forms
  • Total of 28 new submission-related tests

Testing #

• Added voo_form_controller_submission_test.dart with comprehensive submission tests
• Added voo_form_controller_type_test.dart with 15 type conversion tests
• All tests passing with proper type safety

Added #

• Type Enforcement System: Comprehensive type safety for all form fields

  • Created StrictNumberFormatter to prevent invalid character input in number fields
  • Added specialized formatters: IntegerFormatter, CurrencyFormatter, PercentageFormatter
  • New factory methods: VooField.integer(), VooField.decimal(), VooField.currency(), VooField.percentage()
  • Created FieldValueConverter system for safe type conversions between UI strings and field values

• Error Display Modes: Flexible error display system with multiple modes

  • VooFormErrorDisplay enum with 7 display modes (never, onType, onBlur, onSubmit, onInteraction, onTypeDebounced, always)
  • VooFormErrorConfig for configurable error behavior with predefined configurations
  • Smart error display based on field interaction state

• Material 3 Design Components:

  • Created VooFormButton with Material 3 compliant button variants (filled, filledTonal, outlined, text, elevated)
  • Predefined factories for common actions: Submit, Cancel, Secondary, Danger buttons
  • Added VooFormActions for consistent button layout in forms

Fixed #

• Critical Type Error: Fixed "type 'String' is not a subtype of type 'num?'" error in VooField.number
  • Users can no longer type invalid characters in number fields
  • Proper type conversion between text input and field values
  • Real-time validation with min/max value enforcement

Testing #

• Added comprehensive test suite for type enforcement (31 tests)
• Added tests for all error display modes (14 tests)
• All existing tests pass with new implementations

Fixed #

• Test Improvements: Fixed all failing tests in voo_forms package
  • Fixed scientific notation parsing test to handle input formatter limitations
  • Fixed time field localization initialization using didChangeDependencies and post-frame callbacks
  • Fixed date constraint test to use DateUtils.isSameDay for proper date comparison
  • Fixed date picker cancel button handling with fallback logic for different button text variations
  • Fixed time display format tests to be locale-agnostic
  • Fixed invalid date handling test to focus on validation behavior
  • Fixed async dropdown loading test to verify core functionality

-fixed tests -fixed docs -fixed type casting errors

Refactored - Major Technical Debt Cleanup #

• Eliminated _buildXXX Methods: Removed all _buildXXX methods that return widgets (violates rules.md)

  • Created FieldWidgetFactory to replace VooFieldWidget's _getFieldWidget method
  • Created TextFieldPrefixBuilder, TextFieldSuffixBuilder, TextFieldFormattersBuilder helper classes
  • Created DateFieldDecorationBuilder and TimeFieldDecorationBuilder for date/time fields
  • Created DropdownFieldDecorationBuilder for dropdown field decorations
  • Total of 7 _buildXXX methods successfully eliminated

• One Class Per File Rule: Split large files containing multiple classes

  • Validation Rules (13 files): Split validation_rule.dart into individual files in validation_rules/ directory
    • voo_validation_rule.dart (base class)
    • Individual files for: required, min_length, max_length, email, phone, url, pattern, min_value, max_value, range, date_range, custom, compound validations
  • Formatters (12 files): Split formatters.dart into individual files in formatters/ directory
    • voo_formatters.dart (factory class)
    • Individual files for: phone_number, credit_card, date, currency, case, ssn, zip_code, percentage, pattern, mask, international_phone formatters
    • All formatter classes now public (removed underscore prefix)
  • 25+ classes extracted into separate files for better organization

• Import Organization: Fixed all import violations

  • Eliminated all relative imports (../)
  • Properly ordered imports: dart → flutter → package → local files
  • Created barrel exports for clean public APIs

Added #

• Developer Documentation:
  • REFACTORING_SUMMARY.md - Comprehensive summary of all refactoring changes
  • DEVELOPER_GUIDE.md - Complete developer guide with examples and best practices
  • Detailed documentation for all validators and formatters

Improved #

• Code Organization: Much easier to find and navigate code
• IDE Support: Better autocomplete and navigation with one class per file
• Testability: Helper classes are easily mockable and testable
• Maintainability: Smaller, focused files reduce complexity
• Clean Architecture: Proper separation of concerns throughout

Developer Experience #

• Better Code Discovery: Each validator/formatter in its own clearly named file
• Import Flexibility: Can import individual classes or use barrel exports
• Consistent Patterns: All code follows clean architecture principles
• Reduced Coupling: Helper classes reduce dependencies between components
• Easier Onboarding: Clear file structure makes codebase easier to understand

Testing #

• All atomic component tests passing (24/24)
• 92.6% overall test success rate (206/223)
• No breaking changes to public API

Fixed #

• Dropdown Type Casting Errors: Fixed critical type casting errors affecting strongly typed callbacks
  • Resolved "TypeError: Instance of '(CustomType?) => void' is not a subtype of type '((dynamic) => void)?'" errors
  • Added _invokeFieldOnChanged helper method using Function.apply to safely invoke callbacks without type checking
  • Fixed both searchable and regular dropdowns to handle typed callbacks properly
  • All field types now properly handle typed onChanged callbacks without runtime errors

Added #

• Comprehensive Type Safety Tests: Added full test coverage for typed callbacks across all field types
  • Tests for text, number, email, password, phone, url, multiline fields with String callbacks
  • Tests for boolean switch with bool callbacks
  • Tests for checkbox with bool? callbacks
  • Tests for dropdown with custom typed callbacks (e.g., CustomOption)
  • Tests for radio with typed callbacks
  • Tests for slider with double callbacks
  • Tests for date with DateTime? callbacks
  • Tests for time with TimeOfDay? callbacks
  • Ensures no type casting errors occur at runtime

Fixed #

• Dropdown Type Casting with Strongly Typed Callbacks: Fixed runtime type errors when using typed callbacks with dropdowns
  • Error: TypeError: Instance of '(JurisdictionListOption?) => void': type '(JurisdictionListOption?) => void' is not a subtype of type '((dynamic) => void)?'
  • Modified VooFieldWidget to wrap dropdown callbacks with dynamic type handling
  • Removed direct field.onChanged calls from VooDropdownFieldWidget to prevent type mismatches
  • Both regular and async dropdowns now handle strongly typed callbacks correctly
  • Added comprehensive test coverage for typed callbacks with custom types like JurisdictionListOption
  • Ensures type-safe callback handling without runtime errors

Fixed #

• Dropdown Overflow Issues: Fixed subtitle display causing overflow in standard dropdowns
  • Removed subtitles from non-searchable dropdown items to prevent overflow
  • Subtitles are now only displayed in searchable dropdowns with custom overlay
  • Ensures consistent dropdown rendering without visual glitches

Refactored #

• Removed Function Widgets: Eliminated all function widgets following atomic design principles
  • Created DropdownMenuOverlay, DropdownSearchField, DropdownItemsList, and VooDropdownMenuItem as proper widget classes
  • Created FieldLabelWrapper widget to handle label positioning
  • Replaced all _buildXXX methods with proper widget classes or factory methods
  • Improves code organization and follows rules.md requirements

Improved #

• Test Suite Organization: Completely reorganized test structure for better maintainability
  • Created test_helpers.dart with reusable test utilities
  • Organized tests by field type in field_callbacks/ directory
  • Added detailed error messages for all assertions
  • Fixed all compilation errors in tests
  • Removed unsupported API usage from tests
  • Tests now follow atomic design pattern and rules.md requirements
  • Improved test naming conventions for clarity

Developer Experience #

• Test Helpers: Added comprehensive test utilities
  • createTestApp() - Properly wrapped test widgets with required providers
  • tapDropdown() - Works with both regular and searchable dropdowns
  • enterTextWithVerification() - Verifies text entry with detailed error reporting
  • expectFieldValue() - Field value assertions with context
  • expectCallbackInvoked() - Callback verification helpers
  • Created README_TEST_ORGANIZATION.md documenting test structure

Fixed #

• Type Casting in onChanged Callbacks: Resolved all remaining type casting issues in field widget callbacks
  • Fixed type errors in all field widgets (checkbox, switch, radio, rating, color, multiselect, file, datetime, custom)
  • All field widgets now use dynamic invocation to safely call field.onChanged callbacks
  • Number fields now properly parse string input to numeric values before calling onChanged
  • Prevents runtime errors like type '(bool?) => void' is not a subtype of type '((dynamic) => void)?'
  • Added comprehensive test coverage for all field types with typed onChanged callbacks
  • Ensures 100% test pass rate (160/160 tests passing)

Fixed #

• Type Casting in Field Widgets: Fixed type casting errors across all field widget callbacks
  • Fixed TypeError: Instance of '(String?) => void': type '(String?) => void' is not a subtype of type '((dynamic) => void)?'
  • All field widgets now use properly typed callbacks instead of dynamic
  • VooFieldWidget correctly forwards typed callbacks without causing type mismatches
  • Ensures both widget onChanged and field onChanged callbacks are called consistently
  • VooDropdownFieldWidget now uses properly typed ValueChanged<T?>? callback
  • VooSwitchFieldWidget and VooCheckboxFieldWidget now handle bool types correctly
  • All VooField factory methods now work with typed callbacks without runtime errors

Fixed #

• Type Safety in Dropdowns: Fixed runtime type errors in dropdown onChanged callbacks

  • Changed VooDropdownFieldWidget onChanged from ValueChanged<T?>? to ValueChanged<dynamic>? to match VooFieldWidget
  • Fixes errors like "(String?) => void is not a subtype of ((dynamic) => void)?"
  • Ensures proper type casting for all dropdown value types

• Async Dropdown Query Issues: Fixed async dropdown not triggering searches when typing

  • Replaced faulty time-based debounce logic with proper Timer-based implementation
  • Now correctly debounces search queries with configurable delay
  • Properly cancels previous timers to prevent duplicate requests

• Label Position for All Fields: Fixed label positioning issues across all field types

  • Date fields now respect labelPosition setting from form configuration
  • Async dropdowns properly work with VooFieldWidget label wrapping
  • Consistent label positioning for above, left, floating, and placeholder positions

• Initial Values: Fixed initial value display for all field types

  • All fields now check field.value ?? field.initialValue pattern
  • Dropdowns, date, and time fields properly display initial values
  • Consistent initial value handling across the entire form system

• Dropdown Background Styling: Fixed inconsistent dropdown backgrounds

  • Removed explicit background colors from outlined, rounded, and sharp variants
  • Dropdowns now have transparent backgrounds matching TextFormField behavior
  • Fixed VooDropdown in voo_ui_core to match consistent styling
  • Filled variant properly retains its background fill color

Changed #

• VooFormFieldBuilder Refactored: Now uses VooFieldWidget for all field types
  • Simplified form field builder to use single VooFieldWidget
  • Ensures consistent label handling and options propagation
  • Better separation of concerns with atomic design principles

Added #

• onChanged Callbacks: All VooField factory methods now accept onChanged parameter
  • Added ValueChanged<T?>? onChanged parameter to all field types
  • Allows users to provide callback functions directly in field definitions
  • Simplifies form field event handling without needing wrapper widgets
  • Supports type-safe callbacks for each field type (String, bool, DateTime, etc.)

Fixed #

• VooFieldOptions Integration: All field types now properly use config from form builder
  • Added VooFieldOptions parameter to VooTextFormField, VooCheckboxFieldWidget, VooDropdownFieldWidget, VooRadioFieldWidget, and VooSwitchFieldWidget
  • VooFieldWidget now consistently passes options to all field types
  • VooFormFieldBuilder properly passes fieldOptions to all widgets
  • Ensures consistent theming and configuration across all form fields
• Label Positioning: Fixed label display for above and left positions
  • Fixed operator precedence bug in VooFieldWidget that prevented proper label wrapping
  • VooDateFieldWidget, VooTimeFieldWidget, and VooDropdownFieldWidget now correctly omit labels from InputDecoration when position is above/left
  • Labels are now properly displayed externally for above/left positions as intended
• Dropdown Styling: Fixed dropdown background inconsistency
  • VooDropdownFieldWidget now properly applies field variant styling (filled, outlined, etc.)
  • Dropdown fields now match the appearance of other form fields
  • Added _buildDecoration method to apply consistent styling based on field variant
• Async Dropdown Loading: Fixed constant loading state issue
  • Async dropdowns now properly load initial options on mount
  • Fixed issue where async dropdowns would show perpetual loading state
  • Empty query is now sent on initialization to load default options

Changed #

• VooField.dropdownAsync API: Improved to use cleaner List

Added #

• Searchable Dropdown Support: Enhanced dropdown fields with search functionality
  • Local search filtering for existing dropdown options
  • Async options loading for dynamic data from APIs/databases
  • Configurable search debounce for performance optimization
  • Minimum search length configuration
  • Loading indicators and empty state handling
• New VooField Factory Methods:
  • VooField.dropdownAsync() for async data loading with search
  • Enhanced VooField.dropdown() and VooField.dropdownSimple() with enableSearch parameter
• VooFormField Enhancements:
  • Added asyncOptionsLoader for dynamic option loading
  • Added enableSearch, searchHint, searchDebounce, minSearchLength fields
• VooDropdownFieldWidget Updates:
  • Now passes search configuration to enhanced VooDropdown widget
  • Handles both sync and async options seamlessly
• Example Application:
  • Added searchable_dropdown_example.dart demonstrating both local and async search

Changed #

• VooDropdownFieldWidget now handles search functionality internally
• Search implementation kept in voo_forms package, not in voo_ui_core
• VooDropdown in voo_ui_core remains a simple, basic dropdown widget

Fixed #

• Fixed labelPosition: LabelPosition.above not working correctly
• Refactored form field builder to follow atomic design principles
• Created VooTextFieldWidget atomic widget for proper label positioning
• Fixed duplicate labels appearing when using above positioning
• VooTextFormField now properly respects provided decorations

Changed #

• One Class Per File Rule: Refactored voo_field_options.dart into separate files
  • Each enum and class now in its own file following rules.md
  • Created separate files for: LabelPosition, FieldVariant, ErrorDisplayMode, ValidationTrigger, FocusBehavior
  • VooFieldOptions and VooFieldOptionsProvider now in separate files
• Removed Duplicate Responsive Logic: Now using voo_ui_core's VooSpacingSize and VooDesignSystemData
  • Eliminated duplicate size/spacing definitions
  • Using voo_ui_core's existing responsive utilities
  • Better integration with overall design system

Fixed #

• Import paths now properly organized
• No more duplicate responsive logic between packages

Added #

• VooSimpleForm: New simplified form builder for amazing developer experience
  • Works seamlessly with VooField factory constructors
  • Supports all form layouts (vertical, horizontal, grid, stepped, tabbed)
  • Built-in support for VooFieldOptions inheritance
  • Extension method .toForm() for even simpler form creation
• Atomic Layout Widgets: Replaced all _buildXXX methods with proper atomic widgets
  • VooFormVerticalLayout: Vertical form layout organism
  • VooFormHorizontalLayout: Horizontal scrolling form layout
  • VooFormGridLayout: Responsive grid layout with column spanning
  • VooFormSteppedLayout: Wizard-style stepped form layout
  • VooFormTabbedLayout: Tabbed form layout
  • VooFormProgress: Progress indicator molecule
  • VooFormActions: Form action buttons molecule
• Best Practices Example: Comprehensive example demonstrating all new features

Changed #

• VooFormBuilder: Refactored to use atomic widgets instead of _buildXXX methods
  • Improved separation of concerns
  • Better testability and maintainability
  • Follows atomic design principles strictly
• Theme Integration: All form components now properly use theme colors
  • Removed hardcoded green/red colors in favor of theme.colorScheme.tertiary/error
  • Consistent theming throughout all form elements

Fixed #

• Fixed VooFormController import path issues in new atomic widgets
• Fixed type errors in VooFormSection references
• Removed unused _validateCurrentStep method from VooFormBuilder

Added #

• New VooField API with factory constructors for better developer experience:
  • VooField.text(), VooField.email(), VooField.password()
  • VooField.dropdown(), VooField.checkbox(), VooField.radio()
  • VooField.date(), VooField.time(), VooField.slider()
  • And more field types following best practices (no static methods)
• VooFieldOptions system with enum-based configuration:
  • Presets: VooFieldOptions.material, .compact, .comfortable, .minimal
  • Configurable label position, field variant, size, density, validation triggers
  • Inheritable options from parent forms for consistency
• VooFieldOptionsProvider using InheritedWidget pattern for option inheritance
• Parent forms can set defaultFieldOptions that cascade to all children
• New atomic widgets for better code organization:
  • VooSliderFormField for slider inputs
  • VooDateFormField for date selection
  • VooTimeFormField for time selection
• Added rule to rules.md: No _buildXXX methods that return widgets

Changed #

• BREAKING: Removed all hardcoded colors - everything now uses Theme.of(context)
• BREAKING: Refactored VooFieldWidget to follow atomic design (no _buildXXX methods)
• Improved theme integration - respects app's ColorScheme automatically
• Updated VooFormConfig to support defaultFieldOptions
• Enhanced field option inheritance from parent forms

Deprecated #

• VooFieldUtils: Static methods violate best practices. Use VooField factory constructors instead:

  // OLD (deprecated)
  VooFieldUtils.textField(id: 'name', name: 'name')
    
  // NEW (recommended) 
  VooField.text(name: 'name')
  

  Migration guide:
  • VooFieldUtils.textField() → VooField.text()
  • VooFieldUtils.emailField() → VooField.email()
  • VooFieldUtils.passwordField() → VooField.password()
  • VooFieldUtils.phoneField() → VooField.phone()
  • VooFieldUtils.dropdownField() → VooField.dropdown()
  • All other static methods have equivalent factory constructors
  • Will be removed in version 0.2.0

Fixed #

• Fixed green color appearing in switches and other components when not in theme
• Fixed amber color in rating widgets - now uses theme primary color
• Fixed type mismatches in VooField factory constructors
• Fixed VooFormField
• Removed deprecated API usage warnings
• Fixed enum conflicts between form_config.dart and voo_field_options.dart

Developer Experience #

• Intuitive factory constructor API (VooField.text instead of static methods)
• Enum-based configuration for better type safety and IDE support
• Consistent theming throughout all form components
• Better code organization following atomic design principles

Added #

• Initial release of voo_forms package
• Comprehensive form builder with clean architecture
• 20+ field types support including:
  • Text, Email, Password, Phone, URL
  • Number, Slider, Rating
  • Date, Time, DateTime
  • Boolean, Checkbox, Switch
  • Dropdown, Radio, MultiSelect
  • Color picker, File upload
• Form sections with collapsible support
• Form headers for better organization and categorization
• Advanced validation system with 20+ built-in validators:
  • Required, Email, Phone, URL validation
  • Min/Max length and value validators
  • Pattern matching validators
  • Password strength validators
  • Credit card, postal code validators
  • Custom validation support
• 15+ text input formatters:
  • Phone number formatting (US and international)
  • Credit card formatting
  • Currency formatting
  • Date and time formatting
  • Custom mask formatters
• Form controller with state management:
  • Real-time validation
  • Field dependencies
  • Form submission handling
  • Progress tracking
• Multiple form layouts:
  • Vertical, Horizontal, Grid
  • Stepped/Wizard forms
  • Tabbed forms
• Responsive design supporting all screen sizes
• Material 3 compliance
• Theme customization support
• Comprehensive utility classes:
  • VooFormUtils for form operations
  • VooFieldUtils for field creation
  • VooFormTheme for styling
• Export formats:
  • JSON serialization/deserialization
  • Form summary generation
  • Configuration export
• Full TypeScript-like type safety with generics
• Atomic design pattern implementation
• Cross-platform support (iOS, Android, Web, Desktop)