flutter_notification_system 2.0.0

Self-configuring notification system for Flutter with Clean Architecture. Auto-setup with GetIt, Provider, multiple notification types, queue management, and customizable themes.

Flutter Notification System 🔔

Una librería completa de gestión de notificaciones para Flutter que sigue los principios de Clean Architecture.

✨ Características

• 🎯 Type-Safe: Sistema completamente tipado con Dart
• 🏗️ Clean Architecture: Separación clara de responsabilidades
• � Auto-Configurable: No requiere registro manual de dependencias
• 📊 Queue Management: Cola de notificaciones con sistema de prioridades
• 🎨 Personalizable: Temas, colores, animaciones y builders personalizados
• 🔄 Operation Tracking: Mixin para rastrear resultados de operaciones CRUD
• 🧪 Testeable: Cobertura completa de tests unitarios e integración
• ⚡ Performance: Optimizado con Selector y Mixin patterns
• 🔔 Múltiples tipos: Success, Error, Warning, Info
• 📱 Responsive: SnackBars y Dialogs adaptativos
• 🎭 Animaciones: Múltiples efectos de animación configurables

📦 Instalación

Agrega esto a tu pubspec.yaml:

dependencies:
  flutter_notification_system: ^1.0.0

Luego ejecuta:

flutter pub get

🚀 Uso Rápido

1. Configuración Simple (Nueva API)

import 'package:flutter/material.dart';
import 'package:flutter_notification_system/flutter_notification_system.dart';

void main() {
  // ¡Ya NO es necesario inicializar GetIt ni registrar módulos!
  // La librería se encarga de todo automáticamente
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Solo envuelve tu app con AppNotificationListener
    // ¡Eso es todo! La librería configura todo internamente:
    // - GetIt y sus dependencias
    // - ChangeNotifierProvider
    // - Sistema de notificaciones
    return AppNotificationListener(
      // Configuración opcional
      config: NotificationConfig(
        maxQueueSize: 10,
      ),
      child: MaterialApp(
        title: 'Mi App',
        home: HomePage(),
      ),
    );
  }
}

2. Mostrar Notificaciones

Ahora tienes dos formas simples de mostrar notificaciones:

Opción 1: Usando el contexto (BuildContext extension)

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () {
        // Método 1: Extensión de BuildContext
        context.showSuccess('¡Operación exitosa!');
        context.showError(ErrorItem(message: 'Error al guardar'));
        context.showWarning('Advertencia de seguridad');
        context.showInfo('Nueva actualización disponible');
      },
      child: Text('Mostrar notificación'),
    );
  }
}

Opción 2: Usando el helper estático (desde cualquier lugar)

// Puedes usar NotificationSystem desde cualquier parte del código
// incluso fuera de widgets o sin BuildContext
class MyService {
  Future<void> saveData() async {
    try {
      await api.save();
      NotificationSystem.showSuccess('Datos guardados correctamente');
    } catch (e) {
      NotificationSystem.showError(
        ErrorItem(message: 'Error al guardar: $e'),
      );
    }
  }
}

3. Notificaciones con Prioridades

// Prioridad baja
context.showInfo(
  'Sincronización en segundo plano',
  priority: NotificationPriority.low,
);

// Prioridad alta
NotificationSystem.showWarning(
  'Batería baja',
  priority: NotificationPriority.high,
);

// Prioridad crítica (interrumpe otras notificaciones)
context.showError(
  ErrorItem(
    message: 'Conexión perdida',
    errorLevel: ErrorLevelEnum.critical,
  ),
  priority: NotificationPriority.critical,
);

4. Duraciones Personalizadas

// Notificación corta (1 segundo)
NotificationSystem.showSuccess(
  'Guardado',
  duration: const Duration(seconds: 1),
);

// Notificación larga (10 segundos)
context.showInfo(
  'Leyendo documentación importante...',
  duration: const Duration(seconds: 10),
);

🎨 Personalización

Configuración al Inicializar

AppNotificationListener(
  config: NotificationConfig(
    maxQueueSize: 10,
    // Otras opciones de configuración...
  ),
  theme: NotificationTheme.dark(), // Tema oscuro
  child: MaterialApp(...),
)

Widget Personalizado

AppNotificationListener(
  customBuilder: (context, notification) {
    return Container(
      padding: EdgeInsets.all(16),
      decoration: BoxDecoration(
        color: Colors.purple,
        borderRadius: BorderRadius.circular(20),
      ),
      child: Row(
        children: [
          Icon(Icons.star, color: Colors.white),
          SizedBox(width: 12),
          Expanded(
            child: Text(
              notification.message,
              style: TextStyle(color: Colors.white),
            ),
          ),
        ],
      ),
    );
  },
  child: YourApp(),
)

🔄 Migración desde v1.x

Si estás actualizando desde la versión 1.x, aquí está el cambio:

Antes (v1.x)

final getIt = GetIt.instance;

void main() {
  registerNotificationModule(getIt);
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  Widget build(context) => ChangeNotifierProvider.value(
    value: getIt<NotificationViewModel>(),
    child: Consumer<NotificationViewModel>(
      builder: (context, vm, _) {
        vm.setAppContext(context);
        return AppNotificationListener(child: MaterialApp(...));
      },
    ),
  );
}

// Uso
getIt<NotificationViewModel>().showSuccess(message: 'OK');

Ahora (v2.0)

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  Widget build(context) => AppNotificationListener(
    child: MaterialApp(...),
  );
}

// Uso
context.showSuccess('OK');
// o
NotificationSystem.showSuccess('OK');

🧪 Testing

import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_notification_system/flutter_notification_system.dart';

void main() {
  group('NotificationViewModel', () {
    late NotificationViewModel viewModel;

    setUp(() {
      viewModel = getNotificationViewModel();
    });

    tearDown(() {
      resetNotificationSystem();
    });

    test('should show notification', () {
      viewModel.showSuccess(message: 'Test');
      
      expect(viewModel.notification, isNotNull);
      expect(viewModel.notification?.message, equals('Test'));
    });
  });
}

🏛️ Arquitectura

lib/
├── src/
│   ├── models/              # Modelos de datos inmutables
│   │   ├── notification_data.dart
│   │   ├── notification_type.dart
│   │   ├── notification_priority.dart
│   │   ├── notification_config.dart
│   │   ├── operation_result.dart
│   │   └── error_item.dart
│   ├── view_models/         # Lógica de presentación
│   │   ├── notification_view_model.dart
│   │   └── operation_result_mixin.dart
│   ├── widgets/             # Componentes UI
│   │   ├── notification_listener.dart
│   │   ├── notification_presenter.dart
│   │   ├── custom_snackbar.dart
│   │   └── custom_dialog.dart
│   ├── utils/               # Utilidades
│   │   ├── notification_queue.dart
│   │   ├── notification_theme.dart
│   │   └── notification_animations.dart
│   └── di/                  # Inyección de dependencias
│       └── notification_di.dart
└── flutter_notification_system.dart

📚 Ejemplos

Ver la carpeta /example para ejemplos completos que demuestran:

• ✅ Uso básico con las dos APIs (context y NotificationSystem)
• ✅ Notificaciones con diferentes prioridades
• ✅ Duraciones personalizadas
• ✅ Gestión de cola de notificaciones
• ✅ Personalización de temas y animaciones

🤝 Ventajas de la v2.0

1. 🚀 Configuración Instantánea: De ~30 líneas a 1 widget wrapper
2. 💡 API Intuitiva: Dos formas simples de mostrar notificaciones
3. 🔒 Sin Conflictos: GetIt interno no interfiere con tu GetIt global
4. 📦 Auto-Contenida: La librería maneja todas sus dependencias
5. 🎯 BuildContext Extension: Sintaxis natural y familiar
6. 🌍 Helper Estático: Acceso desde cualquier lugar sin contexto
7. 🔄 Retrocompatible: Los métodos antiguos siguen funcionando

📄 Licencia

MIT License - ver LICENSE para detalles.

---

Versión: 2.0.0
Fecha: Enero 2026
Cambios: Sistema auto-configurable con API simplificada