Flutter Smart Suggestions

Pub Version Flutter Version Dart Version Platform Support

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

Platform Support Notes
iOS ✅ Full Native iOS performance
Android ✅ Full Native Android performance
Web ✅ Full WASM compatible
Windows ✅ Full Desktop optimization
macOS ✅ Full Desktop optimization
Linux ✅ Full Desktop optimization

📱 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

Made with ❤️ by Dhia Bechattaoui

Libraries

flutter_smart_suggestions