smart_multi_form_fields 1.3.0

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

1.3.0

Added

OTP / PIN Field (SmartOtpConfig / SmartOtpFieldImpl)

• Segmented box UI (default 6 boxes, configurable via length) backed by a single hidden TextField — no third-party dependency needed
• Native SMS/platform autofill via AutofillHints.oneTimeCode (enableSmsAutofill, default on) — works out-of-the-box on iOS; Android UX varies by OEM autofill service but uses the same standard hint
• Zero-touch background SMS interception support: because the field still accepts an external TextEditingController, an app that reads incoming SMS itself (e.g. via the Android SMS Retriever API) can simply assign controller.text = code — the boxes update and autoSubmit fires automatically, with no special wiring required on the package's side
• obscureText + obscuringCharacter — mask entered digits like a PIN (e.g. '*' instead of showing the digit)
• autoSubmit — optionally treat "code complete" the same as "user pressed submit," auto-dismissing the keyboard and firing onSubmitted
• onCompleted — fires exactly once each time the code reaches full length (fires again if cleared and re-completed)
• Custom OTP validation messages use the same validators: [...] list as every other field type — no OTP-specific one-off message property, for full API consistency with Text/Password/Phone
• Per-field box color overrides (enabledBorderColor, focusedBorderColor, errorBorderColor) on top of the same field → app theme → package default resolution used everywhere else in the package
• Custom animated cursor drawn natively inside the active box (not the OS's own text cursor, which is fully suppressed to avoid a stray blinking line floating between boxes)

Fixed (found during implementation, before any public testing)

• Hardcoded input to digits-only (TextInputType.number + digit-only input formatter) — an alphanumeric OTP keyboard option was considered and dropped, since real-world OTP/PIN codes are numeric and offering the toggle only invited inconsistent formatting
• Removed hint/hintStyle from SmartOtpConfig — a single placeholder string has no sensible place to render across multiple separate boxes
• Removed the default global InputDecorationTheme border from wrapping the whole boxes row (the app's shared text-field border was being drawn around the entire OTP group in addition to each box's own border) — the hidden field now explicitly uses InputBorder.none
• Fixed sequential backspacing: tapping anywhere in the boxes row previously could leave the hidden cursor positioned at the wrong index, silently breaking backspace. The hidden field's selection is now clamped to the end of the entered text on every interaction, so backspace always removes the last entered digit regardless of where the user taps

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)