smart_multi_form_fields 1.0.0

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

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)