Flutter Smart Suggestions #

A powerful Flutter package that provides context-aware input suggestions and autocomplete functionality with support for all 6 platforms including WASM compatibility for web applications.

✨ Features #

• Context-Aware Suggestions: Intelligent suggestions based on input context and field type
• Multi-Platform Support: Works seamlessly on iOS, Android, Web, Windows, macOS, and Linux
• WASM Compatible: Optimized for web applications with WebAssembly support
• Customizable Providers: Easy to extend with custom suggestion providers
• Smart Ranking: Advanced relevance scoring and suggestion ranking algorithms
• Performance Optimized: Efficient suggestion generation with debouncing and caching
• Material Design 3: Beautiful, modern UI components following Material Design guidelines
• Accessibility Ready: Built with accessibility best practices in mind

🚀 Getting Started #

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_smart_suggestions: ^0.0.1

Basic Usage #

import 'package:flutter_smart_suggestions/flutter_smart_suggestions.dart';

// Create a smart suggestions instance
final smartSuggestions = SmartSuggestions();

// Get suggestions for text input
final suggestions = await smartSuggestions.getSuggestions(
  inputText: 'user@',
  cursorPosition: 5,
  fieldType: 'email',
);

// Use suggestions in your UI
for (final suggestion in suggestions) {
  print('${suggestion.text} - ${suggestion.description}');
}

Pre-configured Use Cases #

// Email suggestions
final emailSuggestions = SmartSuggestions.forUseCase('email');

// Search suggestions
final searchSuggestions = SmartSuggestions.forUseCase('search');

// Address suggestions
final addressSuggestions = SmartSuggestions.forUseCase('address');

// Name suggestions
final nameSuggestions = SmartSuggestions.forUseCase('name');

Custom Suggestion Providers #

class CustomSuggestionProvider extends SuggestionProvider {
  @override
  Future<List<Suggestion>> getSuggestions(SuggestionContext context) async {
    // Your custom logic here
    return [
      const Suggestion(
        text: 'Custom Suggestion',
        description: 'Generated by custom provider',
        relevanceScore: 0.9,
      ),
    ];
  }

  @override
  bool canHandle(SuggestionContext context) {
    return context.fieldType == 'custom';
  }

  @override
  int get priority => 100; // Higher priority
}

// Add to your smart suggestions instance
smartSuggestions.addProvider(CustomSuggestionProvider());

🏗️ Architecture #

The package is built with a modular architecture:

• SmartSuggestions: Main entry point and coordination layer
• SuggestionEngine: Manages multiple providers and suggestion generation
• SuggestionProvider: Abstract interface for suggestion sources
• Suggestion: Data model for individual suggestions
• SuggestionContext: Context information for generating relevant suggestions

🌐 Platform Support #

📱 Widgets #

SmartTextField #

A complete text field with built-in suggestion functionality:

SmartTextField(
  onChanged: (text) {
    // Handle text changes
  },
  onSuggestionSelected: (suggestion) {
    // Handle suggestion selection
  },
  fieldType: 'email',
  maxSuggestions: 5,
)

SuggestionOverlay #

A customizable overlay for displaying suggestions:

SuggestionOverlay(
  suggestions: suggestions,
  onSuggestionSelected: (suggestion) {
    // Handle selection
  },
  maxHeight: 200.0,
  backgroundColor: Colors.white,
)

🔧 Configuration #

Suggestion Engine Settings #

final engine = SuggestionEngine(
  maxSuggestions: 15,
  debounceTime: Duration(milliseconds: 500),
);

Provider Priority #

class HighPriorityProvider extends SuggestionProvider {
  @override
  int get priority => 100; // Higher priority = consulted first
}

class LowPriorityProvider extends SuggestionProvider {
  @override
  int get priority => 10; // Lower priority = consulted last
}

📊 Performance #

• Debouncing: Configurable input debouncing to prevent excessive API calls
• Caching: Intelligent suggestion caching for better performance
• Lazy Loading: Suggestions are generated only when needed
• Memory Efficient: Minimal memory footprint with efficient data structures

🧪 Testing #

The package includes comprehensive test coverage:

# Run all tests
flutter test

# Run tests with coverage
flutter test --coverage

📚 API Reference #

Core Classes #

• SmartSuggestions - Main entry point
• SuggestionEngine - Suggestion coordination
• SuggestionProvider - Abstract provider interface
• Suggestion - Suggestion data model
• SuggestionContext - Context for suggestions

Widgets #

• SmartTextField - Complete text field with suggestions
• SuggestionOverlay - Suggestion display overlay

Utilities #

• SuggestionUtils - Helper functions and platform detection

🤝 Contributing #

We welcome contributions! Please see our Contributing Guide for details.

Development Setup #

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments #

• Flutter team for the amazing framework
• Material Design team for design guidelines
• All contributors and users of this package

📞 Support #

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: Contact via GitHub

Made with ❤️ by Dhia Bechattaoui