TeqBench Material Notifications

Extends TbxMatFontIconService from @teqbench/tbx-mat-icons and registers the 'close' Material Symbols ligature. Used as the package-provided default for TbxMatNotificationProviderConfig.closeIconResolverService when the consumer does not supply a custom close icon resolver.

No default SVG close icon service is provided. Consumers who want SVG close icons must create a concrete subclass of TbxMatSvgIconService from @teqbench/tbx-mat-icons and provide it via TbxMatNotificationProviderConfig.closeIconResolverService.

fontSet resolution

The fontSet is resolved by TbxMatFontIconService's fallback chain:

1. Explicit constructor argument — new TbxMatNotificationCloseFontIconService('material-symbols-sharp')
2. TBX_MAT_FONT_ICON_DEFAULT_FONT_SET token — set once in app.config.ts
3. MAT_ICON_DEFAULT_OPTIONS.fontSet — Angular Material's global icon default
4. Error — if none of the above provides a fontSet

// app.config.ts — no explicit close icon service needed, package default used
import { MAT_ICON_DEFAULT_OPTIONS } from '@angular/material/icon';
import { TBX_MAT_NOTIFICATION_PROVIDER_CONFIG, TbxMatNotificationSeverityFontIconService }
    from '@teqbench/tbx-mat-notifications';

providers: [
    { provide: MAT_ICON_DEFAULT_OPTIONS, useValue: { fontSet: 'material-symbols-rounded' } },
    {
        provide: TBX_MAT_NOTIFICATION_PROVIDER_CONFIG,
        useFactory: () => ({
            severityIconResolverService: new TbxMatNotificationSeverityFontIconService(),
            // closeIconResolverService omitted — package default (TbxMatNotificationCloseFontIconService) used
        }),
    },
]

// app.config.ts — consumer provides a custom close icon service
import { TBX_MAT_NOTIFICATION_PROVIDER_CONFIG, TbxMatNotificationSeverityFontIconService,
    TbxMatNotificationCloseFontIconService } from '@teqbench/tbx-mat-notifications';

// Consumer subclass that registers 'cancel' instead of 'close'
// MyCloseIconService is a hypothetical consumer-defined subclass
class MyCloseIconService extends TbxMatNotificationCloseFontIconService {
    protected override initialize(): void {
        this.register('close', 'cancel');
    }
}

providers: [
    {
        provide: TBX_MAT_NOTIFICATION_PROVIDER_CONFIG,
        useFactory: () => ({
            severityIconResolverService: new TbxMatNotificationSeverityFontIconService('material-symbols-rounded'),
            closeIconResolverService: new MyCloseIconService('material-symbols-rounded'),
        }),
    },
]

Wraps Angular Material's MatSnackBar with typed severity levels, configurable duration, and a custom snackbar component that displays an optional severity icon + message + optional action button + optional dismiss button.

Notifications are queued FIFO and displayed one at a time. When the current notification is dismissed (manually or by timeout), the next queued notification is shown automatically. This follows Material Design guidelines — only one snackbar should be visible at a time.

All public methods return a TbxMatNotificationRef synchronously, containing the consumer's config and two promises: - snackBarRef — resolves with the native MatSnackBarRef when the notification displays, or null if cleared from the queue. - result — resolves with a TbxMatNotificationResult containing the TbxMatNotificationDismissReason when the notification is dismissed.

Consumers who do not need the ref or result should use the void prefix to suppress unhandled-promise lint warnings:

void this.notificationService.success('Saved');

Queue state is exposed via Angular signals for reactive consumption: - isActive() — whether a notification is currently visible - pendingCount() — number of notifications waiting in the queue

Inject the service and call the convenience methods for each severity level. Use show() when full control over configuration is needed. Use dismiss() and dismissAll() to programmatically clear notifications. Bind isActive() and pendingCount() in templates or computed signals for reactive state.

private readonly notify = inject(TbxMatNotificationService);

void this.notify.success('Item saved successfully.');
void this.notify.error('Failed to load data. Please try again.');

const ref = this.notify.success('Item deleted.', {
    action: { label: 'Undo' },
    duration: 30_000,
});

const result = await ref.result;
if (result.dismissReason === TbxMatNotificationDismissReason.Action) {
    this.undoDelete();
}

const ref = this.notify.error('Upload failed.', {
    action: { label: 'Retry' },
});

const snackBarRef = await ref.snackBarRef;
snackBarRef?.afterOpened().subscribe(() => {
    console.log('Notification is visible');
});

Extends TbxMatSeverityFontIconService from @teqbench/tbx-mat-severity-theme and registers the shared default Material Symbols ligatures (TBX_MAT_SEVERITY_DEFAULT_FONT_LIGATURES) for every severity level. The inherited resolve() and severity methods (default(), success(), error(), etc.) work via the registered mappings.

fontSet resolution

The fontSet is resolved by TbxMatFontIconService's fallback chain:

1. Explicit constructor argument — new TbxMatNotificationSeverityFontIconService('material-symbols-sharp')
2. TBX_MAT_FONT_ICON_DEFAULT_FONT_SET token — set once in app.config.ts
3. MAT_ICON_DEFAULT_OPTIONS.fontSet — Angular Material's global icon default
4. Error — if none of the above provides a fontSet

For steps 1 and 2, the consuming component must bind [fontSet] on <mat-icon>. For step 3, <mat-icon> already uses the global default — no binding needed.

// app.config.ts
import { MAT_ICON_DEFAULT_OPTIONS } from '@angular/material/icon';
import { TBX_MAT_NOTIFICATION_PROVIDER_CONFIG, TbxMatNotificationSeverityFontIconService }
    from '@teqbench/tbx-mat-notifications';

providers: [
    { provide: MAT_ICON_DEFAULT_OPTIONS, useValue: { fontSet: 'material-symbols-rounded' } },
    {
        provide: TBX_MAT_NOTIFICATION_PROVIDER_CONFIG,
        useFactory: () => ({
            severityIconResolverService: new TbxMatNotificationSeverityFontIconService(),
        }),
    },
]

// app.config.ts
import { TBX_MAT_NOTIFICATION_PROVIDER_CONFIG, TbxMatNotificationSeverityFontIconService }
    from '@teqbench/tbx-mat-notifications';

providers: [
    {
        provide: TBX_MAT_NOTIFICATION_PROVIDER_CONFIG,
        useFactory: () => ({
            severityIconResolverService: new TbxMatNotificationSeverityFontIconService('material-symbols-rounded'),
        }),
    },
]

// app.config.ts
import { TBX_MAT_FONT_ICON_DEFAULT_FONT_SET, TBX_MAT_ICON_FONT_SET_MATERIAL_SYMBOLS_ROUNDED }
    from '@teqbench/tbx-mat-icons';
import { TBX_MAT_NOTIFICATION_PROVIDER_CONFIG, TbxMatNotificationSeverityFontIconService }
    from '@teqbench/tbx-mat-notifications';

providers: [
    { provide: TBX_MAT_FONT_ICON_DEFAULT_FONT_SET, useValue: TBX_MAT_ICON_FONT_SET_MATERIAL_SYMBOLS_ROUNDED },
    {
        provide: TBX_MAT_NOTIFICATION_PROVIDER_CONFIG,
        useFactory: () => ({
            severityIconResolverService: new TbxMatNotificationSeverityFontIconService(),
        }),
    },
]

Extends TbxMatSeveritySvgIconService from @teqbench/tbx-mat-severity-theme and registers the shared default SVG icons (TBX_MAT_SEVERITY_DEFAULT_SVG_ICONS) for every severity level. The inherited resolve() and severity methods (default(), success(), error(), etc.) work via the registered mappings.

Default icons ship with @teqbench/tbx-mat-severity-theme. Subclasses can override any default by overriding initialize() and calling register() with the same key and different SVG markup.

// app.config.ts
import { TBX_MAT_NOTIFICATION_PROVIDER_CONFIG, TbxMatNotificationSeveritySvgIconService }
    from '@teqbench/tbx-mat-notifications';

providers: [
    {
        provide: TBX_MAT_NOTIFICATION_PROVIDER_CONFIG,
        useFactory: () => ({
            severityIconResolverService: new TbxMatNotificationSeveritySvgIconService(),
        }),
    },
]

import { Injectable } from '@angular/core';
import { TbxMatNotificationSeveritySvgIconService } from '@teqbench/tbx-mat-notifications';
import { TbxMatSeverityLevel } from '@teqbench/tbx-mat-severity-theme';

// MyNotificationSvgIcons is a consumer-defined subclass
@Injectable()
export class MyNotificationSvgIcons extends TbxMatNotificationSeveritySvgIconService {
    protected override initialize(): void {
        super.initialize();
        this.register(TbxMatSeverityLevel.Success, '<svg>...</svg>');
    }
}

Rendered inside MatSnackBar via openFromComponent(). Receives its data through MAT_SNACK_BAR_DATA injection token as an internal DTO.

Template element order

All elements are optional except the message. The action button and close button both render within matSnackBarActions and use the matSnackBarAction directive.

Action button rendering

When data.actionLabel is set, the component renders an action button. The button appearance is determined by data.actionButtonType: - 'text' / 'filled' / 'elevated' / 'outlined' / 'tonal' — renders mat-button with [matButton] input binding and optional icon. - 'icon' — renders mat-icon-button with aria-label from data.actionLabel.

Icon rendering

Icons are resolved to a ResolvedIcon ({ name, isSvg }) via computed signals and a shared resolveIcon() helper. Three icon categories exist: severity, action, and close — each backed by a resolver service that determines whether to render a font ligature or an SVG icon.

A shared ng-template (#tbxNgIconTemplate) handles the font vs SVG branching for all icon sites. Each call site passes a ResolvedIcon via ngTemplateOutlet context. The template guards against null internally, so call sites do not need their own null checks.

Content projection and ngProjectAs

Angular Material's button component uses ng-content select to project mat-icon elements into leading and trailing slots: - mat-icon:not([iconPositionEnd]) — leading slot (before the label) - mat-icon[iconPositionEnd] — trailing slot (after the label)

When mat-icon is rendered via ngTemplateOutlet inside an ng-container, Angular's projection matching sees ng-container — not mat-icon — as the direct child of the button. The icon falls into the default <ng-content> slot (.mdc-button__label) instead of the icon slot, breaking alignment.

The ngProjectAs attribute on ng-container solves this. It tells Angular's projection matching (isSelectorInSelectorList in the runtime) to treat the ng-container as if it were the specified selector. The match is exact — the parsed ngProjectAs value must match the parsed ng-content select value element-by-element: - ngProjectAs="mat-icon:not([iconPositionEnd])" — matches the leading slot selector exactly - ngProjectAs="mat-icon[iconPositionEnd]" — matches the trailing slot selector exactly

A plain ngProjectAs="mat-icon" does NOT match the leading slot because the slot selector is mat-icon:not([iconPositionEnd]) — the parsed arrays have different lengths and isSelectorInSelectorList requires exact element-by-element equality.

Countdown bar

Renders only when data.showCountdown is true AND data.duration is positive (not indefinite). Setting showCountdown: true with duration <= 0 has no visible effect — an indefinite notification has no countdown to display.

// Consumers do not instantiate this component directly.
// It is rendered via MatSnackBar.openFromComponent() by the service.
void this.notificationService.success('Item saved.');

Defines the content and appearance of the optional action button rendered in the notification snackbar. The action button sits between the message and the close button in the M3 snackbar anatomy.

Resolution Cascade

Properties set here override the corresponding property on TbxMatNotificationProviderActionConfig. When neither is set, the following defaults apply:

• actionButtonType — 'text' - iconPosition — TbxMatNotificationIconPosition.Before - actionIconResolverService — none (required when iconName is set and the resolved button type uses icons)

Fallback Rules

The service applies fallback rules when the provided combination of fields is invalid:

• actionButtonType is 'icon' but iconName is not set — falls back to 'text' and renders the label as a text button. - actionButtonType is 'text' and iconName is set — the icon is ignored; only the label is rendered. - iconName is set and the resolved button type requires an icon, but no actionIconResolverService is available (neither per-notification nor provider-level) — logs an error and does not render the action.

Add an action to a notification to let users respond inline (e.g., undo, retry, view). Set on TbxMatNotificationConfig.action or passed via the convenience method config args.

this.notificationService.success('Item deleted', {
    action: { label: 'Undo' },
    duration: 30_000,
});

// label serves as the aria-label for accessibility
// myIconService is a hypothetical consumer-defined icon resolver
this.notificationService.error('Upload failed', {
    action: {
        label: 'Retry',
        iconName: 'refresh',
        actionButtonType: 'icon',
        actionIconResolverService: myIconService,
    },
});

// myIconService is a hypothetical consumer-defined icon resolver
this.notificationService.warning('Connection lost', {
    action: {
        label: 'Retry',
        iconName: 'sync',
        actionButtonType: 'tonal',
        iconPosition: TbxMatNotificationIconPosition.Before,
        actionIconResolverService: myIconService,
    },
});

Set on TbxMatNotificationProviderConfig.actionConfig to establish application-wide defaults for action button appearance, icon position, and icon resolution. Individual notifications can override any of these via TbxMatNotificationAction.

All properties are optional. When a property is not set here and not overridden per-notification, the following defaults apply:

• actionButtonType — 'text' - iconPosition — TbxMatNotificationIconPosition.Before - actionIconResolverService — none

Configure action button defaults in the provider config when all or most action buttons in the application share the same appearance or icon resolver. Omit entirely if action buttons are not used or defaults are sufficient.

// app.config.ts
import { TBX_MAT_NOTIFICATION_PROVIDER_CONFIG }
    from '@teqbench/tbx-mat-notifications';

providers: [
    {
        provide: TBX_MAT_NOTIFICATION_PROVIDER_CONFIG,
        useFactory: () => ({
            severityIconResolverService: new TbxMatNotificationSeverityFontIconService('material-symbols-rounded'),
            // MyActionIconService is a hypothetical consumer-defined icon resolver
            actionConfig: {
                actionButtonType: 'tonal',
                iconPosition: TbxMatNotificationIconPosition.Before,
                actionIconResolverService: new MyActionIconService(),
            },
        }),
    },
]

Returned synchronously from all TbxMatNotificationService methods (show(), success(), error(), warning(), information(), help()). Contains three members:

• config — the consumer-provided configuration, available immediately. - snackBarRef — a promise that resolves with the native MatSnackBarRef when the notification is displayed (comes off the FIFO queue), or null if the notification was cleared from the queue before being displayed (e.g., via TbxMatNotificationService.dismissAll). - result — a promise that resolves with a TbxMatNotificationResult containing the TbxMatNotificationDismissReason when the notification is dismissed.

Native Ref vs Service Dismiss Methods

The snackBarRef promise exposes the full MatSnackBarRef API, including dismiss(), dismissWithAction(), afterOpened(), afterDismissed(), and onAction(). Using the native ref for read-only operations (subscriptions, inspection) is safe and recommended. However, calling dismiss() or dismissWithAction() directly on the native ref bypasses the enriched TbxMatNotificationDismissReason tracking — the result promise may resolve with an incorrect reason (e.g., Timeout instead of ProgrammaticDismissCurrent).

For accurate dismiss reason tracking, use the service convenience methods (TbxMatNotificationService.dismiss, TbxMatNotificationService.dismissAll) or the component's action/close buttons.

Fire-and-Forget Usage

Consumers who do not need the dismiss result or native ref should prefix the call with void to suppress unhandled-promise lint warnings:

void this.notificationService.success('Saved');

Capture the returned ref to react to notification dismissal, access the native snackbar ref for subscriptions, or inspect the original config.

const ref = this.notificationService.success('Item deleted', {
    action: { label: 'Undo' },
    duration: 30_000,
});

const result = await ref.result;

if (result.dismissReason === TbxMatNotificationDismissReason.Action) {
    this.undoDelete();
}

const ref = this.notificationService.error('Upload failed', {
    action: { label: 'Retry' },
});

const snackBarRef = await ref.snackBarRef;

snackBarRef?.afterOpened().subscribe(() => {
    console.log('Notification is visible');
});

void this.notificationService.success('Saved');

Resolved by the TbxMatNotificationRef.result promise when a notification is dismissed for any reason — user action, timeout, or programmatic dismissal. The dismissReason property indicates which trigger caused the dismissal.

Await the result promise from any TbxMatNotificationService method to determine how a notification was dismissed and react accordingly.

const ref = this.notificationService.success('Item deleted', {
    action: { label: 'Undo' },
    duration: 30_000,
});

const result: TbxMatNotificationResult = await ref.result;

if (result.dismissReason === TbxMatNotificationDismissReason.Action) {
    this.undoDelete();
}

Returned as part of TbxMatNotificationResult via TbxMatNotificationRef.result. Each value corresponds to a distinct dismissal trigger:

• Action — the user clicked the action button. - Close — the user clicked the close button. - Timeout — the notification auto-dismissed after the configured duration expired. - ProgrammaticDismissAll — TbxMatNotificationService.dismissAll was called, clearing the queue and dismissing the active notification. - ProgrammaticDismissCurrent — TbxMatNotificationService.dismiss was called, dismissing only the currently active notification.

When the consumer dismisses via the native MatSnackBarRef obtained from TbxMatNotificationRef.snackBarRef, the enriched reason tracking is bypassed — the result may resolve with Timeout instead of the expected programmatic reason. Use the service convenience methods for accurate reason tracking.

Inspect the dismiss reason after awaiting the result promise to determine which user or programmatic action closed the notification.

const ref = this.notificationService.success('Item deleted', {
    action: { label: 'Undo' },
    duration: 30_000,
});

const result = await ref.result;

if (result.dismissReason === TbxMatNotificationDismissReason.Action) {
    this.undoDelete();
}

Controls whether an icon renders before or after the label text on an action button. Applies only when the resolved TbxMatNotificationActionButtonAppearance is not 'icon' (icon-only buttons have no label to position relative to).

The position can be set at the provider level via TbxMatNotificationProviderActionConfig.iconPosition or per-notification via TbxMatNotificationAction.iconPosition. Per-notification takes precedence. When neither is set, defaults to Before.

Set the icon position when an action button has both a label and an icon, and the default leading position is not desired.

this.notificationService.success('File uploaded', {
    action: {
        label: 'View',
        iconName: 'open_in_new',
        iconPosition: TbxMatNotificationIconPosition.After,
    },
});

Union of MatButtonAppearance ('text' | 'filled' | 'elevated' | 'outlined' | 'tonal') and the custom 'icon' value for icon-only action buttons.

Values other than 'icon' map directly to the [appearance] input on Angular Material button directives. The 'icon' value renders a mat-icon-button instead.

This type is coupled to MatButtonAppearance from @angular/material/button. If Angular Material renames, removes, or adds values to that type, this type will need a corresponding update.

The appearance can be set at the provider level via TbxMatNotificationProviderActionConfig.actionButtonType or per-notification via TbxMatNotificationAction.actionButtonType. Per-notification takes precedence. When neither is set, defaults to 'text' per M3 guidelines (snackbars are the lowest-priority notification surface).

Specify the action button appearance when the default 'text' style is not desired.

// Tonal action button
this.notificationService.warning('Connection lost', {
    action: {
        label: 'Retry',
        actionButtonType: 'tonal',
    },
});

// Icon-only action button
this.notificationService.error('Upload failed', {
    action: {
        label: 'Retry', // used as aria-label
        iconName: 'refresh',
        actionButtonType: 'icon',
    },
});

• Snackbar container. Notifications render inside Angular Material's snackbar overlay, which announces new snackbars to assistive technology via its built-in politeness handling. Consumers can pass politeness through the snackBarConfig passthrough on TbxMatNotificationConfig to customize the announcement level ('polite', 'assertive', or 'off').
• Keyboard. The action button and close button are focusable in DOM order. Enter and Space activate them; the native Material button keyboard behavior is preserved.
• Focus. Focus is not moved into the notification — they are non-blocking surfaces and should not steal focus from the user's current task.
• Action button labeling. Icon-only action buttons (actionButtonType: 'icon') use the label field as the button's aria-label, so screen readers announce the action's purpose even when no visible text is rendered.
• Close button labeling. The close button has a fixed aria-label="Dismiss notification" so its purpose is announced consistently across severities and configurations.
• Severity icons. Severity icons are decorative and marked aria-hidden; the severity meaning is carried by the message text itself, not by the icon alone.
• Color contrast. The default severity palette meets WCAG AA contrast for body text on each background. Overriding the severity CSS custom properties is the consumer's responsibility to re-verify.