Genesis foundation notifications

The foundation-notifications package is used for creating and displaying various types of notification, including alert, toast, banner, snackbar and dialog. These notifications are configurable and can be used in different scenarios, ranging from status update to interactive user alerts.

Notifications can be centrally managed within an application using notification-listener component, ensuring consistent user experience. With the help of different notification components and configurations, this package allows users to create a variety of notifications effortlessly.

API documentation

For more detailed information on API and configurations, refer to the API documentation.

Example

Look at an example of one of the many notification components in this module: the dialog notification component. Further examples are shown below.

Show Dialog

Genesis

 import { showNotificationDialog } from '@genesislcap/foundation-notifications';

 @customElement({
   name: 'my-element',
   template: html`
     <div class="container">
       <rapid-button @click=${(x) => x.showDialog()}>Show Dialog</rapid-button>
     </div>
   `,
 })
 export class MyElement extends GenesisElement {
   showDialog() {
     showNotificationDialog(
       {
         title: 'Important message',
         body: 'Lorem ipsum',
         dialog: {
           confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
           dismissingAction: {
             label: 'Dismiss',
             action: () => console.log('Lorem ipsum'),
           },
         },
       },
       'rapid',
     );
   }
 }

React

import { showNotificationDialog } from '@genesislcap/foundation-notifications';

export function MyComponent() {
  const showDialog = (event) => {
    showNotificationDialog(
      {
        title: 'Important message',
        body: 'Lorem ipsum',
        dialog: {
          confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
          dismissingAction: {
            label: 'Dismiss',
            action: () => console.log('Lorem ipsum'),
          },
        },
      },
      'rapid',
    );
  };

  return (
    <rapid-button onClick={showDialog}>Show Dialog</rapid-button>
  );
}

Angular

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { showNotificationDialog } from '@genesislcap/foundation-notifications';

@Component({
  selector: 'my-root',
  template: `
    <rapid-button
      (click)="showDialog($event)"
    >Show Dialog</rapid-button>
  `,
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  imports: [FormsModule],
})
export class AppComponent {
  showDialog(event: Event) {
    showNotificationDialog(
      {
        title: 'Important message',
        body: 'Lorem ipsum',
        dialog: {
          confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
          dismissingAction: {
            label: 'Dismiss',
            action: () => console.log('Lorem ipsum'),
          },
        },
      },
      'rapid',
    );
  }
}

Notification Components

Here is a list of available notification components in Genesis's foundation-notifications package:

• Alert: Alerts are quick messages that share important information without interrupting the user.
• Toast: These are short, auto-closing notifications that are displayed at edge of screen and are ideal for transient messages like success confirmations or error notifications.
• Banner: banner is used to show important notifications such as messages for system update. It appears on top of screen.
• Snackbar: These are interactive notifications that appear at bottom of screen. snackbar are persistent until dismissed.
• Dialog: dialog is used for displaying critical notifications as they block the underlying interface until dismissed by user action. One example will be confirmation dialog shown on deleting a user.

Understanding notification components with examples:

The notifications component implemented by foundation-notifications package are designed to serve specific use cases. These components aids users in providing timely feedback, warning or interactive prompts.

Alert

alerts are simple, non-intrusive notifications that are used for giving information to user without interrupting their workflow. They are great for showing messages that don't require user interaction such as updates, confirmations or warnings. It functions similarly to the built-in JavaScript alert() method

Here's an example of using alerts with the showNotificationAlert method from the package.For the parameters, refer to AlertStructure in the package API documentation.

Show Alert

 showNotificationAlert({ title: 'Important message', body: 'Lorem ipsum' });

Toast

Toast notifications are short, auto-closing notifications that are displayed at edge of the screen. They are used for transient messages like success confirmations, error notifications or updates that don't require user acknowledgement.

Here's an example of using toast with the showNotificationToast method from the package.For the parameters, refer to ToastStructure in the package API documentation.

Show Toast

 showNotificationToast(
   {
   title: 'Important message',
   body: 'Lorem ipsum',
   toast: {
     autoClose: true,
     closeTimeout: 3000,
     type: 'success',
   },
 },
 'rapid',
 );

As mentioned before, they automatically close after a specific duration by using autoClose and closeTimeout options. Like snackbar, they can be styled using the type option that supports error, success, warning and info styles.

Banner

Banner notifications are used for delivering key messages and appears at top of the screen. It supports confirming and dismissing actions with callbacks. Here's an example of using banner with the showNotificationBanner method from the package. For the parameters, refer to BannerStructure in the package API documentation.

Show Banner

 showNotificationBanner(
   {
     body: 'Lorem ipsum',
     banner: {
       confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
       dismissingAction: {
         label: 'Dismiss',
         action: () => console.log('Lorem ipsum'),
       },
     },
   },
   'rapid',
 );

Snackbar

snackbars are notifications that appear at bottom of screen. These notifications can have interactive button unlike toasts. They can be used for brief updates that require user interaction, like showing a status or confirming an action.

type property in snackbar config can be used to set the notification style. Supported types are error,success, info or warning.

Here's an example of using snackbar with the showNotificationSnackbar method from the package.For the parameters, refer to SnackbarStructure in the package API documentation.

Show Snackbar

 showNotificationSnackbar(
 {
   body: 'Lorem ipsum',
   snackbar: {
     confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
     type: 'error',
   },
 },
 'rapid',
);

Snackbar are persistent until dismissed. They can disappear automatically after a short time by setting the autoClose property in the snackbar config.

  showNotificationSnackbar(
    {
      body: 'Lorem ipsum',
      snackbar: {
        confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
        type: 'error',
        autoClose: true
      },
    },
    'rapid',
  );

Dialog

This notification component uses a modal-like window to display notification. Dialog notifications requires user to take an action before proceeding as they block the underlying interface until dismissed. Therefore, these are used for critical interactions such as warnings, confirmations or important announcements. Dialog notification component also supports multiple action buttons.

One of the most common use case for dialog is confirming before deleting.

An example for using dialog component is shown in the Example section above. Multiple action buttons can be shown in a dialog by using confirmingActions property as shown in below snippet:

showNotificationDialog(
  {
    title: 'Important message',
    body: 'Lorem ipsum',
    dialog: {
      confirmingActions: [
        { label: 'Confirm', action: () => console.log('Lorem ipsum') },
        { label: 'Save', action: () => console.log('Lorem ipsum') }
      ],
      dismissingAction: {
        label: 'Dismiss',
        action: () => console.log('Lorem ipsum'),
      },
    },
  },
  'rapid',
);

Notification listener Component

rapid-notification-listener component is a key utility in Genesis that listens for notifications event dispatched form any part of your application. It processes the event payload and dynamically displays the appropriate notification component (e.g., Alert, Toast, Dialog, etc.).

By centralizing notification management, the notification-listener makes it easy to handle different types of notification in a consistent and modular way.

The client app need to create notification-listener at top of the component tree. Any child under notification-listener component can dispatch custom NotificationEvent event

Example: Usage of Notification listener

Lets look at code example to setup and use the notification-listener component. You will need to follow the following steps to achieve this:

1. Wrap your application with the notification-listener

As discussed earlier notification-listener component needs to be placed at the top of component tree to ensure it can capture events from any child component. You can find the rapid-design-system-provider tag in your application and place the notification-listener tag inside it, whether you're using React, Angular, or Genesis framework.

<rapid-design-system-provider>
  <rapid-notification-listener>
    // other application components go here
  </rapid-notification-listener>
</rapid-design-system-provider>

2. Dispatching notification using NOTIFICATION_EVENT

To dispatch notification, you can use NotificationEvent.NOTIFICATION_EVENT. You can specify the type of notification component you want to display in the config object. For this example we are displaying snackbar.

this.$emit( NotificationEvent.NOTIFICATION_EVENT,
  {
    title: 'Important message',
    body: 'Lorem ipsum',
    config: {
      snackbar: {
        confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
        type: 'error',
        autoClose: true
      },
    },
  } as NotificationStructure,)

3. Provide a UI element to trigger notification

Now you can trigger your notification on clicking on a UI element like button.

Lets complete the above example and trigger the notification event from a child component.

Genesis

import {NotificationEvent, NotificationStructure} from '@genesislcap/foundation-notifications'
...
@customElement({
  name: 'my-element',
  template: html`
    <div class="container">
      <rapid-button @click=${(x) => x.triggerNotification()}>Show Notification</rapid-button>
    </div>
  `,
})
export class MyElement extends GenesisElement {
  triggerNotification() {
    this.$emit( NotificationEvent.NOTIFICATION_EVENT,
      {
        title: 'Important message',
        body: 'Lorem ipsum',
        config: {
          snackbar: {
            confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
            type: 'error',
            autoClose: true
          },
        },
      } as NotificationStructure,)
  }
}

React

import { NotificationEvent, NotificationStructure } from '@genesislcap/foundation-notifications';
import { useRef } from 'react';

export function MyComponent() {
  const ref = useRef();
  const triggerNotification = (event) => {
    const notificationPayload = {
      title: 'Important message',
      body: 'Lorem ipsum',
      config: {
        snackbar: {
          confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
          type: 'error',
          autoClose: true
        },
      },
    } as NotificationStructure;
    ref.current.dispatchEvent(customEventFactory(NotificationEvent.NOTIFICATION_EVENT, notificationPayload))
  };

  return (
    <rapid-button onClick={triggerNotification} ref={ref}>Show Notification</rapid-button>
  );
}

customEventFactory is a helper function to create events in the expected payload format. You can either import it from the PBC module if you're using it, or copy this function into your codebase.

export function customEventFactory(type: string, detail?: any) {
    return new CustomEvent(type, {
        bubbles: true,
        cancelable: true,
        composed: true,
        detail,
    });
}

Angular

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { NotificationEvent, NotificationStructure } from '@genesislcap/foundation-notifications';

@Component({
  selector: 'my-root',
  template: `
    <rapid-button
      (click)="triggerNotification($event)"
    >Show Notification</rapid-button>
  `,
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  imports: [FormsModule],
})
export class AppComponent {
  constructor(private el: ElementRef) {}
  triggerNotification(event: Event) {
    const notificationPayload = {
      title: 'Important message',
      body: 'Lorem ipsum',
      config: {
        snackbar: {
          confirmingActions: [{ label: 'Confirm', action: () => console.log('Lorem ipsum') }],
          type: 'error',
          autoClose: true
        },
      },
    } as NotificationStructure;
    this.el.nativeElement.dispatchEvent(customEventFactory(NotificationEvent.NOTIFICATION_EVENT, notificationPayload));
  }
}

customEventFactory is a helper function to create events in the expected payload format. You can either import it from the PBC module if you're using it, or copy this function into your codebase.

export function customEventFactory(type: string, detail?: any) {
    return new CustomEvent(type, {
        bubbles: true,
        cancelable: true,
        composed: true,
        detail,
    });
}

Additionally we can also provide resource-name attribute to notification-listener component. This attribute allows the component to connect to a datasource and listen to the notifications on actions like insert, update or delete performed on the specified resource-name.

Installation

To enable this module in your application, follow the steps below.

1. Add @genesislcap/foundation-notifications as a dependency in your package.json file. Whenever you change the dependencies of your project, ensure you run the $ npm run bootstrap command again. You can find more information in the package.json basics page.

{
  "dependencies": {
    "@genesislcap/foundation-notifications": "latest"
  },
}