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.

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 field is fully implemented. Password, Phone, OTP, Date, Dropdown, and File configs exist for compile-time type safety. See the status table below.

---

Implementation Status

Type	Config	Status
Text	SmartTextConfig	✅ Complete
Password	SmartPasswordConfig	🟡 Built internally
Phone	SmartPhoneConfig	⏳ Stub
OTP	SmartOtpConfig	⏳ Stub
Date	SmartDateConfig	⏳ Stub
Dropdown	SmartDropdownConfig	⏳ Stub
File	SmartFileConfig	⏳ Stub

---

Features

• 📱 Supported Platforms: Tested and officially supported on Android & iOS.
• 🎯 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, maxLength, custom validator chain (SmartValidators.email).
• ✍️ Formatting & Capitalization: autoCapitalizeWords, custom inputFormatters, auto-trimming.
• 🔌 External Controller: Optional controller property — you own disposal if provided, package handles it if omitted.
• 🎨 Automatic Theming: Seamlessly inherits app InputDecorationTheme and light/dark ColorScheme.
• ⏱ Debounced & Async Search: SmartTextConfig.search() with race-condition-safe async execution.
• 🔑 Programmatic Control: Validate, reset, read values via GlobalKey<SmartBaseShellState>.

---

Installation

dependencies:
  smart_multi_form_fields: ^1.0.0

---

Usage Examples

import 'package:smart_multi_form_fields/smart_multi_form_fields.dart';

SmartTextFormField Preview

[SmartTextFormField]
[SmartTextFormField]

1. Basic Text Input & Validation

SmartFormField(
  config: SmartTextConfig(
    label: 'Full Name',
    hint: 'John Doe',
    isRequired: true,
    autoCapitalizeWords: true,
    prefixIcon: const Icon(Icons.person),
    validators: [
      (value) => value!.length < 3 ? 'Name must be at least 3 characters' : null,
    ],
  ),
)

2. Email Field with Built-in Validator

SmartFormField(
  config: SmartTextConfig(
    label: 'Email Address',
    hint: '[e-mail]',
    isRequired: true,
    validators: [SmartValidators.email],
    prefixIcon: const Icon(Icons.email),
  ),
)

3. Multiline & Character Counter (Bio / Notes)

SmartFormField(
  config: SmartTextConfig(
    label: 'Bio',
    hint: 'Write a short bio...',
    minLength: 10,
    maxLength: 200,
    maxLines: 4,
    minLines: 2,
    prefixIcon: const Icon(Icons.info),
  ),
)

4. Auto-Clear Button & Icons

SmartFormField(
  config: SmartTextConfig(
    label: 'Address',
    hint: 'Enter your address',
    showClearButton: true, // Auto-shows (×) clear icon when non-empty
    prefixIcon: const Icon(Icons.location_on),
  ),
)

5. Async Search Field with Debounce

SmartFormField(
  config: SmartTextConfig.search(
    label: 'Search Products',
    hint: 'Type product name...',
    debounce: const Duration(milliseconds: 400),
    onSearchAsync: (query, isCurrent) async {
      final results = await myApi.searchProducts(query);
      if (isCurrent()) { // Ensures older, slower API responses don't overwrite newer results
        setState(() => _searchResults = results);
      }
    },
  ),
)

6. External Controller & Focus Traversal

final _nameController = TextEditingController();
final _nextFocus = FocusNode();

SmartFormField(
  config: SmartTextConfig(
    label: 'First Name',
    controller: _nameController,
    nextFocusNode: _nextFocus,
    textInputAction: TextInputAction.next,
  ),
)

// Read or pre-fill value anytime:
_nameController.text = 'Pre-filled';

// Remember: If you pass your own controller, dispose it when your State disposes:
// _nameController.dispose();

7. Programmatic Validation via GlobalKey

final _formKey = GlobalKey<SmartBaseShellState>();

SmartFormField(
  key: _formKey,
  config: SmartTextConfig(label: 'Username', isRequired: true),
)

// On submit button click:
void onSubmit() {
  final error = _formKey.currentState?.validate();
  if (error == null) {
    final value = _formKey.currentState?.value;
    print('Valid value: $value');
  }
}

---

SmartTextConfig Property Reference

Property	Type	Description
label	String?	Field label header shown above input
hint	String?	Placeholder text inside input
helperText	String?	Supporting text shown below field
isRequired	bool	Adds * asterisk and runs empty validation
validators	List<SmartValidator>	Custom validation functions chain
minLength	int?	Minimum character length constraint
maxLength	int?	Maximum character length constraint (renders counter)
maxLines	int?	Maximum lines for multiline input
minLines	int?	Minimum lines for multiline input
autoCapitalizeWords	bool	Automatically capitalizes first letter of every word
showClearButton	bool	Renders (×) clear button when text is non-empty
prefixIcon	Widget?	Icon displayed at the start of input
suffixIcon	Widget?	Icon displayed at the end of input
onSuffixIconTap	VoidCallback?	Tap handler for suffixIcon
readOnly	bool	Focusable and selectable but prevents editing
enabled	bool	Disables field interactions and dims colors
controller	TextEditingController?	External controller override
focusNode	FocusNode?	External focus node override
nextFocusNode	FocusNode?	Focus node to request on keyboard submit
debounce	Duration	Delay for debounced callbacks (default: 300ms)
onDebouncedChanged	ValueChanged<String>?	Sync callback invoked after debounce delay
onSearchAsync	Future<void> Function(query, isCurrent)?	Async search callback with stale response checker
showSearchLoadingIndicator	bool	Auto-swaps suffix icon to spinner during async search

---

License

MIT License.