smart_multi_form_fields 1.0.0-alpha.1

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

Smart Form Field (smart_multi_form_fields)

A production-grade, type-safe Flutter form field package that provides a single public widget (SmartFormField) capable of rendering multiple input types through a sealed configuration hierarchy.

Current status: Text and Password fields are fully implemented. Phone, OTP, Date, Dropdown, and File are stubs only — their config classes exist (required for the sealed hierarchy to compile) but do not yet render functional widgets. See the status table below.

---

Implementation Status

Type	Config	Status
Text	SmartTextConfig	✅ Complete
Password	SmartPasswordConfig	🟡 Built, not yet published
Phone	SmartPhoneConfig	⏳ Not implemented
OTP	SmartOtpConfig	⏳ Not implemented
Date	SmartDateConfig	⏳ Not implemented
Dropdown	SmartDropdownConfig	⏳ Not implemented
File	SmartFileConfig	⏳ Not implemented

---

Features (Text & Password)

• 🎯 Single Public Widget: SmartFormField(config: ...) for every input type.
• 🔒 Type-Safe Sealed Configs: SmartFieldConfig is sealed — compile-time safety, zero dead properties.
• 🛠 Built-in Validation: Required check, minLength, custom validator chain, first-error-wins.
• 🔌 External Controller: Optional controller property, same pattern as focusNode — you own it if you provide it.
• 🎨 Automatic Theming: Matches your app's existing light/dark theme out of the box. If you've already styled your text fields via InputDecorationTheme, this respects that too — no extra setup, no new concept to learn.
• ⏱ Debounced & Async Search: SmartTextConfig.search() with race-condition-safe async handling.
• 🔑 Programmatic Control: Validate, reset, read values via GlobalKey<SmartBaseShellState>.
• 🔐 Password Field: Visibility toggle, animated strength meter, complexity rules, confirm-match validation.

Not yet available: localization of package-generated strings (validation messages, tooltips) — currently hardcoded English. Dev-supplied strings (label/hint/helperText) already work with any localization approach since you provide them directly.

---

Installation

dependencies:
  smart_multi_form_fields: ^1.0.0-alpha.1

---

Usage

import 'package:smart_multi_form_fields/smart_multi_form_fields.dart';

Basic Text Input

SmartFormField(
  config: SmartTextConfig(
    label: 'Full Name',
    hint: 'Enter your name',
    isRequired: true,
    autoCapitalizeWords: true,
  ),
)

External Controller

final _controller = TextEditingController();

SmartFormField(
  config: SmartTextConfig(label: 'Name', controller: _controller),
)

_controller.text = 'Pre-filled value';  // read/write from anywhere
// You provided the controller, so YOU dispose it:
_controller.dispose();

App-Wide Theming (Tier 2)

MaterialApp(
  theme: ThemeData(
    inputDecorationTheme: InputDecorationTheme(
      border: OutlineInputBorder(borderRadius: BorderRadius.circular(16)),
      filled: true,
      fillColor: Colors.grey[100],
    ),
  ),
)
// Every SmartFormField now uses this automatically — no extra setup.

Async Search Field with Debounce

SmartFormField(
  config: SmartTextConfig.search(
    label: 'Search',
    hint: 'Type query…',
    debounce: const Duration(milliseconds: 500),
    onSearchAsync: (query, isCurrent) async {
      final results = await myApi.search(query);
      if (isCurrent()) {              // required — discards stale results
        setState(() => _searchResults = results);
      }
    },
  ),
)

Programmatic Validation

final _key = GlobalKey<SmartBaseShellState>();

SmartFormField(key: _key, config: SmartTextConfig(label: 'Email', isRequired: true))

final error = _key.currentState?.validate();
if (error == null) {
  final value = _key.currentState?.value;
}

---

Planned Architecture (Full Target)

SmartFormField(config: SmartTextConfig(...))     → ✅ text input
SmartFormField(config: SmartPasswordConfig(...)) → ✅ password field
SmartFormField(config: SmartPhoneConfig(...))    → ⏳ phone + country code
SmartFormField(config: SmartOtpConfig(...))      → ⏳ OTP boxes
SmartFormField(config: SmartDateConfig(...))     → ⏳ date/time picker
SmartFormField(config: SmartDropdownConfig(...)) → ⏳ searchable dropdown
SmartFormField(config: SmartFileConfig(...))     → ⏳ file/image picker

---

License

MIT License.