npm package: @ngxhelpers/toast
Description: This service provides a way to display toast notifications in your Angular application. It leverages the `@ngxhelpers/overlay` library for managing overlays.
Latest version: 1.0.5

# ToastService

This service provides a way to display toast notifications in your Angular application. It leverages the `@ngxhelpers/overlay` library for managing overlays.

## Installation

```bash
npm install @ngxhelpers/overlay
```

## Usage

1. **Import `ToastService` and inject it into your component:**

```typescript
import { ToastService } from './toast.service';

constructor(private toastService: ToastService) {}
```

2. **Use the provided methods to display toasts:**

```typescript
// Success toast
this.toastService.success('Data saved successfully!');

// Error toast
this.toastService.error('An error occurred.');

// Warning toast
this.toastService.warning('Please check your input.');

// Info toast
this.toastService.info('Your download has started.');

// Custom title and timeout
this.toastService.success('Operation complete', 'Success', 5000); // 5-second timeout
```

## Configuration

You can customize the toast behavior by providing a `TOAST_CONFIG` InjectionToken in your module:

```typescript
import { ToastService, TOAST_CONFIG, ToastConfigs } from './toast.service';

const toastConfig: ToastConfigs = {
  timeOut: 3000,         // Default timeout (ms)
  position: 'topLeft',    // Default position ('topRight', 'topLeft', 'bottomRight', 'bottomLeft')
  initOffset: 60,        // Initial offset from the edge (px)
  maxOpened: 3,          // Maximum number of toasts displayed simultaneously
  component: MyCustomToastComponent, // Use a custom toast component
  autoDismiss: true      // Automatically dismiss toasts after timeout
};

@NgModule({
  ...
  providers: [
    ToastService,
    { provide: TOAST_CONFIG, useValue: toastConfig }
  ],
  ...
})
export class AppModule { }
```

## API Reference

### Methods

-   **`success(message: string, title?: string, timeout?: number): ActiveToast<any> | null`**: Displays a success toast.
-   **`error(message: string, title?: string, timeout?: number): ActiveToast<any> | null`**: Displays an error toast.
-   **`warning(message: string, title?: string, timeout?: number): ActiveToast<any> | null`**: Displays a warning toast.
-   **`info(message: string, title?: string, timeout?: number): ActiveToast<any> | null`**: Displays an info toast.
-   **`remove(toastId: number): boolean`**: Removes a specific toast by its ID. Returns `true` if successful, `false` otherwise.
-   **`clear()`: void`**: Removes all currently displayed toasts.

### Configurable Options (via `TOAST_CONFIG`)

-   **`timeOut: number`**: Duration the toast is displayed (in milliseconds). Default: 2500.
-   **`position: ToastPosition`**: Position of the toast on the screen ('topRight', 'topLeft', 'bottomRight', 'bottomLeft'). Default: 'topRight'.
-   **`initOffset: number`**: Initial offset of the toast from the edge of the screen (in pixels). Default: 80.
-   **`maxOpened: number`**: Maximum number of toasts that can be displayed simultaneously. Default: 5. If exceeded, older toasts will be removed if `autoDismiss` is true, otherwise, the new toast will be kept inactive until an older one is closed.
-   **`component: ComponentType<any>`**: Custom component to use for rendering the toast. Defaults to `ToastComponent`.
-   **`autoDismiss: boolean`**: Whether toasts should automatically dismiss after the specified `timeOut`. Default: `true`.

## Example with Custom Component

```typescript
import { Component } from '@angular/core';

@Component({
	selector: 'app-my-custom-toast',
	template: `
		<div class="custom-toast {{ type }}">
			<h3>{{ title }}</h3>
			<p>{{ message }}</p>
		</div>
	`,
	styles: [
		`
			.custom-toast {
				/* Your custom styles */
			}
		`
	]
})
export class MyCustomToastComponent {
	title = '';
	message = '';
	type = '';
}
```

Then, provide this component in your `TOAST_CONFIG`:

```typescript
{ provide: TOAST_CONFIG, useValue: { component: MyCustomToastComponent } }
```