@odx/angular 5.7.4 → 6.0.1

package/fesm2022/odx-angular-components-notification.mjs

@@ -38,6 +38,7 @@ var notificationI18n = {
     },
 };
 
+/** @internal */
 function getNotificationsByTags(...tags) {
     const cachedTags = new Set(tags.filter(Boolean));
     return ({ options }) => {
@@ -45,6 +46,7 @@ function getNotificationsByTags(...tags) {
     };
 }
 
+/** @internal */
 function sortNotifications(sortFn) {
     return (source$) => source$.pipe(tap((values) => {
         if (!isFunction(sortFn))
@@ -53,6 +55,7 @@ function sortNotifications(sortFn) {
     }));
 }
 
+/** @internal */
 function toNotificationCollection() {
     return (source$) => source$.pipe(map((notificationRefs) => ({
         values: notificationRefs,
@@ -61,33 +64,118 @@ function toNotificationCollection() {
     })));
 }
 
+/**
+ * Generates and exports configuration tokens for notifications, utilizing Angular's dependency injection.
+ * This function provides a structured approach to configuring and providing notification settings across
+ * an application.
+ *
+ * @example
+ * ```ts
+ * // In module providers:
+ * providers: [
+ *   provideNotificationConfig({
+ *      defaultIdPrefix: 'your-prefix-notifications', // will be used as id prefix for notification items
+ *      options: NotificationOptions, // { icon: 'core::globe', tags: [], dismissable: true } by default
+ *      sortFn: (a: NotificationRef, b: NotificationRef) => b.createdAt.localeCompare(a.createdAt), // default sort function
+ *      tagToIconMap: { message: 'core::mail' }, // custom icon for message tag (default is core::globe)
+ *      actionMap: { view: (notification) => { console.log(notification); } } // custom action handler
+ *  })
+ * ]
+ *
+ * // In component or service:
+ * constructor(@Inject(NotificationConfig) private notificationConfig: NotificationConfig) {...}
+ * ```
+ */
 const { NotificationConfig, NotificationDefaultConfig, injectNotificationConfig, provideNotificationConfig } = createConfigTokens('Notification', '@odx/angular/components/notification', {
     options: { icon: 'core::globe', tags: [], dismissable: true },
     sortFn: orderBy('createdAt', 'DESC'),
     defaultIdPrefix: 'odx-notifications',
 });
+/**
+ * Constructs and provides Angular environment providers for notifications based on provided configurations and features.
+ * Ideal for setting up notifications at the application's top level, ensuring global availability and configurability.
+ *
+ * @param {Partial<NotificationConfig>} [config] - Optional configuration overrides.
+ * @param {...NotificationFeature[]} features - Features to enhance the notification system.
+ * @returns {EnvironmentProviders} Configured providers ready for integration into Angular's environment.
+ *
+ * @example
+ * ```ts
+ * // In module providers:
+ * providers: [
+ *   provideNotifications({
+ *      config, // NotificationConfig
+ *   },
+ *   {
+ *      withBrowserNotifications({...}), // NotificationFeature
+ *   },
+ *  )
+ * ]
+ * ```
+ */
 function provideNotifications(config, ...features) {
     return makeEnvironmentProviders([provideNotificationConfig(config ?? {}), features]);
 }
 
+/** @internal */
 var logger = new Logger('@odx/angular/components/notification');
 
+/**
+ * Represents the injection token for the notification queue.
+ */
 const ODX_NOTIFICATION_QUEUE = new InjectionToken('@odx/angular/component/notifications::Queue', {
     providedIn: 'root',
     factory: () => new Queue(),
 });
 
+/**
+ * The `NotificationService` class provides methods for managing notifications.
+ * It allows you to create, load, dismiss, mark as seen, and execute actions on notifications.
+ * You can also fetch notifications based on specific queries and sort them using custom sort functions.
+ */
 class NotificationService {
     constructor() {
         this.config = injectNotificationConfig();
         this.localizationService = inject(LocalizationService);
         this.queue = inject(ODX_NOTIFICATION_QUEUE);
         this.injector = inject(Injector);
+        /**
+         * An observable stream of all notifications in the queue, sorted by the configured sort function.
+         *
+         * @emits {NotificationCollection} A collection of notifications.
+         */
         this.notifications$ = this.queue.value$.pipe(sortNotifications(this.config.sortFn), toNotificationCollection(), shareReplay({ bufferSize: 1, refCount: true }));
+        /**
+         * An observable stream of all unseen notifications in the queue.
+         * Unseen notifications are those that have not been marked as seen.
+         *
+         * @emits {NotificationCollection} A collection of unseen notifications.
+         */
         this.unseenNotifications$ = this.notifications$.pipe(map((collection) => collection.values.filter(({ hasBeenSeen }) => !hasBeenSeen)), toNotificationCollection(), shareReplay({ bufferSize: 1, refCount: true }));
+        /**
+         * An observable stream of all seen notifications in the queue.
+         * Seen notifications are those that have been marked as seen.
+         *
+         * @emits {NotificationCollection} A collection of seen notifications.
+         */
         this.onNotificationAdd$ = this.queue.onAdd$;
+        /**
+         * An observable stream of notifications that have been removed from the queue.
+         *
+         * @emits {NotificationCollection} A collection of removed notifications.
+         */
         this.onNotificationRemove$ = this.queue.onRemove$;
+        /**
+         * An observable stream of notifications that have been updated in the queue.
+         *
+         * @emits {NotificationCollection} A collection of updated notifications.
+         */
         this.onNotificationUpdate$ = this.queue.onUpdate$;
+        /**
+         * An observable stream of notifications that have been marked as seen.
+         *
+         * @emits {NotificationCollection} A collection of seen notifications.
+         */
         this.onNotificationSeen$ = this.queue.onUpdate$.pipe(filter(({ hasBeenSeen }) => hasBeenSeen));
     }
     /**
@@ -97,11 +185,13 @@ class NotificationService {
      * @param {NotificationSortFn} [sortFn] - An optional sorting function to order the filtered notifications.
      * @returns {Observable<NotificationCollection>} An observable stream of the filtered (and optionally sorted) notification collection.
      * @example
+     * ```ts
      * // Fetch notifications with a specific tag, sorted by creation date
      * const sortedNotifications$ = notificationService.getNotificationsBy$(
      *   notification => notification.tags.includes('important'),
      *   (a, b) => b.createdAt - a.createdAt
      * );
+     * ```
      */
     getNotificationsBy$(query, sortFn) {
         return this.queue.value$.pipe(map((notifications) => notifications.filter(query)), sortNotifications(sortFn), toNotificationCollection(), shareReplay({ bufferSize: 1, refCount: true }));
@@ -111,11 +201,13 @@ class NotificationService {
      *
      * @param {NotificationRef[]} refs - An array of notification references to be loaded.
      * @example
+     * ```ts
      * // Load multiple notifications at once
      * notificationService.load([
      *   { id: '1', item: { title: 'Notification 1' }, options: {dismissable: true, icon: 'plus', tags: ['important']}, hasBeenSeen: false, createdAt: Date.now() },
      *   { id: '2', item: { title: 'Notification 2' }, options: {dismissable: true, icon: 'plus', tags: ['important']}, hasBeenSeen: false, createdAt: Date.now() }
      * ]);
+     * ```
      */
     load(refs) {
         this.queue.addMany(refs);
@@ -126,11 +218,13 @@ class NotificationService {
      * @param {Notification} item - The notification to create.
      * @param {Partial<NotificationOptions>} [options] - Optional settings for the notification.
      * @example
+     * ```ts
      * // Create a new notification with custom options
      * notificationService.create(
      *   { title: 'New Notification' },
      *   { dismissable: true, icon: 'plus', tags: ['important'] }
      * );
+     * ```
      */
     create(item, options) {
         this.queue.add({
@@ -146,8 +240,10 @@ class NotificationService {
      *
      * @param {NotificationRef} notificationRef - The reference to the notification to mark as seen.
      * @example
+     * ```ts
      * // Mark a notification as seen by its reference
      * notificationService.markAsSeen(notificationRef);
+     * ```
      */
     markAsSeen(notificationRef) {
         if (notificationRef.hasBeenSeen)
@@ -159,8 +255,10 @@ class NotificationService {
      *
      * @param {NotificationQuery} query - The query to match notifications to mark as seen.
      * @example
+     * ```ts
      * // Mark all notifications with a specific tag as seen
      * notificationService.markAsSeenBy(notification => notification.tags.includes('important'));
+     * ```
      */
     markAsSeenBy(query) {
         for (const notificationRef of this.queue.toArray().filter(query)) {
@@ -172,8 +270,10 @@ class NotificationService {
      *
      * @param {NotificationRef} notificationRef - The reference to the notification to dismiss.
      * @example
+     * ```ts
      * // Dismiss a notification by its reference
      * notificationService.dismiss(notificationRef);
+     * ```
      */
     dismiss(notificationRef) {
         if (!notificationRef.options.dismissable)
@@ -185,8 +285,10 @@ class NotificationService {
      *
      * @param {NotificationQuery} query - The query to match notifications to dismiss.
      * @example
+     * ```ts
      * // Dismiss all notifications with a specific tag
      * notificationService.dismissBy(notification => notification.tags.includes('expired'));
+     * ```
      */
     dismissBy(query) {
         for (const item of this.queue.toArray().filter(query)) {
@@ -197,8 +299,10 @@ class NotificationService {
      * Dismisses all notifications.
      *
      * @example
+     * ```ts
      * // Dismiss all notifications
      * notificationService.dismissAll();
+     * ```
      */
     dismissAll() {
         this.queue.clear();
@@ -208,8 +312,10 @@ class NotificationService {
      *
      * @param {NotificationRef} notificationRef - The reference to the notification whose action to execute.
      * @example
+     * ```ts
      * // Execute action for a notification
      * notificationService.executeAction(notificationRef);
+     * ```
      */
     executeAction(notificationRef) {
         if (!notificationRef.options.action)
@@ -238,6 +344,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImpo
 /**
  * A service for managing the notification center. This service provides functionalities
  * to filter, sort, and manage actions on notifications.
+ *
+ * @internal
  */
 class NotificationCenterService {
     constructor() {
@@ -246,12 +354,19 @@ class NotificationCenterService {
         this.notificationService = inject(NotificationService);
         this.notificationQuery = computed(() => getNotificationsByTags(this.currentTag()));
         this.title = signal(null);
+        /** @internal */
         this.title$ = toObservable(this.title).pipe(switchMap((title) => (isObservable(title) ? title : of(title))), shareReplay({ bufferSize: 1, refCount: true }));
+        /** @internal */
         this.notifications$ = combineLatest([toObservable(this.notificationQuery), toObservable(this.currentSortFn)]).pipe(switchMap(([query, sortFn]) => this.notificationService.getNotificationsBy$(query, sortFn)));
+        /** @internal */
         this.unseenNotifications$ = this.notifications$.pipe(map((collection) => collection.values.filter(({ hasBeenSeen }) => !hasBeenSeen)), toNotificationCollection());
+        /** @internal */
         this.onNotificationAdd$ = this.queryEvent(this.notificationService.onNotificationAdd$);
+        /** @internal */
         this.onNotificationUpdate$ = this.queryEvent(this.notificationService.onNotificationUpdate$);
+        /** @internal */
         this.onNotificationRemove$ = this.queryEvent(this.notificationService.onNotificationRemove$);
+        /** @internal */
         this.onNotificationSeen$ = this.queryEvent(this.notificationService.onNotificationSeen$);
     }
     /**
@@ -325,6 +440,21 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImpo
             type: Injectable
         }] });
 
+/**
+ * Creates a `NotificationFeature` instance from a given provider or a set of environment providers.
+ * This function is a utility to encapsulate providers into a feature for the notification system, enhancing its configurability.
+ *
+ * @param {(Provider | NotificationFeature)[] | EnvironmentProviders} provider - A single provider, an array of providers, or an environment providers object.
+ * @returns {NotificationFeature} A new `NotificationFeature` encapsulating the provided values.
+ *
+ * @example
+ * ```ts
+ * // Creating a notification feature:
+ * const feature = makeNotificationFeature([
+ *   { provide: SomeService, useClass: SomeServiceImpl }
+ * ]);
+ * ```
+ */
 function makeNotificationFeature(provider) {
     return provider;
 }
@@ -655,8 +785,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImpo
 
 /**
  * A component for displaying and managing a list of notifications. It integrates various sub-components and directives to provide a rich user interface for notification interaction. Supports animations for notification transitions and leverages Angular's change detection strategies for performance.
- *
- * @CSSComponent 'notification-center' - Specifies the CSS class for styling the notification center component.
  */
 let NotificationCenterComponent = class NotificationCenterComponent {
     constructor() {
@@ -697,6 +825,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImpo
 /**
  * A directive that provides an interface for managing notifications.
  * It allows configuring a notification center with dynamic content, sorting, and badge display functionalities.
+ * The directive has hosted directives `BadgeDirective` and `DropdownDirective` for badge and dropdown functionality.
+ *
+ * @see {BadgeDirective}
+ * @see {DropdownDirective}
  */
 class NotificationCenterDirective {
     constructor() {
@@ -710,24 +842,32 @@ class NotificationCenterDirective {
         /**
          * An event that is emitted when a new notification is added.
          * Listeners can use this event to react to new notifications being added to the notification center.
+         *
+         * @emits {NotificationRef} notificationAdd - The notification that was added to the notification center.
          */
         // eslint-disable-next-line @angular-eslint/no-output-rename
         this.notificationAdd = this.notificationCenterService.onNotificationAdd$;
         /**
          * An event that is emitted when a notification is updated.
          * This can be used to react to changes in notifications, such as their read status or content updates.
+         *
+         * @emits {NotificationRef} notificationUpdate - The notification that was updated in the notification center.
          */
         // eslint-disable-next-line @angular-eslint/no-output-rename
         this.notificationUpdate = this.notificationCenterService.onNotificationUpdate$;
         /**
          * An event that is emitted when a notification is removed from the notification center.
          * Use this event to handle the removal of notifications, such as cleaning up resources or updating UI elements.
+         *
+         * @emits {NotificationRef} notificationRemove - The notification that was removed from the notification center.
          */
         // eslint-disable-next-line @angular-eslint/no-output-rename
         this.notificationRemove = this.notificationCenterService.onNotificationRemove$;
         /**
          * An event that is emitted when a notification is marked as seen.
          * This event can be used to perform actions when the user acknowledges a notification.
+         *
+         * @emits {NotificationRef} notificationSeen - The notification that was marked as seen in the notification center.
          */
         // eslint-disable-next-line @angular-eslint/no-output-rename
         this.notificationSeen = this.notificationCenterService.onNotificationSeen$;
@@ -751,11 +891,13 @@ class NotificationCenterDirective {
      * @param value A function that compares two notifications and returns the sort order.
      *
      * @example
+     * ```ts
      *  sortFfn = (a: NotificationRef, b: NotificationRef) => {
-          if (a.createdAt < b.createdAt) return -1;
-          if (a.createdAt > b.createdAt) return 1;
-          return 0;
-        };
+     *     if (a.createdAt < b.createdAt) return -1;
+     *     if (a.createdAt > b.createdAt) return 1;
+     *     return 0;
+     *  };
+     * ```
      */
     set sortFn(value) {
         this.notificationCenterService.setSortFn(value);