@acontplus/ng-notifications

Angular notifications library for AcontPlus applications, providing toast notifications, alerts, and snackbars using popular libraries like ngx-toastr and SweetAlert2.

Installation

# Using npm
npm install @acontplus/ng-notifications @acontplus/ui-kit

# Using pnpm
pnpm add @acontplus/ng-notifications @acontplus/ui-kit

Note: @acontplus/ng-notifications depends on @acontplus/ui-kit for notification constants (messages, durations, icons). Both packages must be installed.

Features

• Toast Notifications: Using ngx-toastr for non-blocking notifications
• SweetAlert2 Integration: Modal alerts and confirmations with Material UI theme support
• Material Snackbar: Angular Material snackbar components
• Auto Theme Detection: Automatically detects light/dark theme for SweetAlert2
• Unified Service: Single service for managing different notification providers
• Flexible Configuration: Customizable configurations for all providers
• TypeScript Support: Full type safety with comprehensive TypeScript definitions
• SSR Compatible: Server-side rendering support
• Lifecycle Callbacks: Support for SweetAlert2 lifecycle hooks (didOpen, willClose, etc.)

Configuration Options

NotificationProviderConfig

interface NotificationProviderConfig {
  defaultProvider: 'sweetalert' | 'toastr' | 'snackbar';
  sweetalert?: {
    defaultTheme?: 'auto' | 'material-ui' | 'material-ui-light' | 'material-ui-dark';
  };
  toastr?: ToastrConfig;
  snackbar?: SnackbarConfig;
}

SweetAlert2 Theme Options

• 'auto' - Auto-detects based on .dark-theme CSS class (default)
• 'material-ui' - Follows system preference
• 'material-ui-light' - Always light theme
• 'material-ui-dark' - Always dark theme

Quick Start

1. Install Dependencies

# Using npm
npm install @acontplus/ng-notifications ngx-toastr sweetalert2

# Using pnpm
pnpm add @acontplus/ng-notifications ngx-toastr sweetalert2

2. Import CSS (in styles.scss)

@import 'ngx-toastr/toastr';
@import 'sweetalert2/themes/material-ui.css';

3. Configure Providers

import { provideNotifications } from '@acontplus/ng-notifications';

// In app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [
    // Basic configuration
    provideNotifications({
      defaultProvider: 'sweetalert', // or 'toastr' | 'snackbar'
    }),

    // Advanced configuration
    provideNotifications({
      defaultProvider: 'sweetalert',
      sweetalert: {
        defaultTheme: 'auto', // auto-detects light/dark theme
      },
      toastr: {
        timeOut: 5000,
        positionClass: 'toast-top-right',
        preventDuplicates: true,
      },
      snackbar: {
        duration: 3000,
        horizontalPosition: 'center',
        verticalPosition: 'bottom',
      },
    }),
  ],
};

4. Use in Components

import { NotificationService } from '@acontplus/ng-notifications';

@Component({...})
export class MyComponent {
  constructor(private notificationService: NotificationService) {}

  // Basic notifications
  showSuccess() {
    this.notificationService.success({
      title: 'Success!',
      message: 'Operation completed successfully'
    });
  }

  showError() {
    this.notificationService.error({
      title: 'Error',
      message: 'Something went wrong'
    });
  }

  // Confirmation dialog
  confirmAction() {
    this.notificationService.confirm({
      title: 'Are you sure?',
      message: 'This action cannot be undone'
    }).subscribe(result => {
      if (result.isConfirmed) {
        console.log('User confirmed');
      }
    });
  }

  // Custom configuration
  showCustom() {
    this.notificationService.info({
      title: 'Info',
      message: 'Custom notification',
      config: {
        duration: 3000, // Auto-close after 3 seconds
        theme: 'material-ui-dark', // Force dark theme
        didOpen: (popup) => {
          console.log('Notification opened', popup);
        }
      }
    });
  }
}

Provider Behaviors

SweetAlert2 (Default)

• Theme: Auto-detects light/dark theme by default
• Duration: Stays open until user interaction (Material Design approach)
• Customization: Full SweetAlert2 API support via config object

// Auto-detects theme, stays open
this.notificationService.success({ title: 'Success', message: 'Saved!' });

// Custom theme and auto-close
this.notificationService.info({
  title: 'Info',
  message: 'Processing...',
  config: {
    theme: 'material-ui-dark',
    timer: 3000,
    timerProgressBar: true,
  },
});

Material Snackbar

• Duration: Auto-dismisses after 5 seconds (Material Design default)
• Position: Bottom center
• Customization: Full MatSnackBarConfig support

// Uses default 5-second duration
this.notificationService.snackbar.success({ message: 'Success!' });

// Custom duration and position
this.notificationService.snackbar.info({
  message: 'Info message',
  config: {
    duration: 2000,
    verticalPosition: 'top',
    horizontalPosition: 'right',
  },
});

Toastr

• Duration: Auto-dismisses based on type (success: 5s, error: 10s)
• Position: Top right
• Customization: Full ngx-toastr configuration support

Theme Configuration

Auto Theme Detection (Default)

provideNotifications({
  defaultProvider: 'sweetalert',
  // No theme config needed - auto-detects light/dark
});

Manual Theme Control

provideNotifications({
  defaultProvider: 'sweetalert',
  sweetalert: {
    defaultTheme: 'material-ui-dark', // Always dark
    // defaultTheme: 'material-ui-light' // Always light
    // defaultTheme: 'material-ui' // System preference
  },
});

Per-Notification Theme Override

this.notificationService.success({
  title: 'Success',
  message: 'Completed',
  config: {
    theme: 'material-ui-light', // Override default theme
  },
});

CDK Overlay Configuration

SweetAlert2 and ngx-toastr use the Angular CDK overlay internally. To prevent conflicts with the native Popover API (which can cause z-index and positioning issues), disable it globally:

import { OVERLAY_DEFAULT_CONFIG } from '@angular/cdk/overlay';

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: OVERLAY_DEFAULT_CONFIG,
      useValue: { usePopover: false },
    },
    provideNotifications({
      defaultProvider: 'sweetalert',
    }),
  ],
};

Why? The native Popover API can interfere with how SweetAlert2 modals and toastr overlays are stacked. Setting usePopover: false forces the CDK to use the traditional overlay strategy, ensuring correct rendering.

Advanced Usage

Lifecycle Callbacks

this.notificationService.success({
  title: 'Success',
  message: 'Data saved',
  config: {
    didOpen: (popup) => {
      console.log('Notification opened');
      popup.querySelector('.swal2-confirm')?.focus();
    },
    willClose: () => {
      console.log('Notification closing');
    },
    didClose: () => {
      console.log('Notification closed');
    },
  },
});

Provider-Specific Access

// Direct provider access
this.notificationService.sweetAlert.success({
  title: 'Success',
  message: 'Done!',
});
this.notificationService.toastr.error({ message: 'Error occurred' });
this.notificationService.snackbar.info({ message: 'Information' });

Quick Methods

// Predefined messages (from @acontplus/ui-kit)
this.notificationService.quickSave(); // "Data saved successfully"
this.notificationService.quickDelete(); // "Item deleted"
this.notificationService.networkError(); // "Network connection error"

Notification Constants

This library re-exports notification constants from @acontplus/ui-kit for backward compatibility:

import {
  NOTIFICATION_MESSAGES,
  NOTIFICATION_DURATIONS,
  NOTIFICATION_ICONS,
} from '@acontplus/ng-notifications';

// Pre-defined messages
NOTIFICATION_MESSAGES.SUCCESS.SAVE; // 'Data saved successfully'
NOTIFICATION_MESSAGES.ERROR.NETWORK; // 'Network error occurred'
NOTIFICATION_MESSAGES.WARNING.UNSAVED_CHANGES; // 'You have unsaved changes'

// Standard durations
NOTIFICATION_DURATIONS.SHORT; // 3000ms
NOTIFICATION_DURATIONS.MEDIUM; // 5000ms
NOTIFICATION_DURATIONS.LONG; // 8000ms

// Icon mappings (Material icons)
NOTIFICATION_ICONS.success; // 'check_circle'
NOTIFICATION_ICONS.error; // 'error'
NOTIFICATION_ICONS.warning; // 'warning'
NOTIFICATION_ICONS.info; // 'info'

These constants are defined in @acontplus/ui-kit to ensure they're framework-agnostic and reusable across different notification implementations.