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: ^3.0.1

đź“Ś Compatibilidad

Esta librería utiliza get_it: ^8.0.3 para garantizar la máxima compatibilidad con otros paquetes en tu proyecto. Si estás usando otros paquetes que dependen de versiones más antiguas de GetIt, esta versión permitirá una mejor convivencia entre dependencias.

Luego ejecuta:

flutter pub get

🚀 Uso Rápido

1. ConfiguraciĂłn Simple (Nueva API)

La librerĂ­a ahora se integra nativamente con flutter_clean_mvvm_toolkit, utilizando sus modelos estandarizados para errores y resultados de operaciones.

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(
          title: 'Error',
          message: 'Error al guardar',
          code: ErrorCode.unknownError,
        ));
        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(
          title: 'Error',
          message: 'Error al guardar: $e',
          code: ErrorCode.unknownError,
        ),
      );
    }
  }
}

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(
    title: 'Error CrĂ­tico',
    message: 'ConexiĂłn perdida',
    code: ErrorCode.networkError,
    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
│   ├── view_models/         # Lógica de presentación
│   │   └── notification_view_model.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
│   │   └── notification_helpers.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 v3.0

  1. đź”— IntegraciĂłn con Toolkit: Interoperabilidad nativa con flutter_clean_mvvm_toolkit.
  2. 🚀 Configuración Instantánea: De ~30 líneas a 1 widget wrapper.
  3. đź’ˇ API Intuitiva: Dos formas simples de mostrar notificaciones.
  4. đź”’ Sin Conflictos: GetIt interno no interfiere con tu GetIt global.
  5. 📦 Auto-Contenida: La librería maneja todas sus dependencias.
  6. 🎯 BuildContext Extension: Sintaxis natural y familiar.
  7. 🌍 Helper Estático: Acceso desde cualquier lugar sin contexto.

đź“„ Licencia

MIT License - ver LICENSE para detalles.

VersiĂłn: 3.0.1
Fecha: Enero 2026
Cambios: IntegraciĂłn con Clean MVVM Toolkit y modelos estandarizados.

Libraries

flutter_notification_system
Flutter Notification System Library