smart_multi_form_fields 1.2.0

A single, production-grade Flutter form field widget rendering text, password, phone, OTP, date, dropdown, and file inputs via sealed configurations.

1.2.0

Added

Phone Field (SmartPhoneConfig / SmartPhoneFieldImpl)

• Country-code picker with flags, powered by intl_phone_field_v2 internally (never exposed to consumers — no need to import it yourself)
• Real per-country phone number format validation via phone_numbers_parser (libphonenumber-derived metadata), not just digit-count checks
• defaultCountryCode — required, not auto-detected. Device locale/language settings are not a reliable proxy for a user's actual country (a phone set to "English (United States)" reports US even when physically elsewhere), so this package deliberately does not guess. You declare the country your app primarily targets; users outside it switch via the flag picker at any time.
• .value (via GlobalKey<SmartBaseShellState>.value) returns the full E.164 number (e.g. "[phone]") — ready to send straight to your backend
• Custom validators receive the raw national number only (no dial code), so your checks stay country-agnostic
• onCountryChanged callback — fires with plain (isoCode, dialCode) strings whenever the user switches country, no third-party types leaked into your code
• invalidNumberMessage — override the default validation error text
• showDropdownIcon — hide the small chevron next to the flag (the flag itself stays tappable)
• flagsButtonPadding / flagsButtonMargin — fine-tune spacing around the flag/dial-code button
• validateMode (AutovalidateMode) — controls whether the field re-validates live as the user types (clears an existing error as soon as it's fixed) or only validates on explicit validate() calls
• Unified error rendering: the field's error/helper text is rendered exclusively by the shared base shell (matching Text and Password fields) — the underlying picker package's own internal error text and length-check UI are fully suppressed so there is never a duplicate or conflicting error message
• Full theming support consistent with Text/Password: respects your app's InputDecorationTheme automatically, falls back to a polished package default otherwise

Known Limitations

• defaultCountryCode requires the developer to know their target market ahead of time; there is no automatic detection based on SIM/carrier or GPS (see the field's own doc comment for the reasoning)

Added

Password Field (SmartPasswordConfig / SmartPasswordFieldImpl)

• Production-grade password field rendering with full feature parity across login, signup, and reset forms.
• Animated Password Strength Meter: 4-segment color-coded strength bar (SmartStrengthMeter) with live accessibility label announcements for screen readers.
• Min Length Baseline: Password strength stays Weak until minPasswordLength threshold baseline is reached.
• Granular Complexity Validation Rules: Opt-in rule flags (requireUppercase, requireLowercase, requireDigit, requireSpecialChar).
• Confirm Password Matching: Real-time exact string match validation via confirmPasswordController and custom error message (confirmMismatchMessage).
• Custom Obscuring Character: obscuringCharacter property allowing developers to set custom mask characters (e.g. '*' or default '•').
• Visibility Toggle Customization: showToggleIcon toggle and toggleIconBuilder for developer-supplied eye icons.
• Custom Strength Scorer: customStrengthScorer callback allowing developers to inject custom security policies overriding default PasswordStrengthScorer.
• Custom Strength Meter UI: strengthMeterBuilder callback allowing complete replacement of default 4-segment strength bar widget tree.
• Custom Validators: Fully supports custom validator lists (validators: [...]) running in sequence.

Performance & Memory Optimizations

• Static Compiled RegExp Allocation: Optimized PasswordStrengthScorer and SmartPasswordFieldImpl regexes into compiled static final constants (uppercaseRegExp, lowercaseRegExp, digitRegExp, specialCharRegExp) to eliminate garbage collection allocations on rapid keystrokes.
• Keystroke Re-render Threshold Guard: Added strength equality checks in _onChanged to prevent unnecessary widget rebuilds when strength scores remain unchanged.

---

1.0.0

Initial release — Text field only. Password, Phone, OTP, Date, Dropdown, and File field types exist internally as part of the sealed configuration hierarchy (required for the type-safe dispatcher to compile) but are not part of the public API surface in this release and will ship in their own future versions.

Added

Architecture

• Sealed configuration hierarchy (SmartFieldConfig) for compile-time-safe, per-type config classes
• Single dispatcher widget (SmartFormField) — one widget for every field type
• Template-method base shell (SmartBaseShell / SmartBaseShellState) for consistent label/error/helper rendering

Text Field (SmartTextConfig / SmartTextFieldImpl)

• Label, hint, helper text, required-field asterisk
• Built-in validation chain: required check → minLength → custom validator list (first error wins)
• minLength with live "Minimum: N characters" hint that switches to the character counter once met
• maxLength with live character counter, warning color near the limit
• Multiline support via maxLines / minLines, with correct handling of Flutter's maxLines/minLines constraint
• Auto-capitalization (autoCapitalizeWords) via a cursor-position-preserving CapitalizeFormatter
• Custom inputFormatters support
• Prefix icon, suffix icon with tap callback
• readOnly mode (visible, focusable, not editable) distinct from enabled: false (dimmed, not focusable)
• autofocus, autofillHints (password manager / browser autofill)
• Keyboard type, textCapitalization hint, smart textInputAction defaulting (next when nextFocusNode is set)
• Focus traversal via nextFocusNode
• onChanged, onSubmitted callbacks

External Controller Support

• Optional controller property on SmartFieldConfig, mirroring the existing focusNode pattern — if you provide a TextEditingController, you own its lifecycle and disposal; if omitted, the field creates and disposes its own internally

Theming — 3-Tier Decoration Resolution

• Every decoration property (borders, fill, label/hint/helper/error text styles) resolves in order: per-field override → your app's Theme.of(context).inputDecorationTheme → package's own ColorScheme-driven default
• No custom ThemeExtension or registration step required — respects your app's existing Material theme automatically, including light/dark mode
• Zero-width-space (\u200B) technique for triggering the error border state without allocating extra layout space

Debounced & Async Search

• SmartTextConfig.search(...) factory constructor — preset with search icon, auto-clear button, TextInputAction.search, and a sensible debounce default
• debounce, onDebouncedChanged (sync/local filtering), onSearchAsync (async, e.g. API calls) properties available on any SmartTextConfig, not just the search preset
• Race-condition-safe async search: onSearchAsync receives an isCurrent() checker so a slow, older request can never overwrite a faster, newer one's results
• showSearchLoadingIndicator — auto-swaps the suffix icon to a spinner while a search is in flight
• showClearButton — general-purpose auto clear (×) icon, available on any text field, not search-exclusive
• Submitting (Enter / search key) cancels any pending debounce and fires the search callback immediately

Programmatic Control

• GlobalKey<SmartBaseShellState> access pattern: validate(), value, reset(), setError(String?), clearError()

Known Limitations

• Validation-message strings, tooltips, and strength-meter labels are hardcoded English — localization support is planned but not yet implemented
• No form-level controller yet (each field needs its own GlobalKey for programmatic access; there is no aggregator for validate-all/get-all-values across multiple fields)