# API of `@koobiq/components/notification-center`

Documented on [Notification Center](https://koobiq.io/en/components/notification-center.md). NgModule: `KbqNotificationCenterModule`.

## Directives

### KbqNotificationCenterTrigger (directive)

```ts
@Directive({
    selector: '[kbqNotificationCenterTrigger]',
    exportAs: 'kbqNotificationCenterTrigger'
})
class KbqNotificationCenterTrigger extends KbqPopUpTrigger<KbqNotificationCenterComponent> {
    readonly backdropClass = input<string>(
        'cdk-overlay-transparent-backdrop'
    );
    readonly panelClass = input<string>('', {
        alias: 'kbqNotificationCenterPanelClass'
    });
    readonly offset = input<number>(defaultOffsetX);
    readonly scrolledToBottomOffset = input<number>(0);
    popoverMode = input<boolean | undefined>();
    popoverHeight = input<string | undefined>();
    disabled = input<boolean | undefined>();
    stickToWindow = input<KbqStickToWindowPlacementValues | undefined>();
    container = input<HTMLElement | undefined>();
    get unreadItemsCounter(): Signal<string>;
    placement: KbqPopUpPlacementValues;
    readonly placementChange: EventEmitter<KbqPopUpPlacementValues>;
    readonly visibleChange: EventEmitter<boolean>;
    isOpen: boolean;
    get isAttached(): boolean;
    get openedChange(): Observable<boolean>;
    arrowCentered: boolean;
    updateOrigin(origin: KbqOverlayOrigin | null): void;
}
```

- `[backdropClass]`: `string` — Class that will be used in the background
- `[kbqNotificationCenterPanelClass]`: `string` — Class that will be used in the panel
- `[offset]`: `number` — Offset of popUp
- `[scrolledToBottomOffset]`: `number` — Distance in pixels from the bottom of the list at which the next page is requested via `onNextPage`.
- `[popoverMode]`: `boolean | undefined` — Use popover or not
- `[popoverHeight]`: `string | undefined` — Set height of popover. Default is `calc(100vh - <navbar height>)`.
- `[disabled]`: `boolean | undefined` — Whether the trigger is disabled.
- `[stickToWindow]`: `KbqStickToWindowPlacementValues | undefined` — Additionally positions the element relative to the window side (Top, Right, Bottom and Left).
  If container is specified, the positioning will be relative to it.
- `[container]`: `HTMLElement | undefined` — Container for additional positioning, used with stickToWindow
- `unreadItemsCounter`: `Signal<string>` — Number of unread notifications, formatted for the trigger badge.
- `placement`: `KbqPopUpPlacementValues` — Placement of popUp
- `placementChange`: `EventEmitter<KbqPopUpPlacementValues>` — Emits a change event whenever the placement state changes.
- `visibleChange`: `EventEmitter<boolean>` — Emits a change event whenever the visible state changes.
- `isOpen`: `boolean` — Whether the pop-up overlay is currently open.
- `isAttached`: `boolean` — Whether the pop-up overlay is currently attached.

  Unlike `isOpen`, which follows the visibility of the pop-up component and therefore lags a task behind
  `show()`/`hide()`, this flips synchronously — it is the window during which the overlay (and its
  backdrop) is present in the DOM. Part of the `KbqSiblingPopup` contract.
- `openedChange`: `Observable<boolean>` — Emits `true` when the pop-up opens and `false` when it closes. Part of the `KbqSiblingPopup` contract.
- `arrowCentered`: `boolean` — Whether the arrow points at the origin center while the panel keeps its placement. Defaults to `false`.
- `updateOrigin()`: `void` — Positions the pop-up against `origin` — an element, or a rectangle in viewport coordinates such as the one
  `kbqCreateCaretOrigin` keeps on the caret — instead of the host element; `null` restores the host
  element. An open pop-up moves to the new origin at once.

  This moves the position origin only. `setExternalNativeElement` moves the host itself, and with it
  the trigger's event listeners, its focus target and the scroll containers the pop-up follows.

## Services

### KbqNotificationCenterService (service)

State and commands of the notification center: the list itself, its modes, and the removal events.

```ts
@Injectable({ providedIn: 'root' })
class KbqNotificationCenterService {
    readonly loadingMore: Signal<boolean>;
    readonly loadMoreErrorMode: Signal<boolean>;
    readonly hasMore: Signal<boolean>;
    readonly onRead: BehaviorSubject<KbqNotificationItem | null>;
    readonly onReload: Subject<void>;
    readonly onNextPage: Subject<void>;
    readonly onDelete: Subject<KbqNotificationDeleteEvent>;
    readonly changes: Observable<void>;
    readonly unreadItemsCounter: Signal<string>;
    items: KbqNotificationItem[];
    get isEmpty(): boolean;
    setSilentMode(value: boolean): void;
    setLoadingMode(value: boolean): void;
    setErrorMode(value: boolean): void;
    setLoadingMore(value: boolean): void;
    setLoadMoreErrorMode(value: boolean): void;
    setHasMore(value: boolean): void;
    push(item: KbqNotificationItem): void;
    hideToast(item: KbqNotificationItem): void;
    remove(removedItem: KbqNotificationItem): void;
    removeGroup(group: KbqNotificationsGroup): void;
    removeAll(): void;
}
```

- `loadingMore`: `Signal<boolean>` — Whether the bottom "load more" spinner is shown while the next page is being loaded.
  Note: this is the infinite-scroll indicator and is distinct from `loadingMode`,
  which renders the full-screen loader instead of the list. Set it with `setLoadingMore()`.
- `loadMoreErrorMode`: `Signal<boolean>` — Whether the bottom "load more" error row (with a retry button) is shown.
  Distinct from `errorMode`, which replaces the whole list with the full-screen error state.
  Set it with `setLoadMoreErrorMode()`.
- `hasMore`: `Signal<boolean>` — Whether there are more notifications to load. While `true`, scrolling to the bottom
  emits `onNextPage`; set it to `false` with `setHasMore()` to stop further infinite-scroll requests.
- `onRead`: `BehaviorSubject<KbqNotificationItem | null>` — Emits a notification the moment it flips from unread to read.
- `onReload`: `Subject<void>` — Triggers an event when the user presses the reload button.
- `onNextPage`: `Subject<void>` — Triggers an event when the list is scrolled to the bottom and the next page should be loaded.
- `onDelete`: `Subject<KbqNotificationDeleteEvent>` — Triggers an event when an item, a group, or all notifications are removed.
- `changes`: `Observable<void>` — Emits whenever any part of the center's state changes. Carries no payload — it is a ping — and
  emits nothing on subscription.
- `unreadItemsCounter`: `Signal<string>` — Number of unread notifications, formatted for the trigger badge: empty while nothing is unread,
  and `"99+"` above `maxUnreadItemsLength`.
- `items`: `KbqNotificationItem[]` — The notifications, as a snapshot: reading them does not make an `effect()` or a `computed()` depend on the
  list, so an effect can read and reassign it. Follow `changes` to react to updates.
- `isEmpty`: `boolean` — Whether there are no notifications. A snapshot, like `items`.
- `setSilentMode()`: `void` — Set silent mode
- `setLoadingMode()`: `void` — Set loading mode
- `setErrorMode()`: `void` — Set error mode
- `setLoadingMore()`: `void` — Set the bottom "load more" spinner visibility.
- `setLoadMoreErrorMode()`: `void` — Set the bottom "load more" error state visibility.
- `setHasMore()`: `void` — Set whether there are more notifications to load via infinite scroll.
- `push()`: `void` — Adds a notification to the list and, unless silent mode is on, shows it as a toast.
  Re-pushing the very same notification object is a no-op: a duplicate would show a second toast
  and produce a colliding list key. A different notification carrying an `id` the list already
  uses is added under a freshly generated one instead of being dropped.
- `hideToast()`: `void` — Hides the toast that corresponds to the given notification item.
- `remove()`: `void` — Removes a notification. Removing one that is not in the list is a no-op and emits nothing.
- `removeGroup()`: `void` — Removes a whole day group. Only the notifications that are actually in the list are removed and
  reported; a group holding none of them — a stale reference kept from an earlier `groupedItems`
  value — is a no-op and emits nothing.
- `removeAll()`: `void` — Removes every notification. Removing from an already empty list is a no-op and emits nothing.

## Types

### KbqNotificationCenterPanel (interface)

The panel members a rendered notification item depends on.

```ts
interface KbqNotificationCenterPanel {
    readonly localeConfiguration: Signal<KbqNotificationCenterLocaleConfiguration>;
    restoreFocusAfterRemove(): void;
}
```

- `localeConfiguration`: `Signal<KbqNotificationCenterLocaleConfiguration>` — Localized strings of the panel.
- `restoreFocusAfterRemove()`: `void` — Moves focus to a control that survives the removal, once the delete button has unmounted.

### KbqNotificationDeleteEvent (type)

Payload emitted by `KbqNotificationCenterService.onDelete`.

```ts
type KbqNotificationDeleteEvent = {
    type: 'item' | 'group' | 'all';
    items: KbqNotificationItem[];
};
```

- `type`: `'item' | 'group' | 'all'` — What was removed: a single item, a whole date group, or all notifications.
- `items`: `KbqNotificationItem[]` — The notification items that were removed.

### KbqNotificationItem (interface)

A single notification rendered by the notification center.

```ts
interface KbqNotificationItem {
    id?: string;
    toastId?: number;
    title?: string | TemplateRef<unknown>;
    style?: string | KbqToastStyle;
    icon?: boolean | TemplateRef<unknown>;
    iconClass?: string;
    caption?: string | TemplateRef<unknown>;
    content?: string | TemplateRef<unknown>;
    actions?: TemplateRef<unknown>;
    date: string;
    read?: boolean;
}
```

- `id?`: `string` — Identity of the notification, unique across the list — it is the list's track key and the key
  the toast is matched back by. Generated on ingestion when omitted, and replaced by a generated
  one when the supplied value is already taken by another notification.
- `toastId?`: `number` — Numeric id of the shown toast, set by `push()` and consumed by `hideToast()`.
- `title?`: `string | TemplateRef<unknown>` — Heading of the notification.
- `style?`: `string | KbqToastStyle` — Visual style; also selects the built-in icon when `icon` is `true`.
- `icon?`: `boolean | TemplateRef<unknown>` — `true` renders the built-in icon for `style`; a template renders that template instead.
- `iconClass?`: `string` — Extra classes for the built-in icon.
- `caption?`: `string | TemplateRef<unknown>` — Secondary line below the title.
- `content?`: `string | TemplateRef<unknown>` — Body of the notification.
- `actions?`: `TemplateRef<unknown>` — Template with the notification's action controls.
- `date`: `string` — When the notification happened. Any value the configured `DateAdapter` parses without an explicit
  format — ISO 8601, RFC 2822 or SQL for the Luxon adapter. The value drives both the day group and
  the ordering; values the adapter cannot parse are shown verbatim in their own group instead of
  breaking the list.
- `read?`: `boolean` — Whether the user has already read the notification. Defaults to `false` on ingestion.

### KbqNotificationsGroup (type)

Notifications that happened on the same day, as rendered by one sub-header of the panel.

```ts
type KbqNotificationsGroup = {
    id: string;
    title: string;
    items: KbqNotificationItem[];
};
```

- `id`: `string` — Stable identity of the day group; used as the list's track key.
- `title`: `string` — Localized day heading.
- `items`: `KbqNotificationItem[]` — Notifications of that day, newest first.

## Constants

### KBQ_NOTIFICATION_CENTER_CONFIGURATION (const)

Deprecated: Use `KBQ_NOTIFICATION_CENTER_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_NOTIFICATION_CENTER_CONFIGURATION: InjectionToken<KbqNotificationCenterLocaleConfiguration>;
```

### KBQ_NOTIFICATION_CENTER_DEFAULT_CONFIGURATION (const)

Deprecated: Use `KBQ_NOTIFICATION_CENTER_DEFAULT_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_NOTIFICATION_CENTER_DEFAULT_CONFIGURATION: KbqNotificationCenterLocaleConfiguration;
```

### KBQ_NOTIFICATION_CENTER_DEFAULT_LOCALE_CONFIGURATION (const)

Default configuration of notification-center.

```ts
const KBQ_NOTIFICATION_CENTER_DEFAULT_LOCALE_CONFIGURATION: KbqNotificationCenterLocaleConfiguration;
```

### KBQ_NOTIFICATION_CENTER_LOCALE_CONFIGURATION (const)

Injection Token for providing configuration of notification-center.

```ts
const KBQ_NOTIFICATION_CENTER_LOCALE_CONFIGURATION: InjectionToken<KbqNotificationCenterLocaleConfiguration>;
```

### KBQ_NOTIFICATION_CENTER_PANEL (const)

Narrow contract a `kbq-notification-item` consumes from the panel that renders it, instead of
injecting the panel component itself.

```ts
const KBQ_NOTIFICATION_CENTER_PANEL: InjectionToken<KbqNotificationCenterPanel>;
```

### kbqNotificationCenterLocaleConfigurationProvider (const)

Utility provider for `KBQ_NOTIFICATION_CENTER_LOCALE_CONFIGURATION`. Only the strings you pass are overridden; the
rest keep following the active locale.

```ts
const kbqNotificationCenterLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqNotificationCenterLocaleConfiguration>
) => Provider;
```

### maxUnreadItemsLength (const)

Number of unread notifications above which the trigger counter switches to `"99+"`.

```ts
const maxUnreadItemsLength: number;
```
