@avoraui/av-notifications 0.0.2

package/README.md

@@ -0,0 +1,502 @@
+# AvNotification Service (AvoraUI)
+
+A flexible and customizable Angular notification service that provides toast-style notifications with multiple positioning options, themes, and animation effects. Built with Angular Material Dialog for optimal performance and accessibility.
+
+## Features
+
+- ✅ **Multiple Notification Types**: Success, Error, and Warning notifications
+- ✅ **Flexible Positioning**: 8 different position options (top, bottom, corners, sides)
+- ✅ **Theme Support**: Light, dark, and auto themes
+- ✅ **Auto-close Functionality**: Configurable duration with optional manual close
+- ✅ **Animation Effects**: Smooth entrance and exit animations
+- ✅ **Stack Management**: Multiple notifications with proper stacking
+- ✅ **Material Design**: Built with Angular Material components
+- ✅ **Memory Efficient**: Automatic cleanup and tracking of active notifications
+- ✅ **Accessibility**: Full keyboard navigation and screen reader support
+
+## Dependencies
+
+This service requires the following Angular Material modules:
+
+```typescript
+import { MatDialog, MatDialogModule } from "@angular/material/dialog";
+import { MatButton } from "@angular/material/button";
+import { MatIcon } from '@angular/material/icon';
+import { MatCard } from "@angular/material/card";
+```
+
+**Required Dependencies:**
+- `@angular/animations`: "^20.1.3"
+
+## Installation
+
+1. Ensure you have Angular Material installed in your project
+2. Install Angular Animations: `npm install @angular/animations@^20.1.3`
+3. Import the notification service in your module or inject it directly (standalone service)
+4. Add the notification components to your module declarations
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { AvNotificationService } from 'your-library/notification';
+
+export class MyComponent {
+  constructor(private notificationService: AvNotificationService) {}
+
+  showNotifications() {
+    // Success notification
+    this.notificationService.showSuccess('Operation completed successfully!');
+    
+    // Error notification
+    this.notificationService.showFailure('Something went wrong!');
+    
+    // Warning notification
+    this.notificationService.showWarning('Please check your input!');
+  }
+}
+```
+
+## Advanced Configuration
+
+### All Available Options
+
+```typescript
+export class AdvancedNotificationComponent {
+  constructor(private notificationService: AvNotificationService) {}
+
+  showCustomNotifications() {
+    // Success with custom configuration
+    this.notificationService.showSuccess('File uploaded successfully!', {
+      position: 'top-right',
+      duration: 8000,
+      theme: 'dark',
+      showCloseButton: true,
+      autoClose: true,
+      animationDuration: 500
+    });
+
+    // Error with persistent notification (no auto-close)
+    this.notificationService.showFailure('Critical system error occurred', {
+      position: 'center',
+      autoClose: false,
+      theme: 'light',
+      showCloseButton: true
+    });
+
+    // Warning with custom positioning
+    this.notificationService.showWarning('Session will expire in 5 minutes', {
+      position: 'bottom-left',
+      duration: 10000,
+      theme: 'auto',
+      animationDuration: 300
+    });
+  }
+}
+```
+
+## Configuration Options
+
+### NotificationConfig Interface
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `message` | `string` | Yes | - | The notification message to display |
+| `type` | `NotificationType` | Yes | - | Type of notification (success, error, warning) |
+| `position` | `NotificationPosition` | No | `'top'` | Position where notification appears |
+| `duration` | `number` | No | `5000` | Auto-close duration in milliseconds |
+| `animationDuration` | `number` | No | `300` | Animation duration in milliseconds |
+| `showCloseButton` | `boolean` | No | `true` | Whether to show manual close button |
+| `autoClose` | `boolean` | No | `true` | Whether notification auto-closes |
+| `theme` | `NotificationTheme` | No | `'auto'` | Visual theme (light, dark, auto) |
+
+### Position Options
+
+```typescript
+type NotificationPosition = 
+  | 'top'           // Top center
+  | 'bottom'        // Bottom center
+  | 'left'          // Left center
+  | 'right'         // Right center
+  | 'top-left'      // Top left corner
+  | 'top-right'     // Top right corner
+  | 'bottom-left'   // Bottom left corner
+  | 'bottom-right'; // Bottom right corner
+```
+
+### Notification Types
+
+```typescript
+type NotificationType = 'success' | 'error' | 'warning';
+```
+
+### Theme Options
+
+```typescript
+type NotificationTheme = 'light' | 'dark' | 'auto';
+```
+
+## Service Methods
+
+### Core Methods
+
+```typescript
+// Show success notification
+showSuccess(message: string, options?: Partial<NotificationConfig>): MatDialogRef<any>
+
+// Show error notification
+showFailure(message: string, options?: Partial<NotificationConfig>): MatDialogRef<any>
+
+// Show warning notification
+showWarning(message: string, options?: Partial<NotificationConfig>): MatDialogRef<any>
+```
+
+### Management Methods
+
+```typescript
+// Close all active notifications
+closeAll(): void
+
+// Close notifications by type
+closeByType(type: NotificationType): void
+
+// Get count of active notifications
+getActiveCount(): number
+
+// Check if notifications are active
+hasActiveNotifications(type?: NotificationType): boolean
+```
+
+## Real-World Examples
+
+### E-commerce Application
+
+```typescript
+export class EcommerceService {
+  constructor(private notificationService: AvNotificationService) {}
+
+  // Product added to cart
+  addToCart(product: Product) {
+    this.cartService.add(product).subscribe({
+      next: () => {
+        this.notificationService.showSuccess(`${product.name} added to cart!`, {
+          position: 'top-right',
+          duration: 3000,
+          theme: 'light'
+        });
+      },
+      error: () => {
+        this.notificationService.showFailure('Failed to add product to cart', {
+          position: 'top-right',
+          duration: 5000,
+          theme: 'light'
+        });
+      }
+    });
+  }
+
+  // Low stock warning
+  checkStockLevels() {
+    this.notificationService.showWarning('Only 2 items left in stock!', {
+      position: 'bottom-right',
+      duration: 8000,
+      theme: 'auto',
+      showCloseButton: true
+    });
+  }
+
+  // Payment processing
+  processPayment() {
+    this.notificationService.showSuccess('Payment processed successfully!', {
+      position: 'center',
+      duration: 4000,
+      theme: 'dark',
+      animationDuration: 500
+    });
+  }
+}
+```
+
+### Form Validation
+
+```typescript
+export class UserFormComponent {
+  constructor(private notificationService: AvNotificationService) {}
+
+  onSubmit(formData: UserForm) {
+    if (this.validateForm(formData)) {
+      this.userService.save(formData).subscribe({
+        next: () => {
+          this.notificationService.showSuccess('User profile updated successfully!', {
+            position: 'top',
+            duration: 6000,
+            theme: 'light'
+          });
+        },
+        error: (error) => {
+          this.notificationService.showFailure(`Update failed: ${error.message}`, {
+            position: 'top',
+            autoClose: false,
+            theme: 'light',
+            showCloseButton: true
+          });
+        }
+      });
+    } else {
+      this.notificationService.showWarning('Please fill in all required fields', {
+        position: 'top-left',
+        duration: 4000,
+        theme: 'auto'
+      });
+    }
+  }
+}
+```
+
+### File Upload Progress
+
+```typescript
+export class FileUploadComponent {
+  constructor(private notificationService: AvNotificationService) {}
+
+  uploadFile(file: File) {
+    // Start upload notification
+    const uploadingRef = this.notificationService.showSuccess('Starting file upload...', {
+      position: 'bottom-right',
+      duration: 2000,
+      theme: 'dark'
+    });
+
+    this.fileService.upload(file).subscribe({
+      next: (progress) => {
+        if (progress === 100) {
+          this.notificationService.showSuccess('File uploaded successfully!', {
+            position: 'bottom-right',
+            duration: 5000,
+            theme: 'light',
+            animationDuration: 400
+          });
+        }
+      },
+      error: () => {
+        this.notificationService.showFailure('Upload failed. Please try again.', {
+          position: 'bottom-right',
+          autoClose: false,
+          theme: 'light',
+          showCloseButton: true
+        });
+      }
+    });
+  }
+}
+```
+
+### System Notifications
+
+```typescript
+export class SystemNotificationService {
+  constructor(private notificationService: AvNotificationService) {}
+
+  // Session timeout warning
+  showSessionTimeout() {
+    this.notificationService.showWarning('Your session will expire in 2 minutes', {
+      position: 'top',
+      duration: 10000,
+      theme: 'auto',
+      showCloseButton: true,
+      animationDuration: 300
+    });
+  }
+
+  // Maintenance mode
+  showMaintenanceMode() {
+    this.notificationService.showWarning('System maintenance scheduled for tonight', {
+      position: 'bottom',
+      autoClose: false,
+      theme: 'dark',
+      showCloseButton: true
+    });
+  }
+
+  // Connection status
+  showConnectionLost() {
+    this.notificationService.showFailure('Connection lost. Attempting to reconnect...', {
+      position: 'top-right',
+      autoClose: false,
+      theme: 'light',
+      showCloseButton: false
+    });
+  }
+
+  showConnectionRestored() {
+    this.notificationService.showSuccess('Connection restored!', {
+      position: 'top-right',
+      duration: 3000,
+      theme: 'light'
+    });
+  }
+}
+```
+
+## Advanced Usage
+
+### Managing Multiple Notifications
+
+```typescript
+export class NotificationManagerComponent {
+  constructor(private notificationService: AvNotificationService) {}
+
+  showBulkOperationResults() {
+    // Clear any existing notifications
+    this.notificationService.closeAll();
+
+    // Show results
+    this.notificationService.showSuccess('5 items processed successfully', {
+      position: 'top-right',
+      duration: 4000
+    });
+
+    this.notificationService.showWarning('2 items skipped (duplicates)', {
+      position: 'top-right',
+      duration: 6000
+    });
+
+    this.notificationService.showFailure('1 item failed to process', {
+      position: 'top-right',
+      duration: 8000
+    });
+  }
+
+  clearSpecificNotifications() {
+    // Close only error notifications
+    this.notificationService.closeByType('error');
+    
+    // Check if any notifications are still active
+    const hasActiveNotifications = this.notificationService.hasActiveNotifications();
+    console.log('Active notifications:', hasActiveNotifications);
+    
+    // Get count of active notifications
+    const count = this.notificationService.getActiveCount();
+    console.log('Total active notifications:', count);
+  }
+}
+```
+
+### Custom Styling Integration
+
+```scss
+// Custom notification styles
+.notification-dialog {
+  &.notification-top-right {
+    margin-right: 24px !important;
+    margin-top: 24px !important;
+  }
+
+  &.notification-success {
+    .mat-mdc-dialog-container {
+      background: linear-gradient(135deg, #4caf50, #45a049);
+      color: white;
+    }
+  }
+
+  &.notification-theme-dark {
+    .mat-mdc-dialog-container {
+      background: #333;
+      color: #fff;
+    }
+  }
+}
+```
+
+## Browser Support
+
+- Chrome/Edge 57+
+- Firefox 52+
+- Safari 10.1+
+- Modern browsers with CSS Grid and Flexbox support
+
+## Requirements
+
+- Angular 17+
+- Angular Material
+- Modern browser with CSS Grid support
+
+## Performance Considerations
+
+- Notifications are automatically tracked and cleaned up
+- Object URLs are properly revoked to prevent memory leaks
+- Efficient dialog positioning with CSS transforms
+- Minimal DOM impact with Angular Material's overlay system
+
+## Accessibility Features
+
+- Full keyboard navigation support
+- Screen reader compatibility
+- High contrast theme support
+- Focus management for modal notifications
+- ARIA labels and descriptions
+
+## Best Practices
+
+### Do's
+```typescript
+// ✅ Use appropriate notification types
+this.notificationService.showSuccess('Data saved successfully');
+this.notificationService.showFailure('Validation error occurred');
+this.notificationService.showWarning('Session expiring soon');
+
+// ✅ Configure duration based on content importance
+this.notificationService.showSuccess('Quick action completed', { duration: 3000 });
+this.notificationService.showFailure('Critical error', { autoClose: false });
+
+// ✅ Use consistent positioning
+this.notificationService.showSuccess('Success', { position: 'top-right' });
+this.notificationService.showFailure('Error', { position: 'top-right' });
+```
+
+### Don'ts
+```typescript
+// ❌ Don't show too many notifications at once
+// Instead, use closeAll() or batch them appropriately
+
+// ❌ Don't use very short durations for important messages
+this.notificationService.showFailure('Critical error', { duration: 1000 }); // Too short
+
+// ❌ Don't forget to handle notification cleanup in components
+// Always let the service manage notification lifecycle
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Notifications not appearing**
+  - Ensure Angular Material Dialog is imported
+  - Check that notification components are declared
+  - Verify CSS z-index values
+
+2. **Styling issues**
+  - Import Angular Material themes
+  - Check for CSS conflicts with custom styles
+  - Ensure proper theme configuration
+
+3. **Performance issues**
+  - Use `closeAll()` before showing bulk notifications
+  - Avoid very short animation durations
+  - Monitor active notification count
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Changelog
+
+### v0.0.1
+- Initial release
+- Success, error, and warning notification types
+- 8 positioning options
+- Theme support (light, dark, auto)
+- Animation controls
+- Stack management
+- Accessibility features