@scania-nl/tegel-angular-extensions 0.0.1-0

package/README.md

@@ -0,0 +1,217 @@
+# @scania-nl/tegel-angular-extensions
+
+Angular services for working with the [Tegel Angular 17](https://www.npmjs.com/package/@scania/tegel-angular-17) component library.
+Provides simple wrappers for toast and modal (TBC) functionality using Angular 19+ **standalone components** and **dependency injection configuration**.
+
+---
+
+## ✨ Features
+
+- ✅ Drop-in `ToastService` for displaying toasts
+- ✅ Zero boilerplate — no Angular modules required
+- ✅ Fully typed and configurable via DI
+- ✅ Built for Angular 19+ standalone architecture
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @scania-nl/tegel-angular-extensions @scania/tegel-angular-17
+```
+
+> Note: `@scania/tegel-angular-17` is a peer dependency and must be installed separately.
+
+The following peer dependencies should be included automatically when creating an Angular 19+ project:
+
+```json
+{
+  "@angular/common": "^19.0.0",
+  "@angular/core": "^19.0.0",
+  "@angular/router": "^19.0.0",
+  "rxjs": "~7.8.0"
+}
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Add Providers
+In your `app.config.ts`, specifiy the provider with `provideToast()`:
+
+```ts
+import { provideToast } from '@scania-nl/tegel-angular-extensions';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideToast({
+      type: 'information',      // Default toast type
+      title: 'Notification',    // Default title
+      description: '',          // Default description
+      duration: 7500,           // Auto-dismiss delay (ms)
+      closeDuration: 300,       // Fade-out animation duration (ms)
+      closable: true,           // Show a close button
+    }),
+  ],
+};
+```
+> Note: The configuration is optional, all values shown above are the default settings.
+
+### 2. Use in components
+In any standalone component:
+
+```ts
+@Component({
+  standalone: true,
+  selector: 'my-toast-demo',
+  template: `<button (click)="showToast()">Show Toast</button>`,
+})
+export class MyToastDemoComponent {
+  private readonly toastService = inject(ToastService);
+
+  showToast() {
+    this.toastService.create({
+        type: 'success',
+        title: 'Hello Toast',
+        description: 'Toast created successfully!'
+    });
+  }
+}
+```
+
+---
+
+## ⚙️ Configuration Options
+
+You can configure the default appearance and behavior of toasts by passing a `ToastConfig` object to `provideToast()` in your `app.config.ts`.
+
+All options are optional. Defaults will be applied if values are not provided.
+
+| Property        | Type                                                 | Default          | Description                                                                |
+| --------------- | ---------------------------------------------------- | ---------------- | -------------------------------------------------------------------------- |
+| `type`          | `'information' \| 'success' \| 'warning' \| 'error'` | `'information'`  | Default toast type for `create()` calls                                    |
+| `title`         | `string`                                             | `'Notification'` | Default title text for toasts                                              |
+| `description`   | `string`                                             | `''`             | Default description text                                                   |
+| `duration`      | `number`                                             | `7500`           | Duration (ms) before a toast auto-closes (0 = stays until manually closed) |
+| `closeDuration` | `number`                                             | `300`            | Duration (ms) for fade-out animation (0 = remove instantly)                |
+| `closable`      | `boolean`                                            | `true`           | Whether a close button is shown                                            |
+
+> Note: You can override these defaults per toast when using `create()` or convenience methods like `success()`.
+
+---
+
+## 🧩 ToastService API
+
+The `ToastService` provides a signal-based API to create, manage, and dismiss toast notifications in Angular standalone apps. It is automatically available after registering `provideToast()` in your `app.config.ts`.
+
+---
+
+### 📦 Properties
+
+| Property       | Type              | Description                                           |
+| -------------- | ----------------- | ----------------------------------------------------- |
+| `toasts`       | `Signal<Toast[]>` | Read-only list of all toasts (including closed)       |
+| `activeToasts` | `Signal<Toast[]>` | List of currently active toasts (`Open` or `Closing`) |
+
+---
+
+### 🔧 Methods
+
+#### `create(toastOptions: Partial<ToastOptions>): number`
+
+Creates a custom toast with full control over appearance and behavior.
+
+Example:
+
+```ts
+toastService.create({
+  type: 'success',
+  title: 'Saved!',
+  description: 'Your changes have been saved.',
+  duration: 5000,
+});
+```
+
+Returns the unique toast ID.
+
+---
+
+#### Convenience Methods
+
+Creates a toast of a specific type:
+
+```ts
+toastService.success({ title: 'All good!' });
+toastService.error({ title: 'Oops!', description: 'Something went wrong.' });
+toastService.warning({ title: 'Heads up!' });
+toastService.info({ title: 'FYI' });
+```
+
+---
+
+#### `getToast(id: number): Toast | undefined`
+
+Gets a toast by its ID.
+
+---
+
+#### `createRandomToast(props?: Partial<ToastOptions>): number`
+
+Creates a random toast with random type and title. Useful for testing. Returns the toast's unique ID.
+
+```
+toastService.createRandomToast();
+```
+
+---
+
+#### `close(id: number): void`
+
+Triggers the fade-out animation and schedules removal.
+
+---
+
+#### `closeAll(): void`
+
+Closes all currently open toasts.
+
+---
+
+#### `remove(id: number): void`
+
+Immediately removes a toast (no animation).
+
+---
+
+#### `removeAll(): void`
+
+Force-removes all toasts instantly (no animations).
+
+---
+
+### 🔁 Toast Lifecycle Hooks
+
+Each toast supports optional lifecycle callbacks:
+
+| Callback           | Description                                  |
+| ------------------ | -------------------------------------------- |
+| `onCreated(toast)` | Called immediately after toast is created    |
+| `onClose(toast)`   | Called when toast is closed (before removal) |
+| `onRemoved(toast)` | Called when toast is fully removed           |
+
+Example:
+
+```ts
+toastService.success({
+  title: 'Logged out',
+  duration: 5000,
+  onRemoved: (toast) => console.log(`Toast ${toast.id} removed`)
+});
+```
+
+---
+
+## 📄 License
+
+All CSS, HTML and JS code are available under the MIT license. The Scania brand identity, logos and photographs found in this repository are copyrighted Scania CV AB and are not available on an open source basis or to be used as examples or in any other way, if not specifically ordered by Scania CV AB.

package/eslint.config.mjs

@@ -0,0 +1,48 @@
+import nx from '@nx/eslint-plugin';
+import baseConfig from '../../eslint.base.config.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: ['{projectRoot}/eslint.config.{js,cjs,mjs}'],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+  ...nx.configs['flat/angular'],
+  ...nx.configs['flat/angular-template'],
+  {
+    files: ['**/*.ts'],
+    rules: {
+      '@angular-eslint/directive-selector': [
+        'error',
+        {
+          type: 'attribute',
+          prefix: 'lib',
+          style: 'camelCase',
+        },
+      ],
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'tds-ext',
+          style: 'kebab-case',
+        },
+      ],
+    },
+  },
+  {
+    files: ['**/*.html'],
+    // Override or add rules here
+    rules: {},
+  },
+];

package/jest.config.ts

@@ -0,0 +1,21 @@
+export default {
+  displayName: 'tegel-angular-extensions',
+  preset: '../../jest.preset.js',
+  setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
+  coverageDirectory: '../../coverage/libs/tegel-angular-extensions',
+  transform: {
+    '^.+\\.(ts|mjs|js|html)$': [
+      'jest-preset-angular',
+      {
+        tsconfig: '<rootDir>/tsconfig.spec.json',
+        stringifyContentPathRegex: '\\.(html|svg)$',
+      },
+    ],
+  },
+  transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
+  snapshotSerializers: [
+    'jest-preset-angular/build/serializers/no-ng-attributes',
+    'jest-preset-angular/build/serializers/ng-snapshot',
+    'jest-preset-angular/build/serializers/html-comment',
+  ],
+};

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/libs/tegel-angular-extensions",
+  "lib": {
+    "entryFile": "src/index.ts"
+  }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@scania-nl/tegel-angular-extensions",
+  "version": "0.0.1-0",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@angular/common": "^19.0.0",
+    "@angular/core": "^19.0.0",
+    "@angular/router": "^19.0.0",
+    "@scania/tegel-angular-17": "^1.0.0",
+    "rxjs": "~7.8.0"
+  },
+  "sideEffects": false,
+  "author": {
+    "name": "Patrick Groot Koerkamp",
+    "email": "patrick.groot.koerkamp@scania.com"
+  }
+}

package/project.json

@@ -0,0 +1,36 @@
+{
+  "name": "tegel-angular-extensions",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/tegel-angular-extensions/src",
+  "prefix": "lib",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/angular:ng-packagr-lite",
+      "outputs": ["{workspaceRoot}/dist/{projectRoot}"],
+      "options": {
+        "project": "libs/tegel-angular-extensions/ng-package.json"
+      },
+      "configurations": {
+        "production": {
+          "tsConfig": "libs/tegel-angular-extensions/tsconfig.lib.prod.json"
+        },
+        "development": {
+          "tsConfig": "libs/tegel-angular-extensions/tsconfig.lib.json"
+        }
+      },
+      "defaultConfiguration": "production"
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "libs/tegel-angular-extensions/jest.config.ts"
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/toast/provide-toast';
+export * from './lib/toast/toast.config';
+export * from './lib/toast/toast.service';
+export * from './lib/toast/models/toast.model'

package/src/lib/toast/models/toast-state.enum.ts

@@ -0,0 +1,19 @@
+/**
+ * Represents the current lifecycle state of a toast.
+ */
+export enum ToastState {
+  /**
+   * The toast is fully visible and active.
+   */
+  Open = 'open',
+
+  /**
+   * The toast is transitioning out (e.g., fading out).
+   */
+  Closing = 'closing',
+
+  /**
+   * The toast is fully removed or dismissed.
+   */
+  Closed = 'closed',
+}

package/src/lib/toast/models/toast-type.ts

@@ -0,0 +1,9 @@
+/**
+ * List of available toast types (inherited from Tegel)
+ */
+export const TOAST_TYPES = ['success', 'information', 'warning', 'error'] as const;
+
+/**
+ * Type representing valid toast type values.
+ */
+export type ToastType = (typeof TOAST_TYPES)[number];

package/src/lib/toast/models/toast.model.ts

@@ -0,0 +1,87 @@
+import { ToastState } from './toast-state.enum';
+import { ToastType } from './toast-type';
+
+/**
+ * Defines the base structure for a toast message.
+ */
+export interface ToastOptions {
+  /**
+   * The visual style of the toast (e.g., success, error).
+   */
+  type: ToastType;
+
+  /**
+   * The main title text displayed in the toast.
+   */
+  title: string;
+
+  /**
+   * Optional description text providing additional context.
+   */
+  description?: string;
+
+  /**
+   * Duration in milliseconds before the toast auto-dismisses.
+   * Use `0` for persistent toasts.
+   */
+  duration: number;
+
+  /**
+   * Duration in milliseconds for the fade-out transition.
+   */
+  closeDuration: number;
+
+  /**
+   * Whether the toast can be manually closed by the user.
+   */
+  closable?: boolean;
+
+  /**
+   * Optional router link to navigate to when the toast is clicked.
+   */
+  link?: string;
+
+  /**
+   * Custom link text shown if a link is provided.
+   */
+  linkText?: string;
+
+  /**
+   * Optional callback triggered when the linkText is clicked.
+   * Used as an alternative to `link` for invoking custom behavior.
+   */
+  action?: () => void;
+
+  /**
+   * Optional callback triggered when the toast is created.
+   * @param toast The created toast instance.
+   */
+  onCreated?: (toast: Toast) => void;
+
+  /**
+   * Optional callback triggered when the toast begins to close.
+   * @param toast The toast that is closing.
+   */
+  onClose?: (toast: Toast) => void;
+
+  /**
+   * Optional callback triggered when the toast has been fully removed.
+   * @param toast The removed toast instance.
+   */
+  onRemoved?: (toast: Toast) => void;
+}
+
+/**
+ * Represents a fully instantiated toast, including unique ID and current state.
+ */
+export interface Toast extends ToastOptions {
+  /**
+   * Unique identifier for the toast instance.
+   */
+  id: number;
+
+  /**
+   * The current state of the toast (open, closing, or closed).
+   */
+  state: ToastState;
+}

package/src/lib/toast/provide-toast.ts

@@ -0,0 +1,29 @@
+import {
+  EnvironmentProviders,
+  makeEnvironmentProviders,
+  provideAppInitializer,
+} from '@angular/core';
+import { bootstrapGlobalComponent } from '../utils/bootstrap-global-component';
+import { ToastComponent } from './toast.component';
+import {
+  DEFAULT_TOAST_CONFIG,
+  TOAST_CONFIG,
+  ToastConfig,
+} from './toast.config';
+
+export function provideToast(
+  config: Partial<ToastConfig> = {}
+): EnvironmentProviders {
+  return makeEnvironmentProviders([
+    {
+      provide: TOAST_CONFIG,
+      useFactory: () => ({
+        ...DEFAULT_TOAST_CONFIG,
+        ...(config ?? {}),
+      }),
+    },
+    provideAppInitializer(() => {
+      bootstrapGlobalComponent(ToastComponent, { reuseIfExists: true });
+    }),
+  ]);
+}

package/src/lib/toast/toast.component.html

@@ -0,0 +1,41 @@
+<ul class="toast-list" aria-live="polite" aria-atomic="true">
+  @for (toast of toastsSignal(); track toast.id) {
+  <li
+    class="toast-item"
+    [class]="'toast-' + toast.type"
+    [class.toast-closing]="toast.state === 'closing'"
+    [style.--duration.ms]="toast.duration"
+    [style.--close-duration.ms]="toast.closeDuration"
+    role="status"
+  >
+    <tds-toast
+      [variant]="toast.type"
+      [header]="toast.title"
+      [subheader]="toast.description"
+      [closable]="toast.closable"
+      tds-close-aria-label="Toast close button"
+    >
+      @if (toast.link) {
+      <tds-link slot="actions">
+        <a [routerLink]="toast.link">
+          {{ toast.linkText ?? 'Click here' }}
+        </a>
+      </tds-link>
+      } @else if (toast.action) {
+      <tds-link slot="actions">
+        <a href="#" (click)="toast.action()">
+          {{ toast.linkText ?? 'Click here' }}
+        </a>
+      </tds-link>
+      }
+    </tds-toast>
+    @if (toast.closable) {
+    <button
+      class="toast-close"
+      (click)="closeToast(toast)"
+      aria-label="Close toast"
+    ></button>
+    }
+  </li>
+  }
+</ul>

package/src/lib/toast/toast.component.scss

@@ -0,0 +1,118 @@
+$default-close-duration: 300ms;
+$default-duration: 7000ms;
+$item-gap: 6px;
+
+:host {
+  position: fixed;
+  right: 0;
+  bottom: 0;
+  overflow: hidden;
+  z-index: 9999;
+}
+
+.toast-list {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: $item-gap;
+  /* List resets */
+  list-style: none;
+  padding: $item-gap;
+  margin: 0;
+}
+
+.toast-item {
+  position: relative;
+  animation: fadeIn $default-close-duration ease-in forwards;
+
+  &.toast-closing {
+    animation-name: fadeOut;
+    animation-duration: var(--close-duration, $default-close-duration);
+    animation-fill-mode: forwards;
+    pointer-events: none;
+  }
+
+  &::before {
+    content: '';
+    position: absolute;
+    height: 3px;
+    width: 100%;
+    bottom: 0;
+    left: 4px; /* Toast border itself */
+    right: 0;
+
+    animation: progress var(--duration, $default-duration)
+      linear forwards;
+
+    border-top-right-radius: 4px;
+    border-bottom-right-radius: 4px;
+  }
+
+  &.toast-information::before {
+    background: var(--tds-information);
+  }
+  &.toast-success::before {
+    background: var(--tds-positive);
+  }
+  &.toast-warning::before {
+    background: var(--tds-warning);
+  }
+  &.toast-error::before {
+    background: var(--tds-negative);
+  }
+
+  /*
+  Custom Close element for TDS, which is just a transparent block covering the close-button of the TdsToast element
+
+  Height, width, and positioning values are equal to TdsToast's button.close element for a perfect overlap
+  */
+  .toast-close {
+    height: 20px;
+    width: 20px;
+
+    box-sizing: border-box;
+    cursor: pointer;
+    position: absolute;
+    top: 14px;
+    right: 14px;
+
+    border: 0;
+    background: transparent;
+
+    &:active {
+      border: 2px solid var(--tds-blue-400);
+      outline-offset: -2px;
+    }
+  }
+}
+
+@keyframes fadeIn {
+  0% {
+    transform: translateY(40%);
+    opacity: 0;
+    margin-bottom: -25%;
+  }
+  100% {
+    transform: translateY(0);
+    opacity: 1;
+    margin-bottom: 0%;
+  }
+}
+
+@keyframes fadeOut {
+  0% {
+    transform: translateY(0);
+    opacity: 1;
+    margin-top: 0;
+  }
+  100% {
+    opacity: 0;
+    transform: translateY(75%);
+    margin-top: -25%;
+  }
+}
+
+@keyframes progress {
+  100% {
+    width: 0%;
+  }
+}

package/src/lib/toast/toast.component.spec.ts

@@ -0,0 +1,28 @@
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { provideToast } from './provide-toast';
+import { ToastComponent } from './toast.component';
+
+describe('ToastComponent', () => {
+  let component: ToastComponent;
+  let fixture: ComponentFixture<ToastComponent>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      declarations: [],
+      imports: [ToastComponent],
+      providers: [
+        provideToast()
+      ]
+    }).compileComponents();
+  });
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(ToastComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});

package/src/lib/toast/toast.component.ts

@@ -0,0 +1,37 @@
+import { CommonModule } from '@angular/common';
+import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { TegelModule } from '@scania/tegel-angular-17';
+
+import { Toast } from './models/toast.model';
+import { ToastService } from './toast.service';
+
+/**
+ * Displays toast notifications provided by the ToastService.
+ *
+ * Toasts are non-blocking messages that automatically disappear after a set duration
+ * or can be dismissed manually by the user.
+ */
+@Component({
+  selector: 'tds-ext-toast',
+  templateUrl: './toast.component.html',
+  styleUrls: ['./toast.component.scss'],
+  imports: [CommonModule, TegelModule, RouterLink],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ToastComponent {
+  private readonly toastService = inject(ToastService);
+
+  /**
+   * A reactive signal of all currently active toasts (open or closing).
+   */
+  readonly toastsSignal = this.toastService.activeToasts;
+
+  /**
+   * Initiates the closing process for the given toast.
+   *
+   * @param toast The toast to be closed.
+   * @returns void
+   */
+  closeToast = (toast: Toast) => this.toastService.close(toast.id);
+}

package/src/lib/toast/toast.config.ts

@@ -0,0 +1,50 @@
+import { InjectionToken } from '@angular/core';
+import { ToastType } from './models/toast-type';
+
+/**
+ * Global default configuration for toast behavior.
+ * Used when individual toast properties are not explicitly set.
+ */
+export interface ToastConfig {
+  /**
+   * Default toast type (e.g., 'success', 'information', etc.).
+   */
+  type: ToastType;
+
+  /**
+   * Default title to use when none is provided.
+   */
+  title: string;
+
+  /**
+   * Default description to use when none is provided.
+   */
+  description: string;
+
+  /**
+   * Default duration (ms) before auto-dismiss.
+   * Use `0` for persistent toasts.
+   */
+  duration: number;
+
+  /**
+   * Default duration (ms) for the fade-out animation.
+   */
+  closeDuration: number;
+
+  /**
+   * Whether toasts are closable by default.
+   */
+  closable: boolean;
+}
+
+export const TOAST_CONFIG = new InjectionToken<ToastConfig>('ToastConfig');
+
+export const DEFAULT_TOAST_CONFIG: Required<ToastConfig> = {
+  type: 'information',
+  title: 'Notification',
+  description: '',
+  duration: 7500,
+  closeDuration: 300,
+  closable: true,
+};

package/src/lib/toast/toast.service.ts

@@ -0,0 +1,275 @@
+import { computed, inject, Injectable, signal } from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { delay, filter, mergeMap, of, Subject, tap } from 'rxjs';
+import { ToastState } from './models/toast-state.enum';
+import { TOAST_TYPES } from './models/toast-type';
+import { Toast, ToastOptions } from './models/toast.model';
+import { TOAST_CONFIG, ToastConfig } from './toast.config';
+
+/**
+ * Service for creating, managing, and removing toast notifications.
+ * Supports automatic dismissal, manual control, and lifecycle hooks.
+ */
+@Injectable({
+  providedIn: 'root',
+})
+export class ToastService {
+  private readonly config = inject<ToastConfig>(TOAST_CONFIG);
+
+  //*------------------------------------------------------------
+  //* Section: Internal variables
+  //*------------------------------------------------------------
+
+  /** Internal ID tracker for unique toast IDs */
+  private id = 0;
+
+  /** Signal state holding all toasts */
+  private readonly _toasts = signal<Toast[]>([]);
+
+  /** Public signal of all toasts */
+  readonly toasts = this._toasts.asReadonly();
+
+  /** Signal of toasts that are not yet closed (open or closing) */
+  readonly activeToasts = computed(() =>
+    this._toasts().filter((toast) => toast.state !== ToastState.Closed)
+  );
+
+  /** Internal stream for auto-closing toasts */
+  private readonly autoCloseSubject = new Subject<Toast>();
+
+  /** Internal stream for fade-out/removal of toasts */
+  private readonly closeSubject = new Subject<Toast>();
+
+  constructor() {
+    // Auto-close after toast.duration
+    this.autoCloseSubject
+      .pipe(
+        takeUntilDestroyed(),
+        filter((toast) => toast.duration > 0),
+        mergeMap((toast: Toast) =>
+          of(toast).pipe(
+            delay(toast.duration),
+            filter(() => this.shouldAutoClose(toast.id)),
+            tap(() => this.close(toast.id))
+          )
+        )
+      )
+      .subscribe();
+
+    // Remove after toast.closeDuration (fade-out)
+    this.closeSubject
+      .pipe(
+        takeUntilDestroyed(),
+        mergeMap((toast: Toast) =>
+          of(toast).pipe(
+            delay(toast.closeDuration),
+            filter(() => this.shouldRemove(toast.id)),
+            tap(() => this.remove(toast.id))
+          )
+        )
+      )
+      .subscribe();
+  }
+
+  //*------------------------------------------------------------
+  //* Section: Public methods
+  //*------------------------------------------------------------
+
+  /**
+   * Creates and adds a new toast.
+   * @param toastOptions Partial toast definition.
+   * @returns The toast's unique ID.
+   */
+  create(toastOptions: Partial<ToastOptions>): number {
+    const id = this.createId();
+    const toast: Toast = {
+      ...this.config,
+      ...toastOptions,
+      id,
+      state: ToastState.Open,
+      duration: this.normalizeDuration(
+        toastOptions.duration,
+        this.config.duration
+      ),
+      closeDuration: this.normalizeDuration(
+        toastOptions.closeDuration,
+        this.config.closeDuration
+      ),
+    };
+
+    this.addToast(toast);
+    toast.onCreated?.(toast);
+
+    // Schedule auto-close if duration > 0
+    if (toast.duration > 0) {
+      this.autoCloseSubject.next(toast);
+    }
+
+    return id;
+  }
+
+  /**
+   * Initiates the fade-out transition for a toast.
+   * @param id The toast ID.
+   */
+  close(id: number): void {
+    let toast = this.getToast(id);
+    if (!toast || toast.state !== ToastState.Open) return;
+
+    toast = this.updateToastState(toast.id, ToastState.Closing);
+    toast?.onClose?.(toast);
+
+    // Schedule removal after close duration
+    if (toast) this.closeSubject.next(toast);
+  }
+
+  /**
+   * Immediately marks a toast as closed and removes it from display.
+   * @param id The toast ID.
+   */
+  remove(id: number): void {
+    const toast = this.updateToastState(id, ToastState.Closed);
+    toast?.onRemoved?.(toast);
+  }
+
+  /**
+   * Closes and removes all toasts immediately without fade-out.
+   */
+  removeAll(): void {
+    const closedToasts: Toast[] = [];
+
+    this._toasts.update((toasts) =>
+      toasts.map((toast) => {
+        if (toast.state !== ToastState.Closed) {
+          const updated = { ...toast, state: ToastState.Closed };
+          closedToasts.push(updated);
+          return updated;
+        }
+        return toast;
+      })
+    );
+
+    closedToasts.forEach((toast) => toast.onRemoved?.(toast));
+  }
+
+  /**
+   * Initiates closing process for all open toasts.
+   */
+  closeAll(): void {
+    const openToasts = this.toasts().filter(
+      (toast) => toast.state === ToastState.Open
+    );
+    openToasts.forEach((toast) => this.close(toast.id));
+  }
+
+  /**
+   * Gets a toast by ID.
+   * @param id The toast ID.
+   * @returns The toast instance or undefined.
+   */
+  getToast(id: number): Toast | undefined {
+    return this._toasts().find((toast) => toast.id === id);
+  }
+
+  //*------------------------------------------------------------
+  //* Section: Internal methods
+  //*------------------------------------------------------------
+
+  /** Whether the toast is eligible for auto-closing */
+  private shouldAutoClose(id: number): boolean {
+    const currentToast = this.getToast(id);
+    return currentToast?.state === ToastState.Open;
+  }
+
+  /** Whether the toast is eligible for final removal */
+  private shouldRemove(id: number): boolean {
+    const currentToast = this.getToast(id);
+    return currentToast?.state === ToastState.Closing;
+  }
+
+  /** Add toast to signal list */
+  private addToast(toast: Toast): void {
+    this._toasts.update((prev) => [...prev, toast]);
+  }
+
+  /**
+   * Updates the state of a toast.
+   * @param id Toast ID
+   * @param state New state
+   * @returns The updated toast or undefined
+   */
+  private updateToastState(id: number, state: ToastState): Toast | undefined {
+    let updatedToast: Toast | undefined;
+
+    this._toasts.update((prev) =>
+      prev.map((toast) => {
+        if (toast.id === id) {
+          updatedToast = { ...toast, state };
+          return updatedToast;
+        }
+        return toast;
+      })
+    );
+
+    return updatedToast;
+  }
+
+  /**
+   * Creates a unique id
+   * @returns New id
+   */
+  private createId(): number {
+    return ++this.id;
+  }
+
+  //*------------------------------------------------------------
+  //* Section: Public convenience methods
+  //*------------------------------------------------------------
+
+  /**
+   * Creates a success toast.
+   * @param props Toast props without type.
+   */
+  readonly success = (props: Partial<Omit<ToastOptions, 'type'>> = {}) =>
+    this.create({ ...props, type: 'success' });
+
+  /**
+   * Creates an error toast.
+   * @param props Toast props without type.
+   */
+  readonly error = (props: Partial<Omit<ToastOptions, 'type'>> = {}) =>
+    this.create({ ...props, type: 'error' });
+
+  /**
+   * Creates a warning toast.
+   * @param props Toast props without type.
+   */
+  readonly warning = (props: Partial<Omit<ToastOptions, 'type'>> = {}) =>
+    this.create({ ...props, type: 'warning' });
+
+  /**
+   * Creates an informational toast.
+   * @param props Toast props without type.
+   */
+  readonly info = (props: Partial<Omit<ToastOptions, 'type'>> = {}) =>
+    this.create({ ...props, type: 'information' });
+
+  /**
+   * Creates a random toast for testing/demo purposes.
+   * @param props Optional overrides
+   */
+  readonly createRandomToast = (props: Partial<ToastOptions> = {}) =>
+    this.create({
+      type: TOAST_TYPES[~~(Math.random() * 4)],
+      title: `Random Toast ${Math.random().toString(36).substring(7)}`,
+      ...props,
+    });
+
+  //*------------------------------------------------------------
+  //* Section: Helper methods
+  //*------------------------------------------------------------
+  private normalizeDuration(value: unknown, fallback: number): number {
+    const num = typeof value === 'number' ? value : fallback;
+    return !Number.isFinite(num) || num < 0 ? 0 : num;
+  }
+}

package/src/lib/utils/bootstrap-global-component.ts

@@ -0,0 +1,73 @@
+import {
+    ApplicationRef,
+    ComponentRef,
+    EmbeddedViewRef,
+    EnvironmentInjector,
+    Type,
+    createComponent,
+    inject,
+} from '@angular/core';
+
+/**
+ * Internal map to track which global components have been bootstrapped.
+ */
+const bootstrappedComponents = new WeakMap<
+  Type<unknown>,
+  ComponentRef<unknown>
+>();
+
+interface BootstrapGlobalComponentOptions {
+  /**
+   * If true, avoids re-creating the component if it's already mounted.
+   */
+  reuseIfExists?: boolean;
+}
+
+/**
+ * Bootstraps a global Angular component directly into the <body> element.
+ * Useful for toasts, modals, and other global overlays.
+ *
+ * @param component - The component class to bootstrap.
+ * @param options - Optional settings like preventing duplicates.
+ * @returns The created ComponentRef.
+ */
+export function bootstrapGlobalComponent<T>(
+  component: Type<T>,
+  options?: BootstrapGlobalComponentOptions
+): ComponentRef<T> {
+  const appRef = inject(ApplicationRef);
+  const injector = inject(EnvironmentInjector);
+
+  const existing = bootstrappedComponents.get(component);
+  if (existing && options?.reuseIfExists) {
+    return existing as ComponentRef<T>;
+  }
+
+  const cmpRef = createComponent(component, {
+    environmentInjector: injector,
+  });
+
+  appRef.attachView(cmpRef.hostView);
+
+  const viewRef = cmpRef.hostView as EmbeddedViewRef<unknown>;
+  const element = viewRef.rootNodes[0] as HTMLElement;
+
+  document.body.appendChild(element);
+
+  bootstrappedComponents.set(component, cmpRef);
+
+  return cmpRef;
+}
+
+/**
+ * Destroys a previously bootstrapped global component.
+ *
+ * @param component - The component class to remove from DOM.
+ */
+export function destroyGlobalComponent<T>(component: Type<T>): void {
+  const cmpRef = bootstrappedComponents.get(component);
+  if (cmpRef) {
+    cmpRef.destroy();
+    bootstrappedComponents.delete(component);
+  }
+}

package/src/test-setup.ts

@@ -0,0 +1,6 @@
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
+
+setupZoneTestEnv({
+  errorOnUnknownElements: true,
+  errorOnUnknownProperties: true,
+});

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ],
+  "extends": "../../tsconfig.base.json",
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  }
+}

package/tsconfig.lib.json

@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "declaration": true,
+    "declarationMap": true,
+    "inlineSources": true,
+    "types": []
+  },
+  "exclude": [
+    "src/**/*.spec.ts",
+    "src/test-setup.ts",
+    "jest.config.ts",
+    "src/**/*.test.ts"
+  ],
+  "include": ["src/**/*.ts"]
+}

package/tsconfig.lib.prod.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  },
+  "angularCompilerOptions": {}
+}

package/tsconfig.spec.json

@@ -0,0 +1,16 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "target": "es2016",
+    "types": ["jest", "node"]
+  },
+  "files": ["src/test-setup.ts"],
+  "include": [
+    "jest.config.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.d.ts"
+  ]
+}